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 Loop response includes an ordered sequence of slots. The sequence is the shortest collection of loop iterations which satisfies line item and creative targeting requirements for the requesting venue. This sequence should be displayed repeatedly, in order, until a specified end_time.

Example: If a line item is set up to run 1x per 4 loops, the loop response includes at least 4 loop iterations. 

Note: Partners should make new loop requests at least every half hour, even if the end_time is several hours away. This will ensure that the device does not miss out on any new campaigns that may have gone live and are targeting the venue in between requests.

Note: The API can be used to view schedules up to 10 days in the future. Trying to a view a display time more than 10 days in the future will display programmatic slots.

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

URL

Sample JSON Request

{
  "venue_id": "string",
  "network_id": "string",
  "api_key": "string",
  "display_time": "string"
  }

Responses

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": 1717298630,
  "start_time": 1717270221
}

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 parameter to the query string so that reporting reflects the time the ad played rather than the time the tracking_url was hit. 

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 30 days in the past. Any display_time beyond 30 days will result in a 400 error. 

Offline Behavior: The tracking_url does not expire to allow devices to continue to play loop content if a device goes offline. If you do not append the display time, reporting reflects that all ads played at the time the device resumes connectivity.  

Parameters

https://api.vistarmedia.com/v1beta1/loop/slot:track?p=acNxZ-M-t_
TXIc9AWn-yARzV1Qmvbdhxdq6vymlLmxt7ACRR3L9clC6vNtoHA6doPkS-WPtmxSm3tqk
q2mUj-RHgUmZkci3AwVWt&display_time=1364832421

FAQs