Brightcove Player Loader

Player Loader の概要

Brightcove Player のユーザーで、Videoタグ埋め込みコードや iframe プレーヤー実装をコピー & ペーストしたくない場合、このモジュールを Web アプリケーションに組み込み、Brightcove Player をダウンロードして埋め込むための統合コードを書く必要なく、プレーヤーを利用できるようにします。このツールは、任意の公開済み Brightcove Player をダウンロードして DOM に埋め込める Brightcove ライブラリとして問題を解決します。

このライブラリは、Chrome、Firefox、Edge、Safari といった一般的な最新ブラウザをサポートしています。

本書では Brightcove Player Loader の使用例を紹介します。詳細は、ライブラリの brightcove / player-loader GitHub リポジトリを参照してください。

Brightcove Player と併せて利用できる webpack プラグインも存在します。詳細は player-loader-webpack-plugin の GitHub リポジトリを参照してください。

インストール

このライブラリは NPM を使用して次のようにインストールします。

      npm install --save @brightcove/player-loader

ライブラリの読み込み

利用方法に応じたライブラリの読み込み方法については、GitHub リポジトリを参照してください。

Promise を使用した実装

JavaScript の Promise をライブラリと併用できます。Promise は必須ではありませんが推奨されています。デフォルトでは、このライブラリはグローバル Promise を探しますが、本書で後述する Promise パラメーターを使用して明示的に実装を指定することもできます。

以下は Promise を利用した実装例です。重要なポイントは、Promise の then 内で var myPlayer = success.ref; を使用することで、プレーヤーへの参照を取得することです。

      <!doctype html>
      <html>
      
      <head>
        <meta charset="UTF-8">
        <title>Untitled Document</title>
        <style>
          .video-js {
            height: 344px;
            width: 610px;
          }
        </style>
      
      </head>
      
      <body>
        <script src="brightcove-player-loader.min.js"></script>
      
        <div id="theDiv">
        </div>
      
        <script>
          brightcovePlayerLoader({
            refNode: document.querySelector('#theDiv'),
            accountId: '1752604059001',
            playerId: 'wHBRh9M3o',
            videoId: '4607357817001'
          })
          .then(function(success) {
            var myPlayer = success.ref;
            console.log('success', success);
            myPlayer.on('loadedmetadata',function(){
              myPlayer.muted(true);
              myPlayer.play();
            });
          })
          .catch(function(error) {
            console.log('error', error);
          })
        </script>
      
      </body>
      
      </html>

コールバックを使用した実装

Brightcove Player Loader は、onSuccess および onFailure コールバック関数を利用して実装することもできます。

以下は、コールバックを使用したライブラリ実装の例です。重要なポイントは、onSuccess コールバック関数内で var myPlayer = success.ref; を使用してプレーヤーへの参照を取得することです。

        <!doctype html>
        <html>
        
        <head>
          <meta charset="UTF-8">
          <title>Untitled Document</title>
          <style>
            .video-js {
              height: 344px;
              width: 610px;
            }
          </style>
        
        </head>
        
        <body>
          <script src="brightcove-player-loader.min.js"></script>
        
          <div id="theDiv">
          </div>
        
          <script>
          brightcovePlayerLoader({
            refNode: document.querySelector('#theDiv'),
            accountId: '1752604059001',
            playerId: 'wHBRh9M3o',
            videoId: '4607357817001',
            onSuccess: function(success) {
              var myPlayer = success.ref;
              console.log('success', success);
              myPlayer.on('loadedmetadata',function(){
                myPlayer.muted(true);
                myPlayer.play();
              });
            },
            onFailure(error) {
              console.log('error', error);
            }
          });
          </script>
        
        </body>
        
        </html>

再生制限の使用

再生制限（Playback Restrictions）を Brightcove Player Loader と併用するには、プレーヤーへの参照を取得し、JSON Web Token（JWT）をプレーヤーに渡すだけで利用できます。

以下はその例です：

        <!DOCTYPE html>
        <html lang="en">
              
        <head>
            <title>Brightcove Player</title>
            <meta charset="UTF-8">
            <script crossorigin
                src="player-loader/dist/brightcove-player-loader.min.js"></script>
        </head>
              
        <body>
            <main>
                <h1>Brightcove Player</h1>
                <div id="theDiv"></div>
            </main>
        </body>
        
        <script>
            var myJwtToken = "your jwt token";
            var myVideoId = "your video Id";
              
            // +++ Brightcove Player の追加 +++
            brightcovePlayerLoader({
                refNode: document.querySelector('#theDiv'),
                accountId: 'your account Id',
                playerId: 'your player Id',
                onSuccess: function (success) {
                    // BC プレーヤーへの参照を取得
                    var myPlayer = success.ref;
                    console.log('success', success);
                      
                    myPlayer.ready(function () {
                        // 本来はプレーヤー設定で行うべき項目
                        myPlayer.catalog.setPolicyKey(null);
                        myPlayer.catalog.setBcovAuthToken(myJwtToken);
        
                        myPlayer.catalog.get({
                            id: myVideoId,
                            type: 'video'
                        })
                        .then(function (data) {
                            myPlayer.catalog.load(data);
                            myPlayer.muted(true);
                            myPlayer.play();
                        })
                        .catch(function (error) {
                            throw new Error(error);
                        });
                    });
                },
                onFailure(error) {
                    console.log('error', error);
                }
            });
        </script>
        </html>

利用可能なパラメーター

Name: accountId

Data Type: string | number

Description:
Video Cloud のアカウント ID。

Name: applicationId

Data Type: string

Description:
生成される埋め込みコードに適用されるアプリケーション ID。

Name: catalogSearch

Data Type: string | Object

Description:
実行する Video Cloud カタログ検索を指定します。単純な文字列検索、または Catalog の getSearch() メソッドに一致するオブジェクトを指定できます。JSON 形式にシリアライズできない非文字列の値が指定された場合、このパラメーターは無視されます。

Name: catalogSequence

Data Type: Array | Object

Description:
実行する Video Cloud カタログシーケンスを指定します。詳細は Catalog の getLazySequence() メソッドを参照してください。JSON 形式にシリアライズできない非文字列の値が指定された場合、このパラメーターは無視されます。

Name: embedId

Data Type: string

Description:
Brightcove Player の埋め込み ID。デフォルト値は 'default' です。ほとんどのユーザーはデフォルト値で問題ありません。

Name: embedOptions

Data Type: Object

Description:
埋め込みコード生成時に利用する各種オプションを指定します。以下のような項目があります。

`embedOptions.pip`	boolean	`true` の場合、埋め込みコードを `<div class="vjs-pip-container">` 要素でラップします。これは、Brightcove Picture-in-Picture プラグインを利用する必要がある場合に使用します。デフォルト値は `false` です。
`embedOptions.playlist`	boolean	`true` の場合、埋め込みの後に `<div class="vjs-playlist">` 要素が追加されます。これは、Brightcove プレイリスト UI プラグインを利用する必要がある場合に使用します。デフォルト値は `false` です。
`embedOptions.responsive`	boolean \| Object	intrinsic ratio ラッパー方式を用いて、レスポンシブ対応のプレーヤーを生成するために使用します。`true` を指定すると、コンテナ幅いっぱいに表示される 16:9 のアスペクト比を持つレスポンシブな埋め込みコードが生成されます。デフォルト値は `false` です。オブジェクトを指定すると、以下のサブプロパティでカスタマイズできます。 `aspectRatio`：16:9 以外のアスペクト比（例：'4:3'）を指定するための文字列。 `maxWidth`：プレーヤーの最大幅を制限するための文字列。ピクセルなどの CSS 単位（例：'960px'）を使用します。
`embedOptions.unminified`	boolean	`true` の場合、縮小されていない（un-minified）バージョンのプレーヤーを使用します。デバッグには有用ですが、プレーヤーのダウンロードサイズが大きくなるため、本番環境での使用は推奨されません。デフォルト値は `false` です。

Name: embedType

Data Type: string

Description:
生成する埋め込みコードのタイプを指定します。次のいずれかの値を指定します。

'Videoタグ' または brightcovePlayerLoader.EMBED_TYPE_IN_PAGE：in-page 埋め込みコードとも呼ばれ、プレーヤーをトップレベルの Web ページ内に直接挿入します。
'iframe' または brightcovePlayerLoader.EMBED_TYPE_IFRAME：Basic 埋め込みコードとも呼ばれ、プレーヤーを <iframe> 要素として挿入します。

デフォルト値は 'in-page' です。

Name: onEmbedCreated

Data Type: Function (element)

Description:
生成された埋め込み要素（video-js 要素または iframe 要素）が DOM に挿入される前、または embedOptions の結果としてカスタマイズされる前、さらにプレーヤーがダウンロード・初期化される前に、埋め込み要素をカスタマイズするためのコールバックです。埋め込み要素を変更してもよく、このコールバックが要素を返した場合、その要素が埋め込み要素として使用されます。ユースケースとしては、属性の追加・削除や、ソースやトラックなどの子要素の追加があります。

Name: onFailure

Data Type: Function(Error)

Description:
Promise が利用できない、または利用したくない場合に、エラー時の処理を行うためのコールバック関数です。この関数を渡すと、Promise は返されません。単一の Error オブジェクトが引数として渡されます。この関数の戻り値は無視されます。

Name: onSuccess

Data Type: Function(Object)

Description:
Promise が利用できない、または利用したくない場合に、成功時の処理を行うためのコールバック関数です。この関数を渡すと、Promise は返されません。単一の Success オブジェクトが引数として渡されます。この関数の戻り値は無視されます。

Name: options

Data Type: Object

Description:
プレーヤー作成時に渡される Video.js のオプションオブジェクトです。これらのオプションは、Brightcove Player 設定で指定された内容より優先されます。このパラメーターは iframe 埋め込みでは使用できません。

Name: playerId

Data Type: string

Description:
Brightcove Player のプレーヤー ID。デフォルトは 'default' です。

Name: playlistId

Data Type: string | number

Description:
Video Cloud プレイリスト ID、またはプレイリストの参照 ID。

Name: playlistVideoId

Data Type: string | number

Description:

playlistId で指定されたプレイリスト内に存在する Video Cloud の動画 ID を指定します。playlistId が指定されていない場合、このパラメーターは無視されます。

Name: Promise

Data Type: Function(Function)

Description:
Promise 実装を明示的に指定するために使用します。指定された場合、グローバルの Promise の代わりに使用されます。デフォルトは window.Promise です。

Name: refNode

Data Type: Element | string

Description:
必須
プレーヤーが埋め込まれる DOM 要素です。DOM 要素として指定しない場合は、文字列として指定でき、その文字列は document.querySelector に渡されます。

Name: refNodeInsert

Data Type: string

Description:
参照 DOM 要素（refNode で指定）に対して、プレーヤーをどの位置に挿入するかを指定します。以下のいずれかの値を指定します。

'append' または brightcovePlayerLoader.REF_NODE_INSERT_APPEND：プレーヤーは参照ノードの最後の子要素として挿入されます。
'prepend' または brightcovePlayerLoader.REF_NODE_INSERT_PREPEND：プレーヤーは参照ノードの最初の子要素として挿入されます。
'before' または brightcovePlayerLoader.REF_NODE_INSERT_BEFORE：プレーヤーは参照ノードの直前の兄弟要素として挿入されます。
'after' または brightcovePlayerLoader.REF_NODE_INSERT_AFTER：プレーヤーは参照ノードの直後の兄弟要素として挿入されます。
'replace' または brightcovePlayerLoader.REF_NODE_INSERT_REPLACE：参照ノードは削除され、その位置にプレーヤーが挿入されます。

Name: videoId

Data Type: string | number

Description:
Video Cloud の動画 ID、または動画の参照 ID。