On This Page

Plugin Registry

In this topic, you will learn how the Plugin Registry can be used to track and manage the plugins your Brightcove Player is using.

What is the Plugin Registry?

The Plugin Registry is a section of the Player Management API devoted to storing information about Brightcove plugins. The registry serves as a reference for all versions of each stored plugin, as well as the scripts and stylesheets associated with each. Player configuration leverages the Plugin Registry, displaying the current plugin version, and also allowing you to specify a plugin version.

The Plugin Registry is implemented in version 2 of the Player Management API.

Advantages

The advantages of the Plugin Registry for Brightcove Player users are three fold:

You can see exactly what version of plugin is being used with your player, as well as the specific JavaScript and CSS files associated with that specific plugin version.

You can configure plugins to be automatically updated when new versions are released that are compatible with your player version.

If for some reason you choose to keep a player on a specific player version, your plugins will remain on the same specific versions for that player when it was locked. You do not have to worry about a plugin being upgraded to a version that is not compatible with your player version.

Current eligible plugins

The following table shows the Brightcove supplied plugins that work with the Plugin Registry. The Plugin Registry ID will be used with player configuration in conjunction with the Player Management API. Numerous examples will be shown in this document.

Plugin Name

Plugin Registry ID

Custom Endscreen

@brightcove/videojs-custom-endscreen

IMA3 Advertising

@brightcove/videojs-ima3

Quality Selection

@brightcove/videojs-quality-menu

Overlay

@brightcove/videojs-overlay

Playlist UI

@brightcove/videojs-bc-playlist-ui

Social

@brightcove/videojs-social

Specify use of a plugin

To specify the use of a plugin, in your player creation you simply supply the registry ID for the desired plugin. You must specify a version number, either a major version that will auto update (for example 2.x) or a minor version (for example 2.0.10) which will not auto update. Details on setting the version appear later in this document. You can also provide options for the plugin, if any.

Information on the created player is returned by the Player Management API. You can use the url value returned, change the index.html to config.json and browse that URL to see the configuration of the published player.

In the configuration of the published player you see the information on the plugin. Note that a specific version of the plugin is displayed, along with the corresponding values for the JavaScript and CSS files.

Depending on the template version your player is using, the scripts and stylesheets that get injected may either appear at the top level of the player configuration or nested in the plugins object.

Specify specific major version

You can configure a player to use the latest version of the plugin for a specific major version compatible with the player you are using. When you do this, and minor versions of the plugin are released, the plugin will automatically be updated to the latest minor version.

For example, if you want your player to contain the latest compatible version of the custom endscreen plugin for major version 2 of the plugin you would use the following:

Non-compatible assignments

If you try to assign an incompatible plugin to a player, or change the version of a player so a previously assigned plugin is no longer compatible, errors will occur. The errors are detailed here.

Assign plugin to non-compatible player

If at any time, either in player creation or update, you try to specify a plugin version not compatible with a player version, you will get an error. For instance, here is a response from the API when trying to assign a non-compatible, older plugin to a new player:

{
"message": "There are no versions of the plugin that match the specified major version. The major version specified was 1.x for plugin @brightcove/videojs-bc-playlist-ui",
"error_code": "PLAYER_MANAGEMENT_ERROR",
}

Change player version so non-compatible with plugin

If you try to change the version of an existing player, and the player already has a plugin that is not compatible with the newly assigned version of the player, you will get an error similar to the following:

As you can see in the player configuration, a plugin loaded in Studio will be updated using the major version behavior, that is, minor version updates will automatically be applied.

Updating registry information

You can update plugin registry information for a player using standard procedures. For instance, the following curl statement uses the HTTP PATCH method to change a plugin from a specific version to major version update behavior:

Note: Adding a query string in the form ?template_version=$SVTVERSION to the endpoint will result in a response containing only plugin versions compatible with the specified single-video-template version. For example, to get only plugin versions compatible with Brightcove Player template 6.7.0, use ?template_version=6.7.0 .

Although not shown in this response, you can also see a before_template-version property and corresponding value. This will appear for older plugins and sets the latest player template version with which that plugin version is compatible. The minimum_template_version and before_template-version work together to set the range of player template versions with which the plugin is compatible.