API Penyisipan Iklan Dinamis untuk streaming LIVE

Google DAI API memungkinkan Anda menerapkan streaming dengan DAI Google di lingkungan yang tidak mendukung implementasi IMA SDK. Sebaiknya tetap gunakan IMA di platform yang mendukung IMA SDK.

Sebaiknya gunakan DAI API di platform berikut:

  • Smart TV Samsung (Tizen)
  • TV LG
  • 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 aplikasi Anda untuk LIVE stream, 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":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

Respons error

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

Uraikan respons JSON dan simpan nilai berikut:

stream_id
Nilai ini dapat digunakan untuk mengidentifikasi aliran data yang ditampilkan.
stream_manifest
URL ini diteruskan ke pemutar media Anda untuk pemutaran streaming.
media_verification_url
URL ini adalah endpoint dasar untuk melacak peristiwa pemutaran.
metadata_url
URL ini digunakan untuk melakukan polling tentang informasi berkala tentang acara streaming mendatang.
session_update_url
URL ini digunakan untuk memperbarui parameter permintaan streaming yang dikirim selama permintaan streaming awal. Perlu diperhatikan bahwa parameter permintaan ini menggantikan semua parameter yang ditetapkan untuk streaming 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 AdBreak baru pada frekuensi polling, menggunakan URL metadata. Jika tidak ditentukan dalam respons streaming, interval yang direkomendasikan default adalah 10 detik.

Contoh isi permintaan

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

Contoh isi respons

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

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 kali update dari pemutar, atau pada frekuensi yang ditetapkan (direkomendasikan 500 milidetik), periksa antrean peristiwa media untuk peristiwa yang baru diputar dengan membandingkan stempel waktu peristiwa dengan titik pemutaran.
  3. Untuk peristiwa media yang Anda konfirmasi telah diputar, periksa jenisnya dengan mencari ID media di tag jeda iklan yang tersimpan. Perlu diingat bahwa tag yang disimpan hanya berisi awalan ID media sehingga tidak ada pencocokan persis.
  4. Gunakan peristiwa "progres" untuk melacak apakah pengguna berada dalam jeda iklan atau tidak. Jangan kirim peristiwa ini ke endpoint verifikasi media. Untuk jenis peristiwa lainnya, tambahkan ID media ke endpoint verifikasi media dan buat permintaan GET untuk melacak pemutaran.
  5. Hapus peristiwa media dari antrean.

Contoh isi permintaan

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

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 Pemantauan Aktivitas Streaming.

4. Memperbarui parameter sesi livestream

Sebaiknya sesuaikan parameter sesi Anda setelah streaming dibuat. Untuk melakukannya, buat permintaan ke URL pembaruan sesi.

Contoh isi permintaan

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/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 webview, 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, yang 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 sengaja dilakukan untuk mencegah penggunaan endpoint metadata untuk langsung melakukan ping ke semua node verifikasi.

Referensi lainnya