このページは 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 を利用するキャストレシーバーが構築されます。

学習内容

Cast 向けのコンテンツに VMAP と VAST の挿入点を追加する方法
休憩クリップをスキップする方法
シーク時のデフォルトの区切り動作をカスタマイズする方法

必要なもの

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

エクスペリエンス

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

ウェブ開発に関する一般的な知識。
Cast ウェブレシーバーアプリをビルドする

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

通読するのみ

通読し、演習を行う

ウェブアプリの作成経験をどのように評価されますか。

<ph type="x-smartling-placeholder"></ph> 初心者

中級

上達

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

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

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

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

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

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

サーバーを実行する

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

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

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

この Codelab に組み込まれているカスタムレシーバーを Chromecast デバイスで実行できるようにするには、アプリを登録する必要があります。アプリケーションを登録するとアプリケーション ID が生成されます。この ID では、Web Receiver アプリケーションを起動するように送信者アプリケーションを構成する必要があります。

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

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

「New Receiver Application」の画像[カスタムレシーバー] オプションがハイライト表示されたオプション

[Custom Receiver] を選択します。これが構築中のレシーバです。

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

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

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

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

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

[キャストレシーバーデバイスを追加] ダイアログの画像

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

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

5. 開始用プロジェクトを準備する

この 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 で定義された 1 つのメインビューと、js/receiver.js という 1 つの JavaScript ファイルで構成されています。以下で詳しく説明します。

index.html

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

receiver.js

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

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

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

js/receiver.js ファイルで、VastAdsRequest オブジェクトを作成します。LOAD リクエストインターセプタ関数を見つけ、次のコードに置き換えます。このファイルには、DoubleClick のサンプル VMAP タグ URL とランダムな correlator 値が含まれています。この相関値により、同じ 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 ではさまざまな種類の広告がサポートされています。このセクションでは、デジタル動画広告配信テンプレート広告（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 を呼び出して、中断読み込み用のインターセプタを設定する必要があります。js/receiver.js ファイルの context 変数と playerManager 変数を含む行の後に、次の行をコピーして、インスタンスへの参照を取得します。

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 を使って、レシーバーアプリに広告を追加する方法を学びました。

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