始める前に
このガイドでは、IMA DAI SDK がない場合の再生手順についてのみ説明します。
事前に、Google アド マネージャー（GAM）とライブ ストリームを統合するの手順を完了していることを確認してください。
対象のプラットフォームで IMA SDK を使用できない場合は、アプリで必要な API を呼び出して、広告インプレッションをトリガーする必要があります。
そのためには、次の情報が必要になります。
| ロケーション |
ライブ構成が作成された
Google Cloud リージョン
: LOCATION
|
| プロジェクト番号 |
Video Stitcher API を使用する Google Cloud プロジェクトのプロジェクト番号:
PROJECT_NUMBER
|
| OAuth トークン | Video Stitcher ユーザーロールを持つサービス アカウントの有効期間が短い OAuth トークン:
OAUTH_TOKEN 有効期間が短い OAuth トークンの作成の詳細を確認します。 |
| ネットワーク コード | 広告をリクエストするためのアド マネージャー ネットワーク コード:
NETWORK_CODE |
| ライブ構成 ID | ライブ配信イベントの作成時に指定したライブ構成 ID:
LIVE_CONFIG_ID
|
| カスタム アセットキー | Video Stitcher API を使用してライブ配信イベントの設定を作成する のプロセス中に生成されるアド マネージャーのカスタム アセットキー: CUSTOM_ASSET_KEY
|
アド マネージャーにストリーム登録リクエストを送信する
ストリーム登録エンドポイントに POST リクエストを送信します。代わりに、動画合成 API に送信するストリーム ID を含む JSON レスポンスを受け取ります。
API エンドポイント
POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
パスパラメータ
NETWORK_CODE |
お客様の Google アド マネージャー ネットワークのコード
NETWORK_CODE |
CUSTOM_ASSET_KEY |
Google アド マネージャーでこのイベントに関連付けられたカスタム ID。
CUSTOM_ASSET_KEY
|
フォームでエンコードされた本文パラメータ
フォーム エンコードの ターゲティング パラメータ のセット（省略可）。
レスポンス JSON
media_verification_url |
再生トラッキング イベントの ping のベース URL。完全なメディア検証 URL は、このベース URL に広告イベント ID を追加することで作成されます。MEDIA_VERIFICATION_URL
|
metadata_url |
連続配信広告のメタデータをリクエストする URL。
METADATA_URL
|
polling_frequency |
「metadata_url」をポーリングする推奨頻度（ミリ秒単位）。
POLLING_FREQUENCY |
stream_id |
現在のストリーム セッションの識別に使用される文字列。
STREAM_ID
|
valid_for |
現在のストリーム セッションが期限切れになるまでの残り時間。dhms（日、時間、分、秒）形式で指定します。たとえば、2h0m0.000s は 2 時間の期間を表します。 |
valid_until |
現在のストリーム セッションが期限切れになる時刻（ISO 8601 日時文字列、yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 形式）。 |
リクエストの例（cURL）
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/streamレスポンスの例
{
"stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
"media_verification_url":"https://dai.google.com/.../media/",
"metadata_url":"https://dai.google.com/.../metadata",
"session_update_url":"https://dai.google.com/.../session",
"polling_frequency":10
}
エラーの場合、標準の HTTP エラーコードは JSON レスポンスの本文なしで返されます。
JSON レスポンスを解析し、関連する値を保存します。
セッション再生 URI を生成する
新しいライブ セッションを作成するには、動画スティッチャー API の /livesessions エンドポイントに POST リクエストを行います。レスポンスとして、動画プレーヤーに読み込むストリーム マニフェストを含む JSON レスポンスが返されます。
API エンドポイント
POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json
パスパラメータ
PROJECT_NUMBER |
Video Stitcher API を使用する Google Cloud プロジェクトのプロジェクト番号:
PROJECT_NUMBER
|
LOCATION |
ライブ構成が作成された
Google Cloud リージョン
: LOCATION
|
認証ヘッダー パラメータ
OAUTH_TOKEN |
Video Stitcher ユーザーロールを持つサービス アカウントの有効期間が短い OAuth トークン:
OAUTH_TOKEN |
JSON でエンコードされた本文パラメータ
liveConfig |
次の形式のプロジェクト番号、ロケーション、ライブ構成 ID を含む文字列:
projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
|
adTracking |
クライアントサイド トラッキングを有効にするには、"CLIENT" に設定します。 |
gamSettings |
次の形式のストリーム ID を含むオブジェクト。
{"streamId":"STREAM_ID"}
|
レスポンス JSON
name |
セッション ID を含むライブ セッションの名前。 |
playUri |
再生するために動画プレーヤーに読み込む合成されたストリーム マニフェストの URI。 PLAY_URI
|
liveConfig |
リクエスト本文で API に送信されたものと同じ liveConfig 文字列。 |
gamSettings |
リクエスト本文で API に送信された gamSettings オブジェクトと同じオブジェクト。 |
リクエストの例（cURL）
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer OAUTH_TOKEN" \
-d '@request.json' \
https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessionsrequest.json
{
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
"adTracking": "CLIENT",
"gamSettings": {
"streamId": "STREAM_ID"
}
}
レスポンスの例
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
"playUri": PLAY_URI,
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
"gamSettings": {
"streamId": STREAM_ID
}
}
レスポンスの受信後、レスポンス オブジェクトの playUri フィールドのセッションプレイバック URI を参照して、広告合成されたライブ ストリームを再生できます。
Video Stitcher API は、リクエストごとに一意のセッション ID を生成します。この ID は、レスポンス オブジェクトの name フィールドの最後のセクションから取得できます。
アイドル状態のセッションは 5 分後に期限切れになります。一定期間内にマニフェストが取得されなかった場合、セッションはアイドル状態とみなされます。
新しい AdBreak メタデータのポーリング
各ミッドロール挿入点のメタデータを取得するのはアプリケーションであり、どのインプレッションをトリガーする必要があるかを把握しています。これを行うには、新しい広告情報について DAI API metadata_url を定期的にポーリングするタイマーを設定します。ポーリングの間隔は、ストリーム登録レスポンスの polling_frequency フィールドで指定されます。
返される JSON オブジェクトには、次のパラメータが含まれています。
tags |
ストリーム内で発生する広告メディア イベントを記述する Key-Value ペアのセット。各キーは、ストリームの ID3 メタデータに表示される広告メディア ID の最初の 17 文字か、「progress」イベントの場合は広告メディア ID 全体で構成されます。各値は、次のプロパティを持つオブジェクトです。
|
ads |
ストリーム内に表示される広告を記述する Key-Value ペアのセット。各キーは広告 ID です。各値は、次のプロパティを持つオブジェクトです。
|
ad_breaks |
ストリーム内で発生するミッドロール挿入点を表す Key-Value ペアのセット。各キーは広告ブレーク ID です。各値は、次のプロパティを持つオブジェクトです。
|
各ポーリング後にこれらの値を保存して、動画ストリーム内のタイミング付きメタデータ イベントを関連付けます。
リクエストの例（cURL）
curl https://dai.google.com/.../metadata/レスポンスの例
{
"tags":{
"google_0492266569":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"firstquartile"
},
"google_1560331148":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"thirdquartile"
},
"google_1877686714378797835":{
"ad":"0000229836_slate",
"ad_break_id":"0000229836",
"type":"progress"
},
"google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"progress"
},
"google_2032765498":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"midpoint"
},
...
"google_5646900623":{
"ad":"0000229837_ad1",
"ad_break_id":"0000229837",
"type":"complete"
}
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15.01,
"title":"truman-e2e-creativeset4",
"description":"truman-e2e-creativeset4 ad",
"ad_system":"GDFP",
"ad_id":"39066884",
"creative_id":"58092079124",
"clickthrough_url":"https://pubads.g.doubleclick.net/...",
"universal_ad_id":{
"id_value":"58092079124",
"id_registry":"GDFP"
}
},
"0000229834_slate":{
"ad_break_id":"0000229834",
"position":-1,
"duration":14.974977777,
"slate":true
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15.01,
"expected_duration":29.984977776999997,
"ads":1
},
...
}
}
ID3 イベントをリッスンし、再生イベントを追跡する
動画ストリームで特定のイベントが発生したことを確認するには、次の手順で ID3 イベントを処理します。
- メディア イベントをキューに保存し、各メディア ID とタイムスタンプ（プレーヤーによって表示された場合はタイムスタンプ）を保存します。
- プレーヤーから更新するたびに、または設定した頻度（500 ミリ秒を推奨）で更新するたびに、イベントのタイムスタンプとプレイヘッドを比較して、最近再生されたイベントのメディア イベント キューを確認します。
- 再生したメディア イベントの場合は、保存されているミッドロール挿入点タグでメディア ID を検索してタイプを確認します。ミッドロール挿入点タグ オブジェクトには、メディア ID の切り捨てバージョンのみが含まれ、google_ 接頭辞の後の最初の 10 桁に制限されるため、ID3 メディア認証 ID とタグ オブジェクト内のキーは直接一致しません。これは、ID3 イベントが到着する前にイベント検証 ping が送信されないようにするためです。広告イベントの完全なメディア確認 URL を生成するには、ストリーム作成レスポンスの media_verification_url 値に完全な広告イベント ID を追加します。
- 「progress」イベントを使用して、ユーザーがミッドロール挿入点内にいるかどうかを追跡します。HTTP エラーコードを回避するため、これらのイベントをメディア検証エンドポイントに送信しないでください。他のイベントタイプの場合は、メディア ID をメディア確認の URL に追加し、GET リクエストを行って再生を追跡します。
- キューからメディア イベントを削除します。
API エンドポイント
GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com
パスパラメータ
MEDIA_VERIFICATION_URL |
ストリーム登録エンドポイントによって media_verification_url フィールドに返された値：
MEDIA_VERIFICATION_URL
|
AD_MEDIA_ID |
ストリームの ID3 メタデータに表示される完全な広告メディア ID：
AD_MEDIA_ID
|
期待される戻り値
HTTP/1.1 204 No Content |
成功した空のレスポンス。 |
HTTP/1.1 404 Not Found |
メディア確認 ID を認識できませんでした。 |
HTTP/1.1 409 Conflict |
メディアの確認 ID はすでに送信されています。 |
リクエストの例（cURL）
curl MEDIA_VERIFICATION_URLAD_MEDIA_IDレスポンスの例
HTTP/1.1 204 No Content
制限事項
WebView 内で API を使用する場合、ターゲティングに関して次の制限が適用されます。
- UserAgent: ユーザー エージェント パラメータは、基盤となるプラットフォームではなく、ブラウザ固有の値として渡されます。
- rdid、idtype、is_latSTRONG: デバイス ID が正しく渡されていないため、次の機能の機能が制限されます。
- フリークエンシー キャップ
- 広告の順次ローテーション
- オーディエンス セグメンテーションとターゲティング