Playback Restrictions with the Native SDKs

Introduction

By default, the Native SDKs talk to the Brightcove Playback API to retrieve your video and playlist content. A new system to manage playback rights and restrictions sits in front of the Playback API and provides playback authorization using DRM licenses.

You can use Playback Rights with or without DRM, but if you choose to use runtime restrictions, then you will need to use a JSON Web Token (JWT).

License Keys Protection offers an extra level of security when using Dynamic Delivery with DRM-protected or HTTP Live Streaming Encryption (HLSe) content. License requests can be authenticated using a signed JSON Web Token (JWT).

The JWT is used when requesting the video license, once the video has been loaded to the player and the source has been selected.

For more inforation about this feature, see the following:

Requirements

To use Playback Restrictions, you will need the following versions of the Brightcove Native SDKs:

Android: Native SDK for Android version 6.11.0 or later
iOS: Native SDK for iOS version 6.7.0 or later

Additions

Additional features for using Playback Restrictions include:

Android: Native SDK for iOS version 7.1.3 fixed support for Live HLSe License Keys Protection
iOS: Native SDK for iOS version 6.10.5 added support for Live HLSe License Keys Protection

How does it work?

Playback Restrictions refer to the whole solution, which includes:

Playback Rights
License Keys Protection

Playback Rights

By default, the Native SDKs make a request to the Playback API if it has a policy key. The SDK sends the request to the following endpoint, and retrieves your content:

edge.api.brightcove.com

To check Playback Rights with your Playback API request, you will not include the Policy Key. When there is no Policy Key, the SDK sends the request to this endpoint:

edge-auth.api.brightcove.com

If all of the checks associated with Playback Rights pass, then your content is returned.

License Keys Protection

DRM or HLSe content protection uses license/key requests, which can protect every stream request, with the use of a JSON Web Token (JWT).

Your requests to the Playback API will include the Policy Key, and the SDKs will send the request to the following endpoint:

edge.api.brightcove.com

Android: Using Playback Rights

To make Playback API requests which check for Playback Rights, follow these steps:

Start with the Basic Sample App.
Use the catalog Builder pattern without the Policy Key.
```
Catalog catalog = new Catalog.Builder(eventEmitter, account).build();
```
If you are following the Brightcove sample app, it gets the account ID as shown here:
```
String account = getString(R.string.account);
```
Optional: If you want to use runtime restrictions, you need to create a JWT and pass it with the catalog request.
1. Create your JWT. For details, see the Overview: Brightcove Playback Restrictions document.
2. Pass your JWT with the catalog request by setting the JWT in the HttpRequestConfig. For details, see the Android: Using License Keys Protection section.

Android: Using License Keys Protection

The Native SDK for Android currently supports Key/license protection for HLSe and Widevine DASH sources. You will provide your authorization token as part of the Brightcove catalog request for a single video or a playlist.

To make a Brightcove catalog request, follow these steps:

Create an HttpRequestConfig object and set the Brightcove Authorization Token to the value of your JSON Web Token.

HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
  .setBrightcoveAuthorizationToken("your jwt")
  .build();

Use one of the following Catalog methods with your HttpRequestConfig object:

For a video request, use one of the following:
```
findVideoByID(String, HttpRequestConfig, VideoListener)
```
```
findVideoByReferenceID(String, HttpRequestConfig, VideoListener)
```
For a playlist request, use one of the following:
```
findPlaylistByID(String, HttpRequestConfig, PlaylistListener)
```
```
findPlaylistByReferenceID(String, HttpRequestConfig, PlaylistListener)
```
The details of token usage for HLSe and Widevine license acquisition are handled by the SDK.

For playlist requests, all videos in the playlist must use the same token. In a future release, you will be able to assign a different token to each video in the playlist. You will be responsible for maintaining the mapping between Video ID and token. The conid as defined in the JWT claims is the Video ID value associated with a token.

Code example

Here is an example that shows how to pass your authorization token when making a Catalog request:

String myToken = "your jwt";
HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
  .setBrightcoveAuthorizationToken(myToken)
  .build();
...

Catalog catalog = new Catalog.Builder(eventEmitter, account)
  .setPolicy(getString(R.string.policy))
  .build();
catalog.findVideoByReferenceID(videoReferenceId, httpRequestConfig, new VideoListener(){...});

Offline Playback

The OfflineCatalog findVideo, requestPurchaseLicense and requestRentalLicense methods all take an HttpRequestConfig as an argument.

Here's an example:

private HttpRequestConfig httpRequestConfig;
private String myToken = "your jwt";
...
HttpRequestConfig.Builder httpRequestConfigBuilder = new HttpRequestConfig.Builder();
httpRequestConfigBuilder.setBrightcoveAuthorizationToken(myToken);
httpRequestConfig = httpRequestConfigBuilder.build();
playlist.findPlaylist(catalog, httpRequestConfig, new PlaylistListener() {
    @Override
    public void onPlaylist(Playlist playlist) {
        videoListAdapter.setVideoList(playlist.getVideos());
        onVideoListUpdated(false);
        brightcoveVideoView.addAll(playlist.getVideos());
    }

    @Override
    public void onError(String error) {
        String message = showToast("Failed to find playlist[%s]: %s", playlist.displayName, error);
        Log.w(TAG, message);
        onVideoListUpdated(true);
    }
});

For details, see the Offline Playback sample app.

License Keys Protection with Delivery Rules

To combine License Keys Protection with Delivery Rules, configure the HttpRequestConfig.Builder to do the following:

Set the Brightcove Authorization Token (JWT)
Set the Delivery Rule Config ID

The resulting Builder configuration would look like this:

HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
  .addQueryParameter(HttpRequestConfig.KEY_DELIVERY_RULE_CONFIG_ID, "your rules id")
  .setBrightcoveAuthorizationToken("your jwt")
  .build();

Responses

The following responses are associated with License Keys Protection:

200 - License is allowed to continue
401 - The License delivery must not be allowed to continue

iOS: Using Playback Rights

To make Playback API requests which check for Playback rights, follow these steps:

Start with the Basic Sample App.

Create an instance of BCOVPlaybackService, setting the Policy Key to nil.

let playbackService = BCOVPlaybackService(accountId: kViewControllerAccountID, policyKey: nil)

Optional: If you want to use runtime restrictions, you need to create a JWT and pass it with the catalog request.
1. Create your JWT. For details, see the Overview: Brightcove Playback Restrictions document.
2. Pass your JWT with the catalog request. For details, see the iOS: Using License Keys Protection section.

iOS: Using License Keys Protection

When using License Keys Protection, you will need to use the playback service methods that allow you to pass in your JSON Web Token (JWT). This is done using the authToken parameter.

For a video request, use one of the following:

- (void)findVideoWithVideoID:(NSString *)videoID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

- (void)findVideoWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error))completionHandler;

For a playlist request, use one of the following:

- (void)findPlaylistWithPlaylistID:(NSString *)playlistID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

- (void)findPlaylistWithReferenceID:(NSString *)referenceID authToken:(NSString *)authToken parameters:(NSDictionary *)parameters completion:(void (^)(BCOVPlaylist *playlist, NSDictionary *jsonResponse, NSError *error))completionHandler;

The details of token usage for HLSe and FairPlay license acquisition are handled by the SDK.

For playlist requests, all videos in the playlist must use the same token. In a future release, you will be able to assign a different token to each video in the playlist. You will be responsible for maintaining the mapping between Video ID and token. The conid as defined in the JWT claims is the Video ID value associated with a token.

For details, see the Playback Authorization Service section of the Native SDK for iOS reference.

Offline Playback

If you are using the Playback Authorization Service with Offline Playback, there is a new method for renewing a FairPlay license which accepts an authorization token:

// Request license renewal
    [BCOVOfflineVideoManager.sharedManager renewFairPlayLicense:offlineVideoToken
        video:video // recent video from Playback API or Playback Service class
        authToken: authToken
        Parameters: parameters
        completion:^(BCOVOfflineVideoToken offlineVideoToken, NSError *error)
    {
        // handle errors
    }];

When license renewal is finshed, the completion block will be called with the same offline video token that was passed in. An NSError will indicate any problem that occurred (or nil if no error).

For details, see the Renewing a FairPlay License section of the Native SDK for iOS reference.

License Keys Protection with Delivery Rules

To combine License Keys Protection with Delivery Rules, do the following:

Define the parameter for your Delivery Rules ID
Pass the Delivery Rules ID as a parameter with the catalog call to the Playback API
Pass your JSON Web Token (JWT) using the authToken parameter

Here is a code example:

- (void)requestContentFromPlaybackService
  {
    NSDictionary *playbackAPIParameters = @{@"config_id":@"your rules id"};

    [self.playbackService findVideoWithVideoID:kViewControllerVideoID
      authToken:(NSString *)authToken
      parameters:playbackAPIParameters
      completion:^(BCOVVideo *video, NSDictionary *jsonResponse, NSError *error) {

      if (video)
      {
        [self.playbackController setVideos:@[ video ]];
      }
      else
      {
        NSLog(@"ViewController Debug - Error retrieving video playlist: `%@`", error);
      }
    }];
  }

Responses

The following responses are associated with License Keys Protection:

200 - License is allowed to continue
401 - The License delivery must not be allowed to continue