Using Live SSAI with the Native SDKs

Overview

Server-Side Ad Insertion (SSAI) allows you to stitch ads into your video content stream to provide a TV-like viewing experience. To play a live stream with the Native SDKs, you need to pass the playback token with your video request.

Live SSAI allows you to:

• Insert ads using cue points sent from your encoder or create an instant cue point using the Live API
• Ingest "slate" assets to fill any unused ad time
• Avoid ad blockers with ads that are stitched into the live stream on the server side

Steps

To play a live stream with SSAI, follow these steps:

1. Create a live ad configuration using Video Cloud Studio
2. Optional: Create slate assets, and/or Insert cue points and ad beacons
3. Create a live event
4. Get the playback token

5. Build your app:

   • Android implementation
   • iOS implementation
6. Request an ad break

Create a live event

By default, your live stream will use a Brightcove CDN. If you prefer, you can use your own choice of CDN (BYO CDN or "bring your own bandwidth"). To use your own CDN, include the optional step in this section and in the Get the playback token section.

To create a live event, follow these steps:

1. Refer to the Implementing Server-Side Ads in the Live Module document.
2. Expand the Advanced Options section.

3. Select Enable Server-Side Ad Insertion (SSAI), and choose a Fill Slate.

   

4. Optional: To use your own CDN, include these additional steps:

   • In the Advanced Options section, select the Add a multi CDN configuration option.

     

   • Enter a label and URL for your own CDN. For details, see the Content Delivery Options document.

     

5. When you are finished configuring your live event, click Create Event.

Get the playback token

When you enable SSAI with your live stream, the player embed code will contain an adConfigId parameter. This value is the playback token, which you will use when requesting video content in your app.

To get the playback token, follow these steps:

1. In Video Cloud Studio, return to the Live module.
2. In the left side navigation, select Publish and Embed.

3. In the Live Player Options section, expand the Select Ad Configuration option and select your live ad configuration that you created in a previous step.

   

4. Copy the Standard Embed Code to your clipboard.

   

5. From the embed code, copy the VideoId parameter value. You will use this value in a later step. It should look similar to this:

   1700044540369289748

6. From the embed code, copy the adConfigId parameter value. You will use this values in a later step. The adConfigId value is the playback token passed when requesting content from your Video Cloud library. It should look similar to this:

   live.t0vbpNIjTPW6IZ29QsyuWrmgjvQjEWe3u_wPmaMqnhAmE05DCF7aAa-6fDIkvryJctH1rADJnfXYANy7tDg4agQFx23WIvsXMmAjz1BiNl-S3rFZ9tRdzRWdo1E4FTLkET6XcNuNZ2acTnzmow

7. You will also need the Account Id and Policy Key for your account.

Android implementation

To play a live stream, you will include the adConfigId parameter and the value of your playback token to your video request.

Follow these steps to build your app:

1. Use the Basic SSAI Sample App as a starting point for your code.
2. In the res/values/strings.xml file, replace the following with your own values
   • Account Id
   • Policy Key
   • Video Id (from the Get the playback token section above)

3. In the MainActivity.java file, replace the ad_config_id value with your playback token (live URL) that you you copied from the Live module in the Get the playback token section above.

   private final String AD_CONFIG_ID_QUERY_PARAM_VALUE = "live.t0vbpNIjTPW6IZ29QsyuWrmgjvQjEWe3u_wPmaMqnhAmE05DCF7aAa-6fDIkvryJctH1rADJnfXYANy7tDg4agQFx23WIvsXMmAjz1BiNl-S3rFZ9tRdzRWdo1E4FTLkET6XcNuNZ2acTnzmow";

4. The ad_config_id with your playback token value is added to the HTTP request as a query parameter.

   HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
     .addQueryParameter(AD_CONFIG_ID_QUERY_PARAM_KEY, AD_CONFIG_ID_QUERY_PARAM_VALUE)
     .build();
   

5. Make the catalog call to the Playback API with your live stream video id and the updated HTTP request.

   catalog.findVideoByID(getString(R.string.video_id), httpRequestConfig, new VideoListener() {
      @Override
      public void onVideo(Video video) {
          plugin.processVideo(video);
      }
    });
   

6. Your app is ready to play the live stream.

   For more details about using live streams enabled for SSAI with the Native SDK for Android, see the SSAI Plugin changes in 6.9.0 blog post.

iOS implementation

To play a live stream, you will include the adConfigId parameter and the value of your playback token to your video request.

Follow these steps to build your app:

1. Use the Basic SSAI Sample App as a starting point for your code.
2. In the ViewController.swift file, replace the following with your own values
   • Account Id
   • Policy Key
   • Video Id (from the Get the playback token section above)

3. In the ViewController.swift file, replace the AdConfigId value with your playback token (live URL) that you you copied from the Live module in the Get the playback token section above.

   static let AdConfigId = "live.t0vbpNIjTPW6IZ29QsyuWrmgjvQjEWe3u_wPmaMqnhAmE05DCF7aAa-6fDIkvryJctH1rADJnfXYANy7tDg4agQFx23WIvsXMmAjz1BiNl-S3rFZ9tRdzRWdo1E4FTLkET6XcNuNZ2acTnzmow";

4. The AdConfigId with your playback token value is added to the HTTP request as a query parameter.

   let queryParameters = [kBCOVPlaybackServiceParamaterKeyAdConfigId: Constants.AdConfigId]
   

5. Make the catalog call to the Playback API with your live stream video id and the updated HTTP request.

   playbackService.findVideo(withConfiguration: configuration, parameters: queryParameters), completion: { [weak self] (video: BCOVVideo?, jsonResponse: [AnyHashable: Any]?, error: Error?) -> Void in
   
      guard let _video = video else {
        print("ViewController Debug - Error retrieving video: \(error?.localizedDescription ?? "unknown error")")
        return
      }
   
      self?.playbackController?.setVideos([_video] as NSFastEnumeration)
   }
   

6. Your app is ready to play the live stream.