Dengan Google DAI Pod Serve API, Anda dapat melakukan penyisipan iklan sisi server yang didukung oleh Google Ads sekaligus mempertahankan kontrol atas penggabungan video Anda sendiri.
Panduan ini menunjukkan cara berinteraksi dengan Pod Serve API dan mendapatkan fungsi serupa dengan IMA DAI SDK. Untuk pertanyaan tertentu tentang fungsi yang didukung, hubungi Account Manager Google Anda.
Pod Serve API mendukung streaming yang menayangkan pod di protokol streaming HLS atau MPEG-DASH. Panduan ini berfokus pada streaming HLS dan menyoroti perbedaan utama antara HLS dan MPEG-DASH dalam langkah tertentu.
Untuk mengintegrasikan Pod Serve API ke dalam aplikasi untuk streaming VOD, selesaikan langkah-langkah berikut:
Membuat permintaan pendaftaran streaming ke Ad Manager
Buat permintaan POST ke endpoint pendaftaran aliran data. Selanjutnya, Anda akan menerima respons JSON yang berisi ID aliran data untuk dikirimkan ke server manipulasi manifes dan endpoint Pod Serve 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 formulir
Kumpulan opsional parameter penargetan yang dienkode bentuk .
Tanggapan JSON
media_verification_url |
URL dasar untuk melakukan ping ke peristiwa pelacakan pemutaran. URL verifikasi media lengkap dibentuk 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 saat sesi streaming saat ini berakhir, sebagai string tanggal dan waktu ISO 8601 dalam format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
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/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
Contoh respons
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
Jika terjadi error, kode error HTTP standar akan ditampilkan tanpa isi respons JSON.
Mengurai respons JSON dan menyimpan nilai yang relevan.
Meminta manifes streaming dari manipulator manifes
Setiap manipulator manifes memiliki format permintaan dan respons yang berbeda. Hubungi penyedia manipulator Anda untuk memahami persyaratan spesifiknya. Jika Anda mengimplementasikan manipulator manifes sendiri, baca panduan manipulator manifes untuk memahami persyaratan untuk komponen ini.
Secara umum, Anda harus meneruskan ID aliran data yang ditampilkan oleh endpoint pendaftaran di atas ke manipulator manifes agar dapat mem-build manifes khusus sesi. Kecuali dinyatakan lain oleh manipulator manifes Anda, respons terhadap permintaan manifes adalah streaming video yang berisi 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
Muat manifes yang Anda terima dari server manipulasi manifes ke dalam pemutar video dan mulai pemutaran.
Meminta metadata pod iklan dari Ad Manager
Buat permintaan GET
ke metadata_url
yang Anda terima pada langkah pertama. Langkah
ini harus terjadi setelah Anda menerima manifes yang digabungkan dari manipulator
manifes Anda. Sebagai balasannya, Anda akan menerima objek JSON yang berisi parameter berikut:
tags |
Kumpulan key-value pair yang berisi semua peristiwa iklan yang muncul di aliran data. Kuncinya dapat berupa 17 karakter pertama dari ID peristiwa iklan
yang muncul dalam metadata berjangka waktu streaming, atau untuk peristiwa
jenis progress , ID peristiwa iklan lengkap.
Setiap nilai adalah objek yang berisi parameter berikut:
|
||||||||||||||||||
ads |
Kumpulan pasangan nilai kunci yang menjelaskan semua iklan yang muncul di streaming. Kunci
adalah ID iklan yang cocok dengan nilai yang terdapat dalam objek tags
yang tercantum di atas. Setiap nilai adalah objek yang berisi parameter berikut:
|
||||||||||||||||||
ad_breaks |
Kumpulan pasangan nilai kunci yang menjelaskan semua jeda iklan yang muncul di streaming.
Kuncinya adalah ID jeda iklan yang cocok dengan nilai yang ditemukan dalam objek tags
dan ads yang tercantum di atas. Setiap nilai adalah objek yang berisi parameter berikut:
|
Simpan nilai ini untuk dikaitkan dengan peristiwa metadata terjadwal 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
Proses metadata dengan waktu melalui peristiwa iklan yang dipicu di streaming audio/video pada pemutar video Anda.
Untuk streaming MPEG-TS, metadata muncul sebagai tag ID3 v2.3 in-band. Setiap tag metadata memiliki ID TXXX
, dan nilainya diawali dengan string google_
diikuti dengan serangkaian karakter. Nilai ini adalah ID peristiwa iklan.
XXX
di TXXX
bukan placeholder. String TXXX
adalah ID tag ID3 yang dicadangkan untuk "teks yang ditentukan pengguna".
Contoh tag ID3
TXXXgoogle_1234567890123456789
Untuk streaming MP4, ini dikirim sebagai peristiwa emsg in-band yang mengemulasi tag ID3 v2.3. Setiap kotak pesan yang relevan memiliki nilai scheme_id_uri
https://aomedia.org/emsg/ID3
atau
https://developer.apple.com/streaming/emsg-id3
dan nilai message_data
yang diawali dengan ID3TXXXgoogle_
. Nilai message_data
ini, tanpa
awalan ID3TXXX
, adalah ID peristiwa iklan.
Contoh kotak emsg
Struktur data dapat bervariasi, bergantung pada koleksi media player 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 library pemutar media secara otomatis menampilkan peristiwa emsg yang mengemulasi tag ID3 sebagai tag ID3 native. Dalam hal ini, streaming MP4 menampilkan tag ID3 yang identik dengan MPEG_TS.
Mengupdate UI aplikasi pemutar video klien
Setiap ID peristiwa iklan dapat dicocokkan dengan kunci di objek tags
dari langkah 4.
Mencocokkan nilai ini adalah proses dua langkah:
Periksa objek
tags
untuk menemukan kunci yang cocok dengan ID peristiwa iklan lengkap. Jika kecocokan ditemukan, ambil jenis peristiwa serta objekad
danad_break
yang terkait. Peristiwa ini harus memiliki jenisprogress
.Jika kecocokan tidak ditemukan untuk ID peristiwa iklan lengkap, periksa objek
tags
untuk mendapatkan kunci yang cocok dengan 17 karakter pertama ID peristiwa iklan. Ambil jenis peristiwa serta 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, saat Anda menerima peristiwa
start
atauprogress
pertama, sembunyikan kontrol pencari pemain dan tampilkan overlay yang mendeskripsikan posisi iklan saat ini di jeda iklan, 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"
},
...
}
Kirim 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 ID peristiwa
iklan lengkap ke nilai media_verification_url
dari respons pendaftaran
streaming.
Buat permintaan GET dengan URL lengkap. Jika permintaan verifikasi
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