Video Cloud SSAI Ad Tag Validation

Product(s)
Video Cloud
SSAI
Role(s)
Player Developer
Topic(s)
Advertising
SSAI

In this topic, you will learn how to trace ad calls specified with Server-side Ad Insertion (SSAI).

Overview

To help with debugging of server-side ads, Dynamic Delivery with SSAI provides API endpoints to track ad calls.

To debug server-side ads with your video content stored in Video Cloud, follow these steps:

  1. Review general information for API path and authentication
  2. Retrieve detailed trace information without an ad config id
  3. Retrieve detailed trace information with a session id

General information

The following information pertains to all SSAI API requests.

Base URL

The base URL for the SSAI API is:

https://ssai.api.brightcove.com/v1

Account path

In all cases, requests will be made for a specific Video Cloud Account. So, you will always add the term accounts followed by your account id to the base URL:

https://ssai.api.brightcove.com/v1/accounts/your account id

Authentication

Authentication for requests requires an Authorization header:

Authorization: Bearer your access token

The access_token is a temporary OAuth2 access token that must be obtained from the Brightcove OAuth service. For details on how to obtain client credentials and use them to retrieve access tokens, see the Brightcove OAuth Overview.

Operations

When you request client credentials, you will need to specify the type of account access or operations that you want. The following is a list of the currently supported operations for the SSAI API:

  • Video data:

    video-cloud/video/read
    video-cloud/video/all

Tracing without an ad config id

To retrieve ad-call trace information without supplying an ad config id, follow these steps:

Gather information

Gather the following information for the body of your API request:

Parameter Type Description
account_id String User account id
playback_config Object Fields are defined in the Configuration field details section of the SSAI API document.
title_metadata Object Tells the system how long your content is in order to generate the correct ad response.

For example, the following tells the system that the content is 1 minute long. This is used to insert ads accordingly.
"title_metadata": {  "duration": "1m" }
videocloud_metadata Object Optional.
Needed only if you are using template variables that reference metadata fields. These are defined in the Ad variables section of the SSAI API document.

Request

Create an SSAI ad trace for an account.

Method POST
URL https://ssai.api.brightcove.com/v1/accounts/{account_id}/ssai_debug_vmap/debug.xml
Headers Authorization: Bearer access_token (see Getting Access Tokens)
Content-Type: application/json
Sample Body
{
  "playback_config":{
    "name": "config_name",
    "vmap_response_namespace": "config_namespace",
    "account_id": "account_id",
    "ad_config": {
      "enable_ads": true,
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "round_up_cue_points": false,
      "template_url": {
      "template": "template_url"
      }
    },
    "extend_beacon_guard_ttl": false
  },
  "title_metadata":{
    "duration": "39s"
  }
}

Response

The response body consists of the ad server response that would include the VAST or ad server equivalent response.

Sample response:

<?xml version="1.0" encoding="UTF-8" ?>
<vmap:VMAP xmlns:bc="bc" xmlns:vmap="http://www.iab.net/vmap-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
  <vmap:Extensions>
    <bc:Brightcove ttl="1800" contenturi="https://ssaiplayback.us-east-1.prod.boltdns.net/playback/once/v1/hls/v5/clear/1752604059001/debug/debug/195b46a6-f71b-432d-af0a-60c7f2131a7e/debug.m3u8?bc_token=NWIxNmQ4YWFfMzMwMzllMzIwMmZlYjRkNmJhY2ZkMWZiN2Y2NGQwOWVkZTYxYTBiOThhZmEwMTdkZjc5NjEzNGFkZDdiYTFjYw%3D%3D"
    contentlength="39.0000" payloadlength="67.0000" contenttype="application/x-mpegURL"></bc:Brightcove>
    <bc:BrightcoveDebug sessionID="195b46a6-f71b-432d-af0a-60c7f2131a7e"></bc:BrightcoveDebug>
  </vmap:Extensions>
  <vmap:AdBreak breakType="linear" breakId="MidRoll_5_0" timeOffset="00:00:05.0000">
    <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="0">
      <vmap:VASTData>
        <VAST xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
          <Ad id="2">
            <InLine>
              <AdSystem>Test Ad Server</AdSystem>
              <AdTitle>&#xA; Marketing&#xA;</AdTitle>
              <Description>&#xA; Demo ad number 4&#xA;</Description>
              <Error>&#xA; &#xA;</Error>
              <Creatives>
                <Creative>
                  <Linear skipoffset="00:00:05">
                    <CreativeExtensions>
                      <CreativeExtension>
                        <BrightcoveForeignKey>2</BrightcoveForeignKey>
                      </CreativeExtension>
                    </CreativeExtensions>
                    <Duration>00:00:12.0000</Duration>
                    <AdParameters>&#xA; &lt;xml&gt;&lt;/xml&gt;&#xA;</AdParameters>
                    <VideoClicks></VideoClicks>
                  </Linear>
                </Creative>
              </Creatives>
              <Extensions>
                <Extension>
                  <xml>data</xml>
                </Extension>
              </Extensions>
            </InLine>
          </Ad>
        </VAST>
      </vmap:VASTData>
    </vmap:AdSource>
  </vmap:AdBreak>
  ...// additional ad breaks
</vmap:VMAP>

Request2 - using template variables

Create an SSAI ad trace for an account, where you are using template variables that reference metadata fields.

Method POST
URL https://ssai.api.brightcove.com/v1/accounts/{account_id}/ssai_debug_vmap/debug.xml
Headers Authorization: Bearer access_token (see Getting Access Tokens)
Content-Type: application/json
Sample Body
{
  "playback_config":{
    "name": "config_name",
    "vmap_response_namespace": "config_namespace",
    "account_id": "account_id",
    "ad_config": {
      "enable_ads": true,
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "round_up_cue_points": false,
      "template_url": {
      "template": "template_url"
      }
    },
    "extend_beacon_guard_ttl": false
  },
  "title_metadata":{
  "duration": "10s"
  },
  "videocloud_metadata": {
    "name": "ad_name",
    "tags": [ "tag1:tag1_value", "tag2:tag2_value" ],
    "ad_keys":"a=1&b=2",
    "cue_points": [{
      "name":"Pre-roll",
      "type":"AD",
      "time":0,
      "metadata":"type:pre-roll,a=b",
      },
      {
      "name":"Mid-roll",
      "type":"AD",
      "time":10,
      "metadata":"type=mid-roll,x=y",
    }]
  }
}

Response2

Sample response:

<vmap:VMAP xmlns:bc="bc" xmlns:vmap="http://www.iab.net/vmap-1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
<vmap:Extensions>
<bc:Brightcove ttl="1800" contenturi="https://ssaiplayback.us-east-1.qa.boltdns.net/playback/once/v1/hls/v5/clear/accoutn_debug/debug/debug/7592e9c3-214f-4c68-a576-1e2494b7be06/debug.m3u8" contentlength="10.0000" payloadlength="70.0000" contenttype="application/x-mpegURL"></bc:Brightcove>
<bc:BrightcoveDebug sessionID="7592e9c3-214f-4c68-a576-1e2494b7be06"></bc:BrightcoveDebug>
</vmap:Extensions>
<vmap:AdBreak breakType="linear" breakId="PreRoll_0_0" timeOffset="start">
<vmap:AdSource allowMultipleAds="true" followRedirects="true" id="0">
<vmap:VASTData>
  <VAST xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Ad id="test-01-30s">
      <InLine>
        <AdSystem>BIAS</AdSystem>
        <AdTitle>test-01-30s</AdTitle>
        <Creatives>
          <Creative>
            <Linear>
              <CreativeExtensions>
                <CreativeExtension>
                  <BrightcoveForeignKey>test-01-30s</BrightcoveForeignKey>
                </CreativeExtension>
              </CreativeExtensions>
              <Duration>00:00:30.0000</Duration>
              <TrackingEvents>
                <Tracking event="mute">https://solutions.brightcove.com/beacon?event=mute&amp;type=vast&amp;request_id=43a0e4a5-4420-11e8-b306-99b1b6ae5164&amp;parent_request_id=436ae081-4420-11e8-bd7f-41361f814644&amp;ad_id=test-01-30s</Tracking>
                <Tracking event="unmute">https://solutions.brightcove.com/beacon?event=unmute&amp;type=vast&amp;request_id=43a0e4a5-4420-11e8-b306-99b1b6ae5164&amp;parent_request_id=436ae081-4420-11e8-bd7f-41361f814644&amp;ad_id=test-01-30s</Tracking>
                <Tracking event="rewind">https://solutions.brightcove.com/beacon?event=rewind&amp;type=vast&amp;request_id=43a0e4a5-4420-11e8-b306-99b1b6ae5164&amp;parent_request_id=436ae081-4420-11e8-bd7f-41361f814644&amp;ad_id=test-01-30s</Tracking>
                <Tracking event="pause">https://solutions.brightcove.com/beacon?event=pause&amp;type=vast&amp;request_id=43a0e4a5-4420-11e8-b306-99b1b6ae5164&amp;parent_request_id=436ae081-4420-11e8-bd7f-41361f814644&amp;ad_id=test-01-30s</Tracking>
                <Tracking event="resume">https://solutions.brightcove.com/beacon?event=resume&amp;type=vast&amp;request_id=43a0e4a5-4420-11e8-b306-99b1b6ae5164&amp;parent_request_id=436ae081-4420-11e8-bd7f-41361f814644&amp;ad_id=test-01-30s</Tracking>
                <Tracking event="fullscreen">https://solutions.brightcove.com/beacon?event=fullscreen&amp;type=vast&amp;request_id=43a0e4a5-4420-11e8-b306-99b1b6ae5164&amp;parent_request_id=436ae081-4420-11e8-bd7f-41361f814644&amp;ad_id=test-01-30s</Tracking>
                <Tracking event="acceptInvitation">https://solutions.brightcove.com/beacon?event=acceptInvitation&amp;type=vast&amp;request_id=43a0e4a5-4420-11e8-b306-99b1b6ae5164&amp;parent_request_id=436ae081-4420-11e8-bd7f-41361f814644&amp;ad_id=test-01-30s</Tracking>
              </TrackingEvents>
              <VideoClicks>
                <ClickThrough id="clickthrough">https://www.brightcove.com/en/</ClickThrough>
                <ClickTracking id="43a0e4a5-4420-11e8-b306-99b1b6ae5164"></ClickTracking>
              </VideoClicks>
            </Linear>
          </Creative>
        </Creatives>
      </InLine>
    </Ad>
  </VAST>
</vmap:VASTData>
</vmap:AdSource>
</vmap:AdBreak>
...// additional ad breaks
</vmap:VMAP>

Tracing with a session id

The session_id specifies the caching session. Each session has its own length based on the video content length. You can get the id from the response for the API call in the previous step.

The Session id can be found in the VMAP response as follows:

<bc:BrightcoveDebug sessionID="your session id"></bc:BrightcoveDebug>

Request

To retrieve ad-call trace information by supplying a session id, use a GET request similar to the following:

Method GET
URL https://ssai.api.brightcove.com/v1/accounts/{account_id}/ssai_traces/{session_id}/ad_calls
Headers Authorization: Bearer access_token (see Getting Access Tokens)
Content-Type: application/json

Response

Sample response:

{
  "ad_calls": [
    {
      "timestamp": "2018-04-19T22:23:19.242732189Z",
      "duration_ms": 1020.477211,
      "request": {
        "content_length": 0,
        "event": "request",
        "headers": {
          "Referer": [
            ""
          ],
          "User-Agent": [
            "PostmanRuntime/7.1.1"
          ],
          "X-Device-User-Agent": [
            "PostmanRuntime/7.1.1"
          ],
          "X-Forwarded-For": [
            "63.150.45.170, 34.201.171.201"
          ]
        },
        "method": "GET",
        "url": "https://solutions.brightcove.com/ads?tech=dfpadrules&dur=30&pre=2"
      },
      "response": {
        "content_length": 421,
        "event": "response",
        "headers": {
          "Content-Length": [
            "421"
          ],
          "Content-Type": [
            "application/xml"
          ],
          "Date": [
            "Thu, 19 Apr 2018 22:23:19 GMT"
          ],
          "Via": [
            "1.1 0f3bddd6b971cf08b18fedb5c0a9f2f6.cloudfront.net (CloudFront)"
          ],
          "X-Amz-Apigw-Id": [
            "FnCBrHL8vHcFs1g="
          ],
          "X-Amz-Cf-Id": [
            "eTyxWuLiomnzqOTF02tLEu_P7nhCOF4j_k0ot03ApzWG3FsmscwUtg=="
          ],
          "X-Amzn-Requestid": [
            "436ae081-4420-11e8-bd7f-41361f814644"
          ],
          "X-Amzn-Trace-Id": [
            "sampled=0;root=1-5ad916d7-27fad540fa5ed98a891ac3fa"
          ],
          "X-Cache": [
            "Miss from cloudfront"
          ]
        },
        "status_code": 200
      },
        "body": "base64 encoded string from ad provider"",
        "creatives": [
          creative: {
           "event": "resolve",
           "foreign_key": "test-01-30s",
           "state": "active",
            "url": "https://solutions.brightcove.com/bcls/ads/bc-ads/bcls-ad-6-5seconds.mp4"
           }
        ]
        "errors": null
    },
    ...// additional ad calls
  ]
}

You can use a tool like BASE64 to make the response body readable.

Sample decoded response body:

<vmap:VMAP xmlns:vmap="http://www.iab.net/videosuite/vmap" version="1.0">

  <vmap:AdBreak timeOffset="start" breakType="linear" breakId="preroll">
    <vmap:AdSource id="preroll-ad" allowMultipleAds="false" followRedirects="true">
      <vmap:VASTAdData>
        <VAST version="3.0">
          <Ad id="1">
            <InLine>
              <AdSystem version="1.0">Test Ad Server</AdSystem>
              <AdTitle>
                <![CDATA[Portals]]>
              </AdTitle>
              <Description>
                <![CDATA[Demo ad number 6]]>
              </Description>
              <Error>
                <![CDATA[]]>
              </Error>
              <Creatives>
                <Creative>
                  <Linear>
                    <Duration>00:00:8</Duration>
                    <TrackingEvents/>
                    <AdParameters>
                      <![CDATA[<xml></xml>]]>
                    </AdParameters>
                    <VideoClicks/>
                    <MediaFiles>
                      <MediaFile type="video/mp4" width="1280" height="720" delivery="progressive" id="2" bitrate="4316" minBitrate="320" maxBitrate="320" scalable="true" maintainAspectRatio="true">
                        <![CDATA[http://solutions.brightcove.com/bcls/ads/bc-ads/bcls-ad-6-5seconds.mp4]]>
                      </MediaFile>
                    </MediaFiles>
                  </Linear>
                </Creative>
              </Creatives>
              <Extensions>
                <Extension>
                  <xml>data</xml>
                </Extension>
              </Extensions>
            </InLine>
          </Ad>
        </VAST>
      </vmap:VASTAdData>
    </vmap:AdSource>
  </vmap:AdBreak>
...