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.
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 |
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 |
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 |
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
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
Content-Type: application/json For details, see the Live API Reference document.