API Linear Penyisipan Iklan Dinamis

Dynamic Ad Autocomplete API memungkinkan Anda meminta dan melacak streaming linear DAI (LIVE).

Layanan: dai.google.com

Semua URI di bawah ini relatif terhadap https://dai.google.com

Metode: stream

Metode
stream POST /linear/v1/hls/event/{assetKey}/stream

Membuat streaming DAI untuk ID peristiwa tertentu.

Permintaan HTTP

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

Header permintaan

Parameter
api‑key string

Kunci API yang diberikan saat membuat aliran data harus valid untuk jaringan penayang.

Daripada memberikannya dalam isi permintaan, kunci API dapat diteruskan di header Otorisasi HTTP dengan format berikut:

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

Parameter jalur

Parameter
assetKey string

ID peristiwa streaming.
Catatan: Kunci aset streaming adalah ID yang juga dapat ditemukan di UI Ad Manager.

Isi permintaan

Isi permintaan adalah jenis application/x-www-form-urlencoded dan berisi parameter berikut:

Parameter
dai-ssb Opsional

Setel ke true untuk membuat streaming beaconing sisi server. Nilai defaultnya adalah false. Pelacakan streaming default dilakukan oleh klien dan di-ping pada sisi server.
Parameter Penargetan DFP Opsional Parameter penargetan tambahan.
Mengganti Parameter Streaming Opsional Ganti nilai default parameter pembuatan streaming.
Autentikasi HMAC Opsional Lakukan autentikasi menggunakan token berbasis HMAC.

Isi respons

Jika berhasil, isi respons akan memuat Stream baru. Untuk aliran beaconing sisi server, Stream ini hanya berisi kolom stream_id dan stream_manifest.

Pengukuran Terbuka

DAI API berisi informasi untuk verifikasi Pengukuran Terbuka di kolom Verifications. Kolom ini berisi satu atau beberapa elemen Verification yang mencantumkan resource dan metadata yang diperlukan untuk menjalankan kode pengukuran pihak ketiga guna memverifikasi pemutaran materi iklan. Hanya JavaScriptResource yang didukung. Untuk mengetahui informasi selengkapnya, lihat IAB Tech Lab dan spesifikasi VAST 4.1.

Metode: verifikasi media

Setelah menemukan ID media iklan selama pemutaran, segera buat permintaan menggunakan media_verification_url yang diperoleh dari endpoint stream di atas. Permintaan ini tidak diperlukan untuk streaming beaconing sisi server, tempat server memulai verifikasi media.

Permintaan ke endpoint media verification bersifat idempoten.

Metode
media verification GET /{media_verification_url}/{ad_media_id}

Memberi tahu API mengenai peristiwa verifikasi media.

Permintaan HTTP

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

Isi respons

media verification menampilkan respons berikut:

  • HTTP/1.1 204 No Content jika verifikasi media berhasil dan semua ping akan dikirim.
  • HTTP/1.1 404 Not Found jika permintaan tidak dapat memverifikasi media karena format atau masa berlaku URL salah.
  • HTTP/1.1 404 Not Found jika permintaan verifikasi sebelumnya untuk tanda pengenal ini berhasil.
  • HTTP/1.1 409 Conflict jika permintaan lain sudah mengirim ping pada saat ini.

ID media iklan (HLS)

ID media iklan akan dienkode dalam Metadata Berwaktu HLS menggunakan kunci TXXX, yang disediakan untuk frame "informasi teks yang ditentukan pengguna". Konten frame tidak akan dienkripsi dan akan selalu dimulai dengan teks "google_".

Seluruh konten teks frame harus ditambahkan ke URL verifikasi iklan sebelum membuat setiap permintaan verifikasi iklan.

Metode: metadata

Endpoint metadata di metadata_url menampilkan informasi yang digunakan untuk membuat UI iklan. Endpoint metadata tidak tersedia untuk streaming beaconing sisi server, karena server bertanggung jawab untuk memulai verifikasi media iklan.

Metode
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Mengambil informasi metadata iklan.

Permintaan HTTP

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

GET https://{metadata_url}

Isi respons

Jika berhasil, respons akan menampilkan instance PodMetadata.

Menangani Metadata

Metadata memiliki tiga bagian berbeda: tags, ads, dan iklan breaks. Titik entri ke data adalah bagian tags. Dari sana, lakukan iterasi melalui tag dan temukan entri pertama yang namanya merupakan awalan untuk ID media iklan yang ditemukan dalam streaming video. Misalnya, Anda mungkin memiliki ID media iklan yang terlihat seperti:

google_1234567890

Kemudian, Anda menemukan objek tag bernama google_12345. Dalam hal ini, kolom ini cocok dengan ID media iklan Anda. Setelah menemukan objek awalan media iklan yang tepat, Anda dapat mencari ID iklan, ID jeda iklan, dan jenis peristiwa. Selanjutnya, ID iklan digunakan untuk mengindeks objek ads dan ID jeda iklan digunakan untuk mengindeks objek breaks.

Data respons

Streaming

Stream digunakan untuk merender daftar resource untuk stream yang baru dibuat dalam format JSON.
Representasi 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,
}
Kolom
stream_id string

ID streaming.
stream_manifest string

Manifes streaming, yang sesuai dengan playlist master dalam HLS atau MPD di DASH. Kolom ini adalah satu-satunya kolom selain "stream_id" yang ada dalam respons saat membuat stream beaconing sisi server.
hls_master_playlist string

(TIDAK DIGUNAKAN LAGI) URL playlist master HLS. Sebagai gantinya, gunakan "stream_manifest".
media_verification_url string

URL verifikasi media.
metadata_url string

URL metadata media iklan.
session_update_url string

URL pembaruan sesi.
polling_frequency number

Frekuensi polling URL metadata yang direkomendasikan, dalam hitungan detik.

PodMetadata

PodMetadata berisi informasi metadata tentang iklan, jeda iklan, dan tag ID media.
Representasi JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
}
Kolom
tags map[string, object(TagSegment)]

Peta segmen tag yang diindeks oleh awalan tag.
ads map[string, object(Ad)]

Peta iklan yang diindeks oleh ID iklan.
ad_breaks map[string, object(AdBreak)]

Peta jeda iklan yang diindeks oleh ID jeda iklan.

TagSegment

TagSegment berisi referensi ke iklan, jeda iklan, dan jenis peristiwa. TagSegment dengan type="progress" tidak boleh di-ping ke endpoint verifikasi media iklan.
Representasi JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Kolom
ad string

ID iklan tag ini.
ad_break_id string

ID jeda iklan tag ini.
type string

Jenis peristiwa tag ini.

AdBreak

AdBreak menjelaskan satu jeda iklan dalam streaming. Iklan berisi durasi, jenis (tengah/sebelum/pasca), dan jumlah iklan.
Representasi JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Kolom
type string

Jenis jeda yang valid adalah: pre, mid, dan post.
duration number

Total durasi iklan untuk jeda iklan ini, dalam detik.
expected_duration number

Perkiraan durasi jeda iklan (dalam detik), termasuk semua iklan dan slate (layar pemblokir).
ads number

Jumlah iklan dalam jeda iklan.
Iklan menjelaskan iklan dalam streaming.
Representasi 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),
}
Kolom
ad_break_id string

ID jeda iklan untuk iklan ini.
position number

Posisi iklan ini dalam jeda iklan, mulai dari 1.
duration number

Durasi iklan, dalam detik.
title string

Judul iklan opsional.
description string

Deskripsi opsional iklan.
advertiser string

ID pengiklan opsional.
ad_system string

Sistem iklan opsional.
ad_id string

ID iklan opsional.
creative_id string

ID materi iklan opsional.
creative_ad_id string

ID iklan materi iklan opsional.
deal_id string

ID transaksi opsional.
clickthrough_url string

URL klik-tayang opsional.
click_tracking_urls string

URL pelacakan klik opsional.
verifications [object(Verification)]

Entri verifikasi Pengukuran Terbuka opsional yang mencantumkan resource dan metadata yang diperlukan untuk menjalankan kode pengukuran pihak ketiga guna memverifikasi pemutaran materi iklan.
slate boolean

bool opsional yang menunjukkan entri saat ini adalah slate.
icons [object(Icon)]

Daftar ikon, yang dihilangkan jika kosong.
wrappers [object(Wrapper)]

Daftar Wrapper, dihilangkan jika kosong.
universal_ad_id object(UniversalAdID)

ID iklan universal opsional.
extensions string

Daftar opsional semua node <Extension> di VAST.
companions [object(Companion)]

Pengiring opsional yang dapat ditampilkan bersama iklan ini.
interactive_file object(InteractiveFile)

Materi iklan interaktif opsional (SIMID) yang harus ditampilkan selama pemutaran iklan.

Ikon

Ikon berisi informasi tentang Ikon VAST.
Representasi 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,
}
Kolom
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 berisi informasi tentang klik-tayang ikon.
Representasi JSON
{
  "url": string,
}
Kolom
url string

FallbackImage

FallbackImage berisi informasi tentang gambar penggantian VAST.
Representasi JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Kolom
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Wrapper berisi informasi tentang iklan wrapper. ID Transaksi tidak disertakan jika tidak ada.
Representasi JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Kolom
system string

ID sistem iklan.
ad_id string

ID iklan yang digunakan untuk iklan wrapper.
creative_id string

ID materi iklan yang digunakan untuk iklan wrapper.
creative_ad_id string

ID Iklan Materi Iklan yang digunakan untuk iklan wrapper.
deal_id string

ID transaksi opsional untuk iklan wrapper.

Verifikasi

Verifikasi berisi informasi untuk Pengukuran Terbuka, yang memfasilitasi pengukuran visibilitas dan verifikasi pihak ketiga. Saat ini, hanya resource JavaScript yang didukung. Lihat https://iabtechlab.com/standards/open-measurement-sdk/
Representasi JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Kolom
vendor string

Vendor verifikasi.
java_script_resources [object(JavaScriptResource)]

Daftar resource JavaScript untuk verifikasi.
tracking_events [object(TrackingEvent)]

Daftar peristiwa pelacakan untuk verifikasi.
parameters string

String buram yang diteruskan ke kode verifikasi bootstrap.

JavaScriptResource

JavaScriptResource berisi informasi untuk verifikasi melalui JavaScript.
Representasi JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Kolom
script_url string

URI untuk payload JavaScript.
api_framework string

APIFramework adalah nama framework video yang menjalankan kode verifikasi.
browser_optional boolean

Apakah skrip ini dapat dijalankan di luar browser.

TrackingEvent

TrackingEvent berisi URL yang harus di-ping oleh klien dalam situasi tertentu.
Representasi JSON
{
  "event": string,
  "uri": string,
}
Kolom
event string

Jenis peristiwa pelacakan, saat ini satu-satunya opsinya adalah "verificationNotExecuted" seperti yang ditentukan dalam spesifikasi VAST 4.1.
uri string

Peristiwa pelacakan yang akan di-ping.

UniversalAdID

UniversalAdID digunakan untuk memberikan ID materi iklan unik yang dipertahankan di seluruh sistem iklan.
Representasi JSON
{
  "id_value": string,
  "id_registry": string,
}
Kolom
id_value string

ID Iklan Universal dari materi iklan yang dipilih untuk iklan.
id_registry string

String yang digunakan untuk mengidentifikasi URL situs registry tempat ID Iklan Universal materi iklan yang dipilih dikatalogkan.

Pengiring

Pengiring berisi informasi untuk iklan pengiring yang mungkin ditampilkan bersama iklan.
Representasi JSON
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
}
Kolom
click_data object(ClickData)

Data klik untuk pendamping ini.
creative_type string

Atribut CreativeType pada node <StaticResource> di VAST jika ini adalah pendamping jenis statis.
height int32

Tinggi dalam piksel pendamping ini.
width int32

Lebar dalam piksel pendamping ini.
resource string

Untuk pengiring statis dan iframe, URL ini akan menjadi URL yang akan dimuat dan ditampilkan. Untuk pengiring HTML, ini akan menjadi cuplikan HTML yang harus ditampilkan sebagai pengiring.
type string

Jenis pendamping ini. URL dapat berupa statis, iframe, atau HTML.

InteractiveFile

InteractiveFile berisi informasi untuk materi iklan interaktif (yaitu SIMID) yang harus ditampilkan selama pemutaran iklan.
Representasi JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Kolom
resource string

URL ke materi iklan interaktif.
type string

Jenis MIME file yang disediakan sebagai resource.
variable_duration boolean

Apakah materi iklan ini dapat meminta perpanjangan durasi.
ad_parameters string

Nilai node <AdParameters> di VAST.