Implementing Player Enhancements for Live SSAI

In this topic, you will learn how to create a live stream with server-side ads that utilizes Player Enhancements for Live SSAI for an improved user experience.

Introduction

Brightcove's Player Enhancements for Live SSAI allows you to improve the ad breaks in live streams with ad counts, ad countdown timers, click through ads and companion ads.

Your ad information is specified using an ad configuration which retrieves VAST responses to identify what ads to display. The VAST file also contains information about companion ads and beacon URLs.

Workflow

To create a live stream with SSAI and player enhancements, follow these steps:

Ask your account manager to enable your account for Live streams, Server-Side Ad Insertion (SSAI) and the Player Enhancements for Live SSAI.
Create an ad configuration
Optional: Create slate assets to fill unused ad time
Create a live job
Create the playback token
Configure the player
Begin streaming
Trigger ads using cue points (this can be done before or during the live event)
Cleanup

Create an ad configuration

An ad configuration defines the information needed to include server-side ads with a live stream. This includes ad provider URL, expected ad response type and whether beacons should be sent.

To create a new ad configuration, send a POST request as follows:

Method	`POST`
URL	`https://api.bcovlive.io/v1/ssai/applications`
Header	`X-API-KEY: your API KEY`
Header	Content-Type: application/json

All requests are authenticated using an API key that is provided to you when your account is set up. The key is passed in the X-API-KEY header.

Request body

For details about the request body fields, see the Live API Reference document.

With Player Enhancements for Live SSAI, the highlighted fields can be set inside of the application_ad_configuration object.

Sample request body:

{
  "application_ad_configuration": {
	"ad_configuration_description": "your ad config description",
    "ad_configuration_expected_response_type": "Vast",
	"ad_configuration_headers_for_impressions": false,
	"ad_configuration_strategy": "SingleAdResponse",
	"ad_configuration_transforms": [],
	"ad_configuration_url_format": "your ad server",
    "ad_configuration_client_sdk_enabled": true,
    "client_options": {
      "show_ad_break_remaining_time": true / false,
      "show_ad_remaining_time": true / false,
      "show_number_of_remaining_ads": true / false,
      "client_only_tracking": true / false
    }
  },
  "application_description": "your application description"
}

Here are the ad configuration fields related to Player Enhancements with Live SSAI:

Field	Type	Required	Description
`ad_configuration_expected_response_type`	String	Yes	For this feature, ad configurations MUST have a value of `Vast`
`ad_configuration_client_sdk_enabled`	Boolean	Yes	To enable this feature, this field must have a value of `true`
`client_options`	Object		An object of fields related to Player Enhancements
`client_options. show_ad_break_remaining_time`	Boolean		Display time remaining for an ad break Values: `true`/`false`
`client_options. show_ad_remaining_time`	Boolean		Display time remaining for an ad Values: `true`/`false`
`client_options. show_number_of_remaining_ads`	Boolean		Display the number of ads remaining in the ad break Values: `true`/`false`
`client_options. client_only_tracking`	Boolean		Disable server-side tracking events (impressions/quartiles) Values: `true`/`false` Default: `false` When `true`, our normal processing of ad impressions is bypassed, and they’re instead fired by the client. This makes the impressions more accurate/timely but, we no longer have visibility into the tracking events. Client-side ads can also be blocked by certain ad blockers.

All of the client_options fields are optional. Only client_only_tracking has a default value of false.

Response

Sample response:

{
  "application": {
    "application_description": "Test ad configuration",
    "application_ad_configuration": {
    "ad_configuration_description": "Ad config description",
    "ad_configuration_expected_response_type": "Vast",
    "ad_configuration_strategy": "SingleAdResponse",
    "ad_configuration_transforms": [],
    "ad_configuration_url_format": "https://solutions.brightcove.com/bcls/ads/simple-vast.xml",
    "ad_configuration_headers_for_impressions": false,
    "ad_configuration_client_sdk_enabled": true,
    "client_options": {
      "show_ad_break_remaining_time": true,
      "show_ad_remaining_time": true,
      "show_number_of_remaining_ads": true,
      "client_only_tracking": true
    }
    },
    "application_id": "1234567890abcdefghijkl",
    "application_type": "ads",
    "account_id": "001122334455aabbccddee"
  },
  "action": "inserted"
}

After you successfully create an ad configuration, copy the application_id (ad configuration id) that was generated. You will need this later to find the SSAI playback URL.

To list, update and delete ad configurations, see the Manage ad configurations document

Create a live job

To create a live job, send a POST request as follows:

Method	`POST`
URL	`https://api.bcovlive.io/v1/jobs`
Headers	`X-API-KEY: your API KEY`
Headers	Content-Type: application/json

Request body

For details about the request body fields, see the Live API Reference document.

For a live job with SSAI enabled, set ad_insertion: true in your HTTP request body.

Sample request (Video Cloud video)

To create a Video Cloud video to use for your live stream, and to create VOD clips from the live stream, include the videocloud object in the request body. For details, see the Live API: Creating VOD Clips document.

The highlighted field below is needed for server-side ad insertion (SSAI).

{
  "live_stream": true,
  "ad_insertion": true,
  "region": "us-west-2",
  "reconnect_time": 1800,
  "outputs": [{
      "label": "hls720p",
      "live_stream": true,
      "width": 1280,
      "height": 720,
      "video_codec": "h264",
      "h264_profile": "high",
      "video_bitrate": 2100,
      "segment_seconds": 4,
      "keyframe_interval": 60
    },
    {
      "label": "hls540p",
      "live_stream": true,
      "width": 960,
      "height": 540,
      "video_codec": "h264",
      "h264_profile": "main",
      "video_bitrate": 1500,
      "segment_seconds": 4,
      "keyframe_interval": 60
    },
    {
      "label": "hls360p",
      "live_stream": true,
      "width": 640,
      "height": 360,
      "video_codec": "h264",
      "h264_profile": "main",
      "video_bitrate": 800,
      "segment_seconds": 4,
      "keyframe_interval": 60
    }
  ],
  "videocloud": {
    "video": {
      "name": "Live SSAI VideoCloud Asset",
      "description": "",
      "long_description": "",
      "tags": [],
      "reference_id": "live_ssai_vc_asset",
      "link": {
      "url": "",
      "text": ""
    },
    "schedule": {
      "starts_at": null,
      "ends_at": null
    },
    "custom_fields": {}
    }
  }
}

Sample request (remote video)

To use a remote video for your live stream, your request body should look similar this.

The highlighted field below is needed for server-side ad insertion (SSAI).

{
  "live_stream":true,
  "ad_insertion":true,
  "region":"us-west-2",
  "reconnect_time":1800,
  "outputs":[
    {
      "label": "hls720p",
      "live_stream": true,
      "width": 1280,
      "height": 720,
      "video_codec": "h264",
      "h264_profile": "high",
      "video_bitrate": 2100,
      "segment_seconds": 4,
      "keyframe_interval": 60
    },
    {
      "label": "hls540p",
      "live_stream": true,
      "width": 960,
      "height": 540,
      "video_codec": "h264",
      "h264_profile": "main",
      "video_bitrate": 1500,
      "segment_seconds": 4,
      "keyframe_interval": 60
    },
    {
      "label": "hls360p",
      "live_stream": true,
      "width": 640,
      "height": 360,
      "video_codec": "h264",
      "h264_profile": "main",
      "video_bitrate": 800,
      "segment_seconds": 4,
      "keyframe_interval": 60
    }
  ]
}

Other helpful resources:

Response

Sample response (Video Cloud video)

{
 "id": "227356abcdefghijklmno12345",
 "outputs": [
  {
   "id": "0-2273561a201ec18",
   "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_0/chunklist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_0/chunklist_dvr.m3u8",
   "playback_url_vod": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_0/chunklist_vod.m3u8",
   "playback_added_cdns": [],
   "label": "hls720p"
  },
  {
   "id": "1-2273561a201e8c18",
   "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_1/chunklist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_1/chunklist_dvr.m3u8",
   "playback_url_vod": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_1/chunklist_vod.m3u8",
   "playback_added_cdns": [],
   "label": "hls540p"
  },
  {
   "id": "2-2273561a201ec18",
   "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_2/chunklist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_2/chunklist_dvr.m3u8",
   "playback_url_vod": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/profile_2/chunklist_vod.m3u8",
   "playback_added_cdns": [],
   "label": "hls360p"
  },
  {
   "id": "3-2273561a201ec18",
   "playlist_type": "defaultS3",
   "type": "playlist",
   "filename": "playlist.m3u8",
   "dvr_filename": "playlist_dvr.m3u8",
   "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/playlist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/playlist_dvr.m3u8",
   "ssai_playback_urls": {
    "b907ac7935e2": {
     "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/b907ac7935e2/playlist_ssaiM.m3u8",
     "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/b907ac7935e2/playlist_dvr_ssaiM.m3u8",
     "playback_added_cdns": [],
     "description": "Test ad configuration for SLS",
     "type": "ads"
    },
    "dc9aa8ee3520f2": {
     "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/dc9aa8ee3520f2/playlist_ssaiM.m3u8",
     "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/dc9aa8ee3520f2/playlist_dvr_ssaiM.m3u8",
     "playback_added_cdns": [],
     "description": "Test live ad config for SLS",
     "type": "ads"
    }
   },
   "playback_added_cdns": []
  }
 ],
 "stream_url": "rtmp://ec2-54-184-149-60.us-west-2.compute.amazonaws.com:1935/2273561a201ec18",
 "stream_name": "alive",
 "static": false,
 "job_videocloud_asset_id": "6227380655001",
 "encryption": {},
 "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/playlist.m3u8",
 "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/playlist_dvr.m3u8",
 "ssai_playback_urls": {
  "b907ac7935e2": {
   "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/b907ac7935e2/playlist_ssaiM.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/b907ac7935e2/playlist_dvr_ssaiM.m3u8",
   "playback_added_cdns": [],
   "description": "Test ad configuration for SLS",
   "type": "ads"
  },
  "dc9aa8ee3520f2": {
   "playback_url": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/dc9aa8ee3520f2/playlist_ssaiM.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/2273561a201ec18/us-west-2/NA/dc9aa8ee3520f2/playlist_dvr_ssaiM.m3u8",
   "playback_added_cdns": [],
   "description": "Test live ad config for SLS",
   "type": "ads"
  }
 },
 "playback_added_cdns": []
}

Sample response (remote video)

{
 "id": "bbccddeeffgghhiijjkk0011223344",
 "outputs": [
  {
   "id": "0-bbccddeeffgghhiijjkk0011223344",
   "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_0/chunklist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_0/chunklist_dvr.m3u8",
   "playback_url_vod": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_0/chunklist_vod.m3u8",
   "playback_added_cdns": [],
   "label": "hls720p"
  },
  {
   "id": "1-bbccddeeffgghhiijjkk0011223344",
   "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_1/chunklist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_1/chunklist_dvr.m3u8",
   "playback_url_vod": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_1/chunklist_vod.m3u8",
   "playback_added_cdns": [],
   "label": "hls540p"
  },
  {
   "id": "2-bbccddeeffgghhiijjkk0011223344",
   "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_2/chunklist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_2/chunklist_dvr.m3u8",
   "playback_url_vod": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/profile_2/chunklist_vod.m3u8",
   "playback_added_cdns": [],
   "label": "hls360p"
  },
  {
   "id": "3-bbccddeeffgghhiijjkk0011223344",
   "playlist_type": "defaultS3",
   "type": "playlist",
   "filename": "playlist.m3u8",
   "dvr_filename": "playlist_dvr.m3u8",
   "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/playlist.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/playlist_dvr.m3u8",
   "ssai_playback_urls": {
    "91bc2d5ff4a4441db34c2457c751c3ca": {
     "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/91bc2d5ff4a4441db34c2457c751c3ca/playlist_ssaiM.m3u8",
     "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/91bc2d5ff4a4441db34c2457c751c3ca/playlist_dvr_ssaiM.m3u8",
     "playback_added_cdns": [],
     "description": "Test ad configuration",
     "type": "ads"
    },
    "e7f6e9a3022a45e1b0b322ba57399150": {
     "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/e7f6e9a3022a45e1b0b322ba57399150/playlist_ssaiM.m3u8",
     "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/e7f6e9a3022a45e1b0b322ba57399150/playlist_dvr_ssaiM.m3u8",
     "playback_added_cdns": [],
     "description": "House Ads - 0077db20eb444b5daa7487438c90a271",
     "type": "ads"
    }
   }
  }
 ],
 "stream_url": "rtmp://ep4-usw2.bcovlive.io:1935/bbccddeeffgghhiijjkk0011223344",
 "stream_name": "alive",
 "static": false,
 "encryption": {},
 "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/playlist.m3u8",
 "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/playlist_dvr.m3u8",
 "ssai_playback_urls": {
  "91bc2d5ff4a4441db34c2457c751c3ca": {
   "playback_url": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/91bc2d5ff4a4441db34c2457c751c3ca/playlist_ssaiM.m3u8",
   "playback_url_dvr": "https://bcovlive-a.akamaihd.net/bbccddeeffgghhiijjkk0011223344/us-west-2/NA/91bc2d5ff4a4441db34c2457c751c3ca/playlist_dvr_ssaiM.m3u8",
   "playback_added_cdns": [],
   "description": "Test ad configuration",
   "type": "ads"
  }
 }
}

From the API response, make note of the following field values for the next step:

id - Your live job id
stream_url, stream_name - Inputs for your live stream encoder
job_videocloud_asset_id - Video Cloud video id

Create the playback token

You will need the playback token with your player.

To create the playback token, send a POST request as follows:

Method	`POST`
URL	`https://api.bcovlive.io/v1/jobs/your live job id/playback-token`
Headers	`X-API-KEY: your API KEY`
Headers	Content-Type: application/json

Request body

Sample request body:

{
   "dvr":true / false,
   "application_id":"your ad config id"
}

Response

Sample response:

{
 "playback_token": "live.JhQabcdefghijkl000000000abcdefghi"
}

The response body will include a generated playback token. Use this when making a Playback API call with your player.

Configure the player

The process of playing your live stream from the Playback API is slightly different from the way you play a normal Video Cloud video. In addition to supplying the video id (reference id), you need to include a playback token which identifies the ad configuration you want to use. You will also need to specify if you want DVR playback.

Web player

For details about configuring the Brightcove Player, see the Using Player Enhancements for Live SSAI with Brightcove Player document.

Native Android player

For details about configuring the Native Player for Android, see the Using Player Enhancements for Live SSAI with the Native SDKs document.

Native iOS player

For details about configuring the Native Player for iOS, see the Using Player Enhancements for Live SSAI with the Native SDKs document.

Begin streaming

There are many tools to create a live streaming event. Here are some encoders you can use to produce a live stream delivered by a CDN:

Cleanup

When your live stream is complete, you can clean up the artifacts for your stream as follows:

Stop your streaming encoder

Cancel the live job.

To cancel a live job, send a PUT request as follows:

Method	`PUT`
URL	`https://api.bcovlive.io/v1/jobs/your live job id/cancel`
Headers	`X-API-KEY: your API KEY`
Headers	Content-Type: application/json

For details, see the Live API Reference document.

Delete your ad configuration

To delete an ad configuration, send a DELETE request as follows:

Method	`PUT`
URL	`https://api.bcovlive.io/v1/ssai/applications/application/your ad config id`
Headers	`X-API-KEY: your API KEY`
Headers	Content-Type: application/json

For details, see the Live API Reference document.