Brightcove Player Loader

Product(s)
Video Cloud
Brightcove Player
Role(s)
Player Developer
Task(s)
Create & Configure Players
Type
Support Doc

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, Safari and IE11. Earlier versions of IE or NOT supported.

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>

Available parameters

 

Name Data type Description
accountId string | number Required
A Video Cloud account ID.
applicationId string The application ID to be applied to the generated embed.
catalogSearch string | Object 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.
catalogSequence Array | Object 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.
embedId string The Brightcove Player embed ID for the player. The default value is 'default'. The default value is correct for most users.
embedOptions Object 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.
embedType string 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'.
onEmbedCreated Function (element) 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.
onFailure Function(Error) 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.
onSuccess Function(Object) 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.
options Object 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.
playerId string A Brightcove Player player ID. The default is 'default'.
playlistId string | number A Video Cloud playlist ID or playlist reference ID.
playlistVideoId string | number A Video Cloud video ID that would be found in the resulting playlist specified by playlistId. This parameter is ignored if playlistId is missing.
Promise Function(Function) Used to explicitly provide a Promise implementation. If provided, this will be used in lieu of any global Promise. The default is window.Promise
refNode Element | string 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.
refNodeInsert string 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.
videoId string | number A Video Cloud video ID or video reference ID.