Last week, we pre-released the Brightcove Player 6.22. This version brings some useful API changes that customers and integrators may be interested in.
EXPANDED AUTOPLAY CONFIGURATIONS
As part of Video.js 7.1.0, we’ve made the autoplay configuration more powerful.
Currently, this configuration can be either true or false, which is similar to setting the autoplay attribute (or not) on the <video> element. When it’s true, the player will attempt to autoplay and, if the browser prevents it, will display the so-called Big Play Button.
However, there are cases where customers might want to improve their chances of autoplay succeeding. The expanded autoplay configuration can now accept several new string values (in addition to the existing boolean values).
ANY
Adding the configuration, {"autoplay": "any"}, will cause the player to call play() on the loadstart event. If playback fails, the player will mute itself and call play() again. If playback still fails, the previous state of muted will be restored.
This value offers the most complete solution – when non-muted autoplay is preferred, but muted autoplay is acceptable.
MUTED
Adding the configuration, {"autoplay": "muted"}, will cause the player to mute itself and then call play() on the loadstart event. If playback fails, the previous state of muted will be restored.
This value is the most likely to succeed on the first attempt – when muted autoplay is preferred.
PLAY
Finally, adding the configuration, {"autoplay": "play"}, will cause the player to call play() on the loadstart event.
This has a similar chance of succeeding as setting autoplay: true.
CATALOG PLUGIN IMPROVEMENTS
NOTE: For the time being, these features will only be available via the catalog plugin methods – not via configuration or data- attributes.
STANDARDIZING THE API
The biggest change we made to the catalog plugin is part of an effort to standardize a library API that has grown over the years to have minor inconsistencies between its methods.
The core of this effort was to add a common get() method that works for all request types and takes a single argument: a conventional catalog parameters object (described below). The get() method will return a Promise object.
For example, fetching a video with the common get() method could look like this:
// Request a video from the Playback API.
player.catalog.get({
type: 'video',
id: '123456789',
adConfigId: 'abc123'
})
// The request succeeded, load the video data into the player.
.then(function(data) {
player.catalog.load(data);
})
// The request failed.
.catch(function(err) {
videojs.log.error(err);
});
Additionally, this effort includes backward-compatible changes to the pre-existing methods – getVideo, getPlaylist, getSearch, getSequence, and getLazySequence. These changes are:
getVideo, getPlaylist, and getSearch can now take a catalog parameters object as their first argument as an alternative to their current implementations.- The third argument to all methods,
adConfigId, is now deprecated. Use a catalog parameters object with an adConfigId property instead.
- Each method still expects a second
callback argument and returns an XMLHttpRequest object. If a Promise is preferred, use the common get() method.
It’s important to note that these changes are all backward-compatible. No existing code needs to change!
For example, the above video request could still be made in the old style:
// Request a video from the Playback API.
player.catalog.getVideo('123456789', function(err, data) {
// The request failed.
if (err) {
return;
}
// The request succeeded, load the video data into the player.
player.catalog.load(data);
}, 'abc123');
CATALOG PARAMETERS OBJECTS
This is a convention that we hope to use as the basis for describing requests to the Playback API from the Brightcove Player going forward.
It is supported as the first argument to all get* methods.
All values should be strings.
| Name |
Description |
type |
The type of request to make. Must be one of 'video', 'playlist', or 'search'. |
accountId |
The account ID from which to get data. This will default to the account ID of the player. |
policyKey |
The policy key for this account. This will default to the policy key of the player. |
id |
A video or playlist ID or reference ID prefixed by 'ref:'. Required for video and playlist requests! |
q |
A search query. Required for search requests (except where id is used in its deprecated form), ignored for others. |
adConfigId |
A Video Could SSAI ad configuration ID. |
tveToken |
An optional TVE token to be sent as a query string parameter. |
limit |
Supported for playlist and search types only. Limit the number of videos returned. |
offset |
Supported for playlist and search types only. The number of videos to skip. |
sort |
Supported for search type only. How the videos should be sorted for searches. |
NOTE: For backward-compatibility, there are two additional, deprecated uses of the id parameter. For search types, the id parameter is supported as a search query instead of q. For search types and sequences, the id parameter can contain a sub-object, which is also a catalog parameters object.
PLAYLIST LIMIT AND OFFSET
As a consequence of this standardization, we added support for limit and offset query parameters for playlists. This allows customers to implement longer playlist sizes as well as pagination through their playlists. These can be implemented in the getPlaylist() function like this:
// Request a playlist from the Playback API.
player.catalog.getPlaylist({
id: '123456789',
limit: '25',
offset: '0'
}, function(err, data) {
// If there is an error object, the request failed.
if (err) {
return;
}
// The request succeeded, load the playlist data into the player.
player.catalog.load(data);
});
CONCLUSION
We are pretty excited about these new features in Brightcove Player 6.22. This version is currently in pre-release status, but we’ll be shipping it out to all auto-updating players very soon.
