Aplikasi pemutar video klien untuk live stream

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:

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 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:

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

Referensi lainnya