support Contact Support | system status 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.

    If you are not familiar with SLS, see the Overview: Player Enhancements for Live SSAI document.

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

    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 for SLS",
      "application_ad_configuration": {
       "ad_configuration_description": "SLS Ad Config : BC Learning PAS/SLS",
       "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 body below is needed for server-side ad insertion (SSAI).

    Sample request body:

    {
      "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 for SLS",
         "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 for SLS",
       "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:

    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 Jun 2020