Pod Penyisipan Iklan Dinamis yang menayangkan API live

Dynamic AdPenyisipan API memungkinkan Anda meminta dan melacak livestream DAI.

Layanan: dai.google.com

Semua URI bersifat relatif terhadap https://dai.google.com.

Metode: stream

Metode
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Mendaftarkan sesi livestream penayangan pod DAI DAI.

Permintaan HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Parameter jalur

Parameter
network_code string

Kode jaringan Google Ad Manager penayang.

custom_asset_key string

ID kustom yang terkait dengan peristiwa ini di Google Ad Manager.

Isi permintaan

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

Parameter
Parameter Penargetan DFP Opsional Parameter penargetan tambahan.
Mengganti Parameter Aliran Data Opsional Mengganti nilai default parameter pembuatan streaming.
Autentikasi HMAC Opsional Autentikasi menggunakan token berbasis HMAC.

Isi respons

Jika berhasil, isi respons berisi objek Stream baru.

Pengukuran Terbuka

DAI API berisi informasi untuk verifikasi Pengukuran Terbuka dalam Kolom Verifications. Kolom ini berisi satu atau beberapa Elemen Verification yang mencantumkan resource dan metadata yang diperlukan untuk mengeksekusi kode pengukuran pihak ketiga untuk memverifikasi pemutaran materi iklan. Hanya JavaScriptResource didukung. Untuk informasi selengkapnya, lihat IAB Tech Lab dan Spesifikasi VAST 4.1.

Metode: segmen pod

Metode
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Membuat streaming DAI untuk ID peristiwa yang diberikan.

Permintaan HTTP

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Parameter jalur

Parameter
network_code string

Kode jaringan Google Ad Manager penayang.

custom_asset_key string

ID kustom yang terkait dengan peristiwa ini di Google Ad Manager.

pod_id integer

ID numerik untuk jeda iklan saat ini. ID pod iklan adalah ditetapkan secara bertahap untuk setiap peristiwa, dimulai dari 1.
profile_name string

Tujuan nama dari yang diminta Profil encoding DAI Google Ad Manager. Profil encoding harus berupa salah satu profil encoding yang dikonfigurasi untuk peristiwa yang dipilih.

segment_number integer

Indeks segmen yang diminta dalam pod iklan saat ini, mulai ke nol.
segment_format string

Ekstensi file yang terkait dengan format segmen yang diminta. Ekstensi yang diterima adalah: ts, mp4, vtt, aac, ac3, atau eac3.

Parameter kueri

Parameter
stream_id required string

ID streaming untuk sesi pengguna saat ini. Nilai ini ditampilkan oleh permintaan berhasil ke endpoint stream.
sd required1 integer

Durasi segmen yang diminta, dalam milidetik.
so opsional

Offset segmen yang diminta dalam pod iklan, dalam milidetik. Jika Anda menghapus parameter so, parameter tersebut akan dihitung oleh mengalikan durasi segmen dengan jumlah segmen.
pd wajib2 integer

Durasi pod iklan, dalam milidetik.
auth-token required string

Tanda tangan yang dienkode dengan URL Token HMAC untuk pod iklan saat ini.
last opsional boolean

Menunjukkan segmen terakhir di jeda iklan. Hapus parameter ini untuk semua segmen lainnya.
scte35 opsional string

SCTE-35signal berenkode base64 untuk jeda iklan ini.
cust_params opsional string

Serangkaian pasangan nilai kunci, yang digunakan untuk penargetan kampanye Ad Manager. Ini pasangan harus direpresentasikan sebagai string kueri yang dienkode URL.

Contoh:
Parameter
  • bagian = sports
  • halaman = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Catatan kaki

  1. sd tidak diperlukan untuk segmen inisialisasi. ↩
  2. pd tidak diperlukan untuk acara dengan iklan tanpa durasi jeda iklan diaktifkan. ↩

Isi respons

Jika berhasil, isi respons akan menjadi segmen streaming yang dapat diputar dan cocok dengan format, dan parameter yang ditentukan dalam permintaan.

Metode: Template periode pod DASH

Metode
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Meminta template periode DASH dari Google Ad Manager. Template ini berisi makro yang harus Anda isi dengan parameter streaming. Satu kali makro ini terisi, template menjadi periode jeda iklan, dan yang dapat digabungkan ke dalam manifes DASH.

Permintaan HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Parameter jalur

Parameter
network_code string

Kode jaringan Google Ad Manager penayang.

custom_asset_key string

ID kustom yang terkait dengan peristiwa ini di Google Ad Manager.

Parameter kueri

Parameter
stream_id required string

ID streaming untuk sesi pengguna saat ini. Nilai ini ditampilkan oleh permintaan berhasil ke endpoint stream.

Isi respons

Jika berhasil, isi respons berisi Objek PodTemplateResponse.

Metode: verifikasi media

Setelah menemukan pengenal media iklan selama pemutaran, segera buat permintaan menggunakan media_verification_url yang diperoleh dari stream endpoint, di atas. Permintaan ini tidak diperlukan untuk beaconing sisi server streaming, 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 peristiwa verifikasi media.

Permintaan HTTP

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

Isi respons

media verification akan menampilkan respons berikut:

  • HTTP/1.1 204 No Content jika verifikasi media berhasil dan semua ping terkirim.
  • HTTP/1.1 404 Not Found jika permintaan tidak dapat memverifikasi media karena kesalahan pemformatan atau masa berlaku URL.
  • HTTP/1.1 404 Not Found jika ada permintaan verifikasi sebelumnya untuk tanda pengenal ini berhasil.
  • HTTP/1.1 409 Conflict jika permintaan lain sudah mengirimkan ping di sini baik.

ID media iklan

ID media iklan akan dienkode dalam trek metadata terpisah dengan waktu metadata untuk streaming transpor HLS, atau emsg untuk file mp4. ID media iklan akan selalu dimulai dengan string google_.

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

Metode: metadata

Endpoint metadata di metadata_url menampilkan informasi yang digunakan untuk membuat iklan UI. Endpoint metadata tidak tersedia untuk aliran data di sisi server, di mana 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 menampilkan instance PodMetadata

Mengurai Metadata

Metadata memiliki tiga bagian yang berbeda: tags, ads, dan breaks iklan. Entri mengarah ke data adalah bagian tags. Kemudian, lakukan iterasi tag dan temukan entri pertama yang namanya merupakan awalan untuk ID media iklan yang ditemukan dalam streaming video. Sebagai contoh, Anda mungkin memiliki ID media iklan yang terlihat seperti:

google_1234567890

Kemudian, Anda menemukan objek tag bernama google_12345. Dalam hal ini, cocok dengan ID media iklan. Setelah menemukan objek awalan media iklan yang tepat, Anda dapat mencari ID iklan, ID jeda iklan, dan jenis peristiwa. ID iklan kemudian 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 di dalam format JSON saya.
Representasi JSON
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
Kolom
stream_id string

ID streaming GAM.
media_verification_url string

URL verifikasi media yang digunakan sebagai endpoint dasar untuk melacak peristiwa pemutaran.
metadata_url string

URL metadata yang digunakan untuk polling informasi berkala tentang acara iklan streaming mendatang.
session_update_url string

URL update sesi digunakan untuk memperbarui parameter penargetan untuk streaming ini. Nilai asli untuk parameter penargetan akan diambil selama permintaan pembuatan streaming awal.
heartbeat_url string

URL detak jantung, yang digunakan untuk menjaga streaming beaconing sisi server tetap aktif, server harus di-ping setiap {PollingFrequency} detik. Diisi untuk streaming beaconing sisi server.
polling_frequency number

Frekuensi polling, dalam detik, saat meminta metadata_url atauhear_url.
pod_manifest_url string

Template URL manifes pod digunakan untuk membuat URL guna mengambil manifes pod streaming, yang sesuai dengan URL playlist multi-varian di HLS atau MPD di DASH. Diisi untuk peristiwa Livestream jenis Penyisipan Iklan Dinamis POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

Format manifes adalah format manifes yang diambil dari pod_manifes_url, tanda hubung atau hls.

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 berdasarkan awalan tag.
ads map[string, object(Ad)]

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

Peta jeda iklan yang diindeks oleh ID jeda iklan.

TagSegment

TagSegment berisi referensi ke iklan, jeda iklannya, dan jenis peristiwa. TagSegment dengan type="progress" tidak boleh di-ping ke media iklan endpoint verifikasi.
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

Jeda Iklan mendeskripsikan satu jeda iklan dalam streaming. Video berisi durasi, jenis (mid/pre/post) dan jumlah iklan.
Representasi JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Kolom
type string

Jenis jeda yang valid adalah: sebelum, pertengahan, dan setelah.
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) apa pun.
ads number

Jumlah iklan dalam jeda iklan.
Iklan mendeskripsikan 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 di jeda iklan, mulai dari 1.
duration number

Durasi iklan, dalam detik.
title string

Judul opsional iklan.
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 Open Measurement opsional yang mencantumkan resource dan metadata yang diperlukan untuk mengeksekusi 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, 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 <Ekstensi> node dalam VAST.
companions [object(Companion)]

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

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

PodTemplateResponse

PodTemplateResponse mewakili payload JSON yang ditampilkan ke VTP untuk penggabungan pod.
Representasi JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Kolom
dash_period_template string

DashPeriodTemplate adalah template xml untuk periode yang diisi dengan data yang sesuai sebelum digabungkan.
segment_duration_ms int64

SegmentDurationMS adalah durasi segmen periode dalam milidetik.

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. Laporan 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 verifikasi dan visibilitas 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.
Representasi JSON
{
  "event": string,
  "uri": string,
}
Kolom
event string

Jenis peristiwa pelacakan.
uri string

Peristiwa pelacakan yang akan di-ping.

UniversalAdID

UniversalAdID digunakan untuk memberikan ID materi iklan unik yang dikelola 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 dicantumkan dalam katalog.

Pengiring

Pengiring berisi informasi untuk iklan pengiring yang mungkin 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 di <StaticResource> di VAST jika ini adalah pendamping jenis statis.
height int32

Tinggi pengiring ini dalam piksel.
width int32

Lebar dalam piksel pendamping ini.
resource string

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

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

ID slot untuk pengiring 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 <AdParameters> node di VAST.