ダイナミック広告挿入 Linear API

ダイナミック広告挿入 API を使用すると、DAI リニア（ライブ）ストリームをリクエストして追跡できます。

サービス: dai.google.com

すべての URI は https://dai.google.com を基準にしています

メソッド: stream

メソッド
stream POST /linear/v1/hls/event/{assetKey}/stream

指定されたイベント ID の DAI ストリームを作成します。

HTTP リクエスト

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

リクエスト ヘッダー

パラメータ
api‑key string

ストリームの作成時に指定された API キーは、パブリッシャーのネットワークで有効である必要があります。

API キーは、リクエストの本文で指定する代わりに、次の形式で HTTP Authorization ヘッダーで渡すことができます。

Authorization: DCLKDAI key="<api-key>"

パスパラメータ

パラメータ
assetKey string

ストリームのイベント ID。
注: ストリーム アセットキーは、 アド マネージャーの管理画面でも確認できる識別子です。

リクエストの本文

リクエストの本文は application/x-www-form-urlencoded 型で、次のパラメータが含まれています。

パラメータ
dai-ssb 省略可

サーバーサイド ビーコン ストリームを作成するには、true に設定します。デフォルトは false です。デフォルトのストリームのトラッキングはクライアント側で開始され、サーバー側で ping されます。
DFP ターゲティング パラメータ 省略可 追加のターゲット設定パラメータ。
ストリーム パラメータをオーバーライドする 省略可 ストリーム作成パラメータのデフォルト値をオーバーライドします。
HMAC 認証 省略可 HMAC ベースのトークンを使用して認証します。

レスポンスの本文

成功した場合、レスポンスの本文には新しい Stream が含まれます。サーバーサイド ビーコン ストリームの場合、この Stream には stream_id フィールドと stream_manifest フィールドのみが含まれます。

Open Measurement

DAI API の Verifications フィールドには、Open Measurement 検証の情報が含まれています。このフィールドには、クリエイティブの再生を検証するために第三者による測定コードを実行するために必要なリソースとメタデータをリストする 1 つ以上の Verification 要素が含まれます。JavaScriptResource のみがサポートされています。詳しくは、IAB Tech Lab と VAST 4.1 の仕様をご覧ください。

方法: メディアの確認

再生中に広告メディア ID が検出されたら、ストリーム エンドポイントから取得した media_verification_url を使用して、すぐにリクエストを行います。サーバーがメディア検証を開始するサーバーサイド ビーコン ストリームでは、これらのリクエストは必要ありません。

media verification エンドポイントへのリクエストはべき等です。

メソッド
media verification GET /{media_verification_url}/{ad_media_id}

メディア検証イベントを API に通知します。

HTTP リクエスト

GET https://{media-verification-url}/{ad-media-id}

レスポンスの本文

media verification は次のレスポンスを返します。

  • メディアの検証が成功し、すべての ping が送信された場合は HTTP/1.1 204 No Content。
  • URL の形式が正しくないか、期限切れのため、リクエストでメディアを検証できない場合は HTTP/1.1 404 Not Found。
  • この ID の以前の確認リクエストが成功した場合は HTTP/1.1 404 Not Found。
  • この時点で別のリクエストがすでに ping を送信している場合は HTTP/1.1 409 Conflict。

広告メディア ID（HLS）

広告メディア ID は、HLS のタイムド メタデータで、キー TXXX を使用してエンコードされます。このキーは「ユーザー定義のテキスト情報」フレーム用に予約されています。フレームの内容は暗号化されず、常に "google_" というテキストで始まります。

各広告検証リクエストを行う前に、フレームのテキスト コンテンツ全体を広告検証 URL に追加する必要があります。

メソッド: metadata

metadata_url のメタデータ エンドポイントは、広告 UI の構築に使用される情報を返します。メタデータ エンドポイントは、サーバーが広告メディアの検証を開始するサーバーサイド ビーコン ストリームでは使用できません。

メソッド
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

広告のメタデータ情報を取得します。

HTTP リクエスト

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

クエリ パラメータ

パラメータ
delta_token 省略可 string

クライアントの現在の同期状態を表す不透明トークン。指定された場合、サーバーはトークンの生成以降に変更されたメタデータのみを、レスポンス内の新しい next_delta_token とともに返します。省略した場合、サーバーは DVR 時間枠全体の完全なメタデータを返します。

レスポンスの本文

成功した場合、レスポンスは PodMetadata のインスタンスを返します。

メタデータの操作

メタデータには、tags、ads、広告 breaks の 3 つの個別のセクションがあります。データへのエントリ ポイントは tags セクションです。そこから、タグを反復処理し、名前が動画ストリームで見つかった広告メディア ID の接頭辞である最初のエントリを見つけます。たとえば、次のような広告メディア ID があります。

google_1234567890

次に、google_12345 という名前のタグ オブジェクトを見つけます。この場合、広告メディア ID と一致します。正しい広告メディア接頭辞オブジェクトが見つかったら、広告 ID、ミッドロール挿入点 ID、イベントタイプを検索できます。広告 ID は ads オブジェクトのインデックス登録に使用され、ミッドロール挿入点 ID は breaks オブジェクトのインデックス登録に使用されます。

レスポンス データ

ストリーム

Stream は、新しく作成されたストリームのリソースのリストを JSON 形式でレンダリングするために使用されます。
JSON 表現
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
フィールド
stream_id string

GAM ストリーム ID。
stream_manifest string

ストリームのマニフェスト URL。HLS のマルチバリエーション再生リストまたは DASH の MPD の取得に使用されます。
hls_master_playlist string

（非推奨）HLS マルチバリエーション再生リストの URL。代わりに「stream_manifest」を使用してください。
media_verification_url string

再生イベントのトラッキング用のベース エンドポイントとして使用されるメディア確認用 URL。
metadata_url string

今後のストリーム広告イベントに関する定期的な情報をポーリングするために使用されるメタデータ URL。
session_update_url string

このストリームのターゲティング パラメータを更新するために使用されるセッションの更新 URL。ターゲティング パラメータの元の値は、最初のストリーム作成リクエスト時にキャプチャされます。
polling_frequency number

metadata_url または heartbeat_url をリクエストする際のポーリング頻度（秒単位）。

PodMetadata

PodMetadata には、広告、広告ブレーク、メディア ID タグに関するメタデータ情報が含まれます。
JSON 表現
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
フィールド
tags map[string, object(TagSegment)]

タグ接頭辞でインデックス登録されたタグ セグメントのマップ。
ads map[string, object(Ad)]

広告 ID でインデックス登録された広告のマップ。
ad_breaks map[string, object(AdBreak)]

ミッドロール挿入点 ID でインデックス登録されたミッドロール挿入点のマップ。
next_delta_token string

クライアントが次のポーリングで使用する不透明なトークン。
obsolete_ad_break_ids string

廃止され、クライアントのキャッシュから削除する必要があるミッドロール挿入点 ID のリスト。

TagSegment

TagSegment には、広告、ミッドロール挿入点、イベントタイプへの参照が含まれます。type="progress" の TagSegment は、広告メディア検証エンドポイントに ping してはなりません。
JSON 表現
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
フィールド
ad string

このタグの広告の ID。
ad_break_id string

このタグのミッドロール挿入点の ID。
type string

このタグのイベントタイプ。

AdBreak

AdBreak は、ストリーム内の 1 つのミッドロール挿入点を表します。再生時間、タイプ（ミッドロール/プリロール/ポストロール）、広告数を含みます。
JSON 表現
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
フィールド
type string

有効なブレークの種類は、pre、mid、post です。
duration number

このミッドロール挿入点の広告の合計再生時間（秒）。
expected_duration number

すべての広告とスレートを含む、ミッドロール挿入点の推定時間（秒単位）。
ads number

ミッドロール挿入点内の広告数。
Ad は、ストリーム内の広告を表します。
JSON 表現
{
  "ad_break_id": string,
  "position": 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,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
フィールド
ad_break_id string

この広告のミッドロール挿入点の ID。
position number

ミッドロール挿入点内のこの広告の位置（1 から始まる）。
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。
click_tracking_urls string

省略可能なクリック トラッキング URL。
verifications [object(Verification)]

クリエイティブの再生を検証するために第三者による測定コードを実行するのに必要なリソースとメタデータをリストする、省略可能な Open Measurement 検証エントリ。
slate boolean

現在のエントリがスレートであることを示すブール値（省略可）。
icons [object(Icon)]

アイコンのリスト。空の場合は省略されます。
wrappers [object(Wrapper)]

Wrapper のリスト。空の場合は省略されます。
universal_ad_id object(UniversalAdID)

省略可能なユニバーサル広告 ID。
extensions string

VAST 内のすべての <Extension> ノードの省略可能なリスト。
companions [object(Companion)]

この広告とともに表示される可能性がある省略可能なコンパニオン。
interactive_file object(InteractiveFile)

広告の再生中に表示されるオプションのインタラクティブ クリエイティブ（SIMID）。

アイコン

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 は含まれません。
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。

確認

Verification には、第三者による視認性と検証の測定を容易にする 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

ピンを送信するトラッキング イベント。

UniversalAdID

UniversalAdID は、広告システム全体で維持される一意のクリエイティブ識別子を提供するために使用されます。
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> ノードの値。