This page has moved - you will be directed to the new location in 3 seconds. Please update your bookmarks!

Video Cloud SSAI Ad Config API

In this topic, you will learn how to use the Server-Side Ad Insertion (SSAI) API to create and manage ad configurations.

Ad Configurations define various aspects of SSAI playback, including ad call(s), beacons, and other configuration options. An account can have multiple configurations and currently configurations can not be shared across accounts.

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:

  • SSAI data:

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

Manage ad configurations

The API supports the following GET and PUT requests:

List ad configurations

List the ad configurations defined for an account.

Method GET
URL https://ssai.api.brightcove.com/v1/accounts/your account id/ssai_configs
Headers Authorization: Bearer your access token
Content-Type: application/json

Sample response:

[
  {
    "name": "VMAP Ad Server",
    "vmap_response_namespace": "bc",
    "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
    "account_id": "57838016001",
    "created_timestamp": "2017-07-24T19:28:34.976878586Z",
    "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_config": {
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "template_url": {
          "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
      }
    }
  }
]

Create an ad configuration

Create an ad configuration for an account.

Method POST
URL https://ssai.api.brightcove.com/v1/accounts/your account id/ssai_configs
Headers Authorization: Bearer your access token
Content-Type: application/json

Sample Body:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_config": {
  	"expected_ad_response": "vast_3_0",
  	"disable_server_beacons": false,
    "round_up_cue_points": false,
  	"template_url": {
  		"template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
  	}
  },
  "discontinuities": {
    "hls": [ "*" ]
  }
}

Get ad configuration details

For an account, get the ad configuration details by config Id.

Method GET
URL https://ssai.api.brightcove.com/v1/accounts/your account id/ssai_configs/your ad config id
Headers Authorization: Bearer your access token
Content-Type: application/json

Sample response:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
  "account_id": "57838016001",
  "created_timestamp": "2017-07-24T19:28:34.976878586Z",
  "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
  "ad_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
        "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  },
  "beacon_templates": [
      {
        "type": "content_start",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "content_midpoint",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "ad_start",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "content_complete",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      }
    ],
    "discontinuities": {
      "dash": [
        "*"
      ],
      "hls": [
        "*"
      ]
    },
    "extend_beacon_guard_ttl": true
  }
}

Update an ad configuration

Update an ad configuration by config Id.

Method PUT
URL https://ssai.api.brightcove.com/v1/accounts/your account id/ssai_configs/your ad config id
Headers Authorization: Bearer your access token
Content-Type: application/json
Sample Body 
{
    "name": "VMAP Ad Server - updated"
}

Sample response:

{
  "name": "VMAP Ad Server - updated",
  "vmap_response_namespace": "bc",
  "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
  "account_id": "57838016001",
  "created_timestamp": "2017-07-24T19:28:34.976878586Z",
  "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
  "ad_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
      "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  }
}

Configuration field details

This table defines the ad configuration fields used within the body section of a request.

Field Type Description
name String Human readable name
vmap_response_namespace String Adjusts the VMAP output to use the legacy Unicorn Once namespace format or to use the new Brightcove namespace format.

Values: uo, bc Default: bc
description String Human readable description
ad_config.expected_ad_response String Which tech to use to parse the response. [1]

Values:
  • dfp_ad_rules
  • dfp_vmap
  • smart_xml
  • vast_3_0
ad_config.disable_server_beacons Boolean Flags whether to disable the server side firing of ad impressions/beacons

When set to true, SSAI will not fire any beacons server-side and will include all beacons in the VMAP output

When set to false, SSAI will fire the beacons it is able to server-side and include any it is not able to in the VMAP output
ad_config.round_up_cue_points Boolean Flags whether to round up to the next keyframe when choosing a nearby position for inserting ads.

Default: false, which chooses the closest keyframe to the desired ad position.
ad_config.template_url.template String Ad tag template. Available variables described in a later section.
ad_config.template_url.defaults Object Map of String to String defining the default to use in the case where a url param is not provided.

Can be a literal { "url.foo": "SomeString" }

Or reference another variable { "url.foo": "{{ metadata.title_id }}" }
discontinuities.dash [2] []String Controls which versions of dash to deliver Multi Period Dash manifests.

Set to ["*"] to deliver multi-period dash for all versions

Empty list for never

Example: ["live-timeline"] to deliver for live-timeline but not for hbbtv
discontinuities.hls [2] []String Controls which versions of hls to deliver with discontinuities.

Set to ["*"] to delivery with discontinuities in all versions of HLS

Empty list for never

Example: ["v4","v5"] to deliver for v4 & v5 but not for v3
beacon_templates Array An array of beacons to fire (example: 3rd-party beacons)
beacon_templates[].type String

Type of beacon to fire. Values:

  • content_start
  • content_first_quartile
  • content_midpoint
  • content_third_quartile
  • content_complete
  • content_quartiles
  • content_interval
  • ad_start
  • ad_first_quartile
  • ad_midpoint
  • ad_third_quartile
  • ad_complete
  • ad_quartiles
  • ad_break_start
  • ad_break_end
  • segment_start
  • segment_end
  • on_load
beacon_templates[].template_url.template String Beacon URL template
extend_beacon_guard_ttl Boolean Sets the length of the Beacon Guard TTL (Time to live) to the length of the Content’s Session TTL. Otherwise, the default is 1 minute.

Ad variables

Variables in the template url are identified by double curly braces ({{ … }}) with optional whitespace before and after the variable path. All variables are prefixed by one of three namespaces:

System variables

System variables are provided by the SSAI system and can be information about the end user or helper variables to generate random values. The values must be URI-encoded before being inserted into the URL templates.

System variables are identified as: {{system.*}}

Field Description
ip_address End User's IP Address
random_number_32 Random 32-bit integer
random_guid Random UUID
referer End User's Referer header value
timestamp_utc Current time as a unix timestamp
unique_user_id MD5(ip_address + user_agent)
unix_timestamp Current time as a unix timestamp (seconds)
user_agent End User's User-Agent header value
uuid Random uuid
x_forwarded_for End User's X-Forwarded-For header value
xfp.correlator Random 64-bit Integer
xfp.ip_address End User's IP Address
xfp.unique_user_id MD5(ip_address + user_agent)
xfp.scor Random 64-bit Integer

URL variables

Query Params provided on the entry point VMAP/Manifest are available under the url namespace. Unlike variables under other namespaces, these params are not url encoded when inserting into the template. If variable values need to be url encoded going to the ad provider, they will need to be double url encoded on the entry point url.

URL variables are identified as: {{url.*}}

Metadata variables

Metadata variables are those that describe the content video, derived from both Video Cloud and Dynamic Delivery data sources. The values are URL encoded before being inserted into the URL templates.

Metadata variables are identified as: {{metadata.*}}

Field Description
ad_keys Free form text string that can be added and edited in the Video Cloud Studio Media module
custom_fields.{field_name} Video Cloud custom fields
long_description Video Cloud long description
name Video Cloud video name
reference_id Video Cloud reference id
tags Comma separated list of the Video Cloud tags for the video
title.duration Duration of the content in seconds
title.id Dynamic Delivery title id
title.name Dynamic Delivery title name
video_id Video Cloud video id
Other Video Cloud key/value pairs would be here as well

Entrypoint URL parameters

There are a handful of query parameters that can be added to the SSAI entry point URL (VMAP or manifest) in order to tweak some behaviors:

Parameter Description
?rule=sd-only Filters out any video rendition that has a height less than the threshold set in the Account Configuration
?rule=discos-enabled Enable Playback with Discontinuities in HLS & MultiPeriods in Dash. Takes precedence over discontinuities setting in Playback Config
?rule=discos-disabled Disable Playback with Discontinuities in HLS & MultiPeriods in Dash. Takes precedence over discontinuities setting in Playback Config

Configuration notes

  1. Preloading ads should not be done with SSAI. The reason for this is that if you preload the player will report an ad impression and probably the first quartile beacons before the video is played. This could lead to inaccurate ad analytics. If you configure SSAI in Studio, this will automatically be done, but if you happen to setup SSAI manually you need to be aware of this issue.
  2. If the web player is using SSAI, and one of your motivations for doing so is to work around ad blockers, you should use server-side beacons. Client-side beacons should not be used as they will be blocked.

Client-side macros

Use the page prefix when you want to use client-side ad macros. These macros enable you to use variables in the VMAP and server URLs. For ad macro details, see the Ad macros and the serverURL section of the Advertising with the IMA3 Plugin document.

Client-side macros are prefixed with: {{page.*}}

For example, to add the document.referrer and a pageVariable DOM window variable, you would prefix them with page in the ad template as follows:

https://adserver.com/{{page.document.referrer}}/{{page.pageVariable.whateverIwant}}

The Playback API returns document.referrer and pageVariable.whateverIwant appended to the VMAP and SRC URLs. The Brightcove player then runs through its client-side macro replacement logic to replace the appropriate values, before sending the request:

https://bolt-prefix/blah.vmap?document.referrer={document.referrer}&pageVariable.whateverIwant={pageVariable.whateverIwant}

Ad error beacons

VAST ad error beacons when using SSAI can be helpful for proactively finding and fixing problems with your ad workflow. For details, see the Ad Error Beacons with SSAI document.