プレーヤー イベント

概要

Brightcove Player には、動画再生を制御するための多くのイベントがあります。本トピックでは、イベントのさまざまな種類について概要を説明します。

Brightcove Player のイベントの完全な一覧は、Player Methods/Events API リファレンス ドキュメントで確認できます。このドキュメントには、プレーヤーを構成する実際のコードに含まれているイベントが反映されています。

メディア イベント

HTML Living Standard ドキュメントは、HTML の開発や Web アプリケーションに必要な API に関する情報を得るための有用なリソースです。これは「リビング」ドキュメントであり、Web の進化に関心を持つ人々の成長するコミュニティである Web Hypertext Application Technology Working Group（WHATWG）によって、常に最新の状態に保たれています。

Brightcove Player は HTML フレームワーク上で動作しており、以下の メディア イベント がトリガーされます。

以下は、本ドキュメント内で使用されているイベントに関連する用語です。

blocked

MediaController は、再生が 一時停止 されている場合、blocked と見なされます。メディア要素は、そのコントローラーが blocked media controller である場合に blocked とされます。

MediaController

MediaController は、複数のメディア要素の再生を調整するオブジェクトです。

media element

media element は、音声データ、または映像と音声データをユーザーに提示します。

slaved

デフォルトでは、各メディア要素は MediaController を持ちません。メディア要素が MediaController に関連付けられると、そのコントローラーに slaved されていると言います。コントローラーは、slaved されている各メディア要素の再生速度と音量を変更します。slaved されている要素のいずれかが予期せず停止した場合、コントローラーは他の slaved 要素の再生も停止します。

バッファリングおよび QoS イベント

以下は、バッファリングおよびサービス品質（QoS）に関連するイベントの一部です。

起動イベント

プレーヤーが初期化され、動画を再生する準備を行う際には、いくつかのイベントが発生します。以下に、送出される順番でそれらのイベントを示します。

• loadstart: プレーヤーが初期化されたとき、または再生する新しいソースが指定されて再初期化された場合に送出されます。

• loadedmetadata: プレーヤーが初期の再生時間やサイズ情報を取得したとき、つまり最初のセグメントがダウンロードされたときに送出されます。ライブ動画の場合、loadedmetadata イベントはユーザーが再生をクリックするまで送出されません。これは、ライブ動画ではユーザーが再生をクリックするまでセグメントのダウンロードが開始されないためです。
• loadeddata: 現在の再生位置におけるデータがダウンロードされたときに送出されます。

以下の CodePen では、起動イベントをリッスンし、それらが送出される様子を確認できます。CodePen 上にマウスを合わせると、右下に表示される RERUN ボタンをクリックして、イベントが再度送出される様子を見ることができます。コードを試したい場合は、ヘッダー内の Edit on CODEPEN リンクをクリックして編集環境に移動してください。JS ボタンをクリックすると、イベント リスナーを追加している JavaScript を確認できます。

See the Pen Startup Events Demo by Brightcove Learning Services (@bcls) on CodePen.

ready() メソッド

ready() メソッドは、イベントのように見えますが、メソッドとして使用するという二面性を持っています。このメソッド／イベントは、プレーヤーがコマンドを受け取る準備ができたことを意味します。

ready() メソッドはイベント リスナーとは異なり、すでに ready イベントが発生している場合は、即座に ready() メソッドが実行されます。Brightcove Player を使った開発の開始点として、以下のように使用されることがよくあります。

      videojs.getPlayer('myPlayerID').ready(function(){
        var myPlayer = this;
      });

ready() と on('loadedmetadata',...) の比較

ready() は、たとえばプログラムでプラグインを追加するなど、プレーヤーと対話する場合には正しく機能します。一方、play() のように動画自体と即座に対話したい場合には、上記のコード スニペットは常に正しく動作するとは限りません。その場合は、loadedmetadata をリッスンして動画と対話する方法がより適切です。例を以下に示します。

      videojs.getPlayer('myPlayerID').on('loadedmetadata',function(){
        var myPlayer = this;
        myPlayer.play();
      });

まとめると、プレーヤーと対話する場合は次の方法を使用します。

      videojs.getPlayer('myPlayerID').ready()

プレーヤー内の動画と即座に対話したい場合は、次の方法を使用します。

      videojs.getPlayer('myPlayerID').on('loadedmetadata',function(){})

自動再生イベント

自動再生イベントは、プレーヤーがコンテンツの自動再生を試みた際にトリガーされます。

autoplay-success: ユーザー操作なしで自動再生が正常に開始されたときにトリガーされます。

例

          videojs.getPlayer('myPlayerID').on('autoplay-success',function(){
       console.log('Autoplay was successful.');
       });

autoplay-failure: 自動再生の開始に失敗したときにトリガーされます。

例

          videojs.getPlayer('myPlayerID').on('autoplay-failure',function(){
       console.log('Autoplay failed.');
       });

フルスクリーン イベント

fullscreenchange イベントは、プレーヤーがフルスクリーン モードに切り替わった、またはフルスクリーン モードから戻ったときに送出されます。プレーヤーがフルスクリーンになる場合と通常モードに戻る場合のいずれでも、同じイベントが送出されます。どちらが発生したかを判別する必要がある場合は、player.isFullscreen() メソッドを使用して、現在プレーヤーがフルスクリーン モードかどうかを確認してください。

以下の CodePen は、その方法を示しています。

See the Pen Brightcove Player Fullscreen Events by Brightcove Learning Services (@bcls) on CodePen.

広告イベント

プレーヤーに広告ライブラリや広告機能を組み込むには、IMA3 プラグイン または FreeWheel プラグイン を使用できます。これらは videojs ads framework（videojs-contrib-ads）を基盤として構築されています。これら 2 つの広告プラグインはいずれも、次の表に示す広告イベントを送出できます。また、それぞれの実装に固有のイベントも用意されています。

bc-catalog-error イベント

スクリプト ブロック内の通常の ready() セクションでエラー処理を行うと、問題が発生する可能性があります。たとえば、プレーヤーの準備が完了する前に bc-catalog-error イベントが送出される場合があり、その場合 ready() セクション内でエラーをリッスンしていても、エラーを処理することができません。この問題は、地域フィルタリングを使用している場合、動画が非公開になっている場合、動画がスケジュール範囲外である場合、または別のアカウントに属している場合に発生する可能性があります。bc-catalog-error イベントの処理に関する詳細な説明や例については、Player Catalog ドキュメントを参照してください。

progress と timeupdate

progress イベントと timeupdate イベントの違いについて、混乱が生じることがあります。Brightcove Player は HTML5 video を基盤としており、その仕様では progress イベントは、ブラウザーがデータをダウンロードしているときに送出されます。一方、timeupdate イベントは、現在の再生位置が変更されたときに送出されます。

これは Brightcove Smart Player の利用者にとっては混乱を招く可能性があります。Smart Player API では、progress イベントが、Brightcove Player API における timeupdate と同様の役割を果たしているためです。

timeupdate リスナー削除時の注意点

場合によっては、timeupdate イベントに追加したイベント リスナーを削除したいことがあります。そのユースケースは、Brightcove Player サンプル：プレビュー後に再生を登録する ドキュメントで紹介されています。このケースでは、特定の時間範囲でプレーヤーを一時停止させたい状況で、時間のチェックに timeupdate を使用し、無名のイベント ハンドラー関数を定義しています。一度だけ一時停止させたい場合、その後イベント リスナーを削除する必要があります。その際、次のようにしてはいけません。

      myPlayer.off('timeupdate');

これは timeupdate に対するすべてのイベント リスナーを削除してしまい、他の問題に加えてタイム スクラバーが進まなくなる原因となります。必要なのは、通常の関数定義構文（関数宣言）を使用して関数を作成し、その特定のイベント リスナーのみを削除することです。簡略化したコードを以下に示します。

       // イベント ハンドラーを追加
      myPlayer.on('timeupdate', timeupdateHandler);
      
      // イベントを処理した後、この timeupdate のイベント リスナーのみを削除
      function timeupdateHandler(evt) {
        ...
        myPlayer.off('timeupdate', timeupdateHandler);
      }

Analytics イベント

Analytics データコレクターにビーコンが送信されるたびに、イベントがトリガーされます。すべてのビーコン、または特定のビーコンをリッスンすることができます。

すべてのビーコンをリッスンする

analytics-beacon イベントをリッスンすることで、送信されるすべての Analytics ビーコンを追跡できます。

player.on('analytics-beacon', function(e) {
        videojs.log('sent a(n) ' + e.params.event + ' beacon!', e.params);
      });

特定のビーコンをリッスンする

analytics-beacon-{beacon_name} イベントをリッスンすることで、特定の Analytics ビーコンを追跡できます。

{beacon_name} は、データ コレクターに送信されるプレーヤー イベントのいずれかの名称です。これらのイベントの完全な一覧については、Data Collection API リファレンス を参照してください。

例

player.on('analytics-beacon-video-impression', function(e) {
        videojs.log('sent an impression beacon!', e.params);
      });

メソッド チェーンはサポートされていません

Brightcove Player バージョン 6 以降では、イベントに対するメソッド チェーンはサポートされなくなりました。つまり、次のような記述はできません。

      player.on(event, function () {})
      .on(event, function () {})
      .on(event, function () {})
      .on(event, function () {});