Product Updates | Contact Support | System Status
Page Contents

    Playback Restrictions with the Native SDKs

    In this topic, you will learn how to use Playback Restrictions with the Brightcove 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

    Here are the requirements needed to use Playback Restrictions.

    Android: Brightcove Native SDK for Android version 6.11.0 or later

    iOS: Brightcove Native SDK for iOS version 6.7.0 or later

    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:

    1. Start with the Basic Sample App.

    2. 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);
    3. 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:

    1. 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();
      
    2. 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.

    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:

    1. Start with the Basic Sample App.

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

      let playbackService = BCOVPlaybackService(accountId: kViewControllerAccountID, policyKey: nil)
    3. 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 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

    Page last updated on 07 Jan 2022