Video Cloud SSAI API

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 cannot 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 Authentication for Brightcove API Requests.

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
• Create an ad configuration
• Get ad configuration details
• Update an ad configuration

List ad configurations

List the ad configurations defined for an account.

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": "https://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 }}"
      }
    }
  }
]

For field definitions, see the Configuration field details section.

Create an ad configuration

Create an ad configuration for an account.

Sample Body:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_tracking_sample_percentage": 100,
  "ad_config": {
    "expected_ad_response": "vast_3_0",
    "disable_server_beacons": false,
    "round_up_cue_points": false,
    "template_url": {
      "template": "https://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": [ "*" ]
  }
}

For field definitions, see the Configuration field details section.

Notes

• ad_tracking_sample_percentage determines the percentage of sessions that will be logged. It can any value from 0 (disable logging) to 100 (log all sessions).

Get ad configuration details

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

  {
    "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_tracking_sample_percentage": 100,
    "ad_config": {
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "template_url": {
          "template": "https://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
    }
  }

For field definitions, see the Configuration field details section.

Update an ad configuration

Update an ad configuration by config Id.

{
    "name": "VMAP Ad Server - updated"
}

  {
    "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": "https://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 }}"
      }
    }
  }

For field definitions, see the Configuration field details section.

Configuration field details

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

Ad response types

Here is some additional information about working with ad_config.expected_ad_response types from the table above. Values:

• vast_3_0 - Digital Video Ad Serving Template (VAST)
• dfp_vmap - Video Multiple Ad Playlist (VMAP)
• dfp_ad_rules - Proprietary format for Google DFP, which has been rebranded as Google Ad Manager(GAM)
• smart_xml - Proprietary format for FreeWheel

Process flow

When creating SSAI ad configurations, keep in mind the following process notes:

VMAP

If SSAI Config's Ad Response Type is DFP VMAP:

• Any cue points configured with a video will be ignored.
• SSAI parses the VMAP XML file from the ad provider which contains all the ads with their defined positions.

VAST

If SSAI Config's Ad Response Type is VAST 3.0:

• Define cue points in your video. SSAI will make requests for each cue point in the video to construct ad breaks.
• If no cue point is configured with a video, a preroll ad is inserted by default.

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
• url
• metadata

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.*}}

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.*}}

URL variables are added to the VMAP urls using custom integration as follows:

1. Add {{url.*}} macro variables to the ad tag for a specific server-side ad config. For example:

   https://general.support.brightcove.com/assets/ads/vmap/simple-vmap.xml?foo={{url.foo}}&bar={{url.bar}}

2. Configure a player with the SSAI plugin and the ad configuration containing the ad tag with macros.
3. Pass a vmapURLParams options object to the SSAI plugin containing the variable names and values to replace:

   "options": {
     "vmapURLParams": {
       "foo": 123,
       "bar": "test"
     }
   }

4. Brightcove player with SSAI plugin (v2.4.6+) calls to retrieve the VMAP URL from Playback API and then automatically appends the values of the variables before sending the request.

Metadata variables

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

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

Brightcove Ad Monetization

At minimum, a Brightcove Ad Monetization ad config using SpringServe will include the following macros when used with the Brightcove Web Player. For SDK and other implementations, values should be passed programmatically in-app instead of using the web player macros listed below.

Privacy

To add the privacy-related macros to your ad tag, your implementation needs to collect the data from users and pass them to the player or application at runtime. With a standard web player implementation, each variable is defined as a global JavaScript variable with the same name within the page or app, allowing the player to access them and send them to the ad server when it makes ad requests.

If the variables are named differently within your page or app, ensure that the relevant macro name (pageVariable.macro_name) is updated to match. For example, you could define each variable within a <script> tag at the top of your page like this:

var my_gdpr_variable = true;

The player will then be able to retrieve the gdpr value of true via {pageVariable.my_gdpr_variable} and pass it through to the SSAI system.

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:

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.