Brightcove プレーヤーでサーバーサイド広告を実装する

概要

Server-Side Ad Insertion（SSAI）を使用すると、広告を動画に直接埋め込めるため、ブラウザの広告ブロッカーによって広告がブロックされなくなります。Dynamic Delivery は次世代の取り込みおよび配信システムで、ストレージ使用量を削減し、メディアを動的にパッケージ化します。

SSAI はデフォルトで、広告再生中にカウントダウンタイマーを表示し、すべての広告を視聴することを強制します。この機能は簡単にカスタマイズでき、広告スキップも可能です。

Brightcove プレーヤーを設定すれば、広告がブロックされていない場合はクライアントサイド広告を使用し、広告ブロッカーが検出された場合は自動的に SSAI にフェイルオーバーすることができます。この機能の有効化について詳細は、広告フェイルオーバードキュメントをご確認ください。

以下は概要動画です：

要件

SSAI を利用するには、Video Cloud アカウントが Dynamic Delivery に対応し、SSAI が有効化されている必要があります。この機能を使用するには、弊社営業担当までお問い合わせください。

プレーヤー例

この例では、VMAP ファイルで定義された IMA 広告を使用して、動画ストリームにサーバーサイド広告を挿入しています。プリロール、ミッドロール、ポストロール広告が表示されることを確認できます。VMAP ファイルは広告設定で指定されています。

See the Pen 18468-advertising-ssai-plugin by Brightcove Learning Services (@bcls1969) on CodePen.

ソースコードをご覧ください。

機能

Brightcove SSAI は Once UX 広告配信の最新代替手段です。主な機能は次のとおりです：

より完全な VMAP/VAST パース処理
VAST コンパニオン広告の完全サポート
タイムラインおよびリニア広告ロール操作のための新しい API
プレイリスト、広告マクロ、FairPlay のサポート
SSAI は DRM コンテンツと非 DRM コンテンツの両方に対応
SSAI の主な役割のひとつは、シークや広告に関する特定の挙動を強制することです。
レガシー Once UX VMAP（uo namespace）と新しい Dynamic Delivery VMAP（bc namespace）の両方に対応

開始方法

Video Cloud でサーバーサイド広告を再生するには、以下の手順に従います：

広告設定を作成する
Brightcove プレーヤーを作成する
Studio を使用して SSAI を実装する

以上で、Brightcove プレーヤーがサーバーサイド広告に対応しました。必要に応じて、プログラムによる SSAI 実装のように、プログラムから SSAI を追加することもできます。

広告設定を作成する

広告設定では、広告リクエスト、ビーコン、その他の再生に関するオプションなど、SSAI 再生のさまざまな要素を定義します。広告レスポンスには VAST、VMAP、または GAM Ad Rules を使用できます。広告設定を作成するには、次の手順に従います：

Video Cloud Studio で 管理者 メニューを展開し、サーバーサイド広告設定 を選択します。

広告設定管理画面
広告設定の情報を入力し、保存を選択します。

広告設定

詳細については、サーバーサイド広告設定の構成ドキュメントをご確認ください。

SSAI API を使用して広告設定を作成する方法については、Video Cloud SSAI Ad Config API ドキュメントをご参照ください。

Brightcove プレーヤーを作成する

Video Cloud Studio を使用して新しい Brightcove プレーヤーを作成します。詳細は、Video Cloud 基本操作：プレーヤーの作成ドキュメントをご覧ください。

Studio を使用した SSAI の実装

最も簡単にプレーヤーをサーバーサイド広告対応にするには、Video Cloud Studio を使用します。広告設定とプレーヤーを作成したら、次の手順でプレーヤーを SSAI に対応させます：

PLAYERS モジュールを開き、広告機能を追加したいプレーヤーを探します。
プレーヤーを選択し、プロパティを開きます。
左側のナビゲーションメニューから広告を選択します。
サーバーサイド (SSAI) の有効化 チェックボックスをオンにします。
設定の選択 ドロップダウンから、このプレーヤーに関連付ける広告設定を選択します。
広告上にオーバーレイを表示したい場合は、広告情報オーバーレイの有効化 チェックボックスをオンにします。これには「Learn More」や広告カウントダウンオーバーレイが含まれます。

オーバーレイを表示するには、ここで有効化するだけでなく、VAST 広告タグでオーバーレイを設定する必要があります。
入力が完了すると、フォームは次のようになります：

Players モジュールでの SSAI 広告設定
保存を選択します。
プレーヤーを公開するには、公開と埋め込み > 公開の変更 を選択します。

広告設定の変更を保存すると、SSAI プラグインはプラグイン設定の一部として構成されます。JavaScript と CSS は広告セクションから追加したため非表示になります。

広告付き動画を再生する

Dynamic Delivery で取り込まれた Video Cloud の動画は、広告設定の VMAP ファイルで指定された広告を含みます。SSAI を動作させるには、動画に音声トラックが必要です。

プログラムによる SSAI の実装

前のセクションで示したように、Video Cloud Studio を使用すると、簡単に SSAI をプレーヤーに追加できます。これをプログラムで行いたい場合は、次の手順に従います。

SSAI プラグインを追加する
プレーヤーに広告を関連付ける
広告付き動画を再生する

SSAI プラグインを追加する

SSAI プラグインのファイルを HTML コードに直接追加することも、ここで示すようにプレーヤー設定に追加することもできます。

PLAYERS モジュールを開き、新しいプレーヤーを作成するか、プラグインを追加したいプレーヤーを探します。
プレーヤーのリンクをクリックして、そのプレーヤーのプロパティを開きます。
プラグイン を左側のナビゲーションメニューでクリックします。
プラグインの追加 ドロップダウンから カスタムプラグイン を選択します。
プラグイン名 には ssai と入力します。

JavaScript の URL には次を入力します:

          https://players.brightcove.net/videojs-ssai/2/videojs-ssai.js

CSS の URL には次を入力します:
```
          https://players.brightcove.net/videojs-ssai/2/videojs-ssai.css
```
プレーヤーのバージョンが 6.x の場合は、SSAI プラグインのバージョン 1 を使用する必要があります。その場合は、CSS と JavaScript の URL にある /2/ を /1/ に置き換えてください。
このプラグインについては、オプションを入力する必要はありません。
保存をクリックします。
プレーヤーを公開するには、公開と埋め込み > 変更の公開 をクリックします。
開いているダイアログを閉じるには、閉じる をクリックします。

プレーヤーに広告を関連付ける

次に、広告設定を Brightcove Player に関連付けます。これを行う方法は 3 つあります。

iframe 埋め込みコード
Videoタグ埋め込みコード
カタログを使用する
プレーヤー設定を更新する

iframe 埋め込みコード

iframe 埋め込みコードを使用する場合は、クエリ文字列パラメーター adConfigId に広告設定 ID の値を指定します。

          <iframe src="https://players.brightcove.net/1752604059001/default_default/
          index.html?videoId=5625751316001&adConfigId=your ad config id"
            allowfullscreen
            allow="encrypted-media"
            width="640"
            height="360"></iframe>

Videoタグ埋め込みコード

Videoタグ埋め込みコードを使用する場合は、data-ad-config-id 属性に広告設定 ID の値を指定します。

          <video-js data-video-id="5625751316001"
            data-account="1752604059001"
            data-player="default"
            data-embed="default"
            data-application-id
            data-ad-config-id="your ad config id"
            controls=""
            width="640" height="360"></video-js>
          <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>

カタログを使用する

player catalog を使用して、動画に広告を関連付けることができます。カタログは次の 2 つのリクエストを行うことで動作します。

プレーヤーカタログから動画データをリクエストします。これには VMAP URL が含まれます。
プレーヤーのソースに VMAP URL を設定し、Dynamic Delivery から VMAP ドキュメントのリクエストをトリガーします。その後、プレーヤーのソースは有効な VMAP XML ドキュメントに再設定されます。

SSAI で catalog を使用する場合は、Playback API の getVideo() 呼び出しに広告設定 ID を次のように追加します。

          var adConfigId = "your ad config id";
          var myPlayer = videojs.getPlayer('myPlayerId');
          // If you added the SSAI plugin using the Players module, then the initialization
          // step is performed automatically. Uncomment the next line if you
          // did not use the Players module.
          //myPlayer.ssai();
          
          myPlayer.catalog.getVideo("your video id", function(error, video) {
            if (error) {
              myPlayer.error(error);
            } else {
              myPlayer.catalog.load(video);
            }
          }, adConfigId);

プレーヤー設定を更新する

別の方法として、Brightcove Player の設定に広告設定 ID を含めて広告を関連付けることもできます。その場合は、次のように Player Management API を使用します。

PATCH コマンドを使用して、ad_config_id を設定します。以下は cURL を使ってプレーヤーを更新する例です。

          curl \
            --header "Content-Type: application/json" \
            --user $EMAIL \
            --request PATCH \
            --data '{
                "ad_config_id" : "$CONFIG_ID"
            }' \
            https://players.api.brightcove.com/v1/accounts/$ACCOUNT_ID/players/$PLAYER_ID/configuration

次に、以下のようにして変更内容を公開します。

          curl \
            --header "Content-Type: application/json" \
            --user $EMAIL \
            --request POST \
            https://players.api.brightcove.com/v1/accounts/$ACCOUNT_ID/players/$PLAYER_ID/publish

Brightcove Player の設定に、ad_config_id が設定されていること、および ssai プラグインと関連プラグインファイルが含まれていることを確認します。確認するには、次の手順に従います。

Studio の Players モジュールで対象のプレーヤーに移動し、プレーヤー名のリンクをクリックして詳細を表示します。
埋め込みとプレビュー を選択します（プレビューでも公開でも構いません）。URLを取得する のリンクをクリックします。
ブラウザのアドレスバーで、URL 内の index.html を config.json に変更し、新しい URL にアクセスします。

プレーヤー設定は次のような内容になっているはずです。

          {
            "account_id": "1752604059001",
            "ad_config_id": "d6190656-2095-4ff3-8afe-123abcde",
            "compatibility": true,
            "embed_id": "default",
            "player": {
              "template": {
                "name": "single-video-template",
                "version": "7.7.0"
              }
            },
            "player_id": "rJCECV0RZ",
            "player_name": "SSAI Player",
            "plugins": [
              {
                "name": "ssai"
              }
            ],
            "scripts": [
              "https://players.brightcove.net/videojs-ssai/2/videojs-ssai.js"
            ],
            "stylesheets": [
              "https://players.brightcove.net/videojs-ssai/2/videojs-ssai.css"
            ],
            "updated_at": "2017-11-07T16:03:47.161Z",
            "video_cloud": {
              "policy_key": "ABCDE123456789",
              "video": null
            }
          }

プレーヤーのバージョンが 6.x の場合は、SSAI プラグインのバージョン 1 を使用する必要があります。その場合は、CSS と JavaScript の URL にある /2/ を /1/ に置き換えてください。

広告付き動画の再生

Dynamic Delivery で取り込まれた Video Cloud の動画は、広告設定内の VMAP ファイルで指定された広告を含みます。SSAI を動作させるには、動画に音声トラックが含まれている必要があります。

オプション

debug
- true に設定すると、contrib-ads 内でデバッグメッセージを有効にし、videojs-bc-analytics-logger が存在する場合に追加情報をログ出力します。
hideOverlays
- true に設定すると、広告再生中にカウントダウンタイマーや Learn More クリック用オーバーレイが表示されなくなります。
trackingBeacons
- false に設定すると、VMAP から解析された広告ビュー、インプレッション、四分位イベントなどのトラッキングビーコンは送信されません。
timeout
- VMAP を取得するための XHR がタイムアウトするまでのミリ秒数です。
vmapURLParams
VMAP 内のコンテンツ URL に含まれる値を任意で置換するためのパラメーターを含むオブジェクトです。詳細は SSAI - URL Variables セクションをご覧ください。

注意：この SSAI プラグインのオプションは v2.1.0 以降で利用可能です。
- vmapURLParams.* - このオブジェクトのキー名は任意です。このプロパティ名は、❴❴url.*❵❵ の形式に一致する VMAP のソース URL パラメータ文字列と一致している必要があります。一致しない場合、置換されません。
  
  例: vmapURLParams が { foo: 123, bar: 'test' } に設定されている場合：
  - 元の VMAP ソース URL:
```
.../content.vmap?bc_token=1234
```
  - 次のように更新されます：
```
.../content.vmap?bc_token=1234&foo=123&bar=test
```

スタイリング

このプラグインでは、プラグインの状態を判断するためにターゲット可能な有用な HTML クラスがプレーヤーに適用されます。

クラス	用途
`vjs-ssai`	SSAI プラグインが初期化されたことを示しますが、有効化されているとは限りません。SSAI ソースを再生していない場合でも適用されます。
`vjs-ssai-enabled`	SSAI プラグインが現在有効です。つまり、SSAI ソースがプレーヤーに設定されています。
`vjs-ssai-disabled`	SSAI プラグインが現在無効です。
`vjs-ssai-waiting`	SSAI プラグインがデータまたは外部プロセスの待機中です。
`vjs-ssai-not-waiting`	SSAI プラグインが待機状態ではありません。
`vjs-ssai-hide-overlays`	`hideOverlays` オプションが true に設定されています。
`vjs-ssai-show-overlays`	`showOverlays` オプションが true に設定されています（デフォルト）。

メソッド / プロパティ

SSAI プラグインを使用する際に利用可能なパブリックメソッドがいくつかあります。通常のプレーヤーメソッドも併用できます。

SSAI メソッドを使用するには、以下のように JavaScript コード内でプラグインの読み込みを待つ必要があります。

          <script>
            videojs.getPlayer('myPlayerID').ready(function () {
              const myPlayer = this;
              myPlayer.on("loadedmetadata", function () {
                console.log(myPlayer.ssai().currentTimelineState());
              });
            });
          </script>

タイムライン状態メソッド

*TimelineState メソッドは TimelineState オブジェクトを返します。TimelineState オブジェクトは、SSAI ストリームの任意の絶対タイムライン上での再生状態を示す特定のインターフェースを持つ通常のオブジェクトです。

「絶対時間」は、広告とコンテンツを含むストリーム全体のタイムライン上の位置を指します。「相対時間」とは、現在の再生対象（広告またはコンテンツ）内での時間を指します。

contentTimelineState(time)

引数: time - 数値（秒・コンテンツ相対）
戻り値: TimelineState オブジェクト、または SSAI タイムラインが利用できない場合は undefined
目的: 指定したコンテンツ時間（広告を除く）でのタイムライン状態を取得します。

例:

          // 広告を除いたコンテンツの 50 秒地点での状態を取得
          const state = myPlayer.ssai().contentTimelineState(50);
          // 30 秒のプリロールがある場合、absoluteTime は 80 秒になることがあります
          console.log('Absolute time:', state.absoluteTime);

absoluteTimelineState(time)

引数: time - 数値（秒・絶対タイムライン位置）
戻り値: TimelineState オブジェクト、または SSAI タイムラインが利用できない場合は undefined
目的: 指定した絶対時間（広告を含む）でのタイムライン状態を取得します。

例:

          // 広告を含む絶対タイムラインの 45 秒地点での状態を取得
          const state = myPlayer.ssai().absoluteTimelineState(45);
          // 30 秒のプリロールがある場合、これは実際のコンテンツの 15 秒地点となる可能性があります
          console.log('Content time:', state.relativeTime);

currentTimelineState()

引数: なし
戻り値: TimelineState オブジェクト、または SSAI タイムラインが利用できない場合は undefined
目的: プレーヤーの現在の絶対位置でのタイムライン状態を取得します。

例:

          
          const currentState = myPlayer.ssai().currentTimelineState();
          if (currentState.linearAd) {
            console.log('現在広告中:', currentState.linearAd.id());
          } else {
            console.log('コンテンツ再生位置:', currentState.relativeTime, '秒');
          }

relativeTimelineState()

引数: なし
戻り値: TimelineState オブジェクト、または SSAI タイムラインが利用できない場合は undefined
目的: プレーヤーの現在の相対再生位置（広告中は広告相対／コンテンツ中はコンテンツ相対）でのタイムライン状態を取得します。

例:

          
          const relativeState = myPlayer.ssai().relativeTimelineState();
          if (relativeState.linearAd) {
            console.log(`広告の進行状況: ${relativeState.relativeTime}/${relativeState.relativeDuration}`);
          } else {
            console.log(`コンテンツの進行状況: ${relativeState.relativeTime}/${relativeState.relativeDuration}`);
          }

seekInAbsoluteTime(requestedTime, preventAdSkips)

引数:
- requestedTime - 数値（秒・絶対タイムライン）
- preventAdSkips - boolean（省略時は false）
戻り値: 絶対時間（数値）または undefined
目的: 指定した絶対時間にシークします。preventAdSkips=true の場合、広告スキップが防止されます。

例:

          // 広告を含む絶対タイムラインの 90 秒地点にシーク
          const finalTime = myPlayer.ssai().seekInAbsoluteTime(90, true);
          console.log('実際にシークされた位置:', finalTime);

seekInRelativeTime(requestedTime, preventAdSkips) (非推奨)

引数:
- requestedTime - 数値（秒・現在の広告／コンテンツ相対）
- preventAdSkips - boolean（省略時は false）
戻り値: 絶対時間（数値）または undefined
目的: 現在の広告またはコンテンツ内でシークします。広告内では範囲内に制限され、コンテンツ中は seekInContentTime() が呼び出されます。 ※このメソッドは非推奨であり、seekInContentTime() を使用してください。

seekInContentTime(requestedTime, preventAdSkips)

引数:
- requestedTime - 数値（秒・コンテンツ相対）
- preventAdSkips - boolean（省略時は false）
戻り値: 絶対時間（数値）または undefined
目的: コンテンツ相対の時間にシークし、広告時間を自動的に考慮します。

例:

          // 広告時間を考慮しながら、コンテンツの 60 秒地点にシーク
          const finalTime = myPlayer.ssai().seekInContentTime(60);

absoluteDuration()

引数: なし
戻り値: 数値（秒）または undefined
目的: 広告を含むストリームの総再生時間を取得します。

例:

          const totalDuration = myPlayer.ssai().absoluteDuration();
          console.log('広告を含むストリーム全体の再生時間:', totalDuration, '秒');

contentDuration()

引数: なし
戻り値: 数値（秒）または undefined
目的: 広告を除くコンテンツのみの再生時間を取得します。

例:

          const contentDuration = myPlayer.ssai().contentDuration();
          const absoluteDuration = myPlayer.ssai().absoluteDuration();
          const totalAdDuration = absoluteDuration - contentDuration;
          console.log('コンテンツの再生時間:', contentDuration, '秒');
          console.log('広告の総再生時間:', totalAdDuration, '秒');

タイムライン状態プロパティ

タイムライン状態プロパティの値は次のように取得できます：

          myPlayer.ssai().absoluteTimelineState().absoluteDuration;

以下は TimelineState オブジェクトに関連するプロパティ一覧です：

absoluteTime

Type: Number
ストリーム内の絶対時間。

absoluteDuration

Type: Number
ストリームの絶対再生時間。

relativeTime

Type: Number
現在の広告またはコンテンツに対する相対時間。

relativeDuration

Type: Number
現在の広告またはコンテンツの再生時間。

linearAdRoll

Type: LinearAdRoll
絶対時間に基づく現在のリニア広告ロールを表すオブジェクト。

linearAd

Type: LinearAd
絶対時間に基づく現在のリニア広告を表すオブジェクト。

イベント

現時点では、このプラグインによってディスパッチされる SSAI 固有のイベントは 1 つだけです。

bcov-ssai-click-through

このイベントは、広告のクリックスルーがリクエストされたことを示すために、プラグイン内部からディスパッチされます。

設定に関する注意事項

SSAI 使用時には広告のプリロードは行わないでください。理由として、プリロードを行うと、動画が再生される前にプレーヤーが広告インプレッションや、場合によっては最初の四分位ビーコンを送信してしまうためです。その結果、広告分析が不正確になる可能性があります。Studio で SSAI を設定した場合は、この点は自動的に処理されますが、手動で SSAI を設定する場合は、この問題を認識しておく必要があります。
Web プレーヤーで SSAI を使用しており、その目的のひとつが広告ブロッカーの回避である場合は、サーバーサイドビーコンを使用するべきです。クライアントサイドビーコンはブロックされるため使用すべきではありません。

用語集

このプラグインでは、SSAI ストリームにおける absolute（絶対）時間と content（コンテンツ）時間という概念を区別しています。従来の動画プレーヤーは、再生中の URI の開始から終了までの content 時間のみを扱います。SSAI ストリームは、本質的に複数の content ストリームに広告動画がステッチされたものなので、動画広告を含むステッチ済みのストリーム全体を考慮する absolute 時間の概念を導入しています。

プロパティやメソッドで absolute というプレフィックスが付いている場合、その時間はステッチされたストリーム全体に対する時間を意味します。一方、content プレフィックスが付いている場合、その時間はストリームにステッチされた特定のコンテンツ（メインコンテンツまたは単一のリニア広告）に対する時間を意味します。

Absolute time : SSAI ストリーム全体のタイムライン上の任意の時点を指します。例えば、0:30 のプリロール広告が付いた 2:00 の動画は、合計の absolute time が 2:30 になります。absolute time 0:15 はプリロール中、absolute time 0:31 はコンテンツの最初の 1 秒です。
Relative time : 現在再生中のメディアブロック（コンテンツまたは広告）に対する時間を指します。上記の例を拡張すると、プリロール中は relative time 0:15 は absolute time 0:15 と同義ですが、absolute time 0:31 は relative time 0:01 に相当します。

一般的に、relative time はプレーヤー UI に表示される時間であり、このプラグインおよび関連ミドルウェアの主な役割のひとつは、absolute time と relative time の相互変換を行うことです。
Content time は、SSAI ストリームのコンテンツタイムライン（すべての広告を無視）における時点を指します。例えば、0:30 のプリロール広告が付いた 2:00 の動画は、content time は 2:00 になります。content time の 0:15 は、absolute time の 0:45（プリロール 0:30 ＋コンテンツ 0:15）に相当します。

既知の問題

SSAI プラグイン使用時の既知の問題は次のとおりです。

Safari 10/11 では、動画の最後にポストロールの最終フレームが表示される場合があります。
SSAI はオーバーレイ広告を動画ストリームにステッチしません。

補足情報

SSAI VOD

Brightcove Playback API (PAPI) のレスポンスを基に独自実装を行う場合は、次の点に注意してください。
- Server-Side Ad Insertion (SSAI) を使用する場合、サムネイルマニフェストは PAPI レスポンスではなく VMAP 内に含まれます。
- SSAI を使用しない場合、サムネイルマニフェストは PAPI レスポンスに含まれます。
制限事項の一覧は、SSAI の概要ドキュメントを参照してください。

SSAI Live

ライブ SSAI 用の VMAP は現在サポートされていません。
ライブ再生での SSAI には SSAI プラグインは不要であり、ライブに対してはクライアントサイド機能の SSAI 再生は利用できません。
制限事項の一覧は、Brightcove Live API（SSAI 対応）ドキュメントを参照してください。

SSAI ミッドロールの挙動

サーバーサイド広告（SSAI）はストリームに直接ステッチされるため、SSAI のミッドロール広告の扱いは CSAI のミッドロール広告とは異なります。 SSAI ミッドロールにおいて想定される挙動は次のとおりです：

ユーザーがミッドロール広告を視聴せずにその位置をシークで飛ばした場合、コンテンツが再開する前に、そのミッドロール広告が再生されます。
ユーザーが一度ミッドロール広告を視聴した後に、その位置をシークで飛ばした場合、プレーヤーはそのミッドロール広告をスキップします。

変更履歴

SSAI プラグインリリースノートを参照してください。

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