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
    • Type: MEDIA_ERR_ABORTED
    • Headline: The video download was cancelled
    • Message: You aborted the media playback
  • エラー コード: 2
    • Type: MEDIA_ERR_NETWORK
    • Headline: The video connection was lost, please confirm you're connected to the internet
    • Message: A network error caused the media download to fail part-way. 現時点では MP4 やプログレッシブ ダウンロード動画フォーマットで最も役立ちます。詳細については、本ドキュメントの既知の問題セクションをご参照ください。
  • エラー コード: 3
    • Type: MEDIA_ERR_DECODE
    • Headline: The video is bad or in a format that can't be played on your browser
    • Message: The media playback was aborted due to a corruption problem or because the media used features your browser did not support.
  • エラー コード: 4
    • Type: MEDIA_ERR_SRC_NOT_SUPPORTED
    • Headline: This video is either unavailable or not supported in this browser
    • Message: The media could not be loaded, either because the server or network failed or because the format is not supported.
  • エラー コード: 5
    • Type: MEDIA_ERR_ENCRYPTED
    • Headline: The video you're trying to watch is encrypted and we don't know how to decrypt it
    • Message: The media is encrypted and we do not have the keys to decrypt it.

エラーに関連付けられたエラー コードがない場合は、汎用メッセージが表示されます。

  • エラー コード: unknown
    • Message: MEDIA_ERR_UNKNOWN
    • Description: An unanticipated problem was encountered, check back soon and try again

テキストの上書き

変更可能なエラー メッセージの部分は次の 3 つです。

  • headline : 上部のメッセージ テキストです。
  • type : Error Code: のテキストです。
  • message : Technical details: のテキストです。
error message plugin

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

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

ページ コードでの使用

コードに errors スクリプトを含めている場合は、次のようにメッセージ テキストを上書きできます。

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 モジュールで、Overview タブの Plugins セクションを展開します。

  3. Add Plugin ボタンを展開し、Custom Plugin を選択します。

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

    • Plugin Name - プラグインの名前
    • JavaScript URL - 最初のステップで作成したプレーヤー プラグインの場所

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

Brightcove で定義されたカスタム エラー

カスタム エラーも定義できます。Brightcove は、本セクションで説明する複数のカスタム エラーを定義しており、次のセクションで詳述するとおり、独自のカスタム エラーを作成することもできます。

  • Brightcove は、カスタム エラー コード値を文字列にすることを推奨しています。提供されているエラーのうち 2 つは歴史的な理由で負の数を使用していますが、英数字／説明的な文字列の方が衝突問題を引き起こしにくいです。
  • カスタム エラー メッセージには任意の名前を付けることができます。Brightcove では、混乱を避けるため、type には標準化された MEDIA_ERR ではなく PLAYER_ERR で始めることを推奨しています。
  • 本セクションで後述するとおり、カスタム エラーを閉じられるようにするか、閉じられないようにするかを設定できます。

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

  • エラー コード: -1
    • Message: PLAYER_ERR_NO_SRC
    • Description: No video has been loaded
  • エラー コード: -2
    • Message: PLAYER_ERR_TIMEOUT
    • Description: Could not download the video
  • エラー コード: 未設定
    • Message: PLAYER_ERR_DOMAIN_RESTRICTED
    • Description: This video is restricted from playing on your current domain
  • エラー コード: 未設定
    • Message: PLAYER_ERR_IP_RESTRICTED
    • Description: This video is restricted at your current IP address
  • エラー コード: 未設定
    • Message: PLAYER_ERR_GEO_RESTRICTED
    • Description: This video is restricted from playing in your current geographic region

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

独自のカスタム エラーを定義する際、Brightcove は code を使用しないことを推奨しています。（前述のセクションで、Brightcove が定義している新しいカスタム エラーで現在この方針を採用していることがわかります。）一貫性のために、カスタム エラーには PLAYER_ERR_ プレフィックスを使用することも検討すべきですが、もちろん任意の名前を付けることができます。

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

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() メソッドを使用すると、特定のプレーヤーに登録されているすべてのエラーを確認できます。getAll() メソッドは、たとえば player.errors() が呼び出された後など、errors プラグインが初期化された後であればいつでも呼び出すことができます。メソッドの呼び出し例は次のとおりです。

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

一部のエラーを展開して詳細を表示したコンソール表示の例は次のとおりです。

getAll console display

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 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 は、プレーヤーに報告されたのと同じタイミング、同じ件数でエラーを分析に送信します。たとえば、プレーヤーにメディアがない状態で、コードがなんらかの理由で 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 のリリース ノートで報告されます。

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