Brightcove Player Loader

In this topic, you will learn how to use the Brightcove Player Loader to load a Brightcove Player using modern build tooling. This library is seen as a tool for more technical customers.

Player loader overview

For users of Brightcove Player would don't want to copy and paste either the in-page embed or iframe player implementations, this module is bundled into their web application and provides a way to use Brightcove Players without needing to write integration code to download their players and embed them. This tool solves the problem with a Brightcove library that can download any published Brightcove Player and embed it in the DOM.

This library supports common evergreen browsers, Chrome, Firefox, Edge, and Safari.

This document essentially provides example uses of the Brightcove Player Loader. For complete details see the library's brightcove / player-loader GitHub repo.

There is a webpack that can be utilized with Brightcove Player. Details for that can be found in the player-loader-webpack-plugin GitHub repo.

Installation

The library is installed using NPM, using the following:

npm install --save @brightcove/player-loader

Including the library

For different methods of including the library for your use please see the GitHub repo for the library.

Implementation using a Promise

You can use a JavaScript Promise with the library. Promises are not required for this library to work, but they are recommended. By default, this library will look for a global Promise. However, you can explicitly provide a Promise implementation via the Promise parameter, detailed later in this document.

The following shows an implementation of the library using a Promise. A key concept is that you obtain a reference to the player by using var myPlayer = success.ref; in the then section of handling the promise:

<!doctype html>
<html>

<head>
  <meta charset="UTF-8">
  <title>Untitled Document</title>
  <style>
    .video-js {
      height: 344px;
      width: 610px;
    }
  </style>

</head>

<body>
  <script src="brightcove-player-loader.min.js"></script>

  <div id="theDiv">
  </div>

  <script>
    brightcovePlayerLoader({
      refNode: document.querySelector('#theDiv'),
      accountId: '1752604059001',
      playerId: 'wHBRh9M3o',
      videoId: '4607357817001'
    })
    .then(function(success) {
      var myPlayer = success.ref;
      console.log('success', success);
      myPlayer.on('loadedmetadata',function(){
        myPlayer.muted(true);
        myPlayer.play();
      });
    })
    .catch(function(error) {
      console.log('error', error);
    })
  </script>

</body>

</html>

Implementation using callbacks

You can also implement the player loader using callbacks via the onSuccess and onFailure callback functions.

The following shows an implementation of the library using callbacks. A key concept is that you obtain a reference to the player by using var myPlayer = success.ref; in the onSuccess callback function:

<!doctype html>
<html>

<head>
  <meta charset="UTF-8">
  <title>Untitled Document</title>
  <style>
    .video-js {
      height: 344px;
      width: 610px;
    }
  </style>

</head>

<body>
  <script src="brightcove-player-loader.min.js"></script>

  <div id="theDiv">
  </div>

  <script>
  brightcovePlayerLoader({
    refNode: document.querySelector('#theDiv'),
    accountId: '1752604059001',
    playerId: 'wHBRh9M3o',
    videoId: '4607357817001',
    onSuccess: function(success) {
      var myPlayer = success.ref;
      console.log('success', success);
      myPlayer.on('loadedmetadata',function(){
        myPlayer.muted(true);
        myPlayer.play();
      });
    },
    onFailure(error) {
      console.log('error', error);
    }
  });
  </script>

</body>

</html>

Using Playback Restrictions

To use Playback Restrictions with the Brightcove Player Loader, all you need to do is get a reference to the player and pass the JSON Web Token (JWT) to it.

Here's an example:

    <!DOCTYPE html>
      <html lang="en">
      
      <head>
          <title>Brightcove Player</title>
          <meta charset="UTF-8">
          <script crossorigin
              src="player-loader/dist/brightcove-player-loader.min.js"></script>
      </head>
      
      <body>
          <main>
              <h1>Brightcove Player</h1>
              <div id="theDiv"></div>
      
          </main>
      </body>
      <script>
          var myJwtToken = "your jwt token";
          var myVideoId = "your video Id";
      
          // +++ Add the Brightcove Player +++
          brightcovePlayerLoader({
              refNode: document.querySelector('#theDiv'),
              accountId: 'your account Id',
              playerId: 'your player Id',
            onSuccess: function (success) {
              // Get a reference to the BC Player
              var myPlayer = success.ref;
              console.log('success', success);
              
              myPlayer.ready(function () {
                // This should ideally be set in the player configuration
                myPlayer.catalog.setPolicyKey(null);
                myPlayer.catalog.setBcovAuthToken(myJwtToken);
                myPlayer.catalog.get({
                  id: myVideoId,
                  type: 'video'
              }).
                  then(function (data) {
                    myPlayer.catalog.load(data);
                    myPlayer.muted(true);
                    myPlayer.play();
                  }).
                  catch(function (error) {
                    throw new Error(error);
                  });
              });
            },
            onFailure(error) {
              console.log('error', error);
            }
          });
    </script>
    </html>

Available parameters

Name: accountId

Data Type: string | number

Description:
A Video Cloud account ID.

Name: applicationId

Data Type: string

Description:
The application ID to be applied to the generated embed.

Name: catalogSearch

Data Type: string | Object

Description:
A Video Cloud Catalog search to perform. This can be a simple string search or a object that matches the Catalog getSearch() method. If a non-string value is given that is not serializable as JSON, this parameter will be ignored.

Name: catalogSequence

Data Type: Array | Object


Description:
A Video Cloud Catalog sequence to perform. See the Catalog getLazySequence() method for more information. If a non-string value is given that is not serializable as JSON, this parameter will be ignored.

Name: embedId

Data Type:string

Description:
The Brightcove Player embed ID for the player. The default value is 'default'. The default value is correct for most users.

Name: embedOptions

Data Type: Object

Description:
Used to provide certain options for embed generation. These include:

embedOptions.pip boolean If true, will wrap the embed in a <div class="vjs-pip-container"> element. This should be used when you need support for the Brightcove Picture-in-Picture plugin. The default value is false.
embedOptions.playlist boolean If true, will add a <div class="vjs-playlist"> element after the embed. This should be used when you need support for the Brightcove Playlist UI plugin. The default value is false.
embedOptions.responsive boolean | Object Used customize the embed code to produce a responsively-sized player using the intrinsic ratio wrapper approach. When true, will produce a responsive embed code with a 16:9 aspect ratio that will fill its container. The default value is false.
An object can be provided to customize this with the following sub-properties:
  • aspectRatio: A string used to customize the aspect ratio to a value other than 16:9 (e.g., '4:3').
  • maxWidth: A string used to restrain the maximum width of the player. This should use CSS units, such as pixels (e.g., '960px').
embedOptions.unminified boolean If true, will use the un-minified version of the player. This can be useful for debugging purposes, but comes at a cost of a larger player download. Not recommended for production! The default value is false.
Name: embedType

Data Type: string

Description:
The embed code type to produce. This parameter's value must be one of the following:

  • 'in-page' or brightcovePlayerLoader.EMBED_TYPE_IN_PAGE: Also referred to as the advanced embed code, this injects the player directly into the top-level web page.
  • 'iframe' or brightcovePlayerLoader.EMBED_TYPE_IFRAME: Also referred to as the basic embed code, this injects the player as an <iframe> element.
The default value is 'in-page'.
Name: onEmbedCreated

Data Type: Function (element)

Description:
A callback used to customize the embed element (either video-js element or an iframe element) before it is inserted into the DOM or customized as a result of embedOptions and before the player is downloaded and initialized. The embed element may be mutated or, if this callback returns an element, that element will be used as the embed element. Potential use-cases are adding/removing attributes or adding child elements, such as sources or tracks.

Name: onFailure

Data Type: Function(Error)

Description:
A callback function which allows handling of failures when Promise is not available or not desired. Passing this function will prevent a Promise from being returned. It gets a single Error object as an argument. The return value of this function is ignored.

Name: onSuccess

Data Type: Function(Object)

Description:
A callback function which allows handling of successes when Promise is not available or not desired. Passing this function will prevent a Promise from being returned. It gets a single Success object as an argument. The return value of this function is ignored.

Name: options

Data Type: Object

Description:
A Video.js options object to pass during the player creation process. These options will take precedence over any settings specified in the Brightcove Player configuration. This parameter cannot be used with iframe embeds.

Name: playerId

Data Type: string

Description:
A Brightcove Player player ID. The default is 'default'.

Name: playlistId

Data Type: string | number

Description:
A Video Cloud playlist ID or playlist reference ID.

Name: playlistVideoId

Data Type: string | number

Description:

A Video Cloud video ID that would be found in the resulting playlist specified by playlistId. This parameter is ignored if playlistId is missing.

Name: Promise

Data Type: Function(Function)

Description:
Used to explicitly provide a Promise implementation. If provided, this will be used in lieu of any global Promise. The default is window.Promise

Name: refNode

Data Type: Element | string

Description:
Required
The DOM element into which the player will be embedded. If not provided as a DOM element, it can be provided as a string, which will be passed to document.querySelector.

Name: refNodeInsert

Data Type: string

Description:
The manner in which the player will be inserted relative to the reference DOM element (specified by refNode). This parameter's value must be one of the following:

  • 'append' or brightcovePlayerLoader.REF_NODE_INSERT_APPEND: The player will be the last child of the reference node.
  • 'prepend' or brightcovePlayerLoader.REF_NODE_INSERT_PREPEND: The player will be the first child of the reference node.
  • 'before' or brightcovePlayerLoader.REF_NODE_INSERT_BEFORE: The player will be previous sibling of the reference node.
  • 'after' or brightcovePlayerLoader.REF_NODE_INSERT_AFTER: The player will be the next sibling after the reference node.
  • 'replace' or brightcovePlayerLoader.REF_NODE_INSERT_REPLACE: The reference node will be removed and replaced by the player.

Name: videoId

Data Type: string | number

Description:
A Video Cloud video ID or video reference ID.