連続広告配信リダイレクトに向けてクライアントを準備する

このガイドでは、連続広告配信 API とマニフェスト マニピュレータを使用して HLS または DASH ライブ配信を読み込むクライアント アプリケーションを開発する方法について説明します。

前提条件

続行する前に、次のものを用意する必要があります。

• Pod serving redirect DAI タイプで構成されたライブ配信イベントのカスタム アセットキー。このキーを取得する手順は次のとおりです。

  • ダイナミック広告挿入用のライブ ストリームを設定します。

  • SOAP API クライアント ライブラリを使用して、LiveStreamEvent オブジェクトと dynamicAdInsertionType プロパティが POD_SERVING_REDIRECT 列挙値に設定された LiveStreamEventService.createLiveStreamEvents メソッドを呼び出します。すべてのクライアント ライブラリについては、クライアント ライブラリとサンプルコードをご覧ください。

• インタラクティブ メディア広告（IMA）SDK がプラットフォームで利用可能かどうかを確認します。収益を増やすには、IMA SDK を使用することをおすすめします。詳しくは、DAI 用の IMA SDK を設定するをご覧ください。

ストリーム リクエストを行う

ユーザーがストリームを選択した場合は、次の処理を行います。

1. ライブ配信サービス メソッドに POST リクエストを送信します。詳細については、メソッド: stream をご覧ください。

2. 広告のターゲット設定パラメータを application/x-www-form-urlencoded または application/json 形式で渡します。このリクエストは、Google DAI にストリーム セッションを登録します。

   次の例では、ストリーム リクエストを作成します。

   フォームのエンコード

   const url = `https://dai.google.com/ssai/pods/api/v1/` +
         `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
   
   const params = new URLSearchParams({
           cust_params: 'section=sports&page=golf,tennis'
   }).toString();
   
   const response = await fetch(url, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/x-www-form-urlencoded'
           },
           body: params
   });
   
   console.log(await response.json());
   

   JSON エンコード

   const url = `https://dai.google.com/ssai/pods/api/v1/` +
         `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
   
   const response = await fetch(url, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json'
           },
           body: JSON.stringify({
             cust_params: {
               section: 'sports',
               page: 'golf,tennis'
             }
           })
   });
   
   console.log(await response.json());
   

   成功すると、次のような出力が表示されます。

   {
   "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
   "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
   "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
   "session_update_url": "https://dai.google.com/linear/.../session",
   "polling_frequency": 10
   }
   

3. JSON レスポンスでストリーム セッション ID を見つけ、以降のステップで使用する他のデータを保存します。

広告メタデータをポーリングする

広告のメタデータをポーリングする手順は次のとおりです。

1. ストリーム登録レスポンスから metadata_url 値を読み取ります。

2. metadata_url エンドポイントに最初の GET リクエストを送信します。

   • delta_token クエリ パラメータを省略します。このプロセスにより、サーバーはストリームのデジタル ビデオ レコーダー（DVR）ウィンドウの完全なメタデータを返すことができます。DVR ウィンドウには、視聴者が巻き戻して再生できる放送の時間枠が含まれます。レスポンスには next_delta_token フィールドが含まれます。

3. 帯域幅を最適化するには、最新のレスポンスから next_delta_token 値を保存します。

4. 次のリクエストで、その値を delta_token クエリ パラメータとして送信します。サーバーは、そのトークンが生成されてから変更されたメタデータのみを返します。常に受け取った最新のトークンを送信します。トークンを解析、変更、構築しようとしないでください。詳細については、メソッド: メタデータをご覧ください。

   次の例では、広告のメタデータを取得しています。

   // Initial request (returns full metadata and next_delta_token)
   let response = await fetch(metadata_url);
   let metadata = await response.json();
   let deltaToken = metadata.next_delta_token;
   
   // Subsequent request (returns only changes since deltaToken)
   if (deltaToken) {
     const url = new URL(metadata_url);
     url.searchParams.append('delta_token', deltaToken);
     response = await fetch(url.toString());
     const deltaMetadata = await response.json();
     // Merge deltaMetadata into your local cache
     mergeMetadata(metadata, deltaMetadata);
     deltaToken = deltaMetadata.next_delta_token;
   }
   

   成功すると、PodMetadata レスポンスが返されます。delta_token パラメータを指定すると、レスポンスには、サーバーがトークンを生成してからサーバーが追加または更新した広告、広告ブレーク、タグのみが含まれます。レスポンスには、新しい next_delta_token 値も含まれます。古い広告ブレークがある場合、レスポンスには、キャッシュから削除する広告ブレークの obsolete_ad_break_ids リストも含まれます。

   {
     "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
     "obsolete_ad_break_ids": ["0003069407"],
     "tags":{
       "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
       },
       ...
     },
     "ads":{
       "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         "clickthrough_url":"https://.../",
         ...
       },
       ...
     },
     "ad_breaks":{
       "0003069408":{
         "type":"mid",
         "duration":30,
         "ads":3
       },
       ...
     }
   }
   

5. tags オブジェクトを保存し、更新をローカル キャッシュに統合します。obsolete_ad_break_ids パラメータが存在する場合は、それらのミッドロール挿入点と関連する広告およびタグをキャッシュから削除します。

6. polling_frequency 値を使用してタイマーを設定し、メタデータを定期的にリクエストします。各ポーリングで、最新のメタデータ レスポンスで返された next_delta_token 値を delta_token クエリ パラメータとして送信します。

動画プレーヤーにストリームを読み込む

登録レスポンスからセッション ID を取得したら、マニフェスト マニピュレータに ID を渡すか、マニフェスト URL を作成して動画プレーヤーにストリームを読み込みます。

セッション ID を渡すには、マニフェスト マニピュレータのドキュメントをご覧ください。マニフェスト マニピュレータを開発する場合は、ライブ配信用のマニフェスト マニピュレータをご覧ください。

次の例では、マニフェスト URL を組み立てています。

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

プレーヤーの準備ができたら、再生を開始します。

広告イベントをリッスンする

ストリームのコンテナ形式で、タイムド メタデータを確認します。

• トランスポート ストリーム（TS）コンテナを使用する HLS ストリームは、タイミング付き ID3 タグを使用してタイミング付きメタデータを伝送します。詳細については、HTTP Live Streaming（HLS）での Common Media Application Format についてをご覧ください。

• DASH ストリームは、EventStream 要素を使用してマニフェスト内のイベントを指定します。

• DASH ストリームでは、セグメントに ID3 タグなどのペイロード データ用のイベント メッセージ（emsg）ボックスが含まれている場合、InbandEventStream 要素が使用されます。詳しくは、InbandEventStream をご覧ください。

• DASH や HLS などの CMAF ストリームは、ID3 タグを含む emsg ボックスを使用します。

ストリームから ID3 タグを取得するには、動画プレーヤーのガイドを参照してください。詳しくは、タイミング付きメタデータの処理ガイドをご覧ください。

ID3 タグから広告イベント ID を取得するには、次の操作を行います。

1. urn:google:dai:2018 または https://aomedia.org/emsg/ID3 を使用して scheme_id_uri でイベントをフィルタします。

2. message_data フィールドからバイト配列を抽出します。

   次の例では、emsg データを JSON にデコードします。

   {
     "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
     "presentation_time": 27554,
     "timescale": 1000,
     "message_data": "ID3TXXXgoogle_1022389921",
     ...
   }
   

3. 形式 TXXXgoogle_{ad_event_ID} で ID3 タグをフィルタします。

   TXXXgoogle_1022389921
   

広告イベントデータを表示する

TagSegment オブジェクトを見つけるには、次の操作を行います。

1. 広告メタデータをポーリングするから広告メタデータ tags オブジェクトを取得します。tags オブジェクトは TagSegment オブジェクトの配列です。

2. 完全な広告イベント ID を使用して、タイプ progress の TagSegment オブジェクトを見つけます。

3. 広告イベント ID の最初の 17 文字を使用して、他のタイプの TagSegment オブジェクトを見つけます。

   クライアント アプリは広告メタデータを定期的にポーリングするため、動画プレーヤーがストリーム内の ID3 タグを検出してから、関連するメタデータが利用可能になるまでに遅延が生じることがあります。クライアント アプリが保存されたタグで ID3 タグを見つけられない場合は、タグをキューに保持し、次のメタデータ ポーリング後にタグを再処理します。処理が完了するまでタグをキューに残します。

4. TagSegment を取得したら、ad_break_id プロパティをキーとして使用して、広告メタデータの ad_breaks オブジェクトで AdBreak オブジェクトを見つけます。

   次の例では、AdBreak オブジェクトを検索します。

   {
     "type":"mid",
     "duration":15,
     "ads":1
   }
   

5. TagSegment と AdBreak のデータを使用して、ミッドロール挿入点内の広告の位置に関する情報を表示します。例: Ad 1 of 3

メディア確認 ping を送信

progress タイプを除くすべての広告イベントで、メディア検証 ping を送信します。Google DAI は progress イベントを破棄します。これらのイベントを頻繁に送信すると、アプリのパフォーマンスに影響する可能性があります。

広告イベントの完全なメディア確認用 URL を生成するには、次の操作を行います。

1. ストリーム レスポンスから、広告イベント ID 全体を media_verification_url 値に追加します。

2. 完全な URL を使用して GET リクエストを行います。

   // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
   const completeUrl = `${media_verification_url}google_1022389921`;
   
   const response = await fetch(completeUrl);
   

   成功すると、コード ステータス 202 レスポンスが返されます。それ以外の場合は、404 エラーコードが返されます。

ストリーム アクティビティ モニター（SAM）を使用すると、すべての広告イベントの履歴ログを確認できます。詳しくは、ライブ配信のモニタリングとトラブルシューティングをご覧ください。