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 token is used when requesting the video license, once the video has been loaded to the player and the source has been selected.

    If you are not familiar with this feature, see the Overview: Brightcove Playback Restrictions document.

    Requirements

    Here are the requirements needed to use Playback Restrictions.

    Android

    • You must use Brightcove Native SDK for Android version 6.11.0 or later

    iOS

    • You must use Brightcove Native SDK for iOS version 6.7.0 or later

    Using Playback Rights: Android

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

    1. Start with the Basic Sample App.

    2. By default, the Native SDK for Android makes a request to the Playback API if it has a policy key. To utilize Playback rights, do not send the policy key with your request.

      Create an instance of com.brightcove.player.edge.Catalog without supplying a policy key. Here is an example:

      Catalog catalog = new Catalog.Builder(eventEmitter, accountId).build();

      If you are following the Brightcove sample app, it gets the account ID as shown here:

      getString(R.string.account)

    3. Optional: If you want to use runtime restrictions, you need to create a JWT token and pass it with the catalog request.

      To create your JWT token, follow the steps in the Runtime restrictions section of the Overview: Brightcove Playback Restrictions document.

      To pass your token with the catalog request, see the Using License Keys Protection: Android section.

    Using Playback Rights: iOS

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

    1. Start with the Basic Sample App.

    2. By default, the Native SDK for iOS makes a request to the Playback API if it has a policy key. To utilize Playback rights, do not send the policy key with your request.

      Create an instance of BCOVPlaybackService, setting the policy key to nil. Here is an example:

      let playbackService = BCOVPlaybackService(accountId: kViewControllerAccountID, policyKey: nil)
    3. Optional: If you want to use runtime restrictions, you need to create a JWT token and pass it with the catalog request.

      To create your JWT token, follow the steps in the Runtime restrictions section of the Overview: Brightcove Playback Restrictions document.

      To pass your token with the catalog request, see the Using License Keys Protection: iOS section.

    Using License Keys Protection: Android

    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 as shown here:

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

      The value of the Authorization token will be the value of your JSON Web Token.

    2. Once you have created the HttpRequestConfig object, pass it to one of the following Catalog methods:

      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 = "...";
    HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
      .setBrightcoveAuthorizationToken(myToken)
      .build();
    …
    
    Catalog catalog = new Catalog(eventEmitter, accountId, policyKey, playbackApiBaseUrl);
    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 pasToken = "your jwt token";
    ...
    HttpRequestConfig.Builder httpRequestConfigBuilder = new HttpRequestConfig.Builder();
    httpRequestConfigBuilder.setBrightcoveAuthorizationToken(pasToken);
    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.

    Responses

    The following responses are associated with PAS:

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

    Limitations

    There is a limitation with the current release:

    • Chromecast is not supported with key/license protection.

    Using License Keys Protection: iOS

    When using key/license protection, you will need to use the playback service methods that allow you to pass in your authorization token. 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.

    Responses

    The following responses are associated with PAS:

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

    Page last updated on 03 May 2021