Google DAI Pod Serving API memungkinkan Anda melakukan penyisipan iklan sisi server yang didukung oleh Google Ads sambil tetap mengontrol penggabungan video Anda sendiri.
Panduan ini menunjukkan cara berinteraksi dengan Pod Serving API dan mencapai fungsi serupa dengan IMA DAI SDK. Untuk pertanyaan spesifik tentang fungsionalitas yang didukung, hubungi Account Manager Google Anda.
Pod Serving API mendukung aliran penayangan pod dalam HLS atau MPEG-DASH protokol {i>streaming<i}. Panduan ini berfokus pada streaming HLS dan menandai tombol perbedaan antara HLS dan MPEG-DASH dalam langkah tertentu.
Untuk mengintegrasikan Pod Serving API ke dalam aplikasi Anda untuk streaming VOD, selesaikan langkah-langkah berikut:
Membuat permintaan pendaftaran streaming ke DAI Pod Serving API
Buat permintaan POST ke endpoint pendaftaran streaming. Selanjutnya, Anda akan menerima Respons JSON yang berisi ID aliran data yang akan dikirim ke manipulasi manifes Anda server dan endpoint Pod Serving API terkait.
Endpoint API
POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
Parameter jalur
{network_code} |
Kode jaringan Google Ad Manager 360 Anda |
{custom_asset} |
ID kustom yang terkait dengan peristiwa ini di Google Ad Manager. |
Parameter isi yang dienkode dengan formulir
Set opsional dari format yang dienkode parameter penargetan .
Tanggapan JSON
media_verification_url |
URL dasar untuk melakukan ping pada peristiwa pelacakan pemutaran. Verifikasi media selesai URL dibuat dengan menambahkan ID peristiwa iklan ke URL dasar ini. |
metadata_url |
URL untuk meminta metadata pod iklan. |
stream_id |
String yang digunakan untuk mengidentifikasi sesi streaming saat ini. |
valid_for |
Jumlah waktu yang tersisa hingga sesi streaming saat ini berakhir, dalam
Format dhms (hari, jam, menit, detik). Misalnya,
2h0m0.000s mewakili durasi 2 jam.
|
valid_until |
Waktu sesi streaming saat ini berakhir, sebagai ISO 8601
string datetime di yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm
format font.
|
Contoh permintaan (cURL)
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream
Contoh respons
{
"stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
"media_verification_url":"https://dai.google.com/.../media/",
"metadata_url":"https://dai.google.com/.../metadata",
"session_update_url":"https://dai.google.com/.../session",
"polling_frequency":10
}
Jika terjadi error, kode error HTTP standar akan ditampilkan tanpa respons JSON {i>body <i}itu.
Mengurai respons JSON dan menyimpan nilai yang relevan.
Meminta manifes streaming dari manipulator manifes
Setiap manipulator manifes memiliki format permintaan dan respons yang berbeda. Kontak penyedia manipulator Anda untuk memahami kebutuhan khusus mereka. Jika Anda menerapkan manipulator manifes Anda sendiri, baca manipulator manifes panduan untuk memahami persyaratan untuk komponen ini.
Secara umum, Anda harus meneruskan ID streaming yang ditampilkan oleh metode titik akhir pendaftaran di atas ke manipulator manifes Anda untuk membangun manifes khusus sesi. Kecuali dinyatakan secara eksplisit oleh manifes Anda manipulator, respons terhadap permintaan manifes adalah streaming video yang berisi yaitu konten dan iklan.
Contoh permintaan (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
Contoh respons (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
Putar streaming
Memuat manifes yang Anda terima dari server manipulasi manifes ke pemutar video dan memulai pemutaran.
Polling untuk metadata Jeda Iklan baru
Aplikasi bertanggung jawab untuk mengambil metadata untuk setiap jeda iklan, sehingga
mengetahui tayangan mana yang perlu dipicu. Untuk melakukannya, Anda akan menyetel
timer untuk secara rutin melakukan polling metadata_url
DAI API untuk iklan baru
tidak akurat atau tidak sesuai. Interval untuk polling ditentukan dalam polling_frequency
dalam respons pendaftaran stream.
Sebagai hasilnya, Anda akan menerima objek JSON yang berisi parameter berikut:
tags |
Kumpulan pasangan nilai kunci yang berisi semua peristiwa iklan yang muncul di
feed. Kunci berupa 17 karakter pertama peristiwa iklan
ID yang muncul di metadata streaming dengan waktu, atau dalam kasus acara
dari jenis progress , ID peristiwa iklan lengkap.
Setiap nilai adalah objek yang berisi parameter berikut:
|
||||||||||||||||||
ads |
Kumpulan pasangan nilai kunci yang mendeskripsikan semua iklan yang muncul di streaming. Tujuan
kunci adalah ID iklan yang cocok dengan nilai yang ditemukan dalam objek tags
yang tercantum di atas. Setiap nilai adalah objek yang berisi parameter berikut:
|
||||||||||||||||||
ad_breaks |
Serangkaian pasangan nilai kunci yang menjelaskan semua jeda iklan yang muncul di streaming.
Kuncinya adalah ID jeda iklan yang cocok dengan nilai yang ditemukan di tags
dan objek ads yang tercantum di atas. Setiap nilai adalah objek
yang berisi parameter berikut:
|
Simpan nilai ini setelah setiap polling untuk mengaitkan peristiwa metadata dengan waktu dalam streaming video Anda.
Contoh permintaan (cURL)
curl https://dai.google.com/.../metadata
Contoh respons
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
Memproses peristiwa iklan
Memproses metadata berwaktu melalui peristiwa iklan yang dipicu di streaming audio/video pemutar video Anda.
Untuk streaming MPEG-TS, metadata muncul sebagai tag in-band ID3 v2.3. Masing-masing
tag metadata memiliki ID TXXX
, dan nilainya dimulai dengan string google_
diikuti dengan serangkaian karakter. Nilai ini adalah ID peristiwa iklan.
XXX
di TXXX
bukan placeholder. String TXXX
adalah ID tag ID3
dan disediakan untuk "teks buatan pengguna".
Contoh tag ID3
TXXXgoogle_1234567890123456789
Untuk streaming MP4, ini dikirim sebagai peristiwa emsg in-band yang mengemulasi ID3 v2.3
{i>tag<i}. Setiap kotak pesan yang relevan memiliki nilai scheme_id_uri
https://aomedia.org/emsg/ID3
atau
Nilai https://developer.apple.com/streaming/emsg-id3
dan message_data
yang diawali dengan ID3TXXXgoogle_
. Nilai message_data
ini, tanpa atribut
Awalan ID3TXXX
, adalah ID peristiwa iklan.
Contoh kotak emsg
Struktur data dapat bervariasi, bergantung pada koleksi pemutar media Anda.
Jika ID peristiwa iklan adalah google_1234567890123456789
, responsnya akan terlihat seperti
ini:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
Beberapa pustaka pemutar media secara otomatis menyajikan kejadian emsg yang mengemulasi ID3 tag sebagai tag ID3 native. Dalam hal ini, aliran MP4 menyajikan tag ID3 yang identik sebagai MPEG_TS.
Mengupdate UI aplikasi pemutar video klien
Setiap ID peristiwa iklan dapat dicocokkan dengan kunci di objek tags
dari langkah 4.
Pencocokan nilai ini melalui proses dua langkah:
Periksa objek
tags
untuk menemukan kunci yang cocok dengan ID peristiwa iklan lengkap. Jika ditemukan kecocokan, mengambil jenis peristiwa danad
yang terkait, sertaad_break
objek. Peristiwa ini harus memiliki jenisprogress
.Jika tidak ditemukan kecocokan untuk ID peristiwa iklan lengkap, periksa
tags
untuk kunci yang cocok dengan 17 karakter pertama ID peristiwa iklan. Ambil jenis peristiwa dan objekad
danad_break
yang terkait. Tindakan ini akan mengambil semua peristiwa dengan jenis selainprogress
.Gunakan informasi yang diambil ini untuk mengupdate UI pemutar Anda. Misalnya, ketika Anda menerima
start
atau eventprogress
pertama, sembunyikan pencari mengontrol dan menampilkan overlay yang menjelaskan posisi iklan saat ini dalam iklan jeda, misalnya: "Iklan 1 dari 3".
Contoh ID peristiwa iklan
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
Contoh objek tag
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
Mengirim ping verifikasi media
Ping verifikasi media harus dikirim ke Ad Manager setiap kali peristiwa iklan
dengan jenis selain progress
diterima.
Untuk membuat URL verifikasi media lengkap dari peristiwa iklan, tambahkan URL lengkap
ID peristiwa iklan ke nilai media_verification_url
dari pendaftaran streaming
yang dihasilkan.
Buat permintaan GET dengan URL lengkap. Jika permintaan verifikasi adalah
berhasil, Anda akan menerima respons HTTP dengan kode status 202
.
Jika tidak, Anda akan mendapatkan kode error HTTP 404
.
Contoh permintaan (cURL)
curl https://{...}/media/google_5555555555123456789
Contoh respons yang berhasil
HTTP/1.1 202 Accepted