Live API: Server-Side Ad Insertion (SSAI)

Product(s)
Live
SSAI
Role(s)
API Developer
Topic(s)
Live Streaming
SSAI
API(s)
Live API

This topic shows you how to set up server-side ad insertion (SSAI) for your live stream jobs.

Overview

SSAI allows you display ads during a live streaming event at specified times. Here are the main features of SSAI:

  • Since ads are stitched into the live stream on the server side, they are not affected by ad blockers
  • Ads are inserted at cue points sent from your encoder or you can create an instant cue point using the Live API
  • You can ingest "slate" assets to fill any unused ad time

Note that much of the SSAI setup can be managed in Studio as well.

Headers

The following headers are required with API requests:

x-api-key: APIKEY-HERE
Content-Type: application/json

Ad configuration variables

The following table provides a summary of ad configuration variables, which are used in the requests to manage ad configurations detailed in the sections that follow.

Ad Configuration Variables
Variable
Description
session.session_id
unique session id
job.job_id
unique job id
application_ad_configuration.description
value of the application at session creation
random.int32
random 32-bit signed integer
random.int64
random 64-bit signed integer
random.uint32
random 32-bit unsigned integer
random.uint64
random 64-bit unsigned integer
random.uuid
random uuid
server.timestamputc
epoch time in milliseconds when the call from the ads-api has been made
client.useragent
http user-agent header value at session creation
client.ipaddress
http x-forwarded-for header value at session creation, if provided, otherwise the remote address
client.referrer
http referer header value at session creation (note: that is the correct spelling)
client.referer
http referer header value at session creation (http spelling)
client.ipuaid
hash value of client.ipaddress and client.useragent
live.adbreak
(currently unused)
live.adbreakdurationms
Ad break duration in milliseconds
live.adbreakduration
Ad break duration in double-precision floating-point seconds
live.adbreakdurationint
Ad break duration in integer seconds
live.adbreak.timestamputc.wallclock
epoch time in milliseconds when the call to the ads server has been made
live.adbreak.timestamputc.origin
epoch time in milliseconds from the origin chunklist. This value indicates the time when the cue out chunk has been created in the origin chunklist.
live.adbreak.timestamputc.session
epoch time in milliseconds from the ssai chunklist. This value indicates the time of the cue out chunk in the ssai chunklist. Since the adbreak content and the adbreak gap are NOT usually the same, after the 1st adbreak the live.adbreak.timestamputc.origin is different from live.adbreak.timestamputc.session . This value takes into account the time adjustments that have been made in the SSAI chunklist.

Targeting using query strings (URL parameters)

Your ad tag, entered in the ad configuration (see Create ad configurations below) will typically look something like this:

The items inside the double curly braces are variables, also called ad macros, which Live will replace with values, if they exist, when it sends the ad request.

These values can be supplied in three ways:

  • Header information, detailed in the Ad configuration variables above, is available for any request - you simply need to specify which ones you want with the appropriate key names in your ad configuration.
  • Additional session values can be appended to the URL for the live stream, like this:
    http://playback.bcovlive.io/e058d9f2737e18/us-west-2/NA/playlist.m3u8?deviceid=123456&sitesection=services"
    
    

    Note that the key names in this example correspond to the variable names in the ad tag shown above.

  • Values for specific ad breaks can be sent with the Manual cue point insertion request (discussed below).

Custom headers for ad requests

The SSAI platform can pass custom header with the Ad calls and all beacons used by the backend platform. Some ad servers such as VideoPlaza require custom headers. Custom headers are specified as a set of key-value pairs in an ad_configuration_headers object that is part of the application_ad_configuration (see the next section on creating an ad configuration).

Notes

  • Standard headers are handled by default such as:
    • X-Forwarded-For
    • X-Device-User-Agent
  • Header values can use the ad configuration variables
  • Header values can also be static strings

Create an ad configuration

To create a new ad configuration, send a POST request to:

https://api.bcovlive.io/v1/ssai/applications

Sample request body

{
  "application_ad_configuration": {
    "ad_configuration_description": "Human readable description of the configuration",
    "ad_configuration_expected_response_type": "Dfp or Vast or SmartXML",
    "ad_configuration_headers": {
    "X-Custom-Header-Rand": "{{random.int32}}",
    "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
    },
    "ad_configuration_headers_for_impressions": false,
    "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
    "ad_configuration_transforms": [
      {
      "xpath": "/",
      "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
      }
    ],
    "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
  },
  "application_description": "Human readable description of the ad application",
  "account_id": "USER'S ACCOUNT ID" [Optional - When omitted, Account ID of requesting user is used]
}

Sample response

{
  "application": {
    "account_id": "USER ACCOUNT ID",
    "application_description": "Human readable description of the ad application",
    "application_ad_configuration": {
      "ad_configuration_description": "Human readable description of the configuration",
      "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
      "ad_configuration_headers": {
        "X-Custom-Header-Rand": "{{random.int32}}",
        "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
      },
      "ad_configuration_headers_for_impressions": false,
      "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
      "ad_configuration_transforms": [
        {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
        }
      ],
      "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
    },
    "application_id": "APPLICATION ID"
  },
  "inserted": true
}

Update an ad configuration

Updating an ad configuration is very similar to creating one. Make a PUT request to:

https://api.bcovlive.io/v1/ssai/applications/application/APPLICATION_ID

Sample request body

{
  "application_ad_configuration": {
    "ad_configuration_description": "Some Updated Description Value",
    "ad_configuration_expected_response_type": "Dfp or Vast or SmartXML,
    "ad_configuration_headers": {
      "X-Custom-Header-Rand": "{{random.int32}}",
      "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
    },
    "ad_configuration_headers_for_impressions": false,
    "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
    "ad_configuration_transforms": [
      {
      "xpath": "/",
      "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
      }
    ],
    "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
  },
  "application_description": "Human readable description of the ad application",
  "account_id": "USER'S ACCOUNT ID" [Optional - When omitted, Account ID of requesting user is used]
}

Sample response

{
  "account_id": "USER ACCOUNT ID",
  "application_description": "Human readable description of the ad application",
  "application_ad_configuration": {
    "ad_configuration_description": "Some Updated Description Value",
    "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
    "ad_configuration_headers": {
    "X-Custom-Header-Rand": "{{random.int32}}",
    "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
    },
    "ad_configuration_headers_for_impressions": false,
    "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
    "ad_configuration_transforms": [
      {
      "xpath": "/",
      "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
      }
    ],
    "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
  },
  "application_id": "APPLICATION ID"
}

Get all ad configurations

To retrieve all the ad configurations for an account, submit a GET request to:

https://api.bcovlive.io/v1/ssai/applications/account/account_id

Sample response

[
  {
    "application_id": "APPLICATION_ID_1",
    "application_description": "DFP Single Midroll",
    "application_ad_configuration": {
    "ad_configuration_description": "DFP Test Config Single Midroll",
    "ad_configuration_strategy": "MultipleAdResponse",
    "ad_configuration_transforms": [],
    "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler",
    "ad_configuration_expected_response_type": "Dfp"
    },
    "account_id": "ACCOUNT_ID"
  },
  {
    "application_id": "APPLICATION_ID_2",
    "application_description": "Test DFP Single Midroll"
    "application_ad_configuration": {
    "ad_configuration_description": "DFP Test Config Single Midroll",
    "ad_configuration_strategy": "MultipleAdResponse",
    "ad_configuration_transforms": [
    {
      "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
      "xpath": "/"
    }
    ],
    "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
    "ad_configuration_expected_response_type": "Dfp"
    },
    "account_id": "ACCOUNT_ID"
  }
]

Get an ad configuration

You can also retrieve a specific ad configuration by its application_id by sending GET request to:

https://api.bcovlive.io/v1/ssai/applications/application/APPLICATION_ID

Sample response

{
  "application_id": "APPLICATION_ID",
  "application_description": "Test DFP Single Midroll",
  "application_ad_configuration": {
    "ad_configuration_description": "DFP Test Config Single Midroll",
    "ad_configuration_strategy": "MultipleAdResponse",
    "ad_configuration_transforms": [
      {
      "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
      "xpath": "/"
      }
    ],
    "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
    "ad_configuration_expected_response_type": "Dfp"
  },
  "account_id": "ACCOUNT_ID"
}

Delete an ad configuration

To delete an ad configuration, send a DELETE request to:

https://api.bcovlive.io/v1/ssai/applications/application/APPLICATION_ID

Sample response

{
"application_id": "APPLICATION_ID",
"deleted": true
}

Cuepoints

Ad breaks are triggered by cuepoints, which can be specified in two ways:

  • Sent to Brightcove by the encoder
  • Immediate cuepoints created via the Live API

From the encoder

The Brightcove live delivery system can interpret cuepoints submitted by the encoder in the AMF format:

AMFDataList
[0]:onCuePoint
[1]:{Obj[]:
time: 1.9889, //Difference from PTS of THIS packet to the first PTS of the 1st video frame in the adbreak
name: "scte35",
type: "event",
ad_server_data: "YWJjZGVmZ2g=",	// optional introduced by Brightcove. It is a base64 encoded json map of parameters e.g. {‘key’:’value’}
parameters: {Obj[]:
type: "avail_in",
duration: 12.0}}

Note that only avail_in type cuepoints are currently supported.

Manual cue point insertion

You can also create immediate cuepoints using the Live API by sending a POST request to:

https://api.bcovlive.io/v1/jobs/JOB_ID/cuepoint

Include a request body specifying the duration of the break in seconds and, optionally, a timecode in SMPTE format (HH:MM:SS:FF) to specify when a set of any variables (key/value pairs) should be passed to the adServer.

Note that the duration of the cue point being inserted needs to be at least twice the length of the segments in the job. For example, if inserting a 10 second cue point in a job with "segment_seconds"=4, it will work fine. However, inserting the same cue point in a job with "segment_seconds"=6 will result in the error below:

"error": "The parameter duration should be greater than
  or equal to (2 * target duration) of the job"

Sample request body

{
  "duration": 30,
  "timecode": "15:50:49:16",
  "ad_server_data" : {
  "adbreakid": 12312
  "breaktheme": "fitness"
  }
}

Notes

  1. The timecode format is HH:MM:SS:FF (FF = frames), and it is optional; if omitted, the cuepoint will be inserted immediately.
  2. If you use the timecode property, the encoder must be sending SMPTE-formatted (HH:MM:SS:FF) timecode stored in the tc property via OnFI. Timecodes are from the start of the live stream.
  3. Software encoders such as Wirecast and OBS do not support the sending timecode via `OnFI` packets in the RTMP stream
  4. Elemental hardware encoders do support the sending timecode via `OnFI` packets in the RTMP stream
  5. The ad_server_data is also optional, and what key/value pairs you pass will depend on the ad server you are using - see your ad server documentation and the Targeting section above for more details.

Sample response

{
  "id": "JOB_ID",
  "cue_point": {
    "id": "adBreak-2f58393ada1442d98eca0817fa565ba4",
    "duration": 30,
    "accuracy": "segment", [Can be segment or frame  ]
    "inserted_at": "2017-07-21T09:30:46.307Z" [ Time when the cue point was inserted in the stream]
  },
}

Managing slates

Slates are your own assets used to fill unused ad time. You can use slates to provide a "be right back" message or any content that you like.

Below are details of the API requests to add and manage slate assets.

Ingest slate media source asset

To add a new slate asset, submit a POST request to:

https://api.bcovlive.io/v1/ssai/slates

Sample request body

{
"source_url": "https://somesourceasset.com/slate-to-ingest.mp4",
"account_id": "ACCOUNT_ID", [Optional - When omitted, Account ID of the requesting user is used.
"source_description": "User identifiable description for the slate" [Optional]
}

Sample response

{
"media_source_asset_id": "NEW_UUID",
"account_id": "ACCOUNT_ID",
"media_source_asset_default": false,
"media_source_asset_type": "slate",
"media_source_asset_url": "https://somesourceasset.com/slate-to-ingest.mp4",
"media_source_asset_status": "transcoding"
"media_source_asset_description": "User identifiable description for the slate"
}

Delete slate media source asset

To delete a slate media asset, send a DELETE request to:

https://api.bcovlive.io/v1/ssai/slates/slate/SLATE_MSA_ID

Sample response

{
"media_source_asset_id": "MSA_UUID",
"media_source_asset_type": "slate",
"media_source_asset_url": "http://someS3urlpath/media.mp4",
"media_source_asset_default": false,
"media_source_asset_status": "ready",
"account_id": "ACCOUNT_ID"
}

Get slate media source assets

You can retrieve an array of all the slate assets for an account by sending a GET request to:

https://api.bcovlive.io/v1/ssai/slates/account/account_id

Sample response

[
{
"media_source_asset_id": "MSA_UUID_1",
"media_source_asset_type": "slate",
"media_source_asset_default": false,
"media_source_asset_url": "http://someS3urlpath.com/media.mp4",
"account_id": "ACCOUNT_ID",
"media_source_asset_status": "ready"
},
{
"media_source_asset_id": "MSA_UUID_2",
"media_source_asset_type": "slate",
"media_source_asset_default": true,
"media_source_asset_url": "http://someS3urlpath.com/media.mp4",
"account_id": "ACCOUNT_ID",
"media_source_asset_status": "ready"
}
]

Beacons

Beacons are data points on playback sent to third-party analytics to track whether and how much of ads were played. In this section we will look at the beacon types that can be set using the Live API, and variables that can be used to provide the data. The next section will detail the API requests use to create and manage beacon sets.

Beacon types

Beacon Types
Beacon Type Description
Load Fired once per session and only triggered when top level manifest is requested
Play Content has been requested and the first segment returned
Heartbeat Target duration (segment seconds)
AdStart Individual ad started
AdFirstQuartile First ad quartile (25%)
AdMidpoint Second ad quartile (50%)
AdThirdQuartile Third ad quartile (75%)
AdComplete Individual ad completed
AdBreakStart Ad break has started
AdBreakComplete ad break has ended

Valid beacon variables

The table below shows the variables you can use to provide data for the beacon URLs. To include a variable, surround with double curly braces, like this: {{job.job_id}} . See the next section on managing beacon sets for full examples.

Beacon Variables
Variable
Description
session.session_id
unique session id
job.job_id
unique job id
application_ad_configuration.description
description value of the application at session creation
random.int32
random 32-bit signed integer
random.int64
random 64-bit signed integer
random.uint32
random 32-bit unsigned integer
random.uint64
random 64-bit unsigned integer
random.uuid
random uuid
server.timestamputc
epoch time in milliseconds when the call from the ads-api has been made
client.useragene
http user-agent header value at session creation
client.ipaddress
http x-forwarded-for header value at session creation, if provided, otherwise the remote address
client.referrer
http referer header value at session creation (correct spelling)
client.referer
http referer header value at session creation (http spelling)
live.adbreak
(currently unused)
live.adbreakduration
double-precision floating-point value in seconds
live.adbreakdurationint
integer value in seconds

Manage beacon sets

This section provides details on the API requests to manage beacon sets. See the previous section for beacon types and variables.

To add a beacon set to a Live job, first create the beacon set, and then include the id when you create the job, like this:

{
"live_stream": true,
"region": "us-west-2",
"reconnect_time": 30,
"ad_insertion": true,
"beacon_set": "beacon_set_id", ...

Create a beacon set

To create a beacon set, send a POST request to:

https://api.bcovlive.io/v1/ssai/beaconsets

Sample request body

{
"account_id": "USER's ACCOUNT ID", [Optional - If omitted, the Account ID of the requesting user is used.]
"beacon_urls": [
{
"beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
"beacon_type": "Load"
},
{
"beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
"beacon_type": "Play"
}
]
}

Sample response

{
"beacon_set": {
"beacon_urls": [{
"beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
"beacon_type": "Load"
},
{
"beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
"beacon_type": "Play"
}],
"beacon_set_id": "Inserted Beacon Set ID",
"account_id": "USER's ACCOUNT ID"
}
"inserted": true
}

Update a beacon set

Updating a beacon set is similar to creating one. Submit a PUT request to:

https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/BEACON_SET_ID

Sample request body

{
  "account_id": "USER's ACCOUNT ID", [OPTIONAL - If omitted, the account id of the requesting user is used.],
  "beacon_urls": [
    {
    "beacon_url": "https://myserver.com/beaconRX/load",
    "beacon_type": "Load"
    },
    {
    "beacon_url": "https://myserver.com/beaconRX/play",
    "beacon_type": "Play"
    }
  ]
}

Sample response

{
  "beacon_set": {
    "account_id": "USER's ACCOUNT ID",
    "beacon_set_id": "BEACON_SET_ID",
    "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX/play",
      "beacon_type": "Play"
    }],
    "updated_beacon_set": {
      "beacon_set_id": "BEACON_SET_ID",
      "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
      },
      {
        "beacon_url": "https://myserver.com/beaconRX/play",
        "beacon_type": "Play"
      }],
      "account_id": "USER's ACCOUNT ID"
    }
  }
}

Get beacon sets

To retrieve the beacon sets for an account, submit a GET request to:

https://api.bcovlive.io/v1/ssai/beaconsets/account/account_id

Sample response

[{
    "account_id": "USER's ACCOUNT ID",
    "beacon_set_id": "BEACON_SET_ID_1",
    "beacon_urls": [{
    "beacon_url": "https://myserver.com/beaconRX/load",
    "beacon_type": "Load"
  }]
  },
  {
    "account_id": "USER's ACCOUNT ID",
    "beacon_set_id": "BEACON_SET_ID_2",
    "beacon_urls": [{
    "beacon_url": "https://myserver.com/beaconRX2/load",
    "beacon_type": "Load"
    },
    {
    "beacon_url": "https://myserver.com/beaconRX2/play",
    "beacon_type": "Play"
    }]
}]

Get beacon sets for requesting user

You can also get the beacon sets for the account of the requesting user without including the account id in the request URL:

https://api.bcovlive.io/v1/ssai/beaconsets

Sample response

[{
    "account_id": "USER's ACCOUNT ID",
    "beacon_set_id": "BEACON_SET_ID_1",
    "beacon_urls": [{
      "beacon_type": "Load",
      "beacon_url": "https://myserver.com/beaconRX/load"
    }]
  },
  {
    "account_id": "USER's ACCOUNT ID",
    "beacon_set_id": "BEACON_SET_ID_2",
    "beacon_urls": [{
    "beacon_type": "Load",
    "beacon_url": "https://myserver.com/beaconRX2/load"
  },
  {
    "beacon_type": "Play",
    "beacon_url": "https://myserver.com/beaconRX2/play"
  }]
}]

Get a beacon set by id

To retrieve a single beacon set by its id, submit a GET request to:

https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/BEACON_SET_ID

Sample response

{
    "account_id": "USER_ACCOUNT_ID",
    "beacon_set_id": "BEACON_SET_ID",
    "beacon_urls": [{
      "beacon_type": "Load",
      "beacon_url": "https://myserver.com/beaconRX2/load"
  },
  {
    "beacon_type": "Play",
    "beacon_url": "https://myserver.com/beaconRX2/play"
  }]
}

Delete a beacon set

Finally, to delete a beacon set, send a DELETE request to:

https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/BEACON_SET_ID

Sample response

The response will look like this:

{
"beacon_set_id": "BEACON_SET_ID",
"deleted": true
}

Notes on DFP

If you are obtaining ads from DFP, here are some things to keep in mind to help prevent issues.

Ad tag

When you are creating an ad tag for Live, be sure you are following the proper guidelines and including /live . See the DFP document Create a master video tag manually for full details.

Concurrency

If you are expecting a high amount of concurrency we recommended that you talk to your DFP account team.

Single/multiple ad responses

The singleadresponse and multiadresponse parameters are not currently used by SSAI.

Live SSAI only makes a single ad server call and expects that the response will contain all the ads for the break with the exception that it will follow any necessary ad wrappers with a limit of 5 redirects per ad. The following ad response formats are accepted and will be parsed as follows:

  • VAST - Single response or a pod of ads in a single response
  • DFP Ad Rules - Aggregates all available ads in the response including pre-, mid-, post-roll defined ads
  • Smart XML - Aggregates all available ads in the response including pre-, mid-, post-roll defined ads

Known issues

  • SSAI requires that the live streaming video have an audio track.
  • If the VAST returned has the same ad ID, then the server will not request the ad content, even though the ad URL uses dynamic variables to make it a unique URL. This does not apply if you are using DFP for ads.
  • If an ad break has a duration less than the MAX duration of the ad URL (min_ad_duration=0&max_ad_duration=30000), if ad is returned longer than the ad break, the ad will not be played.

  • VPAID or clickable ads are not supported for Brightcove Live SSAI.

  • When an ad break has remaining time shorter than the segment seconds of the stream and a slate is displayed, the slate is displayed for its segment duration and the actual ad break will be longer than expected.

Appendix

Below is a screenshot to show a sample cue point setup for the Elemental encoder.

Elemental Cue Point Setup
Elemental Cue Point Setup