VOD ストリーム用のクライアント動画プレーヤー アプリ

Google DAI Pod Serving API を使用すると、独自の動画の結合を維持しながら、Google 広告を活用したサーバーサイド広告挿入を行うことができます。

このガイドでは、Pod Serving API を操作して、IMA DAI SDK で同様の機能を実現する方法について説明します。サポートされている機能についてご不明な点がございましたら、Google アカウント マネージャーにお問い合わせください。

Pod Serving API は、HLS または MPEG-DASH ストリーミング プロトコルの Pod Serving ストリームをサポートしています。このガイドでは、HLS ストリームに焦点を当て、HLS と MPEG-DASH の主要な違いを具体的な手順で説明します。

VOD ストリーム用に Pod Serving API をアプリに統合するには、次の手順を完了します。

アド マネージャーにストリーム登録リクエストを送信する

ストリーム登録エンドポイントに POST リクエストを送信します。マニフェスト操作サーバーと関連する Pod Serving API エンドポイントに送信するストリーム ID を含む JSON レスポンスが返されます。

API エンドポイント

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

パスパラメータ

JSON 本文パラメータ

レスポンス JSON

リクエストの例（cURL）

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

レスポンスの例

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

エラーが発生した場合は、JSON レスポンス本文なしで標準の HTTP エラーコードが返されます。

JSON レスポンスを解析し、関連する値を保存します。

マニフェスト マニピュレータからストリーム マニフェストをリクエストする

マニフェスト マニピュレータごとに、リクエストとレスポンスの形式が異なります。マニピュレータ プロバイダに問い合わせて、具体的な要件を確認してください。独自のマニフェスト マニピュレータを実装する場合は、マニフェスト マニピュレータ ガイドで、このコンポーネントの要件を確認してください。

通常、セッション固有のマニフェストをビルドするには、上記の登録エンドポイントから返されたストリーム ID をマニフェスト マニピュレータに渡す必要があります。マニフェスト マニピュレータで明示的に指定しない限り、マニフェスト リクエストへのレスポンスは、コンテンツと広告の両方を含む動画ストリームです。

リクエストの例（cURL）

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

レスポンスの例（HLS）

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

ストリームを再生する

マニフェスト操作サーバーから受け取ったマニフェストを動画プレーヤーに読み込み、再生を開始します。

アド マネージャーから連続配信広告のメタデータをリクエストする

手順 1 で受け取った metadata_url に GET リクエストを送信します。この手順は、マニフェスト マニピュレータからステッチされたマニフェストを受け取った後に行う必要があります。レスポンスとして、次のパラメータを含む JSON オブジェクトを受け取ります。

これらの値を保存して、動画ストリーム内の時間指定メタデータ イベントに関連付けます。

リクエストの例（cURL）

curl https://dai.google.com/.../metadata

レスポンスの例

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

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

動画プレーヤーの音声/動画ストリームでトリガーされた広告イベントを通じて、タイミング設定されたメタデータをリッスンします。

MPEG-TS ストリームの場合、メタデータはインバンド ID3 v2.3 タグとして表示されます。各メタデータ タグには ID TXXX があり、値は文字列 google_ で始まり、その後に一連の文字が続きます。この値は広告イベント ID です。

TXXX の XXX はプレースホルダではありません。文字列 TXXX は、「ユーザー定義テキスト」用に予約されている ID3 タグ ID です。

ID3 タグの例

TXXXgoogle_1234567890123456789

MP4 ストリームの場合、これらは ID3 v2.3 タグをエミュレートするインバンド emsg イベントとして送信されます。関連する各 emsg ボックスには、scheme_id_uri 値（https://aomedia.org/emsg/ID3 または https://developer.apple.com/streaming/emsg-id3）と、ID3TXXXgoogle_ で始まる message_data 値があります。この message_data 値（ID3TXXX 接頭辞なし）は、広告イベント ID です。

emsg ボックスの例

データ構造は、メディア プレーヤー ライブラリによって異なる場合があります。

広告イベント ID が google_1234567890123456789 の場合、レスポンスは次のようになります。

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

一部のメディア プレーヤー ライブラリは、ID3 タグをネイティブ ID3 タグとしてエミュレートする emsg イベントを自動的に表示します。この場合、MP4 ストリームは MPEG_TS と同じ ID3 タグを提示します。

クライアントの動画プレーヤー アプリの UI を更新する

各広告イベント ID は、手順 4 の tags オブジェクト内のキーと照合できます。これらの値を照合するプロセスは 2 段階に分かれています。

1. tags オブジェクトで、広告イベント ID 全体に一致するキーを確認します。一致が見つかった場合は、イベントタイプとそれに関連付けられた ad オブジェクトと ad_break オブジェクトを取得します。これらのイベントのタイプは progress にする必要があります。

   広告イベント ID 全体に一致するものが見つからない場合は、tags オブジェクトで、広告イベント ID の最初の 17 文字に一致するキーを確認します。イベントタイプと、関連する ad オブジェクトと ad_break オブジェクトを取得します。これにより、progress 以外のタイプのすべてのイベントが取得されます。

2. 取得した情報を使用して、プレーヤーの UI を更新します。たとえば、start イベントまたは最初の progress イベントを受信したら、プレーヤーのシーキング コントロールを非表示にして、ミッドロール挿入点における現在の広告の位置を示すオーバーレイを表示します（「広告 1/3」など）。

広告イベント ID の例

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

タグ オブジェクトの例

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

メディアの確認ピングの送信

progress 以外のタイプの広告イベントが受信されるたびに、メディア確認 ping をアド マネージャーに送信する必要があります。

広告イベントの完全なメディア認証 URL を生成するには、ストリーム登録レスポンスの media_verification_url 値に完全な広告イベント ID を追加します。

完全な URL を使用して GET リクエストを行います。検証リクエストが成功すると、ステータス コード 202 の HTTP レスポンスが返されます。削除しないと、HTTP エラーコード 404 が返されます。

リクエストの例（cURL）

curl https://{...}/media/google_5555555555123456789

正常なレスポンスの例

HTTP/1.1 202 Accepted

参考情報

• IMA SDK のドキュメント
• DAI プレーヤーの実装タイプを比較する