Aplikasi pemutar video klien untuk streaming VOD

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.

Poin Penting: Sebelum mempertimbangkan API ini, periksa apakah sudah ada IMA DAI SDK untuk platform pilihan Anda. IMA DAI SDK direkomendasikan di platform tempatnya tersedia. Pod Serve API ditujukan untuk hanya digunakan pada platform yang tidak memiliki IMA DAI SDK.

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: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Parameter jalur

{network_code}

Kode jaringan Google Ad Manager 360 Anda

Parameter isi JSON

targeting_parameters

Objek JSON yang berisi ID sumber konten (cmsid), ID video (vid), dan parameter penargetan iklan. Wajib

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 \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

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.

Tips: URL yang diberikan dalam respons API dapat berubah tanpa pemberitahuan. Oleh karena itu, gunakan URL seperti yang disediakan dalam respons API, bukan membuatnya sendiri. Hal ini membantu memastikan bahwa kode Anda terus berfungsi dengan benar saat URL berubah.

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. Selanjutnya, 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: ad ID iklan yang cocok dengan kunci dalam objek ads. ad_break_id ID jeda iklan yang cocok dengan kunci dalam objek ad_breaks. type Jenis peristiwa iklan. Jenis peristiwa iklan adalah: start Diaktifkan di awal iklan. firstquartile Dipicu di akhir kuartil pertama. midpoint Diaktifkan di bagian tengah iklan. thirdquartile Dipicu pada akhir kuartil ketiga. complete Diaktifkan di akhir iklan. progress Diaktifkan secara berkala sepanjang iklan, untuk memberi tahu aplikasi bahwa jeda iklan sedang diputar.
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_break_id ID jeda iklan yang cocok dengan kunci dalam objek ad_breaks. position Posisi tempat iklan ini muncul dalam kumpulan iklan pada jeda iklan, dalam detik floating point. duration Durasi iklan dalam detik floating point. clickthrough_url URL yang akan terbuka saat pengguna berinteraksi dengan iklan ini, jika didukung.
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: type Jenis jeda iklan. Jenis jeda iklan meliputi pre (pre-roll), mid (mid-roll), dan post (post-roll). duration Durasi jeda iklan dalam detik floating point. ads Jumlah iklan dalam jeda iklan ini.

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:

1. Periksa objek tags untuk menemukan kunci yang cocok dengan ID peristiwa iklan lengkap. Jika kecocokan ditemukan, ambil jenis peristiwa serta objek ad dan ad_break yang terkait. Peristiwa ini harus memiliki jenis progress.

   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 objek ad dan ad_break yang terkait. Tindakan ini akan mengambil semua peristiwa dengan jenis selain progress.

2. Gunakan informasi yang diambil ini untuk mengupdate UI pemutar Anda. Misalnya, saat Anda menerima peristiwa start atau progress 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.

Tips: Peristiwa iklan dengan jenis progress tidak boleh dikirim ke Ad Manager. Peristiwa ini dimaksudkan untuk memberi tahu aplikasi pemutar video klien bahwa jeda iklan sedang diputar dalam situasi saat peristiwa awal mungkin tidak diterima. Misalnya, jika pengguna mencari ke suatu posisi atau memulai pemutaran pada stempel waktu tertentu yang berada di tengah iklan, mereka tidak akan menerima peristiwa awal. Peristiwa progres yang dikirim ke Ad Manager akan dihapus sehingga dapat berdampak negatif pada performa aplikasi.

Contoh permintaan (cURL)

curl https://{...}/media/google_5555555555123456789

Contoh respons yang berhasil

HTTP/1.1 202 Accepted

Referensi tambahan

• Dokumentasi IMA SDK
• Perbandingan jenis penerapan lapisan DAI