Dynamic Ad Insertion API を使用すると、DAI ビデオ オンデマンド(VOD)ストリームのリクエストとトラッキングを行うことができます。HLS ストリームと DASH ストリームがサポートされています。
サービス: dai.google.com
stream
メソッドのパスは https://dai.google.com
からの相対パスです。
メソッド: stream
メソッド | |
---|---|
stream |
POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
指定されたコンテンツ ソースと動画 ID の HLS DAI ストリームを作成します。
指定されたコンテンツ ソースと動画 ID の DASH DAI ストリームを作成します。 |
HTTP リクエスト
POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream
リクエスト ヘッダー
パラメータ | |
---|---|
api‑key |
string ストリームの作成時に指定する API キーは、パブリッシャーのネットワークに対して有効である必要があります。 API キーは、リクエスト本文ではなく、HTTP Authorization ヘッダーで次の形式で渡すことができます。 Authorization: DCLKDAI key="<api-key>" |
パスパラメータ
パラメータ | |
---|---|
content-source |
string ストリームの CMS ID。 |
video-id |
string ストリームの動画 ID。 |
リクエスト本文
リクエストの本文は application/x-www-form-urlencoded
型で、次のパラメータを含みます。
パラメータ | ||
---|---|---|
dai-ssb |
任意 | サーバーサイド ビーコン ストリームを作成するには、 |
アド マネージャーのターゲティング パラメータ | 任意 | 追加のターゲティング パラメータ。 |
ストリーム パラメータをオーバーライドする | 任意 | ストリーム作成パラメータのデフォルト値をオーバーライドします。 |
HMAC 認証 | 任意 | HMAC ベースのトークンを使用して認証します。 |
レスポンスの本文
成功した場合、レスポンスの本文には新しい Stream
が含まれます。サーバーサイド ビーコン ストリームの場合、この Stream
には stream_id
フィールドと stream_manifest
フィールドのみが含まれます。
Open Measurement
Verifications
フィールドには、サーバーサイド ビーコン以外のストリームの Open Measurement 検証に関する情報が含まれます。Verifications
には、第三者測定コードによるクリエイティブの再生を検証するために必要なリソースとメタデータをリストする 1 つ以上の Verification
要素が含まれます。JavaScriptResource
のみがサポートされています。詳しくは、IAB Tech Lab と VAST 4.1 仕様をご覧ください。
方法: メディアによるオーナー確認
再生中に広告メディア ID を見つけたら、すぐに stream
エンドポイントから media_verification_url
を使用してリクエストを行います。media_verification_url
は絶対パスです。サーバーがメディア検証を開始するサーバーサイド ビーコン ストリームでは、メディア検証リクエストは必要ありません。
media verification
エンドポイントへのリクエストはべき等です。
メソッド | |
---|---|
media verification |
GET {media_verification_url}/{ad_media_id}
メディア検証イベントを API に通知します。 |
HTTP リクエスト
GET {media-verification-url}/{ad-media-id}
レスポンスの本文
media verification
は次のレスポンスを返します。
- メディアの検証が成功し、すべての ping が送信された場合は
HTTP/1.1 204 No Content
。 HTTP/1.1 404 Not Found
: URL の形式や有効期限が正しくないためにリクエストでメディアを確認できない場合。- この ID の前回の確認リクエストが成功した場合は
HTTP/1.1 404 Not Found
。 HTTP/1.1 409 Conflict
(別のリクエストがすでに ping を送信している場合)。
広告メディア ID(HLS)
広告メディア識別子は、「ユーザー定義のテキスト情報」フレーム用に予約されたキー TXXX
を使用して、HLS タイミング メタデータでエンコードされます。フレームの内容は暗号化されず、常に "google_"
というテキストで始まります。
フレームのテキスト コンテンツ全体が、広告確認リクエストごとに media_verification_url に追加する必要があります。
広告メディア ID(DASH)
広告メディア ID は、DASH の EventStream
要素を使用してマニフェストに挿入されます。
各 EventStream
には、urn:google:dai:2018
のスキーム ID URI が含まれます。このイベントには、“google_”
で始まる広告メディア ID を含む messageData
属性のイベントが含まれます。messageData
属性の内容全体を、広告検証リクエストごとに media_verification_url に追加する必要があります。
Response data
ストリーム
Stream は、新しく作成されたストリームのすべてのリソースのリストを JSON 形式でレンダリングするために使用されます。JSON 表現 |
---|
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], } |
フィールド | |
---|---|
stream_id |
string ストリーム ID。 |
total_duration |
number ストリーミング時間(秒) |
content_duration |
number 広告なしのコンテンツの再生時間(秒)。 |
valid_for |
string ストリームの有効期間は「00h00m00s」の形式です。 |
valid_until |
string ストリームの有効期間(RFC 3339 形式)。 |
subtitles |
[object(Subtitle)] 字幕のリスト。空の場合は省略します。HLS のみ。 |
hls_master_playlist |
string (非推奨)HLS マスター再生リストの URL。Stream_manifest を使用します。HLS のみ。 |
stream_manifest |
string ストリームのマニフェスト。HLS のマスター再生リストと DASH の MPD に対応します。 これは、サーバーサイド ビーコン ストリームの作成時にレスポンスに存在する「stream_id」以外の唯一のフィールドです。 |
media_verification_url |
string メディアの確認用 URL |
apple_tv |
object(AppleTV) AppleTV デバイスに固有の情報です(省略可)。HLS のみ。 |
ad_breaks |
[object(AdBreak)] ミッドロール挿入点のリスト。空の場合は省略します。 |
AppleTV
AppleTV には、Apple TV デバイス固有の情報が含まれています。JSON 表現 |
---|
{ "interstitials_url": string, } |
フィールド | |
---|---|
interstitials_url |
string インタースティシャルの URL |
AdBreak
AdBreak は、ストリーム内の 1 つのミッドロール挿入点を表します。位置、再生時間、タイプ(途中/事前/事後)、広告のリストが含まれます。JSON 表現 |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
フィールド | |
---|---|
type |
string 有効なブレークタイプは、mid、pre、post です。 |
start |
number ストリーミングで休憩を開始する位置(秒単位)。 |
duration |
number 広告ブレークの長さ(秒)。 |
ads |
[object(Ad)] 広告のリスト。空の場合は省略します。 |
広告
広告はストリーム内の広告について説明したものです。これには、ブレーク内の広告の位置、広告の再生時間、オプションのメタデータが含まれます。JSON 表現 |
---|
{ "seq": number, "start": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
フィールド | |
---|---|
seq |
number 広告ブレーク内の広告の位置。 |
start |
number 広告が開始するストリーム内の位置(秒単位)。 |
duration |
number 広告の再生時間(秒)。 |
title |
string 広告のタイトル(省略可)。 |
description |
string 広告の説明(省略可)。 |
advertiser |
string オプションの広告主 ID。 |
ad_system |
string オプションの広告システム。 |
ad_id |
string 広告 ID(省略可)。 |
creative_id |
string クリエイティブ ID(省略可)。 |
creative_ad_id |
string オプションのクリエイティブ広告 ID。 |
deal_id |
string 取引 ID(省略可)。 |
clickthrough_url |
string (省略可)リンク先 URL。 |
icons |
[object(Icon)] アイコンのリスト。空の場合は省略されます。 |
wrappers |
[object(Wrapper)] ラッパーのリスト。空の場合は省略します。 |
events |
[object(Event)] 広告のイベントのリスト。 |
verifications |
[object(Verification)] (省略可)Open Measurement の検証エントリ。第三者測定コードを実行してクリエイティブの再生を検証するために必要なリソースとメタデータをリストしたものです。 |
universal_ad_id |
object(UniversalAdID) オプションのユニバーサル広告 ID。 |
companions |
[object(Companion)] この広告と一緒に表示できるオプションのコンパニオンです。 |
interactive_file |
object(InteractiveFile) 広告の再生中に表示されるオプションのインタラクティブ クリエイティブ(SIMID)。 |
イベント
Event には、イベントタイプとイベントのプレゼンテーション時間が含まれます。JSON 表現 |
---|
{ "time": number, "type": string, } |
フィールド | |
---|---|
time |
number この予定の提示時間 |
type |
string この予定のタイプ。 |
字幕
サブタイトルは、動画ストリームのサイドカー 字幕トラックを表します。TTML と WebVTT の 2 つの字幕形式を格納します。TTMLPath 属性には TTML サイドカー ファイルへの URL が含まれ、WebVTTPath 属性には同様に WebVTT サイドカー ファイルへの URL が含まれます。JSON 表現 |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
フィールド | |
---|---|
language |
string 「en」や「de」などの言語コード。 |
language_name |
string 言語のわかりやすい名前。同じ言語に複数の字幕セットが存在する場合、特定の字幕セットを区別します。 |
ttml |
string TTML サイドカー ファイルの URL(省略可)。 |
webvtt |
string WebVTT サイドカー ファイルの URL(省略可)。 |
Icon
アイコンには、VAST アイコンに関する情報が含まれています。JSON 表現 |
---|
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, } |
フィールド | |
---|---|
click_data |
object(ClickData) |
creative_type |
string |
click_fallback_images |
[object(FallbackImage)] |
height |
int32 |
width |
int32 |
resource |
string |
type |
string |
x_position |
string |
y_position |
string |
program |
string |
alt_text |
string |
ClickData
ClickData には、アイコンのクリックスルーに関する情報が含まれます。JSON 表現 |
---|
{ "url": string, } |
フィールド | |
---|---|
url |
string |
FallbackImage
FallbackImage には、VAST 代替画像に関する情報が含まれます。JSON 表現 |
---|
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } |
フィールド | |
---|---|
creative_type |
string |
height |
int32 |
width |
int32 |
resource |
string |
alt_text |
string |
ラッパー
ラッパーには、ラッパー広告に関する情報が含まれています。取引 ID が存在しない場合、取引 ID は記載されません。JSON 表現 |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
フィールド | |
---|---|
system |
string 広告システムの識別子。 |
ad_id |
string ラッパー広告に使用される広告 ID。 |
creative_id |
string ラッパー広告に使用されるクリエイティブ ID。 |
creative_ad_id |
string ラッパー広告に使用されるクリエイティブ広告 ID。 |
deal_id |
string ラッパー広告の取引 ID(省略可)。 |
検証
ベリフィケーションでは Open Measurement に関する情報が含まれ、第三者の視認性および検証測定を容易にします。現在サポートされているのは JavaScript リソースのみです。https://iabtechlab.com/standards/open-measurement-sdk/ をご覧ください。JSON 表現 |
---|
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } |
フィールド | |
---|---|
vendor |
string 検証ベンダー。 |
java_script_resources |
[object(JavaScriptResource)] 検証用の JavaScript リソースのリスト。 |
tracking_events |
[object(TrackingEvent)] オーナー確認のトラッキング イベントのリスト。 |
parameters |
string ブートストラップ確認コードに渡される不透明な文字列。 |
JavaScriptResource
JavaScriptResource には、JavaScript で検証するための情報が含まれます。JSON 表現 |
---|
{ "script_url": string, "api_framework": string, "browser_optional": boolean, } |
フィールド | |
---|---|
script_url |
string JavaScript ペイロードの URI。 |
api_framework |
string APIFramework は、確認コードを実行する動画フレームワークの名前です。 |
browser_optional |
boolean このスクリプトをブラウザの外部で実行できるかどうか。 |
TrackingEvent
TrackingEvent には、特定の状況でクライアントが ping する必要がある URL が含まれます。JSON 表現 |
---|
{ "event": string, "uri": string, } |
フィールド | |
---|---|
event |
string トラッキング イベントのタイプ。 |
uri |
string ping されるトラッキング イベント。 |
UniversalAdID
UniversalAdID は、広告システム間で維持される一意のクリエイティブ ID を提供するために使われます。JSON 表現 |
---|
{ "id_value": string, "id_registry": string, } |
フィールド | |
---|---|
id_value |
string 広告で選択されたクリエイティブのユニバーサル広告 ID。 |
id_registry |
string 選択したクリエイティブのユニバーサル広告 ID がカタログに登録されている登録簿ウェブサイトの URL を識別する文字列。 |
コンパニオン モード
コンパニオンには、広告とともに表示される可能性のあるコンパニオン広告の情報が含まれます。JSON 表現 |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, "ad_slot_id": string, "api_framework": string, "tracking_events": [object(TrackingEvent)], } |
フィールド | |
---|---|
click_data |
object(ClickData) このコンパニオンのクリックデータ。 |
creative_type |
string VAST タイプの <StaticResource> ノードの CreativeType 属性(これが静的タイプのコンパニオンの場合)。 |
height |
int32 このコンパニオンの高さ(ピクセル単位)。 |
width |
int32 このコンパニオンの幅(ピクセル単位)。 |
resource |
string 静的コンパニオンと iframe コンパニオンの場合、これは読み込まれて表示される URL です。HTML コンパニオンの場合は、コンパニオンとして表示される HTML スニペットです。 |
type |
string このコンパニオンのタイプ。静的、iframe、HTML のいずれも使用できます。 |
ad_slot_id |
string このコンパニオンのスロット ID。 |
api_framework |
string このコンパニオンの API フレームワーク。 |
tracking_events |
[object(TrackingEvent)] このコンパニオンのトラッキング イベントのリスト。 |
InteractiveFile
InteractiveFile には、広告の再生中に表示する必要があるインタラクティブ クリエイティブの情報(SIMID など)が含まれます。JSON 表現 |
---|
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } |
フィールド | |
---|---|
resource |
string インタラクティブ クリエイティブの URL。 |
type |
string リソースとして提供されるファイルの MIME タイプ。 |
variable_duration |
boolean このクリエイティブで再生時間の延長がリクエストされるかどうか。 |
ad_parameters |
string VAST 内の <AdParameters> ノードの値 |