VOD API Penyisipan Iklan Dinamis

Dynamic Ad Insertion API memungkinkan Anda meminta dan melacak streaming video on demand (VOD) DAI. Streaming HLS dan DASH didukung.

Layanan: dai.google.com

Jalur metode stream bersifat relatif terhadap https://dai.google.com

Metode: stream

Metode
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

Membuat streaming DAI HLS untuk sumber konten dan ID video yang diberikan.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Membuat streaming DASH DAI untuk sumber konten dan ID video yang diberikan.

Permintaan 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

Header permintaan

Parameter
api‑key string

Kunci API, yang diberikan saat membuat streaming, harus valid untuk jaringan penayang.

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

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

Parameter jalur

Parameter
content-source string

ID CMS aliran data.

video-id string

ID video streaming.

Isi permintaan

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

Parameter
dai-ssb Opsional

Tetapkan ke true untuk membuat streaming beacon sisi server. Nilai defaultnya adalah false. Pelacakan streaming default dimulai oleh klien dan melakukan ping di 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 berisi Stream baru. Untuk streaming beacon sisi server, Stream ini hanya berisi kolom stream_id dan stream_manifest.

Pengukuran Terbuka

Kolom Verifications berisi informasi untuk verifikasi Pengukuran Terbuka untuk streaming beaconing non-sisi server. Verifications berisi satu atau beberapa elemen Verification yang mencantumkan resource dan metadata yang Anda perlukan untuk memverifikasi pemutaran materi iklan dengan kode pengukuran pihak ketiga. Hanya JavaScriptResource yang didukung. Untuk informasi selengkapnya, lihat IAB Tech Lab dan spesifikasi VAST 4.1.

Metode: verifikasi media

Setelah Anda menemukan ID media iklan selama pemutaran, segera buat permintaan menggunakan media_verification_url dari endpoint stream. media_verification_url adalah jalur absolut. Permintaan verifikasi media tidak diperlukan untuk streaming beacon 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 tentang peristiwa verifikasi media.

Permintaan HTTP

GET {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 dikirim.
  • HTTP/1.1 404 Not Found jika permintaan tidak dapat memverifikasi media karena format URL atau masa berlakunya salah.
  • HTTP/1.1 404 Not Found jika permintaan verifikasi sebelumnya untuk ID 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 dicadangkan 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 media_verification_url untuk setiap permintaan verifikasi iklan.

ID media iklan (DASH)

ID media iklan akan disisipkan ke dalam manifes melalui penggunaan elemen EventStream DASH.

Setiap EventStream akan memiliki URI ID Skema urn:google:dai:2018. Peristiwa ini akan berisi peristiwa dengan atribut messageData yang berisi ID media iklan yang diawali dengan “google_”. Seluruh konten atribut messageData harus ditambahkan ke media_verification_url untuk setiap permintaan verifikasi iklan.

Data respons

Streaming

Streaming digunakan untuk merender daftar semua resource untuk streaming yang baru dibuat dalam format JSON .
Representasi 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)],
}
Kolom
stream_id string

ID streaming.
total_duration number

Durasi streaming dalam detik.
content_duration number

Durasi konten, tanpa iklan, dalam detik.
valid_for string

Streaming durasi valid untuk, dalam format "00h00m00s".
valid_until string

Tanggal hingga streaming valid, dalam format RFC 3339.
subtitles [object(Subtitle)]

Daftar Subtitel. Dihilangkan jika kosong. Khusus HLS.
hls_master_playlist string

(TIDAK DIGUNAKAN LAGI) URL playlist master HLS. Gunakan stream_manifest. Khusus HLS.
stream_manifest string

Manifes streaming. Sesuai dengan playlist master di HLS dan MPD di DASH. Ini adalah satu-satunya kolom selain "stream_id" yang ada dalam respons saat membuat streaming beacon sisi server.
media_verification_url string

URL verifikasi media.
apple_tv object(AppleTV)

Informasi opsional khusus untuk perangkat AppleTV. Khusus HLS.
ad_breaks [object(AdBreak)]

Daftar Jeda Iklan. Dihilangkan jika kosong.

AppleTV

AppleTV berisi informasi khusus untuk perangkat Apple TV.
Representasi JSON
{
  "interstitials_url": string,
}
Kolom
interstitials_url string

URL interstisial.

AdBreak

AdBreak menjelaskan satu jeda iklan dalam streaming. Iklan ini berisi posisi, durasi, jenis (mid/pre/post), dan daftar iklan.
Representasi JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Kolom
type string

Jenis jeda yang valid adalah: tengah, pra, dan pasca.
start number

Posisi dalam streaming tempat jeda dimulai, dalam detik.
duration number

Durasi jeda iklan, dalam detik.
ads [object(Ad)]

Daftar Iklan. Dihilangkan jika kosong.
Iklan menjelaskan iklan di streaming. Iklan ini berisi posisi iklan dalam jeda, durasi iklan, dan beberapa metadata opsional.
Representasi 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),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
Kolom
seq number

Posisi iklan dalam jeda iklan.
start number

Posisi dalam streaming tempat iklan dimulai, dalam detik.
duration number

Durasi iklan, dalam detik.
title string

Judul opsional iklan.
description string

Deskripsi opsional untuk 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.
icons [object(Icon)]

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

Daftar Wrapper. Dihilangkan jika kosong.
events [object(Event)]

Daftar peristiwa dalam iklan.
verifications [object(Verification)]

Entri verifikasi Pengukuran Terbuka opsional yang mencantumkan resource dan metadata yang diperlukan untuk mengeksekusi kode pengukuran pihak ketiga guna memverifikasi pemutaran materi iklan.
universal_ad_id object(UniversalAdID)

ID iklan universal opsional.
companions [object(Companion)]

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

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

Metadata opsional untuk iklan yang dapat dilewati. Jika ditetapkan, ini menunjukkan bahwa iklan dapat dilewati dan menyertakan petunjuk tentang cara menangani UI lewati dan peristiwa pelacakan.
extensions string

Daftar opsional semua node <Extension> di VAST.

Acara

Peristiwa berisi jenis peristiwa dan waktu presentasi peristiwa.
Representasi JSON
{
  "time": number,
  "type": string,
}
Kolom
time number

Waktu presentasi acara ini.
type string

Jenis peristiwa ini.

Subjudul

Subtitle menjelaskan trek subtitel sidecar untuk streaming video. File ini menyimpan dua format subtitel: TTML dan WebVTT. Atribut TTMLPath berisi URL ke file sidecar TTML dan atribut WebVTTPath juga berisi URL ke file sidecar WebVTT.
Representasi JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Kolom
language string

Kode bahasa, seperti 'en' atau 'de'.
language_name string

Nama deskriptif bahasa. Ini membedakan kumpulan subtitel tertentu jika ada beberapa kumpulan untuk bahasa yang sama
ttml string

URL opsional ke file sidecar TTML.
webvtt string

URL opsional ke file sidecar WebVTT.

SkipMetadata

SkipMetadata memberikan informasi yang diperlukan bagi klien untuk menangani peristiwa lewati untuk iklan yang dapat dilewati.
Representasi JSON
{
  "offset": number,
  "tracking_url": string,
}
Kolom
offset number

Offset menunjukkan jumlah waktu dalam detik saat pemutar harus menunggu untuk merender tombol lewati. Dihilangkan jika tidak diberikan di VAST.
tracking_url string

TrackingURL berisi URL yang harus di-ping pada peristiwa lewati.

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 ini tidak menyertakan ID Transaksi 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 ke 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.
uri string

Peristiwa pelacakan yang akan dikirimi 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 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 dapat ditampilkan bersama dengan iklan.
Representasi 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)],
}
Kolom
click_data object(ClickData)

Data klik untuk pengiring ini.
creative_type string

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

Tinggi dalam piksel dari pendamping ini.
width int32

Lebar dalam piksel dari pendamping ini.
resource string

Untuk pendamping statis dan iframe, 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. Iklan dapat berupa statis, iframe, atau HTML.
ad_slot_id string

ID slot untuk pendamping ini.
api_framework string

Framework API untuk pendamping ini.
tracking_events [object(TrackingEvent)]

Daftar peristiwa pelacakan untuk pendamping ini.

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.