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

Dynamic Ad Insertion API を使用すると、DAI リニア（LIVE）ストリームをリクエストしてトラッキングできます。

サービス: dai.google.com

以下の URI はすべて、https://dai.google.com に対する相対 URI です。

メソッド: 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 の仕様をご覧ください。

方法: メディアの確認

再生中に広告メディア識別子を検出したら、すぐに上記の stream エンドポイントから取得した 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。
  • HTTP/1.1 404 Not Found: URL の形式が正しくないか、期限切れが原因でメディアを確認できない場合。
  • この ID の以前の確認リクエストが成功した場合は HTTP/1.1 404 Not Found。
  • この時点で別のリクエストがすでに ping を送信している場合は HTTP/1.1 409 Conflict。

広告メディア ID（HLS）

広告メディア識別子は、キー TXXX を使用して HLS 時間指定メタデータでエンコードされます。このキーは「ユーザー定義のテキスト情報」フレーム用に予約されています。フレームのコンテンツは暗号化されず、常に「"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}

レスポンスの本文

成功すると、レスポンスは PodMetadata のインスタンスを返します。

メタデータの操作

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

google_1234567890

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

Response data

ストリーム

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

Google アド マネージャー ストリーム 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)],
}
フィールド
tags map[string, object(TagSegment)]

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

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

ミッドロール挿入点 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 は、ストリーム内の単一の広告ブレークを表します。これには、再生時間、タイプ（中/事前/事後）、広告の数が含まれます。
JSON 表現
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
フィールド
type string

有効な挿入タイプは、事前、途中、後です。
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)]

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

オプションのユニバーサル広告 ID。
extensions string

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

この広告とともに表示できるオプションのコンパニオン。
interactive_file object(InteractiveFile)

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

Icon

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 を識別するために使用される文字列。

コンパニオン モード

Companion には、広告とともに表示できるコンパニオン広告の情報が含まれます。
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> ノードの値。