Vistar’s Unified Ad Serving offering allows media owners to schedule and deliver programmatic, flexible, and loop-based content all within one platform. To enable your content management system to use Unified Ad Serving, Vistar provides media owners with a RESTful interface over HTTP, referred to as Vistar’s Unified Ad Serving API. Using this API, you can request loops, receive loop responses, report back proof of plays (PoPs), receive direction to get programmatic content.
Definitions
Definitions of common terms used throughout the API can be found below:
- Asset – An asset is a file containing content that should be displayed on a screen
- Slot – A slot is a space within a loop for an asset with a known duration
- Loop – A loop is an ordered sequence of slots that should repeat until the loop’s stated end time
- Loop Duration – A loop has a fixed duration specified at the network level. This duration should reflect the desired frequency for “one ad playing every loop”
- Scheduled Content – Scheduled content, also referred to as loop-based content, refers to assets that should be delivered based on some frequency of loops (e.g. one play every loop)
- Programmatic Content – Programmatic content refers to assets that should be delivered according to business rules, such as an impression or dollar goal. Programmatic content can either be direct-sold flexible orders or from PMPs or Open Exchange transactions
Get a Loop
Gets a loop of content to be played on a specific venue at a specific time. The current time is used if no display_time
is specified in the request.
A response Loop
message includes any relevant Assets
and the ordered sequence of Slots
that is scheduled to run until a specified end_time
.
The venue should repeatedly loop over the Slot
sequence in the specified order. As each slot is encountered, the venue should compare its current time with the given end_time
. If the current time is equal to or after the end_time
, then it should abort the current loop and make a new GetLoop
request. Otherwise the Slot
should be handled as follows:
- If the
type
is"advertisement"
or"content"
, then the venue should look up the associatedAsset
by the specifiedasset_url
. It should play theasset
and hit the specifiedtracking_url
upon completion. - If the
type
is"programmatic"
, then the venue should make a programmaticGetAd
request. If a programmatic ad is returned, then the venue should play the ad and hit the associatedproof_of_play_url
. If no programmatic ad is returned, then the venue should advance to the nextslot
in the loop.
Request Body Parameters
Name | Description | Type | Required |
venue_id |
The media owner's identifier for the requesting venue. | String | Required |
network_id |
The ID of the network you are making a request for. This is one of two fields used to authenticate using the Ad Serving API. See API Credentials to learn how to retrieve these credentials. |
String | Required |
api_key |
The unique key for the network. This is one of two fields used to authenticate with the Ad Serving API. See API Credentials to learn how to retrieve these credentials. |
String | Required |
display_time |
The time at which the loop will begin playing, as unix epoch in UTC. Defaults to the time of the request. | String <int64> | Recommended |
URL
POST http://sandbox.api.vistarmedia.com/v1beta2/loop
POST https://api.vistarmedia.com/v1beta2/loop
Sample JSON Request
{
"venue_id": "string",
"network_id": "string",
"api_key": "string",
"display_time": "string"
}
Responses
Name |
Description | Type | Required | ||
slots |
The ordered list of slot content in the loop |
Array | Required | ||
type |
Enum:
|
String | Required | ||
length_in_seconds |
The duration the slot's content should display for, in seconds | Integer | Required | ||
tracking_url |
A URL that should be hit after the slot has completed. Only present for scheduled slots. Vistar recommends appending a display time override (defined below) in instances where the time the URL is hit does not match the time the spot played. |
float | Required | ||
asset_url |
The URL of the creative asset to render on the client. Only present if the slot's type is "scheduled". The Asset referred to by this URL shall have an entry in the loop's assets list as well. |
String | Optional | ||
creative_category |
The ID referring to the creative category of the asset contained within the slot. |
String | Optional | ||
loop_position |
The position of the slot within the loop. The first slot in the loop is labeled with |
Integer | Required | ||
assets |
Array of objects (v1beta1Asset) The potentially empty list of assets that are scheduled in the current or an upcoming loop. It is recommended that all returned assets be cached by the client venue so that assets are ready to play when needed. |
Array | Required | ||
url |
The asset's URL. **Recommended to use the asset URL for mapping to cached creatives** | String | Required | ||
mime_type |
The asset's MIME type |
String | Required | ||
name |
The asset's name |
String | Required | ||
companions |
Only present if the asset has creative companions |
Array | Optional | ||
name |
Name of the creative companion |
String | Required | ||
value |
Value of the creative companion. Note if the companion contains a file, the value will provide the URL at which the file is hosted. |
String | Required | ||
end_time |
The time at which this loop is scheduled to end playing as unix epoch in UTC. The venue should compare this time with its current time before handling any loop slot and abort the loop and make a new GetLoop request if the current time is not before it. |
Integer | Required |
Sample JSON Response
{
"slots": [
{
"type": "__none__",
"length_in_seconds": 0,
"tracking_url": "string",
"asset_url": "string",
"creative_category": "string",
"loop_position": 1
}
],
"assets": [
{
"url": "string",
"mime_type": "string",
"name": "string",
"companions": [
{
"name": "string",
"value": "string"
}
]
}
],
"end_time": 0
}
Tracking URLs
You must notify Vistar after a slot is played by hitting the corresponding tracking_url
located in the loop response. When the tracking_url
is hit, the time is recorded in Vistar’s system as the reported display time. If you hit the tracking_url
at a different time than the slot was played, you can append the display_time
to the query string, as shown in the Sample proof of play URL.
Note: Vistar strongly recommends always storing and passing a display time override to handle cases where players are offline for some period of time. The display_time
can be at most 48 hours in the past. Any display_time
beyond 48 hours will result in a 400 error.
Parameters
Name | Description | Type | Required |
display_time |
The actual time an ad was shown in UTC epoch seconds. Example value: |
Int32 | Optional |
https://api.vistarmedia.com/v1beta1/loop/slot:track?p=acNxZ-M-t_
TXIc9AWn-yARzV1Qmvbdhxdq6vymlLmxt7ACRR3L9clC6vNtoHA6doPkS-WPtmxSm3tqk
q2mUj-RHgUmZkci3AwVWt&display_time=1364832421
FAQs