Your CMS can make calls to Vistar’s ad server to request and cache creatives (also known as assets) in advance. All creatives that qualify to run on your network over the next 30 hours are returned from this endpoint. This is beneficial in the case of poor internet connectivity and can also help save on bandwidth usage.
We recommend using Vistar’s creative caching endpoint to cache creatives in advance (e.g. once a day) in combination with downloading on first sight in ad requests in order to support features such as Dynamic Creatives.
Caching should be based on the asset_url. The asset_url will update for every unique version of the creative that is generated.
Creatives are returned if all of the following are true:
- Creative is active.
- Creative is associated with an active campaign or line item.
- Creative is approved.
- Venue falls within creative or campaign targeting parameters.
Note - device attributes, time of day and day of week targeting filters are not applied when determining the creatives to return from the caching endpoint. This is because as previously mentioned, the endpoint returns all creatives that qualify to run on your network over the next 30 hours.
To view best practices for caching creatives, see the FAQs section in this article.
To request for creative assets
Use the following endpoint URL to make your request. You must specify a display_time to match up with relevant assets.
URL
POST https://sandbox-api.vistarmedia.com/api/v1/get_asset/jsonPOST https://api.vistarmedia.com/api/v1/get_asset/jsonBody parameters
See Ad Serving API for definitions of the body parameters.
Sample JSON request
{
"device_id": "VistarDisplay0",
"device_attribute": [],
"display_area": [
{
"id": "display-0",
"supported_media": [
"application/x-shockwave-dynamic-flash",
"application/x-shockwave-flash",
"image/gif",
"image/jpeg",
"image/png",
"video/mp4",
"video/mpeg",
"video/mpg",
"video/quicktime",
"video/webm",
"video/x-flv",
"video/x-ms-wmv",
"video/x-msvideo"
],
"allow_audio": false,
"width": 1920,
"height": 1280
}
],
"display_time": 1461181625,
"direct_connection": false
"venue_id": "PHX003384",
"network_id": "5U71FqbWTgSMAuO0XS-HHQ",
"api_key": "0f877d21-33fe-40a0-a149-af3527a57130"
}Sample JSON response
{
"asset": [
{
"asset_id": "asset-1",
"creative_id": "creative-1",
"order_id": "Q1_2016_001",
"campaign_id": "campaign-1",
"asset_url": "http://url/to/asset.jpg",
"width": 1280,
"height": 720,
"mime_type": "image/jpeg",
"length_in_seconds": 15,
"length_in_milliseconds": 15000,
"creative_category": "Entertainment"
"advertiser": "Test Advertiser 1",
"creative_name": "Test Creative 1"
},
{
"asset_id": "asset-2",
"creative_id": "creative-2",
"order_id": "Q1_2016_001",
"campaign_id": "campaign-2",
"asset_url": "http://url/to/asset2.mp4",
"width": 1280,
"height": 720,
"mime_type": "image/mp4",
"length_in_seconds": 30,
"length_in_milliseconds": 30000,
"creative_category": "Wildlife",
"advertiser": "Test Advertiser 2",
"creative_name": "Test Creative 2"
}
]
}
FAQs
As a best practice, we recommend sending a call for assets once a day. You should compare the assets in the get_assets response to the pool of already cached creatives using the asset URL. You should only download new creatives identified in the get_asset response.
get_asset call was made, you should download the creative in real time and add it to the pool of cached creatives.Storage needs vary from one media owner to another. There are a number of variables that dictate the volume of caching memory that you (the media owner) should allocate, such as:
- The mime types you can support —See "What are the supported mime-types" in the Frequently asked questions article.
- The demand for your inventory—This can vary from market to market and based on price.
- Your caching criteria.
With this in mind, here are some recommended storage sizes to start out, depending on the types of creatives you support:
| Creative type supported | Recommendation |
| Images only | At least 140 MB of storage |
| Video only | At least 250 MB of storage |
| Images and video | At least 400 MB of storage |
| Dynamic creatives | At least 400 MB of storage |
The following table also shows you asset sizes in the 90th percentile (based on our historical records) for your reference:
| media_type | asset size (bytes) |
| application/cortex-bundle | 6530417 |
| image / gif | 252631 |
| image / jpeg | 1415926 |
| image / png | 2306046 |
| video / mp4 | 5989494 |
| video / mp4 -tt | 11384636 |
| video / ogg | 5938633 |
| video / quicktime | 379911794 |
| video / webm | 4703875 |
| video / x-ms-wmv | 6308185 |
| video / x-flv | 4179606 |
For efficient management of your cache, we recommend the following best practices:
- Clearing the creative from your cache after 30 days.
- It is recommended that you keep track of when a creative is first returned by Vistar’s ad server. For example, you can set a
cache_datefor the creative that you update each time you see the creative returned. You do not need to re-download the creative, but you should update the date to indicate the last time the creative was active.
- It is recommended that you keep track of when a creative is first returned by Vistar’s ad server. For example, you can set a
- Monitoring the memory of your local cache using tools available to you based on your device or server operating system. Depending on the average volume of files cached in a 30 day window, you can adjust your storage size accordingly.