このページは Cloud Translation API によって翻訳されました。

広告ブレーク

概要

Web Receiver SDK は、特定のメディアストリーム内の広告ブレークとコンパニオン広告をネイティブでサポートしています。レシーバに広告ブレークを組み込む方法は 2 つあります。1 つはブレーク、もう 1 つはブレーククリップを使用する方法です。

広告ブレークの開発を始める前に、カスタムウェブレシーバーのセットアップについて理解しておいてください。Cast SDK Ad Breaks API を使用すると、広告が再生に含まれる場合、すべての Cast 対応デバイスで一貫したエクスペリエンスが得られます。

このガイドでは、1 つ以上の広告またはバンパーを含む再生間隔を示し、各広告またはバンパーはブレーククリップといいます。

次の図は、2 つの広告ブレークがあり、それぞれに 2 つの広告が含まれています。

イベント

次の表に、再生中に中断が発生したときにトリガーされるイベントを示します。

休憩イベント	説明
ブレイク開始	ブレークの最初のブレーククリップの読み込みが開始されると呼び出されます。イベントは `cast.framework.events.BreaksEvent` です。
BREAK_ENDED（終了）	ブレークの最後のブレーククリップが終了すると呼び出されます。イベントは `cast.framework.events.BreaksEvent` です。注: ユーザーがブレークの最後の休憩クリップをスキップして、休憩を終了した場合でも、このイベントは発生します。
BREAK_CLIP_LOADING	ブレーククリップの読み込みが開始されると呼び出されます。イベントは `cast.framework.events.BreaksEvent` です。
ブレイク CLIP_STARTED	ブレーククリップが開始されると呼び出されます。イベントは `cast.framework.events.BreaksEvent` です。
BREAK_CLIP_ENDED	ブレーククリップが終了すると呼び出されます。イベントは `cast.framework.events.BreaksEvent` です。注: ユーザーがブレーククリップをスキップしても、このイベントは発生します。`BreaksEvent` の `endedReason` プロパティを確認してください。休憩クリップの視聴時間を確認するには、`PlayerManager` の `getBreakClipCurrentTimeSec` と `getBreakClipDurationSec` を確認してください。

これらのイベントは、分析と広告再生のトラッキングに使用できます。VMAP（Video Multiple Ad Playlist）と VAST（Video Ad Serving Template）が使用されている場合、レスポンスで提供された標準のトラッキングイベントが SDK によって自動的にディスパッチされます。

ブレークの再生中は、Web Receiver SDK が MediaStatus と breakStatus を接続済みのすべての送信者にブロードキャストします。送信者はこの情報を使用して UI を更新し、シークオペレーションを抑制できます。

Web Receiver SDK には、レシーバに広告ブレークを組み込む方法が 2 つあります。クライアント側合成とサーバー側合成です。

クライアントサイドの広告の合成

クライアント側広告スティッチ（埋め込みなし）については、メディアの読み込み時に Break オブジェクトと BreakClip オブジェクトを使って必要な広告情報を指定する必要があります。次のスニペットは、プレロール、ミッドロール、ポストロールのブレークを追加する関数の例です。third_party への参照とそのメソッドは、デベロッパーがアプリで使用するヘルパー関数の例です。このスニペットは、ユーザーが BREAK_CLIP_ENDED イベントをリッスンして endedReason の値を確認することで、最後まで再生した場合のトラッキングイベントの呼び出し方法を示しています。

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    contentId: third_party.getBreakClipUrl('bc1'),
    contentType: third_party.getBreakClipContentType('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0  //pre-roll position
  },
  {
    id: 'b2',
    breakClipIds: ['bc3'],
    position: 10*60 //ten minutes
  },{
    id: 'b3',
    breakClipIds: ['bc4'],
    position: -1  //post-roll position (-1 is only valid client stitching; for server-side ad stitching, exact position is required)
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(cast.framework.events.EventType.BREAK_CLIP_ENDED, function(event){
  if(event.endedReason === cast.framework.events.EndedReason.END_OF_STREAM){
    //call your ad tracking code here for break clip watched to completion
  }
});


playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

VAST 広告

Web Receiver SDK は IAB 標準の VAST 広告に対応しています。メディアに VAST 広告を含めるには、vastAdsRequest オブジェクトを作成し、BreakClip の vastAdsRequest プロパティに代入します。vastAdsRequest オブジェクトには、adsResponse プロパティまたは adTagUrl プロパティが定義されている必要があります。

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    vastAdsRequest:{
      adTagUrl: 'https://castsample.com/vast?rand=' + Math.floor(Math.random()* 10000)
    }
  }];
}

Web Receiver SDK は、指定された adTagUrl にリクエストを送信し、XML レスポンスを解析して BreakClip オブジェクトを生成します。SDK によって生成された BreakClip オブジェクトの例を次に示します。

{
  "id": "GENERATED:0",
  "contentId": "https://file.mp4",
  "contentType": "video/mp4",
  "title": "Preroll",
  "duration": 10,
  "clickThroughUrl": "https://click"
}

VMAP 広告

Web Receiver SDK は IAB VMAP 標準もサポートしています。VMAP が提供されると、Cast SDK は VMAP レスポンスを解析し、レスポンスの指定された <AdBreak> エントリに Break オブジェクトを生成します。また、VMAP で指定された <AdSource> エントリごとに、vastAdsRequest オブジェクトで適切な BreakClips が生成されます。VMAP を使用してコンテンツを広告に挿入するには、vastAdsRequest オブジェクトを作成し、読み込みリクエストの一部として MediaInformation オブジェクトの vmapAdsRequest プロパティに割り当てます。

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.vmapAdsRequest = {
    adTagUrl: 'https://castsample.com/vmap?rand=' + Math.floor(Math.random()* 10000)
  };
}

サーバーサイドの広告合成

サーバーサイドスティッチ（埋め込み広告とも呼ばれます）については、サーバーはプライマリメディアと広告の両方を含む単一のストリームを提供することが想定されています。この場合、デベロッパーは BreakClip の duration と contentType を提供する必要があります。contentUrl は省略されます。また、isEmbedded を true に設定する必要があります。

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1'),
    duration: third_party.getBreakClipDuration('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0,
    isEmbedded: true
  },
  {
    id: 'b2',
    breakClipIds: ['bc3', 'bc4'],
    position: 10*60,
    isEmbedded: true
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

休憩の動作

デフォルトの中断動作

中断が開始されると、isWatched としてマークされます。ユーザーがブレーク前のポイントまでスクラブすると、コンテンツは通常どおりに再生を開始し、その後、前に視聴したことがあるブレークがスキップされます。
ユーザーがブレークを監視せずにブレークをスクラブすると、seekFrom と seekTo の位置の間の最後の未再生のブレークがコンテンツの再生が始まる前に再生されます。

カスタム広告ブレークの動作

ブレーククリップとブレーククリップの default behavior は、BreakManager オブジェクトの setBreakClipLoadInterceptor メソッドと setBreakSeekInterceptor メソッドを使用して変更できます。

setBreakClipLoadInterceptor

中断が発生する前に setBreakClipLoadInterceptor が呼び出されます。この関数は、ブレーククリップごとに 1 回呼び出されます。コールバック関数に BreakClip オブジェクトを渡します。

たとえば、プレロールが設定された場合、再生が開始されるとすぐにプレロールのブレークのために setBreakClipLoadInterceptor が呼び出されます。プレロールの再生が終了するとすぐに、次のブレークの setBreakClipLoadInterceptor が呼び出されます。

コールバック関数で null が返されるか何も返されない場合は、setBreakClipLoadInterceptor に対してブレーククリップがスキップされます。ブレークのすべてのインターセプトはすぐに呼び出されます。

setBreakClipLoadInterceptor を使用すると、再生を開始する前に BreakClip オブジェクトを変更できます。

setBreakSeekInterceptor

setBreakSeekInterceptor はシークオペレーションの後でトリガーされ、BreakSeekData オブジェクトをコールバック関数に渡します。BreakSeekData オブジェクトには、現在のプレイヘッド時刻とシーク先時刻の間の位置が定義されたブレークの配列が含まれます（例: seekFrom と seekTo）。フォワードシーク操作後、デフォルトの動作では、seekTo 時間の前に最後の未再生のブレークが再生されます。ブレークの再生が終了すると、seekTo の位置からコンテンツの再生が再開されます。

このインターセプタにより、個々の Break の BreakClip オブジェクトを変更できます。

この動作をカスタマイズするには、setBreakSeekInterceptor を実装して default behavior をオーバーライドします。setBreakSeekInterceptor が実装されている場合は、再生するブレークを明示的に指定する必要があります。

setBreakSeekInterceptor から null 値または何も返されない場合、このブレークはスキップされます。
コールバック関数に渡された同じオブジェクトが返される場合は、default behavior がオーバーライドされ、すべてのブレークが再生されます。さらに、ユーザーがスクラブして前のポイントに移動した場合、以前にそのブレークを視聴したことがある場合でもブレークが表示されます。setBreakSeekInterceptor が実装されていない場合、すでに視聴されているブレークはスキップされます。

ブレーククリップをスキップ可能にする

ブレーククリップをスキップ可能にするには、BreakClip オブジェクトで、ブレーククリップをスキップ可能になるまでの待機時間を秒数で指定します。

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(media) {
  media.breakClips = [
  {
    id: 'bc1',
    ...
    whenSkippable: 10 //to allow user to skip break clip from sender after 10 seconds
  }];
}

広告の自動スキップ

広告は自動的にスキップされるため、ユーザーの操作は必要ありません。広告をスキップするには、次の 2 つの方法があります。

Break の isWatched プロパティを true に設定すると、自動的に広告ブレークがスキップされます。

playerManager.addEventListener(cast.framework.events.category.CORE, function(event){
  if(event.type === cast.framework.events.EventType.PLAYER_LOADING){
    let breaks = playerManager.getBreaks();
    for(let i in breaks){
      breaks[i].isWatched = true;
    }
  }
});

BreakClip は、setBreakClipLoadInterceptor コールバックで null 値を返すことでスキップできます。
```
playerManager.getBreakManager().setBreakClipLoadInterceptor(breakClip => {
  return null;
});
```

キュー

ライブ