Caching creatives

A creative can take longer to download than its slot lasts. These rules keep files on the device before they are needed. They apply to every player, online or offline.

Download files early

• On every boot and on a schedule, call GET /v1alpha2/ads?playerid=…&key=…&offline=true and download every <MediaFile> it returns. We recommend every 12 hours; that may change. Give each screen its own refresh time, so a site’s screens do not all download at once.
• Download the files in list order. We recommend one at a time: the list puts the most valuable ads first, so on a slow link the most important file arrives first. Parallel downloads are fine too.
• Keep playing from the cache while you refresh. On first boot, start playing as soon as the first file is downloaded.
• Store each file under its media URL. A creative booked with Verve keeps the same URL, so its stored file stays valid.
• When a refresh no longer lists a file, delete it 24 hours later. If the player cannot reach us, delete nothing.

Size the storage

We recommend room for at least 100 ads of up to 50 MB each. Less room is fine if you plan for your bandwidth, since a deleted file may have to download again. Delete the files lowest in the list first, or ask for fewer ads with limit. Do not plan storage from one response: we cap how many ads we send, and the cap may change. A creative booked with Verve stays within its format’s size limit on Ad formats. One from another source has no size we can guarantee, and may not state its fileSize.

Ask a little ahead

Request the online ad a little before the slot starts, but not much earlier: we choose the ad for the people in front of the screen when the request arrives. Never play an online ad past its expires_at.

When the file is not there

Before you download an online ad’s file, check whether it is already stored under its media URL. If it is, play the ad as normal. If not, and the download cannot finish before the slot starts:

1. Play a stored ad instead, chosen by the offline rules, and fire its tracking URLs as normal.
2. Let the online ad’s file finish downloading, and store it.
3. Once it is downloaded, play the online ad in a later slot, and fire its <Impression> and <Tracking> URLs when it plays. If its expires_at has passed by then, skip it and fire nothing.

Ads from an exchange are never in the offline playlist, so their files are often not stored yet.

Never leave the screen black. Never fire the <Impression> or <Tracking> URL of an ad that did not play. If an ad cannot play, fire its <Error> URL; see When an ad cannot play.

When the player cannot refresh

If the player cannot reach us and every stored ad is past its expires_at, keep playing the stored ads in turn and fire their tracking URLs as normal. We decide whether those plays count. Once a refresh succeeds, go back to normal.

If nothing is stored at all, show the player’s own default image and fire nothing for it.