エラーメッセージ表示プラグイン

このトピックでは、デフォルトのエラーメッセージの動作を変更し、カスタム エラーメッセージを作成してエラーを発生させる方法を学びます。

概要

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

エラーメッセージプラグイン

上の画像に表示されているエラーメッセージは、sources プロパティ内で無効な src 値をプレーヤーに設定して作成されたものです。

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

はじめに

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

ページ内のコードからプラグインを更新する場合、まず Brightcove プレーヤーへの参照を取得します。この例では、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
    • 見出し: 視聴しようとしている動画は暗号化されており、復号方法が不明です
    • メッセージ: メディアは暗号化されており、復号キーを持っていません。

エラーに関連するエラーコードがない場合は、汎用メッセージが表示されます：

  • エラーコード: 不明
    • メッセージ: MEDIA_ERR_UNKNOWN
    • 説明: 予期しない問題が発生しました。しばらくしてからもう一度お試しください。

テキストの上書き

エラーメッセージには、変更できる 3 つの部分があります：

  • headline ：上部に表示されるメッセージテキストです。
  • type ：これはエラーコード: のテキスト部分です。
  • message ：これは技術的詳細: のテキスト部分です。
エラーメッセージプラグイン

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

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

ページ内コードで使用する場合

エラー スクリプトをコード内に含める場合、以下のようにメッセージ テキストを上書きできます：

        myPlayer.errors({
          "errors": {
            "4": {
              "headline": "これはカスタムエラーメッセージです",
              "type": "カスタムタイプ",
              "message": "詳細情報はこちらです"
            }
          }
        });

カスタム プラグインを使用する場合

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

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

  1. Brightcove プレーヤー プラグイン コードを含む JavaScript ファイルを作成し、インターネットからアクセス可能な場所に保存します。内容は以下のようになりますが、値は任意に設定してください。 

            videojs.registerPlugin('errorText', function() {
          var myPlayer = this;
        
          myPlayer.errors({
            "errors": {
              "4": {
                "headline": "ライブ配信はまもなく開始されます",
                "type": "CUSTOM_TYPE",
                "message": "ライブイベントが開始したら、再度アクセスしてください！"
              }
            }
          });
        });

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

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

    カスタムプラグイン
    カスタムプラグイン

  4. プラグイン詳細ページで、次の値を入力します：

    • プラグイン名 - プラグイン名
    • JavaScript URL - 最初の手順で作成したプレーヤー プラグインの場所
    プラグイン詳細
    プラグイン詳細
  5. 保存 ボタンを選択します。

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

Brightcove 定義のカスタム エラー

カスタム エラーも定義することができます。このセクションでは Brightcove によって定義された複数のカスタム エラーについて説明し、次のセクションでは独自のカスタム エラーを作成する方法を紹介します。

  • Brightcove では、カスタム エラー コードの値を文字列として定義することを推奨しています。提供されている一部のエラーには歴史的な理由で負の数値が使用されていますが、英数字または説明的な文字列を使用することで衝突の可能性を減らすことができます。
  • カスタム エラー メッセージの名前は自由に付けることができます。Brightcove では、混同を避けるために、標準化された MEDIA_ERR ではなく PLAYER_ERR から始まるタイプ名を使用することを推奨しています。
  • このセクションの後半で説明するように、カスタム エラーを閉じられる（非表示にできる）かどうかを設定することも可能です。

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

  • エラーコード: -1
    • メッセージ: PLAYER_ERR_NO_SRC
    • 説明: 動画が読み込まれていません
  • エラーコード: -2
    • メッセージ: PLAYER_ERR_TIMEOUT
    • 説明: 動画をダウンロードできませんでした
  • エラーコード: 設定なし
    • メッセージ: PLAYER_ERR_DOMAIN_RESTRICTED
    • 説明: この動画は現在のドメインでは再生が制限されています
  • エラーコード: 設定なし
    • メッセージ: PLAYER_ERR_IP_RESTRICTED
    • 説明: この動画は現在の IP アドレスで再生が制限されています
  • エラーコード: 設定なし
    • メッセージ: PLAYER_ERR_GEO_RESTRICTED
    • 説明: この動画は現在の地域で再生が制限されています

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

独自のカスタム エラーを定義する場合、Brightcove はコードを使用しないことを推奨しています。（前のセクションで示したとおり、Brightcove は新しく定義しているカスタム エラーでこの方式を採用しています。）一貫性のために、カスタム エラー名には PLAYER_ERR_ プレフィックスを使用することも検討してください。ただし、もちろん任意の名前を付けることができます。

エラー スクリプトをコードに含める場合、次のようにカスタム メッセージを追加できます：

        videojs.getPlayer('myPlayerID').ready(function() {
          var myPlayer = this;
          //custom error
          myPlayer.errors({
            "errors": {
              "PLAYER_ERR_AGE_GATE": {
                "headline": "18歳以上である必要があります。",
                "message": "一部のユーザーに不適切と見なされる可能性があるコンテンツが含まれています。"
            }
          }
        });

カスタム エラーの表示

カスタム エラーを定義したら、いつ表示するかを 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 に設定していますが、実際にはカスタム エラー メッセージを表示する条件を判定するためのコードを追加してください。

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

ユーザー定義カスタムエラーメッセージ

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

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

閉じることができるエラーメッセージ

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

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

この設定により、エラー メッセージは次のように表示され、閉じることができなくなります。

閉じることができないエラーメッセージ

getAll() メソッド

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

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

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

getAll のコンソール表示

on() メソッド

すべてのエラーを監視するには、以下のように on() メソッドを使用することもできます： 
myPlayer.on('error'), function () {
          ...
        }

広告を再生しており、すべてのエラーを捕捉したい場合は、次のようにします：

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

エラーのディスパッチ

開発時に、設定変更が正しく機能しているかをテストするため、エラーをディスパッチしたい場合があります。次のコード スニペットのようなコードを使用して実行できます。この例では、任意のタイミングでエラーをディスパッチできるよう、ボタンをコードに追加しています。

        <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>

エラーのローカライズ

errors プラグインは複数言語をサポートします。言語を追加するには、プラグインの読み込み後に使用したい言語ファイルを読み込みます：

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

その後、Brightcove プレーヤーをプログラムでローカライズする ドキュメントで示されている手法を使って、エラー メッセージをローカライズできます。

bc-catalog-error

通常の script ブロック内の 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': '視聴しようとしている動画は非アクティブです。',
                  '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 は、プレーヤーに報告されたのと同じタイミング・同じ回数でエラーをアナリティクスに送信します。たとえば、プレーヤーにメディアが無い状態で、コードが play() を連続で 1000 回呼び出した場合、アナリティクスには 1000 件の 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 では、エラーメッセージに対するタップ イベントが親の動画要素へバブリングしません。つまり、エラー メッセージが一度表示されると閉じることができません。ユーザーがフルスクリーンモードのときは、抜け出す手段がなくなるため問題になる可能性があります。

    この問題は現在対応中で、将来のプレーヤー リリースで修正される予定です。現時点では、次のような回避策をお試しください：

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

変更履歴

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

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