Playback Restrictions with Brightcove Player

Introduction

By default, Brightcove Player talks to the Brightcove Playback API. 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.

To configure Brightcove Player for License Keys Protection, you will pass a token parameter when making the catalog request for the video.

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

To help you understand the code in the next section, review the concepts in the following documents:

Requirements

Here are the requirements needed to use Playback Restrictions.

Playback Rights

To use Playback Rights, you need the following:

Player version 6.39.0 or greater

License Keys Protection

To use License Keys Protection, you need the following:

Player version 6.33.0 or later
If using DRM, you will need the DRM plugin version 5.5.0 or later

Using Playback Rights

To utilize playback rights, follow these steps:

Remove the Brightcove Player's policy key. For details, see the Making requests with Playback Rights section.
If you have runtime restrictions, you need an authorization token. When specified, this token is added as an Authorization header for any subsequent requests.

You can add one to the player as follows:
```
player.catalog.setBcovAuthToken('your jwt token');
```

After changing the policy key and/or authorization token, you are ready to request data from the Brightcove Playback API and load it into the player. This process is identical to the default case.

Here is an example of fetching a single video with playback restrictions and an authorization token:

HTML

<div style="max-width: 960px;">
  <video-js id="myPlayerID"
    data-embed="default"
    controls=""
    data-application-id=""
    class="vjs-fluid"></video-js>
</div>
<script src="https://players.brightcove.net/your account id/your player id_default/index.min.js"></script>

JavaScript

<script>
    // +++ Add the player attributes +++
    var myPlayer,
    	myPlayerEl = document.getElementById("myPlayerID");
    myPlayerEl.setAttribute('data-account', your account id);
    myPlayerEl.setAttribute('data-player', 'your player id');

    // +++ Create the player +++
    myPlayer = bc(myPlayerEl);

    // Unset the player policy key
    myPlayer.catalog.setPolicyKey(null);

    // Set the authorization token
    myPlayer.catalog.setBcovAuthToken('your jwt token');
    // This should trigger a request to:
    //
    //   https://edge-auth.api.brightcove.com/playback/v1/videos/1
    //
    // With header:
    //
    //   Authorization: Bearer <span class="bcls-input">your jwt token</span>
    //

    myPlayer.catalog.get({id: 'your video id', type: 'video'}).
    then(function(data) {
      myPlayer.catalog.load(data);
      myPlayer.muted(true);
      myPlayer.play();
    }).
    catch(function(error) {
      throw new Error(error);
    });
</script>

Making requests with Playback Rights

By default, all Brightcove Players make a request to the Playback API if it has a policy key. To make requests that check Playback Rights first, you need to remove the policy key. Here are two ways to do that:

Remove policy key at runtime

Add this line of code to the JS script to unset the player policy key:

myPlayer.catalog.setPolicyKey(null);

Remove policy key from all players

To avoid the ingest of a policy key for new players created in Video Cloud Studio, do the following:

Contact your account manager.
Provide your account ID and ask to enable the remove policy key flag.

Remove policy key from individual players

By default, the remove policy key flag is disabled for your account. To remove the policy key from individual players, do the following:

In Video Cloud Studio, navigate to the Players module.
Select the player that you want to remove the policy key from.
In the left navigation, select JSON Editor.
Set the policy_key field as "none".

JSON editor
Save your changes and publish your player.

Making requests without Playback Rights

The process can be reversed to direct requests back to Playback API without rights and restrictions.

Set the policy key and authorization token as follows:

If you had the remove policy key flag enabled, then contact your account manager to disable it.

If you have the remove policy key flag enabled and you disable it, policy keys will be regenerated for all of your players, except those where you have set the policy_key field to "none".
If you updated individual players in Studio, then update the JSON with your policy key.

JSON editor
Set the authorization token to null.
```
player.catalog.setBcovAuthToken(null);
```

Using License Keys Protection

To use License Keys Protection, you will pass a auth token string as part of the player catalog object, using the property name bcovAuthToken.

This approach works for both DRM and HLSe content. The player will detect the type of source being loaded from the Playback API and provide the correct implementation for that source.

To use License Keys Protection, follow these steps:

Create a signed JSON Web Token (JWT).

Include this token with the video request.

This sample implementation code uses the catalog.get() method to request the video while supplying the token.

Be sure NOT to include the data-video-id parameter in the <video-js> tag.

  <video-js id="myPlayerID"
    data-account="1507807800001"
    data-player="default"
    data-embed="default"
    controls
    data-application-id></video-js>
  <script src="//players.brightcove.net/1507807800001/default_default/index.min.js"></script>
  
  <script>
    (function() {
      var myPlayer = videojs.getPlayer('myPlayerID');
  
      myPlayer.catalog.get({
        type: 'video',
        id: '6015247091001',
        policyKey:'none',
        bcovAuthToken: 'your jwt token'
      })
        .then(function(videoReturned){
          myPlayer.catalog.load(videoReturned);
        })
        .catch(function(err){
          console.log('err:', err);
        });
    })();
  </script>

Using Concurrency and Registration

If you are using Stream Concurrency or Device Registration, then your Brightcove player will need to use the EME plug-in INSTEAD of the standard DRM plug-in.

Follow these steps:

Add the EME plugin to your Brightcove Player. The plugin has been updated to include persistentState.
In Video Cloud Studio, navigate to the Players module. Select a player link to see it's information.
In the left navigation, select Playback.
Make sure that Enable DRM is NOT selected.

Enable DRM option
In the left navigation, select JSON Editor.
In the JSON code, find the player object, and add the eme_options object, as follows:
```
  "player": {
    "eme_options" : {
      // add eme options for all sources here.
    }
  }
```
The EME plug-in has to be configured in the order shown above (scripts & style sheet first then the option) otherwise, it won't work.

This functionality is supported in the DRM plug-in v5.9.1 +.

As an eme option for your specified keySystems, set persistentState as "required".


  "eme_options": {
    "keySystems": {
      "com.widevine.alpha": {
        "persistentState": "required"
      }
    }
  }

Include a JWT auth token, as defined in the Using License Keys Protection section.

Configuring server-side ads (SSAI)

If you are using License Keys Protection with SSAI, then you need to include an additional parameter to the catalog parameters object, named adConfigId.

<video-js id="myPlayerID"
  data-account="1507807800001"
  data-player="default"
  data-embed="default"
  controls
  data-application-id></video-js>
<script src="//players.brightcove.net/1507807800001/default_default/index.min.js"></script>

<script>
  (function() {
    var myPlayer = videojs.getPlayer('myPlayerID');

    myPlayer.catalog.get({
      type: 'video',
      id: '6015247091001',
      bcovAuthToken: 'your jwt token',
      adConfigId: 'your ad configuration id'
    })
      .then(function(videoReturned){
        myPlayer.catalog.load(videoReturned);
      })
      .catch(function(err){
        console.log('err:', err);
      });
  })();
</script>

Using a custom implementation

You may be using a custom implementation where you don't have the bcovAuthToken to set the value with the the catalog.get() method request. If you are using your own or a third-party player, you can use one of the following approaches to pass your token into the license request:

HTTP header: BCOV-Auth (Not supported for HLSe)
Cookie: bcov-auth (Not supported for HLSe)
Query parameter: bcov-auth (Only supported for HLSe) Must be appended to the master manifest url, instead of the license url

Here is an example showing how to set the source.emeHeaders['BCOV-Auth'] attribute on the video object to the token. This inserts the emeHeader on each source AFTER the catalog request.

<video-js id="myPlayerID"
  data-account="1507807800001"
  data-player="default"
  data-embed="default"
  controls
  data-application-id></video-js>
<script src="//players.brightcove.net/1507807800001/default_default/index.min.js"></script>

<script>
  (function() {
    var myPlayer = videojs.getPlayer('myPlayerID');

    myPlayer.catalog.get({
      type: 'video',
      id: '6015247091001'
    })
    .then(function(video){
      sources=video.sources;

      for (let i = 0; i < sources.length; i++) {
        const source = sources[i];

        // Only add the auth token as an eme header for DRM content
        if (your jwt token && source.key_systems) {
          source.emeHeaders = {
              'BCOV-Auth': your jwt token
            };
        }
      }
        myPlayer.catalog.load(video);
      })
      .catch(function(err){
        console.log('err:', err);
      });
  })();
</script>

Using a player loader

If you are using a loader with Brightcove Player, you can still use Playback Restrictions.

React Player Loader

To use the React Player Loader with Playback Restrictions, see the React Player Loader document.