Mengelola live stream DAI

Google DAI API memungkinkan Anda menerapkan streaming yang kompatibel dengan Google DAI di lingkungan yang tidak mendukung penerapan IMA SDK. Sebaiknya Anda tetap menggunakan IMA di platform yang mendukung IMA SDK.

Sebaiknya gunakan DAI API di platform berikut:

  • Samsung Smart TV (Tizen)
  • LG TV
  • HbbTV
  • Xbox (aplikasi JavaScript)
  • KaiOS

API ini mendukung kemampuan dasar yang disediakan oleh IMA DAI SDK. Untuk pertanyaan khusus tentang kompatibilitas atau fitur yang didukung, hubungi Account Manager Google Anda.

Menerapkan DAI API untuk LIVE stream

DAI API mendukung streaming linear (LIVE) menggunakan protokol HLS dan DASH. Langkah-langkah yang dijelaskan dalam panduan ini berlaku untuk kedua protokol.

Untuk mengintegrasikan API ke dalam aplikasi Anda untuk streaming LIVE, selesaikan langkah-langkah berikut:

1. Meminta streaming

Untuk meminta livestream dari DAI API, lakukan panggilan POST ke endpoint streaming. Respons JSON berisi manifes streaming serta endpoint dan nilai DAI API terkait.

Contoh isi permintaan

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Contoh isi respons

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Respons error

Jika terjadi error, kode error HTTP standar akan ditampilkan tanpa isi respons JSON.

Parse respons JSON dan simpan nilai berikut:

stream_id
Nilai ini dapat digunakan untuk mengidentifikasi stream yang ditampilkan.
stream_manifest
URL ini diteruskan ke media player Anda untuk pemutaran streaming.
media_verification_url
URL ini adalah endpoint dasar untuk melacak peristiwa pemutaran.
metadata_url
URL ini digunakan untuk melakukan polling informasi berkala tentang acara streaming mendatang.
session_update_url
URL ini digunakan untuk memperbarui parameter permintaan streaming yang dikirim selama permintaan streaming awal. Perhatikan bahwa parameter permintaan ini menggantikan semua parameter yang ditetapkan untuk aliran sebelumnya.
polling_frequency
Frekuensi, dalam detik, saat meminta Metadata AdBreak yang diperbarui dari DAI API.

2. Polling untuk Metadata AdBreak baru

Setel timer untuk melakukan polling Metadata Istirahat Iklan baru pada frekuensi polling, menggunakan URL metadata. Jika tidak ditentukan dalam respons streaming, interval default yang direkomendasikan adalah 10 detik.

Untuk mengoptimalkan bandwidth, lakukan hal berikut:

  1. Buat permintaan GET awal ke endpoint metadata_url.
    • Hilangkan parameter kueri delta_token. Proses ini memungkinkan server menampilkan metadata lengkap untuk jendela Perekam Video Digital (DVR) streaming. Jendela DVR berisi jangka waktu siaran yang tersedia bagi penonton untuk memutar ulang dan memutar. Respons mencakup kolom objek next_delta_token.
  2. Menyimpan metadata di sisi klien.
  3. Lakukan panggilan berikutnya menggunakan nilai next_delta_token yang ditampilkan oleh respons terbaru. Setiap respons berisi nilai next_delta_token. Selalu kirim nilai terbaru yang Anda terima.
  4. Perbarui metadata yang disimpan untuk menggabungkan perubahan dan menghapus jeda iklan yang sudah tidak digunakan.

Jangan mencoba mengurai, membuat, atau mengubah token delta. Format token dapat berubah. Simpan token yang diterima, dan teruskan token tersebut tanpa perubahan dalam permintaan berikutnya.

Contoh permintaan awal

Permintaan awal tidak menggunakan parameter kueri dan menampilkan metadata lengkap:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Contoh permintaan berikutnya

Setiap permintaan berikutnya akan meneruskan nilai next_delta_token dari respons sebelumnya sebagai parameter delta_token. Responsnya berisi berikut ini:

  • Iklan
  • Jeda iklan
  • Tag yang ditambahkan atau diperbarui oleh server sejak server menerbitkan token.
  • Daftar jeda iklan obsolete_ad_break_ids yang akan dihapus dari metadata tersimpan Anda

Server menghilangkan jeda iklan yang tidak berubah. Contoh berikut menunjukkan polling berikutnya menggunakan token delta untuk mengambil hanya perubahan terbaru ini:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Jika berhasil, Anda akan melihat output yang mirip dengan berikut ini:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. Memproses peristiwa ID3 dan melacak peristiwa pemutaran

Untuk memverifikasi bahwa peristiwa tertentu telah terjadi dalam streaming video, ikuti langkah-langkah berikut untuk menangani peristiwa ID3:

  1. Simpan peristiwa media dalam antrean, simpan setiap ID media beserta stempel waktunya (jika ditampilkan oleh pemutar).
  2. Pada setiap pembaruan waktu dari pemutar, atau pada frekuensi yang ditetapkan (direkomendasikan 500 md), periksa antrean peristiwa media untuk peristiwa yang baru saja diputar dengan membandingkan stempel waktu peristiwa dengan penunjuk putar.
  3. Untuk peristiwa media yang Anda konfirmasi telah diputar, periksa jenisnya dengan mencari ID media di tag jeda iklan yang disimpan. Perlu diingat bahwa tag yang disimpan hanya berisi awalan ID media sehingga kecocokan yang tepat tidak mungkin terjadi.
  4. Karena aplikasi pemutar video Anda melakukan polling URL metadata secara berkala, penundaan mungkin terjadi antara saat pemutar video Anda menemukan tag ID3 dalam streaming dan saat metadata terkait tersedia. Jika tag ID3 tidak ditemukan di tag yang disimpan, simpan tag dalam antrean dan proses ulang tag setelah polling metadata berikutnya. Simpan acara dalam antrean hingga pemrosesan selesai.
  5. Setelah menemukan tag di metadata, periksa kolom type tag terhadap jenis peristiwa iklan yang tercantum di bagian berikut. Untuk melacak apakah pemutar video sedang memutar jeda iklan, gunakan peristiwa dengan nilai progress dari kolom type. Jangan mengirim peristiwa ini ke endpoint verifikasi media. Untuk semua jenis peristiwa lainnya, tambahkan ID media ke endpoint verifikasi media dan buat permintaan GET untuk melacak pemutaran.
  6. Hapus acara media dari antrean.

Jenis peristiwa iklan

Setiap tag dalam objek metadata tags memiliki salah satu jenis peristiwa berikut:

Jenis peristiwa Deskripsi
start Berjalan di awal iklan.
firstquartile Berjalan di akhir kuartil pertama iklan.
midpoint Berjalan di titik tengah iklan.
thirdquartile Berjalan di akhir kuartil ketiga iklan.
complete Berjalan di akhir iklan.
progress Berjalan secara berkala selama jeda iklan, untuk memberi sinyal bahwa jeda iklan sedang diputar. Jangan mengirim peristiwa ini ke endpoint verifikasi media.

Contoh permintaan

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Contoh respons

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Anda dapat memverifikasi peristiwa pelacakan di Pemantau Aktivitas Streaming.

4. Memperbarui parameter sesi livestream

Anda mungkin ingin menyesuaikan parameter sesi setelah streaming dibuat. Untuk melakukannya, buat permintaan ke URL pembaruan sesi.

Contoh isi permintaan

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Contoh isi respons

Successful response would be to look for - HTTP/1.1 200

Batasan

Jika menggunakan API dalam tampilan web, batasan berikut berlaku sehubungan dengan penargetan:

  • UserAgent: Parameter agen pengguna diteruskan sebagai nilai khusus browser, bukan platform yang mendasarinya.
  • rdid, idtype, is_lat: ID perangkat tidak diteruskan dengan benar, sehingga membatasi kemampuan fitur berikut:
    • Pembatasan frekuensi
    • Rotasi iklan berurutan
    • Segmentasi dan penargetan audiens

Praktik terbaik

Perlu diingat bahwa endpoint metadata untuk indeks livestream didasarkan pada awalan tag ID3 yang sesuai. Hal ini dilakukan untuk mencegah penggunaan endpoint metadata untuk langsung melakukan ping ke semua node verifikasi.

Referensi lainnya