Unified Ad Serving API

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 associated Asset by the specified asset_url. It should play the asset and hit the specified tracking_url upon completion.
  • If the type is "programmatic", then the venue should make a programmatic GetAd request. If a programmatic ad is returned, then the venue should play the ad and hit the associated proof_of_play_url. If no programmatic ad is returned, then the venue should advance to the next slot 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

Staging Production
POST http://sandbox.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: 
  • "advertisement" 
  • "content" 
  • "programmatic"
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
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 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"
    }
  ],
  "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: 1338260504

Int32 Optional
Sample proof of play URL
https://api.vistarmedia.com/v1beta1/loop/slot:track?p=acNxZ-M-t_
TXIc9AWn-yARzV1Qmvbdhxdq6vymlLmxt7ACRR3L9clC6vNtoHA6doPkS-WPtmxSm3tqk
q2mUj-RHgUmZkci3AwVWt&display_time=1364832421

 

FAQs

What determines how much programmatic content is contained in the loop?
Vistar determines how much of the fixed loop length is filled by scheduled, or loop-based, content, and then dedicates the remaining time towards programmatic. For example, if your loop length is 300 seconds and a given loop has 200 seconds of “scheduled” content, then there will be 100 seconds of “programmatic” content in your loop.
How should I handle a programmatic slot with a long duration?
The integration should send ad requests to try to fill the whole programmatic time slot. This should be done by initially setting max duration in the ad request to the duration returned by the API. If the ad response that comes back has a duration shorter than the programmatic period, deduct the duration of the returned ad from the total duration and request that new value as the max duration. Continue this process until the full duration is used or the ad server does not return an ad.
Why am I receiving more than one loop’s worth of content in a loop response?
Rather than returning a single loop, Vistar returns the shortest repeating set of content to a loop request. In some cases, this can lead to the total duration of content being longer than the network’s loop length. This could happen if some line items are scheduled to run every X loops or if some line items have multiple associated creatives. Returning the shortest repeating set of content allows you to repeat the returned content until `end_time` is reached.
What do I do if I am unable to get the next loop or programmatic content?
If connectivity issues or some other factors prevent you from requesting and receiving the next loop or programmatic content, Vistar recommends that you continue to play the current loop without any new programmatic content until you can get a new loop. You should continue to hit the tracking URLs for the content that the device plays regardless of whether or not the loop is no longer scheduled. If poor connectivity prevents you from hitting the tracking URLs, Vistar recommends that you store the URLs and hit all URLs for the content that was played once connectivity is restored.

 

Was this article helpful?
1 out of 1 found this helpful