Contact Support | System Status
Page Contents

    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:

    1. Ask your account manager to enable your account for Live streams, Server-Side Ad Insertion (SSAI) and the Player Enhancements for Live SSAI.
    2. Create an ad configuration
    3. Optional: Create slate assets to fill unused ad time
    4. Create a live job
    5. Create the playback token
    6. Configure the player
    7. Begin streaming
    8. Trigger ads using cue points (this can be done before or during the live event)
    9. 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.

    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


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

    1. Stop your streaming encoder
    2. 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.

    3. 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.


    Page last updated on 12 Oct 2021