Plugin Registry

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.

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.

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.

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request POST \
      --data '{
        "name": "Plugin Registry Test Player",
        "configuration": {
          "video_cloud": {
            "video": "4093372393001"
          },
          "plugins": [
           {
              "registry_id": "@brightcove/videojs-custom-endscreen",
              "version": "2.x",
              "options": { "content": "<strong>Content</strong> for <em>custom</em> end screen" }
           }
          ]
        }
      }' \
      https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players
          

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.

    {
      "id": "rkGD9W22Ob",
      "url": "http://players.brightcove.net/1507807800001/rkGD9W22Ob_default/index.html",
      "embed_code": "<iframe src='//players.brightcove.net/1507807800001/rkGD9W22Ob_default/index.html' allowfullscreen allow='encrypted-media'></iframe>",
      "embed_in_page": "http://players.brightcove.net/1507807800001/rkGD9W22Ob_default/in_page.embed",
      "preview_url": "http://preview-players.brightcove.net/v2/accounts/1507807800001/players/rkGD9W22Ob/preview/embeds/default/master/index.html",
      "preview_embed_code": "<iframe src='//preview-players.brightcove.net/v2/accounts/1507807800001/players/rkGD9W22Ob/preview/embeds/default/master/index.html' allowfullscreen allow='encrypted-media'></iframe>"
    }

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.

    {
      "account_id": "1507807800001",
      "compatibility": true,
      "embed_id": "default",
      "player": {
        "template": {
          "name": "single-video-template",
          "version": "6.7.0"
        }
      },
      "player_id": "SyITgzdjb",
      "player_name": "Plugin Registry Test Player",
      "plugins": [{
        "injected_version": "2.0.10",
        "name": "customEndscreen",
        "registry_id": "@brightcove/videojs-custom-endscreen",
        "version": "2.x"
      }],
      "scripts": [
        "//players.brightcove.net/videojs-custom-endscreen/2.0.10/videojs-custom-endscreen.min.js"
      ],
      "stylesheets": [
        "//players.brightcove.net/videojs-custom-endscreen/2.0.10/videojs-custom-endscreen.css"
      ],
      "updated_at": "2017-09-26T17:39:10.080Z",
      "video_cloud": {
        "policy_key": "BCpkADawqM3hOj9...FDx1yFTvWX7m",
        "video": "4093372393001"
      }
    }

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:

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request POST \
      --data '{
        "name": "Plugin Registry Test Player",
        "configuration": {
          "video_cloud": {
            "video": "4093372393001"
          },
          "plugins": [
            {
              "registry_id": "@brightcove/videojs-custom-endscreen",
              "version": "2.x"
            }
          ]
        }
      }' \
      https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players

The resulting configuration will appear similar to the following:

    "plugins": [{
      "injected_version": "2.0.10",
      "name": "customEndscreen",
      "registry_id": "@brightcove/videojs-custom-endscreen",
      "version": "2.x"
    }],
    "scripts": [
      "//players.brightcove.net/videojs-custom-endscreen/2.0.10/videojs-custom-endscreen.min.js"
    ],
    "stylesheets": [
      "//players.brightcove.net/videojs-custom-endscreen/2.0.10/videojs-custom-endscreen.css"
    ],

Specify specific version

You can specify a specific version of the plugin to use. If you do this the plugin will NOT be automatically updated under any circumstances, so you will have to manually update if needed.

To lock a version of the plugin, simply specify the version when creating the player:

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request POST \
      --data '{
        "name": "Plugin Registry Test Player",
        "configuration": {
          "video_cloud": {
            "video": "4093372393001"
          },
          "plugins": [
            {
              "registry_id": "@brightcove/videojs-overlay",
              "version": "1.0.2"
            }
          ]
        }
      }' \
      https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players
          

The player configuration will reflect the specific version, as well as in the JavaScript and CSS files:

    "plugins": [{
      "name": "overlay",
      "registry_id": "@brightcove/videojs-overlay",
      "version": "1.0.2"
    }],
    "scripts": [
      "//players.brightcove.net/videojs-overlay/1.0.2/videojs-overlay.min.js"
    ],
    "stylesheets": [
      "//players.brightcove.net/videojs-overlay/1.0.2/videojs-overlay.css"
    ],
          

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:

    {
      "error_code":"APPLICATION_ERROR",
      "message":"plugin \"@brightcove/videojs-ima3\" is not compatible with template 5.28.1"
    }
    

Studio configured plugin

If a plugin is loaded via Studio, the plugin will reflect new functionality in the Plugin Registry:

    {
      "account_id": "1507807800001",
      "compatibility": true,
      "embed_id": "default",
      "player": {
        "template": {
          "name": "single-video-template",
          "version": "6.7.0"
        }
      },
      "player_id": "SJajDfuiW",
      "player_name": "Plugin Registry Studio Configuration",
      "plugins": [{
        "injected_version": "2.0.10",
        "name": "customEndscreen",
        "options": {
          "content": "<h3>This is the endscreen content</h3>"
        },
        "registry_id": "@brightcove/videojs-custom-endscreen",
        "version": "2.x"
      }],
      "scripts": [
        "//players.brightcove.net/videojs-custom-endscreen/2.0.10/videojs-custom-endscreen.min.js"
      ],
      "stylesheets": [
        "//players.brightcove.net/videojs-custom-endscreen/2.0.10/videojs-custom-endscreen.css"
      ],
      "updated_at": "2017-09-26T18:09:31.940Z",
      "video_cloud": {
        "policy_key": "BCpkADawqM3YPJ...SjFagYpRxuoM8btiEoD",
        "video": null
      }
    }
          

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:

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request PATCH \
      --data '{
        "plugins": [{
          "registry_id": "@brightcove/videojs-custom-endscreen",
          "version": "2.x"
        }]
      }' \
      https://players.api.brightcove.com/v2/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration
          

Remember, you must publish your player after making a change.

Plugin registry API

Two new endpoints have been added to the Player Management API that enable retrieval of plugin information from the registry, which provide functionality for you to:

• Retrieve all plugins in the registry.
• Retrieve information on a specific plugin.

Get all plugins

Use the following to retrieve information about the plugins currently in the registry.

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request GET \
      https://players.api.brightcove.com/v2/plugins
          

The returned information will appear similar to the following:

    [{
      "documentation": "https://support.brightcove.com/configuring-adobe-analytics-event-tracking",
      "description": "Adobe Analytics Player Plugin",
      "id": "@brightcove/videojs-bc-aa",
      "name": "bcAa",
      "current_version": "1.x"
    }, {
      "documentation": "https://support.brightcove.com/configuring-google-analytics-event-tracking",
      "description": "Google Analytics Player Plugin",
      "id": "@brightcove/videojs-bc-ga",
      "name": "bcGa",
      "current_version": "1.x"
    }, {
      "documentation": "https://support.brightcove.com/google-tag-manager-plugin-brightcove-player",
      "description": "Google Tag Manager Player Plugin",
      "id": "@brightcove/videojs-bc-gtm",
      "name": "bcGtm",
      "current_version": "1.x"
    }, {
      "documentation": "https://support.brightcove.com/playlist-ui-plugin",
      "description": "Brightcove customizations to videojs-playlist-ui",
      "id": "@brightcove/videojs-bc-playlist-ui",
      "name": "bcPlaylistUi",
      "current_version": "3.x"
    }, {
      "documentation": "https://support.brightcove.com/tealium-plugin-brightcove-player",
      "description": "Tealium Player Plugin",
      "id": "@brightcove/videojs-bc-tealium",
      "name": "bcTealium",
      "current_version": "1.x"
    }, {
      "documentation": "https://support.brightcove.com/beta-chromecast-plugin-brightcove-player",
      "description": "A Chromecast Receiver plugin for the Brightcove Player",
      "id": "@brightcove/videojs-chromecast-receiver",
      "name": "chromecastReceiver",
      "current_version": "1.x"
    }, {
      "documentation": "https://support.brightcove.com/custom-endscreen-plugin",
      "description": "Custom endscreens for video.js.",
      "id": "@brightcove/videojs-custom-endscreen",
      "name": "customEndscreen",
      "current_version": "2.x"
    }, {
      "documentation": "https://support.brightcove.com/configuring-brightcove-player-drm",
      "description": "Cross-browser support for MPEG-DASH w/ DRM using dash.js and silverlight and HLS Fairplay DRM",
      "id": "@brightcove/videojs-drm",
      "name": "eme",
      "current_version": "5.x"
    }, {
      "documentation": "https://support.brightcove.com/advertising-ima3-plugin",
      "description": "Google Interactive Media Ads (IMA) v3 support for video.js",
      "id": "@brightcove/videojs-ima3",
      "name": "ima3",
      "current_version": "3.x"
    }, {
      "documentation": "https://support.brightcove.com/display-overlay-plugin",
      "description": "Overlay for video.js.",
      "id": "@brightcove/videojs-overlay",
      "name": "overlay",
      "current_version": "2.x"
    }, {
      "documentation": "https://support.brightcove.com/picture-picture-plugin-aka-floating-or-pinned",
      "description": "A plugin for enabling a Picture-In-Picture mode for the Brightcove Player",
      "id": "@brightcove/videojs-pip",
      "name": "pip",
      "current_version": "1.x"
    }, {
      "documentation": "https://support.brightcove.com/manual-rendition-selection-plugin",
      "description": "Quality Selection Menu UI",
      "id": "@brightcove/videojs-quality-menu",
      "name": "qualityMenu",
      "current_version": "1.x"
    }, {
      "documentation": "https://support.brightcove.com/social-media-plugin",
      "description": "Social sharing integrations for video.js.",
      "id": "@brightcove/videojs-social",
      "name": "social",
      "current_version": "3.x"
    }, {
      "documentation": "https://support.brightcove.com/advertising-ssai-plugin",
      "description": "A plugin for the Brightcove Player implementing playback of SSAI streams.",
      "id": "@brightcove/videojs-ssai",
      "name": "ssai",
      "current_version": "1.x"
    }]
          

Get specific plugin information

Use the following to retrieve information about a specific plugin. Note that the plugin name must be URL encoded, so instead of @brightcove/videojs-ima3 use %40brightcove%2fvideojs-ima3 .

    curl \
      --header "Content-Type: application/json" \
      --user $EMAIL \
      --request GET \
      https://players.api.brightcove.com/v2/plugins/%40brightcove%2fvideojs-ima3
          

The returned information will appear similar to the following:

    {
      "versions": [{
        "scripts": ["//players.brightcove.net/videojs-ima3/3/videojs.ima3.min.js"],
        "stylesheets": ["//players.brightcove.net/videojs-ima3/3/videojs.ima3.min.css"],
        "version_number": "3.x",
        "minimum_template_version": "6.0.0"
      }, {
        "minimum_template_version": "5.0.0",
        "version_number": "2.x",
        "stylesheets": ["//players.brightcove.net/videojs-ima3/2/videojs.ima3.min.css"],
        "scripts": ["//players.brightcove.net/videojs-ima3/2/videojs.ima3.min.js"]
      }, {
        "minimum_template_version": "1.14.0",
        "version_number": "1.x",
        "stylesheets": ["//players.brightcove.net/videojs-ima3/1/videojs.ima3.min.css"],
        "scripts": ["//players.brightcove.net/videojs-ima3/1/videojs.ima3.min.js"]
      }],
      "documentation": "https://support.brightcove.com/advertising-ima3-plugin",
      "description": "Google Interactive Media Ads (IMA) v3 support for video.js",
      "id": "@brightcove/videojs-ima3",
      "name": "ima3",
      "current_version": "3.x"
    }

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.