Aplikasi pemutar video klien untuk streaming VOD

Google DAI Pod Serving API memungkinkan Anda melakukan penyisipan iklan sisi server yang didukung oleh Google Ads sekaligus mempertahankan kontrol 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 yang menyediakannya. Pod Serving API hanya ditujukan untuk digunakan di platform yang tidak memiliki IMA DAI SDK.

Panduan ini menunjukkan cara berinteraksi dengan Pod Serving API dan mendapatkan fungsi serupa dengan IMA DAI SDK. Untuk pertanyaan spesifik tentang fungsi yang didukung, hubungi Account Manager Google Anda.

Pod Serving API mendukung streaming penayangan pod dalam protokol streaming HLS atau MPEG-DASH. Panduan ini berfokus pada streaming HLS dan menyoroti perbedaan utama antara HLS dan MPEG-DASH dalam langkah-langkah tertentu.

Untuk mengintegrasikan Pod Serving API ke dalam aplikasi Anda untuk streaming VOD, selesaikan langkah-langkah berikut:

Membuat permintaan pendaftaran streaming ke Ad Manager

Buat permintaan POST ke endpoint pendaftaran streaming. Anda akan menerima respons JSON yang berisi ID streaming untuk dikirim ke server manipulasi manifes dan endpoint Pod Serving 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 parameter penargetan iklan. Wajib

Tanggapan JSON

media_verification_url	URL dasar untuk mengirim 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 berakhirnya sesi streaming saat ini, sebagai string tanggal & waktu ISO 8601 dalam format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

Contoh permintaan (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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 sewaktu-waktu tanpa pemberitahuan. Oleh karena itu, gunakan URL seperti yang diberikan 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 menerapkan manipulator manifes sendiri, baca panduan manipulator manifes untuk memahami persyaratan komponen ini.

Secara umum, Anda harus meneruskan ID streaming yang ditampilkan oleh endpoint pendaftaran di atas ke manipulator manifes agar dapat mem-build manifes khusus sesi. Kecuali jika dinyatakan secara eksplisit oleh manipulator manifes, respons terhadap permintaan manifes Anda 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

Memutar 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 di langkah pertama. Langkah ini harus dilakukan setelah Anda menerima manifes yang digabungkan dari manipulator manifes. Sebagai gantinya, Anda akan menerima objek JSON yang berisi parameter berikut:

tags	Kumpulan key-value pair yang berisi semua peristiwa iklan yang muncul di stream. Kuncinya adalah 17 karakter pertama dari ID peristiwa iklan yang muncul di metadata berwaktu streaming, atau dalam kasus 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 Diaktifkan di akhir kuartil pertama. midpoint Diaktifkan di titik tengah iklan. thirdquartile Diaktifkan di akhir kuartil ketiga. complete Diaktifkan di akhir iklan. progress Diaktifkan secara berkala di seluruh iklan, untuk memberi tahu aplikasi bahwa jeda iklan sedang diputar.
ads	Kumpulan pasangan nilai kunci yang mendeskripsikan semua iklan yang muncul di streaming. Kuncinya 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_break_id ID jeda iklan yang cocok dengan kunci dalam objek ad_breaks. position Posisi tempat iklan ini muncul dalam kumpulan iklan di 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 mendeskripsikan 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 adalah 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 berwaktu 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 berwaktu melalui peristiwa iklan yang dipicu di streaming audio/video pemutar video Anda.

Untuk streaming MPEG-TS, metadata muncul sebagai tag ID3 v2.3 dalam band. Setiap 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 yang dicadangkan untuk "teks yang ditentukan pengguna".

Contoh tag ID3

TXXXgoogle_1234567890123456789

Untuk streaming MP4, peristiwa ini dikirim sebagai peristiwa emsg dalam band yang mengemulasi tag ID3 v2.3. Setiap kotak emsg yang relevan memiliki nilai scheme_id_uri berupa 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 prefiks ID3TXXX, adalah ID peristiwa iklan.

Contoh kotak emsg

Struktur data dapat bervariasi, bergantung pada library 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 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 sebagai MPEG_TS.

Memperbarui UI aplikasi pemutar video klien

Setiap ID peristiwa iklan dapat dicocokkan dengan kunci di objek tags dari langkah 4. Pencocokan nilai ini adalah proses dua langkah:

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

   Jika tidak ada kecocokan untuk ID peristiwa iklan lengkap, periksa objek tags untuk menemukan kunci yang cocok dengan 17 karakter pertama ID peristiwa iklan. Ambil jenis peristiwa dan objek ad dan ad_break terkait. Tindakan ini akan mengambil semua peristiwa dengan jenis selain progress.

2. Gunakan informasi yang diambil ini untuk memperbarui UI pemutar Anda. Misalnya, saat Anda menerima peristiwa start atau progress pertama, sembunyikan kontrol pencarian pemutar dan tampilkan overlay yang menjelaskan posisi iklan saat ini dalam 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"
  },
  ...
}

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 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 jenis progress tidak boleh dikirim ke Ad Manager. Peristiwa ini dimaksudkan untuk memberi tahu aplikasi pemutar video klien bahwa jeda iklan diputar dalam situasi saat peristiwa awal mungkin belum diterima. Misalnya, jika pengguna mencari posisi atau memulai pemutaran pada stempel waktu tertentu yang berada di tengah iklan, mereka tidak akan menerima peristiwa mulai. Peristiwa progres yang dikirim ke Ad Manager akan dihapus, yang dapat berdampak negatif pada performa aplikasi.

Contoh permintaan (cURL)

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

Contoh respons yang berhasil

HTTP/1.1 202 Accepted

Referensi lainnya

• Dokumentasi IMA SDK
• Perbandingan jenis penerapan pemutar DAI