search

brightcove / player-loader

An asynchronous script loader and embed generator for the Brightcove Player.
Other
28 stars 15 forks source link

readme

Brightcove Player Loader

Build Status Greenkeeper badge

NPM

An asynchronous script loader for the Brightcove Player.

Table of Contents generated with DocToc

License

Apache-2.0. Copyright (c) Brightcove, Inc.

While this library, Brightcove Player Loader, has an open-source license and is free-to-use, the Brightcove Player is not open-source or free-to-use; it is governed by the proprietary Brightcove Software License and is Copyright (c) Brightcove, Inc.

Similarly, all files in vendor/ do not fall under the Apache-2.0 license. Rather, they are governed by the proprietary Brightcove Software License and are Copyright (c) Brightcove, Inc.

Why do I need this library?

Each Brightcove Player is constructed for our customers and served via our CDN. This works great for most traditional websites where adding an embed code into a template or CMS is straightforward - especially for non-developers!

However, as the web moves toward ES modules and our more technical customers adopt modern build tooling, many users don't want a copy/paste embed code. They want a module they can bundle into their web application without needing to write a lot of integration code to download their players and embed them.

This tool aims to solve that problem by providing our own library that can download any published Brightcove Player and embed it in the DOM.

Brightcove Player Support

Currently, this library supports Brightcove Players v6.0.0 and higher.

It may work for v5.x players in some configurations, but this is not a supported use-case.

Browser Support

This library supports common evergreen browsers - Chrome, Firefox, Edge, Safari - and IE11. Earlier versions of IE are not supported.

Installation

npm install --save @brightcove/player-loader

Inclusion

To include the Brightcove Player Loader on your website or web application, use any of the following methods.

ES6 Modules (e.g. Rollup, Webpack)

This is the most modern use-case.

import brightcovePlayerLoader from '@brightcove/player-loader';

brightcovePlayerLoader();

CommonJS (e.g. Browserify)

When using with CommonJS or Browserify, install @brightcove/player-loader via npm and require the library as you would any other module:

var brightcovePlayerLoader = require('@brightcove/player-loader');

brightcovePlayerLoader();

AMD (e.g. RequireJS)

NOTE: Use either dist/brightcove-player-loader.js or dist/brightcove-player-loader.min.js. In either case, the global variable brightcovePlayerLoader will be created.

When using with RequireJS (or another AMD library), get the script in whatever way you prefer and require the library as you normally would:

require(['@brightcove/player-loader'], function(brightcovePlayerLoader) {
  brightcovePlayerLoader();
});

<script> Tag

NOTE: Use either dist/brightcove-player-loader.js or dist/brightcove-player-loader.min.js. In either case, the global variable brightcovePlayerLoader will be created.

This is the simplest case. Get the script in whatever way you prefer and include it:

<script src="https://github.com/brightcove/player-loader/raw/master//path/to/@brightcove/brightcove-player-loader.min.js"></script>
<script>
  brightcovePlayerLoader();
</script>

Usage

Note: If you want to use this with React, we have an official react component called @brightcove/react-player-loader

The Brightcove Player Loader exposes a single function. This function takes an parameters object which describes the player it should load and returns a Promise which resolves when the player is loaded and created and rejects if anything fails.

Examples

This is a minimal example, using only the required parameters, which will load a Video Cloud account's default player:

brightcovePlayerLoader({
  refNode: someElement,
  accountId: '123456789'
});

This is a more complete example, using some optional parameters and handling the returned Promise:

brightcovePlayerLoader({
  refNode: someElement,
  refNodeInsert: 'replace',
  accountId: '123456789',
  playerId: 'AbCDeFgHi',
  embedId: 'default',
  videoId: '987654321'
})
  .then(function(success) {
    // The player has been created!
  })
  .catch(function(error) {
    // Player creation failed!
  });

Pre-Existing Players

This library will attempt to detect pre-existing players on the page. In other words, if this library runs after a Brightcove Player script was included earlier in the DOM, it will detect it and prevent additional downloads of the same player. For example:

<div id="player-container"></div>
<script src="https://players.brightcove.net/123456789/default_default/index.min.js"></script>
<script src="https://github.com/brightcove/player-loader/raw/master/path/to/brightcove-player-loader.js"></script>
<script>

  // This will create a player in #player-container, but will not download
  // the player script a second time!
  brightcovePlayerLoader({
    refNode: '#player-container',
    accountId: '123456789'
  });
</script>

However, there is a limitation to this behavior. Players from separate accounts on the same page are not guaranteed to be properly detected. This is considered an unsupported use-case.

Avoiding Downloads

When used with the related webpack plugin, you can take advantage of the Player Loader's embed creation capabilities while avoiding an additional, asynchronous request by bundling your Brightcove Player into your webpack bundle.

Simply configure both libraries simultaneously and your player(s) should be bundled and no longer download asynchronously.

Use of Promises or Callbacks

By default, this library will look for a global Promise. However, you can explicitly provide a Promise implementation via the Promise parameter:

brightcovePlayerLoader({
  refNode: someElement,
  accountId: '123456789',
  playerId: 'AbCDeFgHi',
  Promise: MyCustomPromise
})
  .then(function(success) {
    // The player has been created!
  })
  .catch(function(error) {
    // Player creation failed!
  });

Promises are not required for this library to work, but they are recommended. The only major browser that does not support Promise natively is IE11. We recommend polyfilling the window.Promise constructor if it does not exist.

In cases where no Promise global exists and none is provided, the Brightcove Player Loader will return undefined. There are callbacks available, which can be used instead of Promise - passing them will prevent a Promise from being returned:

brightcovePlayerLoader({
  refNode: someElement,
  accountId: '123456789',
  onSuccess: function(success) {
    // The player has been created!
  },
  onFailure: function(error) {
    // Player creation failed!
  }
});

NOTE: Providing these callbacks means opting-out of promises entirely. No Promise object will be returned!

Success

For resolved Promises or onSuccess callbacks, a single argument will be passed. This "success object" can have the following properties:

Property Description
type Either 'in-page' or 'iframe', describing the type of embed that was created.
ref The type of value assigned to this property will vary by the type. For 'in-page' embeds, it will be a Video.js Player object and for 'iframe' embeds, it will be the <iframe> DOM element.

Failure

For rejected Promises or onFailure callbacks, a single argument will be passed. This will be a native Error object with a message describing what went wrong.

Cleaning Up

The Brightcove Player will create global variables and add elements to the DOM. This library exposes a reset() function, which can reset that state. Calling it will have the following effects:

brightcovePlayerLoader({
  refNode: someElement,
  refNodeInsert: 'replace',
  accountId: '123456789',
  playerId: 'AbCDeFgHi',
  embedId: 'default',
  videoId: '987654321'
})
  .then(function(success) {

    /*
      At this point:
      - at least one video player will be in the DOM.
      - at least one script created by this library will be in the DOM.
      - window.bc will exist.
      - window.videojs will exist.
     */

     brightcovePlayerLoader.reset();

    /*
      At this point:
      - no video players will be in the DOM.
      - no scripts created by this library will be in the DOM.
      - window.bc will not exist.
      - window.videojs will not exist.
     */
  });

This reset() function can be useful in long-lived web pages, such as in single page applications and similar. It is left to implementers to determine whether or not they need to merely dispose their players or completely reset the Brightcove-provided functions.

Parameters

The following are all the parameters that can be passed to the Brightcove Player Loader function. Required parameters are marked with an asterisk (*).

Parameters must be passed as an object.

accountId*

A Video Cloud account ID.

adConfigId

The Video Cloud SSAI Ad Config ID to be applied to the generated embed.

applicationId

The application ID to be applied to the generated embed.

catalogSearch

NOTE: Only supported for Brightcove Player versions 6.18.0 and newer.

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.

For example, this:

brightcovePlayerLoader({
  // ...
  catalogSearch: 'some search term'
});

...or:

brightcovePlayerLoader({
  // ...
  catalogSearch: {
    q: 'some search term',
    limit: 10
  }
});

catalogSequence

NOTE: Only supported for Brightcove Player versions 6.18.0 and newer.

A Video Cloud Catalog sequence to perform. See the Catalog getLazySequence method documentation for more.

If a non-string value is given that is not serializable as JSON, this parameter will be ignored.

For example, this:

brightcovePlayerLoader({
  // ...
  catalogSequence: [{
    type: 'search',
    id: {
      q: 'some search term',
      limit: 10
    }
  }, {
    type: 'video',
    id: '1234567890'
  }, {
    type: 'playlist',
    id: '0987654321'
  }]
});

deliveryConfigId

The Dynamic Delivery Rules Config ID to be applied to the generated embed.

embedId

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

embedOptions

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

embedOptions.pip

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.

embedOptions.playlist

For in-page embeds, 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.

Also for in-page embeds, our legacy playlist UI plugin used a <ul> element instead of a <div>. You can pass an object with legacy: true here to use a <ul>.

For iframe embeds, this parameter will be ignored.

embedOptions.responsive

NOTE: This approach should work for in-page embeds, but it is recommended that you use the Video.js fluid and/or aspectRatio options instead:

options: {
  aspectRatio: '16:9'
}

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.

An object can be provided to customize this with the following sub-properties:

embedOptions.tagName

Used to customize the embed element's tag name. This parameter's value must be one of:

This option is only supported when embedType is 'in-page'; it is ignored when embedType is 'iframe'.

embedOptions.unminified

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!

embedType

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

onEmbedCreated

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

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

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

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.

NOTE: Cannot be used with iframe embeds!

playerUrl

If you host the player that you are trying to load yourself, and you don't want to load the player from brightcove, pass the url for the player here.

Note: iframes should resolve to an HTML page and other embeds should point to a JavaScript file.

playerId

A Brightcove Player ID.

playlistId

A Video Cloud video ID or reference ID.

playlistVideoId

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

poster

A URL to a poster image to override that returned by the Playback API.

This option is only supported when embedType is 'in-page'; it is ignored when embedType is 'iframe'.

Promise

Used to explicitly provide a Promise implementation. If provided, this will be used in lieu of any global Promise.

refNode*

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

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:

videoId

A Video Cloud video ID or reference ID.

Constants

The library exposes several constants attached to the main library function, brightcovePlayerLoader. Most can be used for parameter values and are mentioned under the relevant headings, but collected here for reference as well:

Constant Relevant Parameter
EMBED_TAG_NAME_VIDEO embedOptions.tagName
EMBED_TAG_NAME_VIDEOJS embedOptions.tagName
EMBED_TYPE_IN_PAGE embedType
EMBED_TYPE_IFRAME embedType
REF_NODE_INSERT_APPEND refNodeInsert
REF_NODE_INSERT_PREPEND refNodeInsert
REF_NODE_INSERT_BEFORE refNodeInsert
REF_NODE_INSERT_AFTER refNodeInsert
REF_NODE_INSERT_REPLACE refNodeInsert
VERSION n/a

Base URL

By default, the base URL used is the Brightcove CDN. However, for some non-production cases and testing, you may want to override the base URL. This can be achieved via a call to the setBaseUrl function:

brightcovePlayerLoader.setBaseUrl('https://localhost:9999/');