ミッドロール挿入点

概要

Web Receiver SDK は、特定のメディア ストリーム内の広告ブレークとコンパニオン広告をネイティブにサポートしています。広告ブレークとそれに関連するブレーククリップについて、広告の位置、広告ソース、動作を設定するための API が用意されています。このガイドでは、Break は 1 つ以上の広告またはバンパーを含む再生の間隔を意味し、個々の広告またはバンパーは BreakClip と呼ばれます。挿入点は、読み込みまたは再生中のメディアに関連付けられます。

広告の種類

Web Receiver SDK は、クライアントサイド広告挿入（CSAI）とサーバー合成広告挿入（SSAI）をサポートしています。クライアント合成広告は、アプリケーションで手動で設定することも、VAST および VMAP テンプレート ファイルから抽出することもできます。サーバーで合成された広告は、コンテンツの読み込み前に埋め込み広告として手動で指定し、コンテンツの再生中に埋め込み拡張広告として動的に設定する必要があります。各広告タイプの実装方法について、以下で詳しく説明します。

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

プレーヤーのタイムライン タイプ

プレーヤー インスタンスを作成すると、Web Receiver SDK は、コンテンツ再生中の広告再生をサポートするタイムライン タイプを選択します。各タイムラインでは、特定のミッドロール挿入点タイプを追加できます。タイムライン タイプは、LoadRequestData の MediaInformation で読み込み中に表示される広告タイプによって決まります。埋め込みミッドロール挿入点が存在する場合、embedded タイムラインが選択されます。クライアントが合成したミッドロール挿入点が存在する場合、stitched タイムラインが選択されます。広告が存在しない場合、SDK はデフォルトで embedded タイムラインを使用します。タイムラインを選択すると、現在のメディア アイテムの変更はできません。以下の表に、各タイムラインの詳細を示します。

以下の図 1 ～ 3 は、さまざまな広告タイプとそれぞれのタイムライン値を持つコンテンツを示しています。コンテンツは、2 つのブレーク クリップを含む「プレロール」ブレークと、1 つのブレーク クリップを含む「ミッドロール」および「ポストロール」ブレークで構成されます。コンテンツ再生開始からの実時間、メイン コンテンツのメディア時間、現在再生中のブレーク クリップの時刻は、それぞれの図の下揃えになされます。

挿入点の配置

Web Receiver SDK では、デベロッパーは Break の position プロパティを設定することで、ミッドロール挿入点を配置する場所を指定できます。この値はメイン コンテンツのメディア時間に対応し、pre-roll、mid-roll、post-roll のミッドロール挿入点の作成に使用できます。これらは次のように定義されます。

相互運用性マトリックス

ご参考までに、各広告タイプの概要と広告関連機能との互換性を表 1 に示します。

イベント

キーブレーク イベントが発生すると、キャスト SDK は BreaksEvent タイプのイベントをディスパッチします。レシーバー アプリは、PlayerManager addEventListener API を使用してサブスクライブできます。

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

イベントの種類と発生するタイミングを、表 2 に詳しく記載しています。

広告の挿入

キャスト SDK を使用すると、キャスト セッションのさまざまなタイミングでアプリが広告を挿入したり、削除したりできます。広告挿入には、静的と動的の 2 種類があります。静的広告挿入では、プレーヤーを作成する前に LoadRequestData で広告を指定する必要があります。動的広告挿入では、BreakManager addBreak API を使用して、読み込み済みのコンテンツに挿入できます。各タイプの挿入方法は、特定の広告の種類に対応しています。互換性の概要については、相互運用性マトリックスをご覧ください。

静的広告挿入

静的広告挿入では、プレーヤーの作成前に関連する広告メタデータが追加されることが特徴です。この情報は、LoadRequestData の MediaInformation で提供されます。たとえば、接続されている送信者の元の読み込みリクエストで設定するか、LOAD リクエストをインターセプトしてウェブ レシーバー アプリケーションによって挿入されます。LoadRequestData が処理のために Web Receiver SDK に返されると、プレーヤーが作成されます。詳しくは、メディアの読み込みをご覧ください。以下のサンプルでは、LOAD リクエスト インターセプタに追加されている手動クライアント合成広告を示しています。

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

ダイナミック広告挿入

ダイナミック広告挿入の特長は、コンテンツの再生中に広告ブレークを設定することです。これを行うには、BreakManager のインスタンスを取得し、addBreak API を呼び出します。これは少なくとも 2 つのパラメータ（埋め込み展開済み Break と BreakClip の配列）を取ります。オプションの 3 つ目のプロパティを使用して、true に設定されている場合に、接続されている送信者に変更を MediaStatus ブロードキャストを介して強制的に送信します。挿入点と挿入点クリップを追加する場合、対応する ID は一意である必要があります。これらの広告は、プレーヤーの作成後にのみ追加できます。プレーヤーが作成されると、Web Receiver SDK は PLAYER_LOADING イベントを呼び出します。以下のサンプルは、ストリームの ID3 メタデータの変更に応答し、Break オブジェクトと BreakClip オブジェクトを作成してタイムラインに挿入するイベント ハンドラの使用方法を示しています。

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

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

動的広告の削除

動的な中断を削除するには、アプリで再生中に removeBreakById を呼び出す必要があります。この関数は、タイムラインから削除するブレークの文字列 ID を受け取ります。指定する breakId は、埋め込み拡張ミッドロール挿入点を指す必要があります。他の種類のミッドロール挿入点が検出されると、その挿入点はタイムラインに残ります。以下の例では、休憩をなくしています。

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

breakManager.removeBreakById('break_midroll_embedded_expanded');

休憩の動作

この SDK では、プレーヤーが休憩に入るときと休憩を取るときのデフォルト動作が定義されており、BreakManager で提供される API を使用してさらにカスタマイズする方法が用意されています。

デフォルトの中断動作

通常の再生または Break のシークによって Break が入力されると、SDK は isWatched プロパティをチェックして、ユーザーがすでに表示しているかどうかを評価します。作成時のこのプロパティのブレークのデフォルト値は false です。プロパティが true の場合、入力時にブレークは再生されず、メイン コンテンツの再生が継続されます。プロパティが false の場合、入力時にブレークが再生されます。

過去の中断をシークする場合、デフォルトの実装では、position がシーク オペレーションの seekFrom 値と seekTo 値の間にあるすべての Break アイテムが取得されます。SDK は、このブレークのリストから、position が seekTo 値に最も近い Break を再生し、isWatched プロパティが false に設定されます。すると、ブレークの isWatched プロパティが true に設定され、プレーヤーはブレーク クリップの再生を開始します。休憩が視聴されると、メイン コンテンツは seekTo の位置から再生を再開します。そのようなブレークが存在しない場合、ブレークは再生されず、メイン コンテンツの再生は seekTo の位置から再開されます。

ブレーク再生中に、SDK は MediaStatus で、接続されている送信側アプリに関連する更新をブロードキャストします。これらのアプリは、ブロードキャストを使用して breakStatus プロパティを読み取り、広告の UI を更新します。このプロパティは、ブレーク再生中にのみ定義されます。

また、レシーバー アプリは、PlayerManager getBreakClipCurrentTimeSec を呼び出すことで、表示される BreakClip の現在の時刻に関するプレイヘッドの位置に関する情報を直接クエリできます。同様に、アプリは getBreakClipDurationSec を呼び出すことで、現在の BreakClip の期間を照会できます。

カスタムブレーク動作

ブレーク クリップとブレーク クリップのデフォルトの動作は、BreakManager で提供される setBreakClipLoadInterceptor メソッドと setBreakSeekInterceptor メソッドを使用して変更できます。

シーク インターセプタの中断

ブレークシーク インターセプタを使用すると、アプリで広告ブレークをシークする動作を制御できます。この関数は、1 つ以上のブレークで前方または後方シークするシーク操作がリクエストされるとトリガーされます。呼び出されると、BreakSeekData がパラメータとしてコールバック関数に渡されます。BreakSeekData オブジェクトには Break オブジェクトの配列が含まれます。このオブジェクトの position プロパティは、seekFrom として定義されている現在のプレイヘッド時間とシーク目的地時間 seekTo の間の数値に設定されます。

このインターセプタを使用すると、それぞれのブレーク内の Break オブジェクトを変更できます。挿入時シーク インターセプタは、必要に応じて変更された BreakSeekData オブジェクトを返すことにより、再生する広告ブレークを指定する必要があります。プレーヤーは、戻り値に含まれるすべての休憩を再生します。値 null が返されるか、ブレーク シーク インターセプタから何も返されない場合、ブレークはスキップされます。

以下のサンプルのシンプルな実装例をご覧ください。インターセプタは、デフォルトの動作をオーバーライドして、すでに視聴されているブレークを除いて、シークされたすべての広告ブレークを監視します。

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

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

クリップ読み込みインターセプタのブレーク

ブレーク クリップの読み込み インターセプタを使用すると、再生の開始前に BreakClip オブジェクトを変更できます。

ブレーク クリップの読み込みインターセプタは、合成されたタイムラインのブレークに対してのみ呼び出され、setBreakClipLoadInterceptor を使用して設定できます。Break に入る前に、このインターセプタは、そのブレークで定義された BreakClip ごとに 1 回呼び出されます。SDK は元の BreakClip オブジェクトをコールバック関数のパラメータとして渡します。アプリはこの BreakClip を変更して返すことができます。これにより、SDK は更新された構成でブレーク クリップを取得して表示できるようになります。null が返されないか何も返されない場合、ブレーク クリップはスキップされます。

以下に、ユーティリティ関数呼び出し getUrlFromClipId を使用してブレーク クリップの contentUrl を変更する例を示します。ここでは BreakClip の id が URL にマッピングされています。

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

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

広告のスキップ

Web Receiver SDK には、ミッドロール挿入点と、ミッドロール挿入点内の個々の挿入点クリップをスキップする API が用意されています。この SDK では、送信側アプリまたはスマートディスプレイ デバイスを操作して、ブレーク クリップをスキップすることもできます。

ユーザーがスキップできるブレーク クリップ

ブレーク クリップをスキップ可能に設定すると、ユーザーは接続済みのセンダーアプリやスマートディスプレイ デバイスと通信し、現在再生中のブレーク クリップの残りの部分をスキップできるようになります。whenSkippable プロパティに負でない秒数を設定すると、BreakClip オブジェクトに対してこの機能が有効になります。ブレーク クリップが指定の秒数の間再生されると、プレーヤーはブレーク クリップをスキップ可能と見なします。この値を 0 に設定すると、ユーザーはすぐにブレーク クリップをスキップできます。

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

この情報は、送信側の元の読み込みリクエストまたは受信側のアプリで設定できます。スキップされた場合、合成されたタイムラインの広告ブレーク内のブレーク クリップは、現在のブレーク クリップの再生を停止します。プレーヤーは次のブレーク クリップ（存在する場合）を読み込むか、メイン コンテンツを読み込みます。埋め込みタイムラインの広告ブレークのブレーク クリップがスキップされた場合、ブレーク クリップの最後にシークされ、その時点でストリームの再生が続行されます。

プログラムによる広告のスキップ

広告は、ユーザーが操作しなくても自動的にスキップされます。

再生の休憩全体をスキップするには、アプリで Break の isWatched プロパティを true に設定する必要があります。これは、読み込みシーケンスまたはコンテンツの再生中にいつでも実行できます。isWatched プロパティは、メイン コンテンツの現在の時刻で休憩の position が満たされると、プレーヤーによって評価されます。その時点で、プレーヤーは休憩を入れるかどうかを判断します。以下のサンプルは、すべてのブレークをループして、プレーヤーの読み込み時に値を変更するものです。

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

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

プログラムで特定のブレーク クリップをスキップするには、ブレーク クリップの読み込み インターセプタを使用する必要があります。null を返すか、コールバック関数で値を返さないことで、そのブレーク内のクリップはスキップされます。

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

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});