ダイナミック広告挿入（DAI）の API を使用すると、IMA SDK がサポートされていない収益化ストリーム（スマートテレビなど）にアクセスできます。サポートされているプラットフォームでは、IMA を使用する必要があります。この API は既存のすべての DAI 機能をサポートしていますが、これらの機能を使用するにはサイト運営者（パブリッシャー）側での実装が必要です。
API を使用する際の要件
API の使用にあたって、パブリッシャー側で次の機能の実装が必要です。
- HTTP エンドポイントを介した DAI ストリームへのアクセスと JSON レスポンスの処理
- API パラメータの作成と Key-Value のターゲティング
- ユーザー エクスペリエンスの実装（リンク先 URL やアイコンなど）
- プレーヤーの ID3 イベントをリッスンして、ライブリニアと VOD でプレーヤーのコントロールと広告のトラッキング、測定を実装する
- スクラブ動作、スナップバック、ブックマーク機能の実装
- ストリーミング形式の選択（HLS または DASH）
ビデオ オンデマンドまたはライブリニア ストリームの API を使用してストリームをリクエストし処理する方法については、以下の情報をご参照ください。
ビデオ オンデマンド（VOD）
VOD API のストリーム作成から広告再生の検証までのライフサイクルはシンプルです。
-
コンテンツ ソース ID（
cmsid）と動画 ID（vid）、API キーまたは HMAC トークン、広告ターゲティング パラメータを使用して、HTTP POST でストリームをリクエストします。https://dai.google.com/ondemand/v1/hls/content/<contentId>/vid/<vid>/stream -
コンテンツ再生マニフェスト、字幕、広告ブレーク、コンテンツのタイミング情報のレスポンスを処理します。
{"content_duration": 123.451,"stream_manifest": "https://dai.google.com/.../master.m3u8","media_verification_url": "https://dai.google.com/.../media/","stream_id": "9ca0c62a-3291-4f95-986f-d1721f8b96f0","total_duration": 163.451,"valid_for": "8h0m0s","valid_until": "2018-05-16T23:21:16.558053292-07:00","ad_breaks": [...]} -
各広告ブレークについて、リンク先 URL、コンパニオン、広告ブレークの長さなど、UI としてレンダリングする個々の広告要素の情報を処理します。
{"clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400","description": "プレロール広告の例","duration": 10,"seq": 1,"title": "プレロールの例"} -
広告ごとに、広告メディア再生から追加された ID3 値を使用して
media_verification_urlをトリガーします。https://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/
progress イベントは、広告ブレークでの再生かそれ以外かを区別するためのもので、他の広告トラッキングの用途には使用されません。
progress イベントを識別するには、メタデータの json ファイルでメディア識別子を検索し、type フィールドが progress に設定されているかどうかを検証します。progress ID3 は、動画コントロールのブロックなどに使用できます。
ライブリニア ストリーム
リニア API のストリーム作成から広告再生の検証までのライフサイクルはシンプルです。
-
イベント ID、API キーまたは HMAC トークン、広告ターゲティング パラメータを使用して、HTTP POST でストリームをリクエストします。
https://dai.google.com/linear/v1/hls/event/<eventid>/stream
https://dai.google.com/linear/v1/dash/event/<eventid>/stream -
コンテンツ再生マニフェスト、字幕、広告ブレーク、コンテンツのタイミング情報のレスポンスを処理します。
{"stream_manifest": "https://dai.google.com/linear/.../master.m3u8","media_verification_url": "https://dai.google.com/linear/.../media/","metadata_url": "https://dai.google.com/linear/.../metadata","polling_frequency": 10,"stream_id": "793bf10c-2323-404d-b23b-0a529d96e651:MRN",} -
ポーリング頻度または各 ID3 広告メディア ID ごとに広告のメタデータをリクエストし、広告メディア ID をクエリ パラメータのメタデータ URL に追加します。
{"ad_breaks": {"0001127859": {"ads": 3,"duration": 30,"type": "mid"}},"ads": {"0001127859_ad2": {"ad_break_id": "0001127859","ad_id": "39135088","ad_system": "GDFP","clickthrough_url": "http://pubads.g.doubleclick.net/pcs/click?...","creative_id": "103990016608","description": "10 秒のリニア広告の例","duration": 10,"position": 2,"title": "リニア広告の例"}},"tags": {"google_0028792773": {"ad": "0001127859_ad2","ad_break_id": "0001127859","type": "firstquartile"}, ...}} -
広告ごとに、広告メディア再生の ID3 値を追加して
media_verification_urlをトリガーします。https://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/
progress イベントは、広告ブレークでの再生かそれ以外かを区別するためのもので、他の広告トラッキングの用途には使用されません。
progress イベントを識別するには、メタデータの json ファイルでメディア識別子を検索し、type フィールドが progress に設定されているかどうかを検証します。progress ID3 は、動画コントロールのブロックなどに使用できます。
DAI API を使用してストリーム内の広告ブレークの開始と終了を検出する
DAI は、四分位イベント（開始、25%、50%、75%、完了など）の ID3 メタデータを広告セグメントに挿入し、進捗イベント（1 秒ごと）を広告とスレート セグメントに挿入します。このような ID3 タグが初めて確認されると、「広告ブレーク開始」イベントが発生します。その後、このような ID3 タグがたとえば 2.5 秒間検出されなかった場合は、「広告ブレーク終了」イベントが発生します。DAI によって挿入される ID3 タグは、「google_」接頭辞と、メタデータ JSON ファイル内に存在するかどうかで識別できます。
ユーザー ストリームごとにターゲティングや Key-Value を動的に更新する
session_update_url を使用して、今後のライブ ストリームの広告リクエストに使用されるすべての広告タグ パラメータを置き換えることができます（replaceAdTagParameters と同様です）。番組ごととユーザーごとにターゲティング情報を更新する必要がある場合（たとえば、ターゲティングが事前にわからないライブ スポーツの場合）などに便利です。