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

概要

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

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

Brightcove Player を、広告がブロックされていない場合にはクライアントサイド広告を使用し、広告ブロッカーが検出された場合に自動的に SSAI にフェイルオーバーするように設定できます。この機能を有効にする方法の詳細については、Ad failover ドキュメントを参照してください。

こちらは概要動画です:

要件

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 の主な役割の 1 つは、シーク操作および広告に関する特定の動作を強制することです。
レガシーの Once UX VMAP（uo 名前空間を使用）と新しい Dynamic Delivery VMAP（bc 名前空間を使用）の両方をサポート

はじめに

Video Cloud からのサーバーサイド広告を再生するには、次の手順に従います:

広告設定を作成する
Brightcove Player を作成する
Studio を使用して SSAI を実装する

これで完了です。Brightcove Player はサーバーサイド広告用に設定されました。必要に応じて、プログラム的に SSAI を実装するセクションで示すように、SSAI をプログラムで追加することもできます。

広告設定を作成する

広告設定では、広告呼び出し、ビーコン、その他の設定オプションなど、SSAI 再生のさまざまな側面を定義します。広告レスポンスは VAST、VMAP、または GAM Ad Rules のいずれかにすることができます。広告設定を作成するには、次の手順に従います:

Video Cloud Studio で Admin モジュールを開き、VOD Server-Side Ad Settings を選択します。
New + を選択し、設定の詳細を入力して、Add を選択します。

詳細については、Configuring Server-Side Ad Settings ドキュメントを参照してください。

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

Brightcove Player を作成する

Video Cloud Studio を使用して新しい Brightcove Player を作成します。詳細については、Video Cloud Basics: Creating a Player ドキュメントを参照してください。

Studio を使用した SSAI の実装

サーバーサイド広告用にプレーヤーを設定する最も簡単な方法は、Video Cloud Studio を使用することです。広告設定とプレーヤーを作成したら、次の手順でプレーヤーを SSAI 用に設定できます:

Players モジュールを開き、広告機能を追加したいプレーヤーを見つけます。
そのプレーヤーへのリンクを選択して、プレーヤーのプロパティを開きます。
Overview タブの Advertising アコーディオンを展開します。
Enable Server-Side (SSAI) トグルを有効にします。
Ad Configuration (VOD) ドロップダウンから、このプレーヤーに関連付けたい広告設定を選択します。
広告の上にオーバーレイを表示したい場合は、Enable ad information overlays トグルを有効にします。これには「Learn More」および広告のカウントダウンオーバーレイが含まれます。

オーバーレイは、ここで有効化し、VAST 広告タグでも設定するまで表示されません。
公開済みのプレーヤーに設定を反映するには、Publish Changes をクリックします。

広告プロパティへの変更が保存されると、SSAI プラグインがプラグイン設定の一部として構成されます。Advertising セクションを介して追加されたため、JavaScript および CSS は非表示になります。

JSON Editor を使用して実装する

プレーヤー 7.21.0 以降では、JSON Editor を使用して次の手順でプラグインを追加することもできます:

Players モジュールで、設定したいプレーヤーに移動します。Overview タブの JSON Editor セクションを展開します。 "plugins" 配列を変更して、SSAI プラグインを追加します。

  
    "plugins": [
    {
      "name": "ssai",
      "is_packaged": true,
      "options": {
        ...
      }
    }
  ]

広告付きの動画を再生する

Dynamic Delivery で取り込まれた Video Cloud から取得する動画には、広告設定の VMAP ファイルで指定された広告が含まれます。SSAI を機能させるには、動画にオーディオトラックが関連付けられている必要があります。

プログラム的に SSAI を実装する

サーバーサイド広告用にプレーヤーを設定する最も簡単な方法は、前のセクションで示したように Video Cloud Studio を使用することです。Studio の Advertising セクションから SSAI を有効にすると、SSAI プラグインがプレーヤー設定に自動的に含まれます。

実行時にプログラム的に広告を関連付けたり、広告のロード方法をカスタマイズしたりする必要がある場合は、いくつかの方法で実現できます:

Iframe 埋め込みコード

Iframe 埋め込みコードでは、広告設定 ID の値を持つ adConfigId クエリ文字列パラメーターを含めます:

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

JavaScript 埋め込みコード

JavaScript 埋め込みコードでは、広告設定 ID の値を持つ data-ad-config-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);

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

広告を関連付けるもう 1 つの方法は、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 の設定に、設定 ID の値を持つ ad_config_id と、関連するプラグインファイルを含む ssai プラグインが含まれていることを確認します。次の手順に従います:
1. Studio の Players モジュールでプレーヤーに移動します。プレーヤー名のリンクをクリックして詳細を表示します。
2. Embed Code & URL（Preview または Published のいずれか）を選択します。Player URL リンクをクリックします。
3. ブラウザのアドレスバーで 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.40.0"
    }
  },
  "player_id": "rJCECV0RZ",
  "player_name": "SSAI Player",
      "plugins": [
  {
    "name": "ssai",
    "is_packaged": true,
    "options": {
      ...
    }
  }
],
  "updated_at": "2017-11-07T16:03:47.161Z",
  "video_cloud": {
    "policy_key": "ABCDE123456789",
    "video": null
  }
}
```

広告付きの動画を再生する

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 オブジェクトを返します。タイムライン状態オブジェクトは、絶対タイムライン上の任意の時点における SSAI ストリームの再生状態を詳述する特定のインターフェイスを持つプレーンオブジェクトです。

「絶対時間」とは、ストリームの完全なタイムライン（広告とコンテンツの両方を含む）における時点を指します。「相対時間」とは、現在のコンテンツ（広告またはコンテンツ）に対する相対的な時間を指します。

contentTimelineState(time)

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

例:

// Get timeline state at 50 seconds into the content (excluding ads)
const state = myPlayer.ssai().contentTimelineState(50);
// If there's a 30s pre-roll, absoluteTime might be 80s
console.log('Absolute time:', state.absoluteTime);

absoluteTimelineState(time)

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

例:

// Get timeline state at 45 seconds into the absolute timeline (including ads)
const state = myPlayer.ssai().absoluteTimelineState(45);
// With a 30s pre-roll, this would be 15 seconds into the actual content
console.log('Content time:', state.relativeTime);

currentTimelineState()

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

例:


const currentState = myPlayer.ssai().currentTimelineState();
if (currentState.linearAd) {
  console.log('Currently in ad:', currentState.linearAd.id());
} else {
  console.log('In content at:', currentState.relativeTime, 'seconds');
}

relativeTimelineState()

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

例:


const relativeState = myPlayer.ssai().relativeTimelineState();
if (relativeState.linearAd) {
  console.log(`Ad progress: ${relativeState.relativeTime}/${relativeState.relativeDuration}`);
} else {
  console.log(`Content progress: ${relativeState.relativeTime}/${relativeState.relativeDuration}`);
}

seekInAbsoluteTime(requestedTime, preventAdSkips)

引数:
- requestedTime - 数値（秒、絶対タイムライン位置）。
- preventAdSkips - 真偽値（オプション、デフォルトは false）。
戻り値: 数値（最終的にシークされた絶対時間）、または SSAI タイムラインが利用できない場合は undefined。
目的: 特定の絶対ストリーム時間にシークします。preventAdSkips が true の場合、広告強制機能により広告のスキップが防止されます。

例:

// Seek to 90 seconds into the absolute timeline (including ads)
const finalTime = myPlayer.ssai().seekInAbsoluteTime(90, true);
console.log('Seeked to:', finalTime);

seekInRelativeTime(requestedTime, preventAdSkips) （非推奨）

引数:
- requestedTime - 数値（秒、現在再生中のセグメントを基準とする時間: 広告中は広告相対、コンテンツ中はコンテンツ相対）。
- preventAdSkips - 真偽値（オプション、デフォルトは false）。
戻り値: 数値（最終的にシークされた絶対時間）、または SSAI タイムラインが利用できない場合は undefined。
目的: 現在再生中のセグメント（広告またはコンテンツ）内でシークします。広告中の場合、シークは広告の境界にクランプされます。コンテンツ中の場合は seekInContentTime() に委譲されます。注: このメソッドは非推奨であり、seekInContentTime() に置き換える必要があります。

seekInContentTime(requestedTime, preventAdSkips)

引数:
- requestedTime - 数値（秒、コンテンツ相対）。
- preventAdSkips - 真偽値（オプション、デフォルトは false）。
戻り値: 数値（最終的にシークされた絶対時間）、または SSAI タイムラインが利用できない場合は undefined。
目的: 広告の長さを自動的に考慮してコンテンツ相対時間にシークします。

例:

// Seek to 60 seconds into the content (ads will be accounted for automatically)
const finalTime = myPlayer.ssai().seekInContentTime(60);

absoluteDuration()

引数: なし。
戻り値: 数値（秒）、または SSAI タイムラインが利用できない場合は undefined。
目的: すべての広告を含む合計ストリーム長を取得します。

例:

const totalDuration = myPlayer.ssai().absoluteDuration();
console.log('Total stream duration with ads:', totalDuration, 'seconds');

contentDuration()

引数: なし。
戻り値: 数値（秒）、または SSAI タイムラインが利用できない場合は undefined。
目的: すべての広告を除くコンテンツのみの長さを取得します。

例:

const contentDuration = myPlayer.ssai().contentDuration();
const absoluteDuration = myPlayer.ssai().absoluteDuration();
const totalAdDuration = absoluteDuration - contentDuration;
console.log('Content duration:', contentDuration, 'seconds');
console.log('Total ad duration:', totalAdDuration, 'seconds');

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

タイムライン状態プロパティの値を取得するには、次の構文を使用できます:

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

TimelineState オブジェクトに関連付けられたプロパティの一覧は次のとおりです:

absoluteTime

型: 数値
ストリーム内の絶対時間。

absoluteDuration

型: 数値
ストリームの絶対長。

relativeTime

型: 数値
現在のリニア広告またはコンテンツ自体に対する相対的な、ストリーム内の時間。

relativeDuration

型: 数値
現在のリニア広告またはコンテンツ自体の長さ。

linearAdRoll

型: LinearAdRoll
絶対時間に対する現在のリニア広告を表すオブジェクト。

linearAd

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

イベント

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

bcov-ssai-click-through

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

設定上の注意事項

SSAI で広告のプリロードを行うべきではありません。プリロードを行うと、動画が再生される前にプレーヤーが広告のインプレッションおよびおそらく最初のクォータイルビーコンを報告してしまうためです。これにより広告アナリティクスが不正確になる可能性があります。Studio で SSAI を設定すると自動的に処理されますが、手動で SSAI をセットアップする場合はこの問題に注意する必要があります。
ウェブプレーヤーが SSAI を使用しており、その動機の 1 つが広告ブロッカーへの対策である場合は、サーバーサイドビーコンを使用すべきです。クライアントサイドビーコンはブロックされる可能性があるため、使用すべきではありません。

用語集

このプラグインでは、SSAI ストリーム内の絶対時間とコンテンツ時間の概念を区別します。従来の動画プレーヤーにはコンテンツ時間の概念しかありません。これは、現在再生中の URI の開始から終了までの時間です。SSAI ストリームは本質的に複数のコンテンツストリームをつなぎ合わせたものであるため、動画広告を含む完全に結合されたストリームを考慮する絶対時間という概念を導入しました。

プロパティまたはメソッドのプレフィックスとしてabsoluteが付いている場合、想定される時間や返される時間は結合されたストリーム全体に対する相対値です。contentのプレフィックスが付いている場合、想定される時間や返される時間はストリームに結合された特定のコンテンツ（メインコンテンツまたは単一のリニア広告）に対してのみ相対値となります。

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

一般に、相対時間はプレーヤー UI で表示される時間であり、このプラグインおよび関連するミドルウェアの作業の多くは、絶対時間から相対時間への変換です。
コンテンツ時間は、SSAI ストリームのコンテンツタイムライン内の時点を指し、すべての広告を無視します。例えば、0:30 のプレロール広告がある 2:00 の動画は、コンテンツ時間が 2:00 です。コンテンツ時間 0:15 は絶対時間 0:45（プレロール + 15 秒）に相当します。

既知の問題

SSAI プラグインを使用する際の既知の問題は次のとおりです:

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

注意事項

SSAI VOD

Brightcove Playback API（PAPI）のレスポンスをベースにしてカスタム実装を構築する場合、次の点に注意してください:
- Server-Side Ad Insertion（SSAI）では、サムネイルマニフェストは PAPI レスポンスではなく VMAP に含まれます。
- 非 SSAI の場合、サムネイルマニフェストは PAPI レスポンスに含まれます。
制限事項の一覧については、SSAI Overview ドキュメントを参照してください。

SSAI Live

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

SSAI ミッドロールの動作

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

ユーザーがミッドロール広告を視聴せずにシークして通り過ぎた場合、コンテンツが再開する前にその広告が再生されます。
ユーザーが広告を既に視聴した後にシークしてミッドロール広告を通り過ぎた場合、プレーヤーはミッドロール広告をスキップします。

変更履歴

v2.8.2 までの過去のリリースノートおよび変更履歴については、SSAI Plugin Releases を参照してください。

v2.8.2 以降に行われた重要な変更は、Brightcove Player リリースノートに記載されます。