An asynchronous script loader for the Brightcove Player.
npm install @brightcove/player-loader



An asynchronous script loader for the Brightcove Player.
Table of Contents generated with DocToc
- License
- Why do I need this library?
- Brightcove Player Support
- Browser Support
- Installation
- Inclusion
- ES6 Modules (e.g. Rollup, Webpack)
- CommonJS (e.g. Browserify)
- AMD (e.g. RequireJS)
- Tag
- Usage
- Examples
- Pre-Existing Players
- Avoiding Downloads
- Use of Promises or Callbacks
- Success
- Failure
- Cleaning Up
- Parameters
- accountId\*
- adConfigId
- applicationId
- catalogSearch
- catalogSequence
- deliveryConfigId
- embedId
- embedOptions
- embedOptions.pip
- embedOptions.playlist
- embedOptions.responsive
- embedOptions.tagName
- embedOptions.unminified
- embedType
- onEmbedCreated
- onFailure
- onSuccess
- options
- playerUrl
- playerId
- playlistId
- playlistVideoId
- poster
- Promise
- refNode\*
- refNodeInsert
- videoId
- Constants
- Base URL
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.
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.
It _may_ work for v5.x players in some configurations, but this is not a supported use-case.
sh
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.$3
This is the most modern use-case.`js
import brightcovePlayerLoader from '@brightcove/player-loader';brightcovePlayerLoader();
`
$3
When using with CommonJS or Browserify, install @brightcove/player-loader via npm and require the library as you would any other module:`js
var brightcovePlayerLoader = require('@brightcove/player-loader');brightcovePlayerLoader();
`$3
> 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:`js
require(['@brightcove/player-loader'], function(brightcovePlayerLoader) {
brightcovePlayerLoader();
});
`$3
> 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:
`html
`Usage
> Note: If you want to use this with React, we have an official react component called @brightcove/react-player-loaderThe 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.$3
This is a minimal example, using only the required parameters, which will load a Video Cloud account's default player:`js
brightcovePlayerLoader({
refNode: someElement,
accountId: '123456789'
});
`This is a more complete example, using some optional parameters and handling the returned
Promise:`js
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!
});
`$3
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:`
`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._
$3
When used with [the related webpack plugin][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.
$3
By default, this library will look for a global Promise. However, you can explicitly provide a Promise implementation via the Promise parameter:`js
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:`js
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][vjs-player] and for 'iframe' embeds, it will be the