Contact Support | System Status
Page Contents

    Playback Restrictions with Brightcove Player

    In this topic, you will learn how to configure Brightcove Player to use Playback Restrictions.

    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:

    1. Remove the Brightcove Player's policy key. For details, see the Making requests with Playback Rights section.

    2. 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');
    3. 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 from all players

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

    1. Contact your account manager.
    2. 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:

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

      JSON editor
      JSON editor
    5. 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:

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

    2. If you updated individual players in Studio, then update the JSON with your policy key.

      JSON editor
      JSON editor
    3. Set the authorization token to null.

      player.catalog.setBcovAuthToken(null);

    Using an auth token

    To use License Keys Protection, pass a string token 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:

    1. Create a signed JSON Web Token (JWT).
    2. Include this token with the video request.

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

        <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'
            })
              .then(function(videoReturned){
                myPlayer.catalog.load(videoReturned);
              })
              .catch(function(err){
                console.log('err:', err);
              });
          })();
        </script>

    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>

    Page last updated on 04 May 2021