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

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

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

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

VOD ストリーム用のアプリに Pod Serving API を統合する手順は次のとおりです。

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

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

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":{"cmsid":"12345","vid":"sample-video"}}' \
     -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"
}

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

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 ボックスには、https://aomedia.org/emsg/ID3 または https://developer.apple.com/streaming/emsg-id3 の scheme_id_uri 値と、ID3TXXXgoogle_ で始まる message_data 値があります。ID3TXXX プレフィックスのない message_data 値が広告イベント ID です。

メール ボックスの例

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

広告イベント 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"
  },
  ...
}

メディアの確認 ping を送信する

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 レイヤの実装タイプの比較