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

ウェブレシーバーへの Ad Breaks API サポートの追加

1. 概要

Google Cast のロゴ

この Codelab では、Cast Ad Breaks API を使用するカスタムウェブレシーバーアプリを作成する方法について説明します。

Google Cast とは

Google Cast では、ユーザーはモバイルデバイスからテレビにコンテンツをキャストできます。ユーザーは自分のモバイルデバイスをリモコンとして使い、テレビでのメディア再生を行うことが可能です。

Google Cast SDK を使うと、アプリを拡張してテレビやサウンドシステムを制御できます。Cast SDK では、Google Cast デザインチェックリストに沿って、必要な UI コンポーネントを追加できます。

Google Cast デザインチェックリストは、サポートされているすべてのプラットフォームで、キャストの操作を直感的にするために設けられています。

達成目標

この Codelab を完了すると、Break API を利用するキャストレシーバーが構築されます。

学習内容

キャスト用のコンテンツに VMAP および VAST ブレークを含める方法
休憩クリップをスキップする方法
シーク時のデフォルトの中断動作をカスタマイズする方法

必要なもの

最新の Google Chrome ブラウザ。
Firebase Hosting や ngrok などの HTTPS ホスティングサービス。
インターネットに接続するように設定された Chromecast や Android TV などの Google Cast デバイス。
HDMI 入力対応のテレビまたはモニター、または Google Nest Hub

エクスペリエンス

この Codelab を続行する前に、次の経験があることを確認してください。

ウェブ開発に関する一般的な知識。
Cast ウェブレシーバーアプリケーションの構築。

このチュートリアルの利用方法をお選びください。

通読するのみ

通読し、演習を行う

ウェブアプリ作成のご経験についてお答えください。

初心者

中級者

上級者

2. サンプルコードを取得する

すべてのサンプルコードをパソコンにダウンロードします。

ダウンロードした ZIP ファイルを解凍します。

3. レシーバーをローカルにデプロイする

ウェブレシーバーをキャストデバイスで利用するには、キャストデバイスからアクセスできる場所にホストする必要があります。HTTPS に対応しているサーバーを使用できる場合は、次の手順をスキップして、サーバーの URL をメモしておきます。この情報は次のセクションで必要になります。

使用できるサーバーがない場合、Firebase Hosting または ngrok を使用できます。

サーバーを実行する

目的のサービスが設定されたら、app-start に移動してサーバーを起動します。

ホスト型レシーバーの URL をメモします。次のセクションで使用します。

4. Cast Developer Console でアプリを登録する

この Codelab で作成するカスタムレシーバーを Chromecast デバイスで実行できるようにするには、アプリの登録が必要です。アプリを登録すると、アプリ ID が生成されます。この ID を使用して、ウェブレシーバーアプリを起動するようにセンダーアプリを構成する必要があります。

[新しいアプリを追加] ボタンがハイライト表示された Google Cast SDK デベロッパーコンソールの画像

[Add new application（新しいアプリを追加）] をクリックします。

[カスタムレシーバー] オプションがハイライト表示された [新しいレシーバーアプリケーション] 画面の画像

[Custom Receiver]（カスタムレシーバー）を選択します（これを今から作成します）。

[受信アプリケーションの URL] フィールドに URL を入力しているユーザーを示す [新しいカスタム受信機] 画面の画像

新しい受信者の詳細を入力します。Web Receiver アプリケーションのホスティングを予定している場所を示す URL を使用してください。アプリケーションを登録したら、コンソールで生成されたアプリケーション ID をメモします。送信側のアプリケーションは、後のセクションでその ID を使用するように構成されます。

また、公開する前にレシーバーアプリにアクセスできるように、Google Cast デバイスを登録する必要があります。レシーバーアプリを公開した後は、すべての Google Cast デバイスからアクセスできるようになります。この Codelab では、非公開のレシーバアプリを使用することをおすすめします。

[新しいデバイスを追加] ボタンがハイライト表示された Google Cast SDK Developer Console の画像

[Add new Device]（新しいデバイスを追加）をクリックします。

[Add Cast Receiver Device] ダイアログの画像

キャストデバイスの背面に記載されているシリアル番号を入力し、わかりやすい名前を付けます。シリアル番号は、Google Cast SDK Developer Console へのアクセス時に Chrome で画面をキャストして確認することもできます。

レシーバーとデバイスがテストできるようになるまでに 5 ～ 15 分かかります。5 ～ 15 分待ってから、キャストデバイスを再起動します。

5. Start プロジェクトを準備する

この Codelab を始める前に、広告ブレーク API の概要について説明している広告デベロッパーガイドを確認しておくことをおすすめします。

ダウンロードした開始用アプリに Google Cast のサポートを追加する必要があります。この Codelab で使用する Google Cast の用語は以下のとおりです。

送信側アプリはモバイルデバイスやノートパソコンで動作します。
レシーバー アプリは Google Cast デバイスで動作します。

お好きなテキストエディタを使用して、開始用プロジェクトを基に作業する準備を行います。

ダウンロードしたサンプルコードから app-start ディレクトリを選択します。
js/receiver.js と index.html を開きます。

この Codelab の作業を進めていくと、選択したウェブホスティングソリューションが更新され、変更が反映されます。検証とテストを続行するには、変更をホストサイトに push していることを確認してください。

アプリの設計

前述のように、この Codelab では、Cast セッションを開始するセンダーアプリと、ミッドロール挿入点 API を使用するように変更するレシーバーアプリを使用します。

この Codelab では、Cast and Command Tool が、レシーバーアプリを起動するためのウェブ送信側として機能します。まず、Chrome ブラウザでツールを開きます。Cast SDK デベロッパーコンソールで取得した受信側アプリ ID を入力し、[設定] をクリックして、送信側アプリをテスト用に構成します。

注: キャストアイコンが表示されない場合は、ウェブレシーバーとキャストデバイスが Cast Developer Console に正しく登録されていることを確認してください。まだ行っていない場合は、登録したばかりのキャストデバイスの電源を切って入れ直します。

この Codelab では、レシーバーアプリに主に焦点を当てます。このアプリは、index.html で定義されたメインビューと、js/receiver.js という JavaScript ファイルで構成されます。以下で詳しく説明します。

index.html

この HTML ファイルには、cast-media-player 要素によって提供されるレシーバーアプリの UI が含まれています。また、CAF SDK と Cast Debug Logger ライブラリも読み込みます。

receiver.js

このスクリプトは、レシーバーアプリのすべてのロジックを管理します。現時点では、キャストコンテキストを初期化し、初期化時に動画アセットを読み込む基本的な CAF レシーバーが含まれています。また、キャストアンドコマンドツールにロギングを戻すためのデバッグロガー機能も追加されました。

6. コンテンツに VMAP を追加する

Cast Web Receiver SDK は、Digital Video Multiple Ad 再生リスト（VMAP）で指定された広告に対応しています。XML 構造では、メディアのミッドロール挿入点とそれに関連付けられた挿入点クリップのメタデータを指定します。これらの広告を挿入するために、SDK には MediaInformation オブジェクトに vmapAdsRequest プロパティが用意されています。

js/receiver.js ファイルで、VastAdsRequest オブジェクトを作成します。LOAD リクエストインターセプタ関数を見つけ、次のコードに置き換えます。DoubleClick のサンプル VMAP タグ URL が含まれており、ランダムなコレレータ値が指定されているため、同じ URL への後続のリクエストで、まだ視聴されていないミッドロール挿入点を含む XML テンプレートが生成されます。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

変更を js/receiver.js に保存し、ファイルをウェブサーバーにアップロードします。キャストツールとコマンドツールでキャストアイコンをクリックして、キャストセッションを開始します。VMAP 広告が再生され、その後メインコンテンツが再生されます。

7. コンテンツに VAST を追加する

前述のように、Web Receiver SDK ではさまざまな種類の広告がサポートされています。このセクションでは、Digital Video Ad Serving Template（VAST）広告を統合するために使用できる API について説明します。前のセクションの VMAP コードを実装している場合は、コメント化します。

以下を、読み込みリクエストインターセプタの後に js/receiver.js ファイルにコピーします。これには、DoubleClick の 6 つの VAST ミッドロール挿入点クリップと、ランダムなコレレータ値が含まれています。これらのミッドロール挿入点は 5 つのミッドロール挿入点に割り当てられています。各ミッドロール挿入点の position は、メインコンテンツを基準とした秒単位の時間に設定します。これには、プレロール（position は 0 に設定）やポストロール（position は -1 に設定）のミッドロール挿入点が含まれます。

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

注: 休憩の breakClipIds プロパティは配列です。つまり、各休憩に複数の休憩クリップを割り当てることができます。

js/receiver.js file で LOAD メッセージインターセプタを見つけ、次のコードに置き換えます。VAST タイプの広告を表示するため、VMAP の処理はコメントアウトされています。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

変更を js/receiver.js に保存し、ファイルをウェブサーバーにアップロードします。キャストアンドコマンドツールでキャストアイコンをクリックして、キャストセッションを開始します。VAST 広告が再生された後、メインコンテンツが再生されます。

8. ミッドロール挿入点のスキップ

CAF には、広告の動作に関するカスタムビジネスルールの実装を支援する BreakManager というクラスがあります。これらの機能の 1 つでは、アプリケーションが特定の条件に基づいて、休憩をスキップしたり、クリップを分割したりできます。この例では、コンテンツの最初の 30 秒以内にある広告ブレークをスキップする方法を示します。ポストロール ブレークはスキップしません。前のセクションで構成した VAST 広告を使用する場合、5 つのミッドロール挿入点（15 秒、60 秒、100 秒のプレロール挿入点と 1 つのポストロール挿入点）が定義されます。手順を完了すると、位置が 15 秒のプレロールとミッドロールのみがスキップされます。

そのためには、アプリケーションが BreakManager で利用可能な API を呼び出して、中断読み込みのインターセプタを設定する必要があります。インスタンスへの参照を取得するために、context 変数と playerManager 変数を含む行の後に、次の行を js/receiver.js ファイルにコピーします。

const breakManager = playerManager.getBreakManager();

アプリは、30 秒未満のミッドロール挿入点は無視するが、ポストロール挿入点は考慮する（position 値が -1 であるため）というルールを持つインターセプタを設定する必要があります。このインターセプタは、PlayerManager の LOAD インターセプタと同様に機能しますが、挿入点クリップの読み込みに固有のものです。これを LOAD リクエストインターセプタの後に、addVASTBreaksToMedia 関数の宣言の前に設定します。

以下を js/receiver.js ファイルにコピーします。

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

注: ここで null を返すと、処理中の BreakClip はスキップされます。Break にブレーククリップが定義されていない場合、ブレーク自体はスキップされます。

変更を js/receiver.js に保存し、ファイルをウェブサーバーにアップロードします。キャストアンドコマンドツールでキャストアイコンをクリックして、キャストセッションを開始します。VAST 広告が処理される。プレロールと最初のミッドロール（position が 15 秒）の広告は再生されません。

9. 休憩時のシーク動作をカスタマイズする

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

シーク時に再生するミッドロール挿入点のカスタマイズには、Cast SDK の BreakManager にある setBreakSeekInterceptor API を使用します。アプリケーションがその API を介してカスタムロジックを提供する場合は、1 つ以上の休憩でシークオペレーションが実行されるたびに SDK によって呼び出されます。コールバック関数には、seekFrom の位置と seekTo の位置の間のすべてのブレークを含むオブジェクトが渡されます。その後、アプリケーションは BreakSeekData を変更して返す必要があります。

使用方法を示すため、以下のサンプルでは、シークされたすべての休憩を取得し、タイムラインに表示される最初の休憩のみを再生することで、デフォルトの動作をオーバーライドしています。

以下を js/receiver.js ファイルの setBreakClipLoadInterceptor の定義にコピーします。

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

注: 関数が値を返さない場合、または null を返す場合は、休憩は再生されません。

変更を js/receiver.js に保存し、ファイルをウェブサーバーにアップロードします。キャストアイコンをクリックして、キャストとコマンドツールでキャストセッションを開始します。VAST 広告は処理する必要があります。プレロールと最初のミッドロール（position が 15 秒）の広告は再生されません。

再生時間が 30 秒に達して、ミッドロール挿入点クリップの読み込みインターセプタによってスキップされたすべてのミッドロール挿入点が過ぎるのを待ちます。到達したら、[メディアコントロール] タブに移動してシークコマンドを送信します。[Seek Into Media] 入力に 300 秒を入力し、[TO] ボタンをクリックします。Break Seek インターセプタに出力されたログをメモします。デフォルトの動作がオーバーライドされ、seekFrom の時間に近づけてミッドロール挿入点が再生されるようになりました。

10.完了

最新の Cast Receiver SDK を使用してレシーバーアプリに広告を追加する方法は以上です。

詳しくは、ミッドロール挿入点のデベロッパーガイドをご覧ください。