Aplikasi pemutar video klien untuk streaming VOD

Google DAI Pod Serving API memungkinkan Anda melakukan penyisipan iklan sisi server yang didukung oleh Google Ads sambil tetap mengontrol 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 jika tersedia. Pod Serving API dimaksudkan untuk digunakan hanya pada platform yang tidak memiliki IMA DAI SDK.

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 Ad Manager

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: /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 penargetan iklan parameter. Wajib

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 \
     -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 respons JSON {i>body <i}itu.

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 diberikan dalam respons API, bukan membangunnya sendiri. Hal ini membantu memastikan 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. 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.

Meminta metadata pod iklan dari Ad Manager

Buat permintaan GET ke metadata_url yang Anda terima pada langkah pertama. Ini harus terjadi setelah Anda menerima manifes yang digabungkan dari manifes manipulator. Sebagai hasilnya, Anda akan menerima objek JSON yang berisi hal berikut parameter:

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: ad ID iklan yang cocok dengan kunci di objek ads. ad_break_id ID jeda iklan yang cocok dengan kunci di ad_breaks . type Jenis peristiwa iklan. Jenis peristiwa iklan adalah: start Diaktifkan di awal iklan. firstquartile Diaktifkan di akhir kuartil pertama. midpoint Diaktifkan pada bagian tengah iklan. thirdquartile Diaktifkan pada akhir kuartil ketiga. complete Diaktifkan pada akhir iklan. progress Diaktifkan secara berkala di sepanjang iklan, untuk memberi tahu aplikasi bahwa iklan waktu istirahat sedang diputar.
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_break_id ID jeda iklan yang cocok dengan kunci di ad_breaks . position Posisi tempat iklan ini tampil dalam kumpulan iklan di iklan jeda, 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	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: 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 dengan waktu dalam video Anda feed.

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:

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

   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 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, ketika Anda menerima start atau event progress pertama, sembunyikan pencari serta menampilkan 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 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.

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

Contoh permintaan (cURL)

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

Contoh respons yang berhasil

HTTP/1.1 202 Accepted

Referensi lainnya

• Dokumentasi IMA SDK
• Jenis penerapan pemutar DAI perbandingan