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.

For a high-level overview, see the Overview: Player Enhancements for Live SSAI document.

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 a remote video
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.

For this feature, ad configurations MUST have an ad_configuration_expected_response_type value of Vast.

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.

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 aaplication description"
}

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

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

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.

If you wish to create a VOD clip from the live stream, include the videocloud parameter in the request body. For details, see the Live API: Creating VOD Clips document.

The highlighted field in the request bodies below (for jobs using a Video Cloud video and using a remote video) is needed for server-side ad insertion (SSAI).

Sample request body (using a Video Cloud video):

{
  "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 body (using remote video):

{
  "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:

Sample response:

{
 "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 job id and the stream_url properties. You will need these later.

In the response body, there will be an object containing SSAI information for each ad configuration in your account. The sample above shows the object for one ad configuration. This should be the ad configuration id you created in the previous step.

The playback_url or playback_url_dvr field associated with your ad configuration id is used in the next step to create a remote video asset.

Create a remote video

In Video Cloud, you will create a remote video which points to your live stream. For this step, you will need the playback_url or playback_url_dvr from the previous step.

There are two ways to create a remote video:

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.

Create the playback token

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

Sample request body:

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

Sample response:

{
 "playback_token": "live.JhQabcdefghijkl000000000abcdefghi"
}

The response body will include a generated playback token. Use this when making a Playback API call with the following players:

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: (Use the playback_url from a previous step)

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.

Page Contents

Implementing Player Enhancements for Live SSAI

Introduction

Workflow

Create an ad configuration

Create a live job

Sample request body (using a Video Cloud video):

Sample request body (using remote video):

Create a remote video

Configure the player

Create the playback token

Web player

Native Android player

Native iOS player

Begin streaming

Cleanup