ガイド：広告パートナー統合

概要

広告システムが Google IMA3 に準拠している場合は、この情報は不要で、IMA3 プラグインを使用した広告ガイドに記載されている IMA3 用の既存プラグインをそのまま使用できます。

この機能が必要であると判断した場合、本コンテンツでは Brightcove Player と広告を統合するために必要な広告 API フレームワークについて説明します。Brightcove が提供しているこのフレームワークの実装例として、Google の IMA3 および FreeWheel 向けの実装があります（参考ドキュメントは次の段落に記載）。

繰り返しますが、このドキュメントは、既存の広告フレームワークを使って動画に広告を表示したいお客様向けのものではありません。そのようなお客様には、以下のドキュメントの方が適しています:

広告フレームワークの機能

Brightcove は、カスタム広告プラグインの基盤となる広告 API フレームワークを提供しています。このフレームワークは、Brightcove Player と連携して動作する動画広告ライブラリに必要な共通機能を提供し、広告統合のために記述するコード量を削減します。フレームワークはオープンソースプロジェクトとして提供されており、自由に拡張できます。プロジェクトコードは GitHub リポジトリ videojs-contrib-ads から入手できます。

広告フレームワークにより、広告パートナーは以下を実現できます:

広告再生中のプレーヤーの外観や動作など、広告体験を完全に制御できます。
カスタムまたは独自の広告サーバーと連携できます。
広告リクエストのタイミングやクリエイティブのバッファリング方法など、広告実装の低レベル部分を管理できます。
動画分析プロバイダーや Brightcove Player エコシステムと容易に連携できます。

基礎知識

広告 API フレームワークを使用し、さらに拡張していくには、Brightcove Player プラグインアーキテクチャを十分に理解しておく必要があります。以下のドキュメントでその知識を得ることができます:

必要に応じて、Brightcove の視点から見た動画広告の概要も以下で確認できます:

学習ガイド：動画広告

フレームワークの使用

以下のセクションでは、フレームワークの使用方法について詳しく説明します。

フレームワークリソースの読み込み

プラグインを使用するには、まずプラグインの CSS と JavaScript を確実に読み込む必要があります。

    <link rel="stylesheet" href="//mypath/videojs.ads.css">
    <script src="//mypath/videojs.ads.js"></script>

JavaScript を読み込んだら、次に広告フレームワークを初期化する関数を呼び出します。

    <script type="text/javascript">
      videojs.getPlayer('myPlayerID').one('loadedmetadata', function(){
        var myPlayer = this;
        // 広告フレームワークを初期化
        myPlayer.ads();
      });
    </script>

注: ready() メソッドはプレーヤーが読み込まれ準備完了であることを示すために使用されますが、loadedmetadata イベントは広告などのプレーヤーコンテンツが操作可能になったことを示すために使用されます。また、one() メソッドを使用することで、プラグインが最初に読み込まれた時だけ関数が実行され、動画が読み込まれるたびに実行されることを防ぎます。詳細は Player イベントドキュメントを参照してください。

設定オプション

フレームワークには複数の設定オプションがあります。たとえば、timeout オプションがあります。このオプションを設定するには次のコードを使用します:

    <script type="text/javascript">
      videojs.getPlayer('myPlayerID').one('loadedmetadata', function(){
        var myPlayer = this;
        // 広告フレームワークを初期化
        myPlayer.ads({
          "timeout": 3000
        });
      });
    </script>

以下の表は使用可能なオプションの一覧です:

オプション	タイプ	デフォルト	説明
`timeout`	number	5000	広告実装が再生前に初期化されるまで待機する最大時間（ミリ秒）
`prerollTimeout`	number	1000	広告実装がプリロールを開始するまで待機する最大時間（ミリ秒）
`postrollTimeout`	number	100	広告実装がポストロールを開始するまで待機する最大時間（ミリ秒）
`debug`	boolean	false	true に設定すると、再生中に広告プラグインの状態に関する追加情報を出力します

イベント

以下のイベントは 2 つのタイプに分類されます。分類と説明は以下のとおりです。

adstart と adend イベントは、広告インテグレーターのメソッド呼び出しに応じてフレームワークによってトリガーされます。これらのイベントは広告インテグレーターが直接トリガーしてはいけません。

イベント	説明
adstart	プレーヤーがリニア広告再生モードに入ったことを示します
adend	プレーヤーがリニア広告再生モードから戻ったことを示します

adskip と adtimeout イベントは、広告インテグレーターが任意でトリガーできるイベントで、プレーヤーにプリロールまたはポストロールをスキップさせるために使用します。

イベント	説明
adskip	プレーヤーがリニア広告機会をスキップし、コンテンツ再生を即座に再開することを示します
adtimeout	プラグインが管理するタイムアウトが発生し、通常の動画コンテンツの再生が始まったことを示します

ランタイム設定

プラグインの初期化後、その動作を変更するために使用できるプロパティがあります。

プロパティ説明

contentSrc このプロパティは、新しい動画が読み込まれたことを検知し、プレーヤーを「プリロール再生準備状態」にリセットするために使用されます。広告プロバイダーが直接操作することは通常ありませんが、例えばレンディションセレクターの実装のために動画ソースを変更したいプラグイン作成者は、contentSrc を変更することで、レンディション切替時にプリロールが開始されないようにできます。

プロパティ	説明
contentSrc	このプロパティは、新しい動画が読み込まれたことを検知し、プレーヤーを「プリロール再生準備状態」にリセットするために使用されます。広告プロバイダーが直接操作することは通常ありませんが、例えばレンディションセレクターの実装のために動画ソースを変更したいプラグイン作成者は、`contentSrc` を変更することで、レンディション切替時にプリロールが開始されないようにできます。

例

このセクションでは、完全に動作するサンプルを含む実装例を紹介します。

<!DOCTYPE html>
    <html lang="en">
    
    <head>
      <meta charset="UTF-8">
      <meta http-equiv="X-UA-Compatible" content="IE=edge">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Contrib ads ad plugin</title>
    </head>
    
    <body>
    
      <video-js id="myPlayerID"
        data-account="1752604059001"
        data-player="default"
        data-embed="default"
        controls=""
        data-video-id="6077029038001"
        data-playlist-id=""
        data-application-id=""
        width="960" height="540"></video-js>
    
      <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>
      <script src="https://cdnjs.cloudflare.com/ajax/libs/videojs-contrib-ads/6.9.0/videojs.ads.js"></script>
    
      <script>
        const player = videojs.getPlayer("myPlayerID");
        let creative = '';
    
        player.ads();
    
        player.on('contentupdate', function () {
    
        // コンソール出力
        console.log("### videojs EVENT: contentupdate");
    
        // ここで広告インベントリを取得可能...
        player.setTimeout(() => {
          creative = 'https://solutions.brightcove.com/bcls/ads/bc-ads/bcls-ad-1-8seconds.mp4';
        }, 100);
        player.trigger('adsready');
    
        // コンソール出力
        console.log("### videojs EVENT: adsready");
    
        });
    
        player.on('loadedmetadata', function () {
        // コンソール出力
        console.log("### videojs EVENT: loadedmetadata");
        });
    
        player.on('readyforpreroll', function () {
    
          // コンソール出力
          console.log("### videojs EVENT: readyforpreroll");
    
          player.ads.startLinearAdMode();
          // リニア広告を再生
          player.src(creative);
          player.one('durationchange', function () {
            player.play();
          });
          // 広告終了時にプレーヤーを元に戻す
          player.one('adended', function () {
    
            // コンソール出力
            console.log("### videojs EVENT: adended");
    
            player.ads.endLinearAdMode();
          });
        });
    
        player.on('ended', function () {
          // コンソール出力
          console.log("### videojs EVENT: ended");
        });
      </script>
    </body>
    
    </html>

よくある質問

広告プラグインはメディアメタデータにどのようにアクセスできますか？

Video Cloud を利用している場合、プラグインは mediainfo オブジェクトを通じて Video Cloud で設定されたメタデータにアクセスします。Brightcove Player を使用している場合は、Video Cloud CMS を利用しないため、mediainfo オブジェクトを手動で設定する必要があります。

広告プラグインのオプションはどのように指定できますか？

プラグインオプションは、Studio の Players > プラグイン セクションで設定できます。オプションを含むプラグインを適用したプレーヤーは iframe またはインページ埋め込みコードで公開できますが、プラグインオプションは静的情報（例：description）を含む点に注意が必要です。動的データは、プラグインへのデータ受け渡しに記載の方法でプラグインへ渡すことができます。

広告プラグインは Flash ベースの広告をどのようにサポートすべきですか？

Brightcove では、Flash ベースの広告プレーヤーを広告プラグインの一部として組み込み、プレーヤーがリニア広告モードの間はそのプレーヤーをコンテンツ上にオーバーレイすることを推奨しています。

キューポイントはどのようにしてミッドロールをトリガーできますか？

キュー変更時に startLinearAdMode() を呼び出すことでミッドロールを開始できます。キューポイントのリッスンや設定方法については、キューポイントの使用ドキュメントを参照してください。