Display Error Messages プラグイン

このトピックでは、デフォルトのエラーメッセージ動作の変更、カスタム エラーメッセージの作成、エラーのディスパッチ方法について学びます。

概要

エラーメッセージ プラグインは、プレーヤーがエラーに遭遇した際に、ユーザーフレンドリーなメッセージを表示できるようにするものです。デフォルトのスタイルシートでは、メッセージは動画要素の上に半透明のオーバーレイとして表示されます。既存のメッセージテキストを変更したり、独自のスタイルを追加したりできます。また、任意のタイミングでトリガーされるカスタム メッセージを作成することも可能です。

error message plugin

上の画像に表示されているエラーメッセージは、sources プロパティに不正な src 値を設定したことで生成されたものです。

エラーメッセージ プラグインはデフォルト プラグインであり、Brightcove Player に自動的に読み込まれます。しかし、読み込まないようにすることも可能です。このプラグインがない場合、表示されるエラーメッセージは限定的になり、一部のエラーはブラウザのコンソールにしか表示されません。プレーヤー作成時にデフォルト プラグインを読み込まない方法については、プレーヤー プラグイン概要 を参照してください。

始める

プレーヤーのすべてのインスタンスを更新したい場合、Studio の Brightcove Players モジュールを使用してカスタム プラグインを実装できます。この方法は、以下のセクションでエラーメッセージ プラグインを更新する手順として使用されています。ページから直接プラグインを更新する場合、そのプレーヤーのインスタンスにのみ影響します。

ページコードからプラグインを更新するには、まず Brightcove Player への参照を取得します。この例では、JavaScript 内で myPlayer という変数を作成し、プレーヤーへの参照を代入しています。

      <video-js id="myPlayerID"
        data-video-id="4443311217001"
        data-account="1507807800001"
        data-player="default"
        data-embed="default"
        controls=""></video-js>
      <script src="https://players.brightcove.net/1507807800001/default_default/index.min.js"></script>
      <script type="text/javascript">
        videojs.getPlayer('myPlayerID').ready(function(){
          var myPlayer = this;

標準エラー

このプラグインには、実行時のエラーコード値に基づく標準 HTML5 動画エラー向けのデフォルト エラーメッセージ セットがあります：

  • エラーコード: 1
    • タイプ: MEDIA_ERR_ABORTED
    • 見出し: 動画のダウンロードがキャンセルされました
    • メッセージ: メディア再生が中断されました
  • エラーコード: 2
    • タイプ: MEDIA_ERR_NETWORK
    • 見出し: 動画の接続が失われました。インターネット接続をご確認ください
    • メッセージ: ネットワークエラーによりメディアのダウンロードが途中で失敗しました。これは主に MP4 やプログレッシブダウンロード形式の場合に役立つ情報です。詳細はこのドキュメントの 既知の問題 セクションを参照してください。
  • エラーコード: 3
    • タイプ: MEDIA_ERR_DECODE
    • 見出し: この動画は破損しているか、ブラウザが再生できない形式です
    • メッセージ: メディアが破損している、またはブラウザがサポートしていない機能を使用していたため再生が中止されました。
  • エラーコード: 4
    • タイプ: MEDIA_ERR_SRC_NOT_SUPPORTED
    • 見出し: この動画は利用できないか、このブラウザではサポートされていません
    • メッセージ: メディアを読み込めませんでした。サーバーまたはネットワークの障害、または形式がサポートされていないことが原因です。
  • エラーコード: 5
    • タイプ: MEDIA_ERR_ENCRYPTED
    • 見出し: この動画は暗号化されていますが、復号化方法が不明です
    • メッセージ: メディアは暗号化されており、復号化キーがありません。

エラーコードが存在しない場合は、汎用メッセージが表示されます：

  • エラーコード: unknown
    • メッセージ: MEDIA_ERR_UNKNOWN
    • 説明: 想定外の問題が発生しました。しばらくしてから再度お試しください。

テキストの上書き

エラーメッセージには、変更可能な 3 つの部分があります。

  • headline : メッセージ上部に表示されるテキスト
  • type : Error Code: のテキスト
  • message : Technical details: のテキスト
error message plugin

以下の例は、エラーコード 4 の標準エラーメッセージのテキストを上書きする方法を示したものです。プロパティは次のように定義されています。

  • plugins：このプロパティは複数のプロパティと値を含む配列です。このプラグインでは、name プロパティに errors を指定するだけで十分です。
  • options：プラグインにデータを渡すために使用されるプロパティです。
  • errors：更新したいエラーコードを定義します。ここでは、headline、type、message を上書きしています。

ページ内コードでの使用

エラースクリプトをコード内で読み込んでいる場合、メッセージテキストを次のように上書きできます。

        myPlayer.errors({
          "errors": {
            "4": {
              "headline": "This is a custom error message",
              "type": "custom type",
              "message": "these are details"
            }
          }
        });

カスタム プラグインの使用

プレーヤーの全インスタンスを更新したい場合は、カスタムプラグインを作成して Video Cloud Studio の Players モジュールに追加します。プラグインについて詳しくは、プレーヤープラグインの設定 を参照してください。

標準メッセージ テキストを上書きするプラグインを作成するには、以下の手順に従います。

  1. インターネット上からアクセス可能な場所に、Brightcove Player 用のプラグインコードを記述した JavaScript ファイルを作成します。構造は以下のようになります（値は任意に変更してください）。

            videojs.registerPlugin('errorText', function() {
          var myPlayer = this;
        
          myPlayer.errors({
            "errors": {
              "4": {
                "headline": "The Live Stream will begin soon",
                "type": "CUSTOM_TYPE",
                "message": "Please come back, once the live event has begun!"
              }
            }
          });
        });

  2. Players モジュールで、左ナビゲーションから プラグイン を選択します。

  3. プラグインの追加 ボタンを展開し、カスタム プラグイン を選択します。

    Custom Plugin
    Custom Plugin

  4. プラグイン詳細ページで、以下の値を追加します：

    • プラグイン名 - 任意のプラグイン名
    • JavaScript URL - 手順 1 で作成したプラグインの URL
    Plugin details
    Plugin details
  5. 保存 ボタンを選択します。

  6. プレーヤーを公開します。

Brightcove 定義のカスタム エラー

カスタム エラーも定義できます。Brightcove では、いくつかのカスタム エラーを定義しており、このセクションで説明します。また、次のセクションでは独自のカスタム エラーを作成する方法も説明します。

  • Brightcove では、カスタム エラーコードの値を文字列にすることを推奨しています。歴史的な理由で負の数を使用しているエラーが 2 つありますが、英数字や説明的な文字列の方が競合を起こしにくくなります。
  • カスタム エラーメッセージには任意の名前を付けることができます。Brightcove では、標準化された MEDIA_ERR と混同しないよう、PLAYER_ERR から始めることを推奨しています。
  • このセクションの後半で説明するように、カスタム エラーを閉じられる状態にするかどうかを制御できます。

参考として、以下の 5 つのカスタム エラー メッセージが追加されています。

  • Error code: -1
    • Message: PLAYER_ERR_NO_SRC
    • Description: 動画が読み込まれていません
  • Error code: -2
    • Message: PLAYER_ERR_TIMEOUT
    • Description: 動画をダウンロードできませんでした
  • Error code: Not set
    • Message: PLAYER_ERR_DOMAIN_RESTRICTED
    • Description: この動画は現在のドメインでは再生できません
  • Error code: Not set
    • Message: PLAYER_ERR_IP_RESTRICTED
    • Description: この動画は現在の IP アドレスでは再生できません
  • Error code: Not set
    • Message: PLAYER_ERR_GEO_RESTRICTED
    • Description: この動画は現在の地域では再生できません

ユーザー定義のカスタム エラー

独自のカスタム エラーを定義する場合、Brightcove は code を使用しないことを推奨しています。（前のセクションで説明したように、Brightcove が新しいカスタム エラーを定義する際もコードを使用していません。）また、整合性のために PLAYER_ERR_ の接頭辞を使用することを推奨しますが、もちろん任意の名前を付けることができます。

エラースクリプトをページで読み込んでいる場合、カスタム メッセージは次のように追加できます：

        videojs.getPlayer('myPlayerID').ready(function() {
          var myPlayer = this;
          //custom error
          myPlayer.errors({
            "errors": {
              "PLAYER_ERR_AGE_GATE": {
                "headline": "You must be at least 18 years of age.",
                "message": "Content may be considered inappropriate for some users."
            }
          }
        });

カスタム エラーの表示

カスタム エラーを定義したら、それをいつ表示するか Brightcove Player に知らせる必要があります。これを行うには、エラーを表示する条件を判断するコードを自身で作成し、次のように error() 関数を使用します：

        //display custom message
        var age_appropriate = false;
        myPlayer.on("loadstart", function () {
          if(!age_appropriate) {
            myPlayer.error({code:'PLAYER_ERR_AGE_GATE'});
          }
        });

ここでは age_appropriate 変数を false にしていますが、実際には自身の条件に基づいてカスタム エラーの表示を制御できます。

ユーザーに表示されるエラーは次のようになります：

user custom error message

カスタム エラーを閉じられないようにする

デフォルトでは、カスタム エラー メッセージは視聴者が閉じることができます。次のスクリーンショットのように、ウィンドウを閉じるための OK ボタンと、右上の X が表示されます。

dismissible error message

視聴者にエラーメッセージを閉じさせたくない場合は、そのように設定できます。error() メソッドを呼び出す際に dismiss プロパティを false に設定します。

        myPlayer.error({code:'age-gate-error', dismiss: false});

この設定を行うと、以下のようにエラー メッセージが表示され、閉じる手段がなくなります。

not dismissible error message

getAll() メソッド

getAll() メソッドを使用して、特定のプレーヤーに登録されているすべてのエラーを確認できます。errors プラグインが初期化された後、つまり player.errors() が呼ばれた後であればいつでも getAll() を呼び出せます。以下はその例です：

        console.log('myPlayer.errors.getAll()',myPlayer.errors.getAll());

いくつかのエラー詳細を展開した状態のコンソール表示例は次のとおりです：

getAll console display

on() メソッド

on() メソッドを使って、すべてのエラーを監視することもできます。次のように使用します：

myPlayer.on('error'), function () {
          ...
        }

広告を再生している場合、すべてのエラーを補足したいのであれば、次のようにする必要があります：

myPlayer.on(['error','aderror')], function () {
          ...
        }

エラーの発生（Dispatch）

開発時に、設定変更が正しく動作しているか確認するために、意図的にエラーを発生させたい場合があります。次のコード スニペットのように記述することで可能です。この例では、任意のタイミングでエラーを発生させるためにボタンを追加しています。

        <video-js id="myPlayerID"
          data-video-id="4443311217001"
          data-account="1507807800001"
          data-player="default"
          data-embed="default"
          controls=""></video-js>
        <script src="https://players.brightcove.net/1507807800001/default_default/index.min.js"></script>
        <p><button onclick="changeVideo()">change video</button></p>
        <script type="text/javascript">
          var changeVideo;
          videojs.getPlayer('myPlayerID').ready(function() {
            var myPlayer = this;
            changeVideo = function(){
              myPlayer.error({code:'2'});
            }
          });
        </script>

エラーのローカライズ

エラープラグインは複数言語をサポートしています。特定の言語を利用するには、プラグインが読み込まれた後に該当する言語ファイルを読み込みます：

        <script src="lang/es.js"></script>

その後、Brightcove Player をプログラムでローカライズする ドキュメントで紹介されている方法を使用して、エラーメッセージをローカライズできます。

bc-catalog-error

通常の ready() セクション内でエラー処理を行うと、問題が発生する場合があります。たとえば、bc-catalog-error イベントがプレーヤーの準備完了前にディスパッチされることがあり、その場合 ready() 内でエラーを待ち受けても処理できません。この問題は、地域制限、動画が非アクティブ、配信スケジュール範囲外、別アカウントなどのケースで発生する可能性があります。コードに問題がなくても、ブラウザ依存の挙動である可能性があるため注意が必要です。

以下は、動画が非アクティブの場合にメッセージを表示するプラグイン コードの例です：

        videojs.registerPlugin('inactiveErrorCheck', function() {
          var myPlayer = this;
          myPlayer.one('bc-catalog-error', function(){
            var specificError;
            myPlayer.errors({
              'errors': {
                  'inactive-video-error': {
                  'headline': 'The video you are trying to watch is inactive.',
                  'dismiss': false
                }
              }
            });
            if (typeof(myPlayer.catalog.error) !== 'undefined') {
              specificError = myPlayer.catalog.error.data[0];
              if (specificError !== 'undefined' & specificError.error_code == "VIDEO_NOT_PLAYABLE") {
                myPlayer.error({code:'inactive-video-error'});
              };
            };
          });
        });

エラー率が過剰に見える場合

報告されるエラー数が異常に多いと感じる場合、同じセッション内で重複したエラー イベントが多数発生している可能性があります。Brightcove Player は、プレーヤーが受け取ったタイミングと件数のままエラーをアナリティクスへ送信します。

たとえば、プレーヤーに動画が設定されていない状態で、コードが 1,000 回連続で play() を呼び出すと、1,000 件の PLAYER_ERR_NO_SRC がアナリティクスに報告されます。

ごく一部のセッションで大量のエラーが発生し、全体の統計をゆがめている可能性があるため、実際の状況を把握するには次の計算方法の使用を推奨します：

        number_of_sessions_with_errors / total_number_of_sessions

以下のような比率よりも：

        count of errors/number of views

既知の問題

  • Windows 10 の Edge で動画を読み込む際（Studio および公開 URL の両方）、MEDIA_ERR_SRC_NOT_SUPPORTED エラーが表示され、動画が再生できないことがあります。

  • Android デバイスや iPhone では、エラーメッセージのタップ イベントが親の video 要素にバブリングしません。そのため、一度表示されたエラーメッセージを閉じることができません。

    特にフルスクリーン時にはユーザーが抜け出せなくなるため問題となります。

    この問題は修正予定ですが、それまでの回避策として次のコード例が利用できます：

            player.on("touchstart", function(e) {
          if (player.error_) {
            player.error(null);
            e.preventDefault();
          }
        })

更新履歴

エラープラグインは現在プレーヤー本体に統合されており、プラグイン機能に関する変更は Brightcove Player のリリースノートで報告されます。

過去のリリースノートについては こちらの更新履歴 を参照してください。