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.

This document applies to NextGen Live and to legacy live streams that use the SSAI plugin. Live 1.0 has been decommissioned. For NextGen Live channel configuration and SDK compatibility details, see Using NextGen Live with the Native SDKs.

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:

Create a live ad configuration using Video Cloud Studio
Optional: Create slate assets, and/or Insert cue points and ad beacons
Create a live event
Get the playback token
Build your app:
- Android implementation
- iOS implementation
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:

Refer to the Implementing Server-Side Ads in the Live Module document.
Expand the Advanced Options section.
Select Enable Server-Side Ad Insertion (SSAI), and choose a Fill Slate.

Enable SSAI
Optional: To use your own CDN, include these additional steps:
- In the Advanced Options section, select the Add a multi CDN configuration option.
  
  Multi CDN Configuration
- Enter a label and URL for your own CDN. For details, see the Content Delivery Options document.
  
  Add label and URL
When you are finished configuring your live event, click Create Event.

Get the playback token

When you publish a live stream, the player embed code contains the playback token. Current NextGen Live embed codes expose it as livePlaybackToken; older live embed codes used adConfigId. Use this value when requesting video content in your app.

To get the playback token, follow these steps:

In Video Cloud Studio, open the Live module and select your channel.
In the Control Room, select Embed on Web.
Choose your player, sizing and any advanced options. When SSAI is enabled on the channel, the generated embed uses the channel's playback token.
Copy the embed code to your clipboard.

Legacy Live 1.0 embed code (historical)
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
```

From the embed code, copy the livePlaybackToken parameter value. You will use this value in a later step. It is a JWT and starts with eyJ, similar to this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtbiI6InBsYXlsaXN0Iiwic3NhaSI6dHJ1ZSwiYWNpZCI6IjRmMWFjYWQyLTE2MDMtNDg1Ni1hZmFjLThhYWM3NjM1YzEyYyIsImlzcyI6ImJsaXZlLXBsYXliYWNrLW1hbmFnZW1lbnQtYXBpIiwic3ViIjoicGxheWJhY2t0b2tlbiIsImF1ZCI6WyI2NDE1NTE4NjI3MDAxIl0sImp0aSI6IjYzNzk3ODk3NTIxMTIifQ.zdWC1VA5nm3CKNqNclYYNi6aSL3FbjbeHHmb5oHoziQ

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

Android implementation

To play a live stream, include the livePlaybackToken parameter with your playback token in your video request. The legacy Playback API query key is ad_config_id, not the embed option name adConfigId. Passing a legacy key does not add NextGen Live ad features to an SDK released before NextGen Live support.

Follow these steps to build your app:

Use the Basic SSAI Sample App as a starting point for your code.
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)
In the MainActivity.java file, replace the livePlaybackToken value with the playback token you copied from the Live module in the Get the playback token section above.
```
private final String LIVE_PLAYBACK_TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
```

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

HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
  .addQueryParameter("livePlaybackToken", LIVE_PLAYBACK_TOKEN)
  .build();

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);
   }
 });

Your app is ready to play the live stream.

For SSAI improvements and fixes in each SDK version, see the Native SDK for Android release notes.

iOS implementation

To play a live stream, include the livePlaybackToken parameter with your playback token in your video request. The legacy Playback API query key is ad_config_id, not the embed option name adConfigId. Passing a legacy key does not add NextGen Live ad features to an SDK released before NextGen Live support.

Follow these steps to build your app:

Use the Basic SSAI Sample App as a starting point for your code.
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)
In the ViewController.swift file, replace the LivePlaybackToken value with the playback token you copied from the Live module in the Get the playback token section above.
```
static let LivePlaybackToken = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

The livePlaybackToken with your token value is added to the request as a query parameter.

let queryParameters = [BCOVPlaybackService.ParameterKeyLivePlaybackToken: Constants.LivePlaybackToken]

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

let configuration = [BCOVPlaybackService.ConfigurationKeyAssetID: Constants.VideoId]
playbackService.findVideo(withConfiguration: configuration, queryParameters: queryParameters) { [weak self] (video: BCOVVideo?, jsonResponse: 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])
}

Your app is ready to play the live stream.