プラグイン レジストリ

このトピックでは、Brightcove Player が使用しているプラグインを追跡および管理するために、プラグイン レジストリをどのように利用できるかを説明します。

プラグイン レジストリとは

プラグイン レジストリは、Brightcove プラグインに関する情報を保存するために用意された Player Management API のセクションです。このレジストリは、保存されている各プラグインのすべてのバージョンと、それぞれに関連付けられたスクリプトおよびスタイルシートの参照情報として機能します。プレーヤー設定ではプラグイン レジストリを利用して、現在のプラグインバージョンを表示するとともに、使用するプラグインのバージョンを指定することもできます。

利点

Brightcove Player ユーザーにとってのプラグイン レジストリの利点は、主に次の 3 点です。

  • プレーヤーで使用されているプラグインの正確なバージョンと、その特定のプラグイン バージョンに関連付けられている JavaScript および CSS ファイルを確認できます。
  • プレーヤーのバージョンと互換性のある新しいバージョンがリリースされた際に、プラグインを自動的に更新するよう設定できます。
  • 何らかの理由で特定のプレーヤー バージョンに固定することを選択した場合でも、そのプレーヤーがロックされた時点の特定バージョンのままプラグインが維持されます。プレーヤーのバージョンと互換性のないプラグインにアップグレードされる心配はありません。

現在利用可能なプラグイン

以下の表は、プラグインレジストリで利用可能な Brightcove 提供のプラグインを示しています。Plugin Registry ID は、Player Management API と組み合わせてプレーヤー設定で使用されます。本ドキュメントでは、数多くの例を紹介します。

説明 Plugin Registry ID プラグイン名
Adobe Analytics プレーヤープラグイン @brightcove/videojs-bc-aa bcAa
AirPlay と統合するための Brightcove Player 用 Video.js プラグイン @brightcove/videojs-bc-airplay bcAirplay
Google Analytics プレーヤー プラグイン @brightcove/videojs-bc-ga bcGa
Google Tag Manager プレーヤー プラグイン @brightcove/videojs-bc-gtm bcGtm
videojs-playlist-ui に対する Brightcove 独自のカスタマイズ @brightcove/videojs-bc-playlist-ui bcPlaylistUi
Tealium プレーヤー プラグイン @brightcove/videojs-bc-tealium bcTealium
Brightcove Player 用 Chromecast Receiver プラグイン @brightcove/videojs-chromecast-receiver chromecastReceiver
video.js 用のカスタム エンドスクリーン @brightcove/videojs-custom-endscreen customEndscreen
dash.js および Silverlight を使用した DRM 付き MPEG-DASH、ならびに HLS FairPlay DRM のクロスブラウザ再生をサポート @brightcove/videojs-drm eme
Brightcove Player 用 FreeWheel プラグイン @brightcove/videojs-freewheel FreeWheelPlugin
video.js 向け Google Interactive Media Ads（IMA）v3 サポート @brightcove/videojs-ima3 ima3
Brightcove Player を Kollective eCDN と統合するためのプラグイン @brightcove/videojs-kollective kollective
video.js 用オーバーレイ @brightcove/videojs-overlay overlay
Brightcove Player でピクチャー・イン・ピクチャー モードを有効にするプラグイン @brightcove/videojs-pip pip
動画の終了時にプレイリストを表示する Brightcove Player 用プラグイン @brightcove/videojs-playlist-endscreen playlistEndscreen
品質選択メニュー UI @brightcove/videojs-quality-menu qualityMenu
video.js 向けソーシャル共有連携 @brightcove/videojs-social social
SSAI ストリームの再生を実装する Brightcove Player 用プラグイン @brightcove/videojs-ssai ssai
進行バー上にサムネイル画像を表示するためのプラグイン @brightcove/videojs-thumbnails thumbnails

プラグインの使用を指定する

プラグインの使用を指定するには、プレーヤー作成時に使用したいプラグインのレジストリ ID を指定するだけです。バージョン番号の指定は必須で、自動更新されるメジャーバージョン（例：2.x）か、自動更新されないマイナーバージョン（例：2.0.10）のいずれかを指定します。バージョン設定の詳細については、本ドキュメントの後半で説明します。また、必要に応じてプラグイン用の options を指定することもできます。

    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

作成されたプレーヤーに関する情報は Player Management API から返されます。返却された url の値で、index.html を config.json に置き換えてその URL にアクセスすると、公開されたプレーヤーの設定内容を確認できます。

    {
      "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>"
    }

公開されたプレーヤーの設定では、プラグインに関する情報を確認できます。対応する JavaScript および CSS ファイルの値とともに、実際に使用されている特定のプラグイン バージョンが表示されている点に注意してください。

    {
      "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"
      }
    }

特定のメジャー バージョンを指定する

使用しているプレーヤーと互換性のある、特定のメジャーバージョンにおける最新のプラグインを使用するように、プレーヤーを設定できます。この設定を行うと、プラグインのマイナー バージョンがリリースされた際に、自動的に最新のマイナー バージョンへ更新されます。

たとえば、カスタム エンドスクリーン プラグインのメジャー バージョン 2における最新の互換バージョンをプレーヤーに含めたい場合は、次のように指定します。

  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

生成される設定は、次のような内容になります。

  "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"
  ],

特定のバージョンを指定する

使用するプラグインの特定のバージョンを指定することもできます。この場合、プラグインはいかなる状況でも自動更新されません。必要に応じて、手動で更新を行う必要があります。

プラグインのバージョンを固定するには、プレーヤー作成時にバージョンを指定するだけです。

  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

プレーヤーの設定には、指定したバージョンが JavaScript および CSS ファイルとともに反映されます。

  "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"
  ],

非互換の割り当て

互換性のないプラグインをプレーヤーに割り当てようとした場合、またはプレーヤーのバージョンを変更した結果、以前に割り当てられていたプラグインが互換性を失った場合、エラーが発生します。ここでは、そのエラー内容について説明します。

非互換のプレーヤーにプラグインを割り当てる

プレーヤーの作成時または更新時に、プレーヤーのバージョンと互換性のないプラグイン バージョンを指定しようとすると、エラーが返されます。たとえば、新しいプレーヤーに対して、互換性のない古いプラグインを割り当てようとした場合、API から次のようなレスポンスが返されます。

  {
    "message": "指定されたメジャー バージョンに一致するプラグインのバージョンが存在しません。指定されたメジャーバージョンは、プラグイン @brightcove/videojs-bc-playlist-ui の 1.x です",
    "error_code": "PLAYER_MANAGEMENT_ERROR"
  }

プラグインと非互換になるようにプレーヤー バージョンを変更する

既存のプレーヤーのバージョンを変更し、そのプレーヤーにすでに割り当てられているプラグインが、新しく指定したプレーヤー バージョンと互換性を持たない場合、次のようなエラーが返されます。

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

Studio で設定されたプラグイン

Studio 経由でプラグインが読み込まれている場合、そのプラグインは 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>これはエンド スクリーンのコンテンツです</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
    }
  }

プレーヤー設定から分かるように、Studio で読み込まれたプラグインはメジャー バージョン指定の挙動で更新されます。つまり、マイナーバージョンの更新は自動的に適用されます。

レジストリ情報の更新

標準的な手順を使用して、プレーヤーのプラグイン レジストリ情報を更新できます。たとえば、次の curl ステートメントでは、HTTP の PATCH メソッドを使用して、プラグインを特定のバージョン指定からメジャー バージョン自動更新の挙動に変更しています。

  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

変更後は、必ずプレーヤーを公開する必要がある点に注意してください。

プラグイン レジストリ API

Player Management API には、レジストリからプラグイン情報を取得するための 2 つの新しいエンドポイントが追加されています。これにより、次の操作が可能になります。

  • レジストリ内のすべてのプラグインを取得する
  • 特定のプラグインの情報を取得する

すべてのプラグインを取得

現在レジストリに登録されているプラグイン情報を取得するには、次を使用します。

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

返される情報は、次のような形式になります。

  [{
    "documentation": "https://support.brightcove.com/configuring-adobe-analytics-event-tracking",
    "description": "Adobe Analytics プレーヤープラグイン",
    "id": "@brightcove/videojs-bc-aa",
    "name": "bcAa",
    "current_version": "1.x"
  }, {
    "documentation": "https://support.brightcove.com/configuring-google-analytics-event-tracking",
    "description": "Google Analytics プレーヤープラグイン",
    "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 プレーヤープラグイン",
    "id": "@brightcove/videojs-bc-gtm",
    "name": "bcGtm",
    "current_version": "1.x"
  }, {
    "documentation": "https://support.brightcove.com/playlist-ui-plugin",
    "description": "videojs-playlist-ui に対する Brightcove のカスタマイズ",
    "id": "@brightcove/videojs-bc-playlist-ui",
    "name": "bcPlaylistUi",
    "current_version": "3.x"
  }, {
    "documentation": "https://support.brightcove.com/tealium-plugin-brightcove-player",
    "description": "Tealium プレーヤープラグイン",
    "id": "@brightcove/videojs-bc-tealium",
    "name": "bcTealium",
    "current_version": "1.x"
  }, {
    "documentation": "https://support.brightcove.com/beta-chromecast-plugin-brightcove-player",
    "description": "Brightcove Player 用 Chromecast Receiver プラグイン",
    "id": "@brightcove/videojs-chromecast-receiver",
    "name": "chromecastReceiver",
    "current_version": "1.x"
  }, {
    "documentation": "https://support.brightcove.com/custom-endscreen-plugin",
    "description": "video.js 用のカスタムエンドスクリーン",
    "id": "@brightcove/videojs-custom-endscreen",
    "name": "customEndscreen",
    "current_version": "2.x"
  }, {
    "documentation": "https://support.brightcove.com/configuring-brightcove-player-drm",
    "description": "dash.js と silverlight を使用した DRM 付き MPEG-DASH、および HLS Fairplay DRM のクロスブラウザ対応",
    "id": "@brightcove/videojs-drm",
    "name": "eme",
    "current_version": "5.x"
  }, {
    "documentation": "https://support.brightcove.com/advertising-ima3-plugin",
    "description": "video.js 用 Google Interactive Media Ads (IMA) v3 サポート",
    "id": "@brightcove/videojs-ima3",
    "name": "ima3",
    "current_version": "3.x"
  }, {
    "documentation": "https://support.brightcove.com/display-overlay-plugin",
    "description": "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": "Brightcove Player でピクチャーインピクチャーモードを有効にするプラグイン",
    "id": "@brightcove/videojs-pip",
    "name": "pip",
    "current_version": "1.x"
  }, {
    "documentation": "https://support.brightcove.com/manual-rendition-selection-plugin",
    "description": "画質選択メニュー UI",
    "id": "@brightcove/videojs-quality-menu",
    "name": "qualityMenu",
    "current_version": "1.x"
  }, {
    "documentation": "https://support.brightcove.com/social-media-plugin",
    "description": "video.js 用ソーシャル共有連携",
    "id": "@brightcove/videojs-social",
    "name": "social",
    "current_version": "3.x"
  }, {
    "documentation": "https://support.brightcove.com/advertising-ssai-plugin",
    "description": "SSAI ストリームの再生を実装する Brightcove Player 用プラグイン",
    "id": "@brightcove/videojs-ssai",
    "name": "ssai",
    "current_version": "1.x"
  }]

特定のプラグイン情報を取得

特定のプラグインに関する情報を取得するには、次を使用します。プラグイン名は URL エンコードする必要がある点に注意してください。そのため、@brightcove/videojs-ima3 の代わりに %40brightcove%2fvideojs-ima3 を使用します。

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

返される情報は、次のような形式になります。

    {
      "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": "video.js 用 Google Interactive Media Ads (IMA) v3 サポート",
      "id": "@brightcove/videojs-ima3",
      "name": "ima3",
      "current_version": "3.x"
    }

このレスポンスには表示されていませんが、before_template-version プロパティとそれに対応する値も確認できます。これは主に古いプラグインに対して表示され、そのプラグイン バージョンと互換性のある最新のプレーヤー テンプレート バージョンを示します。minimum_template_version と before_template-version は組み合わせて使用され、プラグインが互換性を持つプレーヤー テンプレート バージョンの範囲を定義します。