Untuk mengaktifkan Video Stitcher API untuk project Anda, hubungi Account Representative atau hubungi Sales untuk mempelajari lebih lanjut.

Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan integrasi kustom

Sebelum memulai

Panduan ini hanya membahas petunjuk pemutaran tanpa IMA DAI SDK.

Pastikan Anda telah menyelesaikan langkah-langkah di artikel Mengintegrasikan Google Ad Manager (GAM) dengan live stream sebelumnya.

Jika IMA SDK tidak tersedia untuk platform yang diinginkan, Anda harus meminta aplikasi untuk memanggil API yang diperlukan dan memicu tayangan iklan itu sendiri.

Untuk melakukannya, Anda memerlukan informasi berikut:

Location	Region Google Cloud tempat konfigurasi live Anda dibuat: `LOCATION`
Nomor project	Nomor project project Google Cloud yang menggunakan Video Stitcher API: `PROJECT_NUMBER`
Token OAuth	Token OAuth berumur pendek akun layanan dengan peran pengguna Video Stitcher: `OAUTH_TOKEN` Baca selengkapnya tentang cara membuat token OAuth jangka pendek. Poin Penting: Token OAuth dapat digunakan kembali di beberapa permintaan selama belum habis masa berlakunya.
Kode jaringan	Kode jaringan Ad Manager untuk meminta iklan: `NETWORK_CODE`
ID konfigurasi live	ID konfigurasi live yang Anda tentukan saat membuat acara live stream: `LIVE_CONFIG_ID`
Kunci aset kustom	Kunci aset kustom Ad Manager yang dibuat selama proses membuat konfigurasi untuk peristiwa live stream dengan Video Stitcher API: `CUSTOM_ASSET_KEY`

Membuat permintaan pendaftaran streaming ke Ad Manager

Buat permintaan POST ke endpoint pendaftaran streaming. Sebagai gantinya, Anda akan menerima respons JSON yang berisi ID streaming untuk dikirim ke API penyambungan video.

Endpoint API

POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

Parameter jalur

`NETWORK_CODE`	Kode jaringan Google Ad Manager 360 Anda: `NETWORK_CODE`
`CUSTOM_ASSET_KEY`	ID kustom yang mengaitkan peristiwa ini di Google Ad Manager: `CUSTOM_ASSET_KEY`

Parameter isi yang dienkode formulir

Kumpulan opsional parameter penargetan yang dienkode dalam bentuk .

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. `MEDIA_VERIFICATION_URL`
`metadata_url`	URL untuk meminta metadata pod iklan. `METADATA_URL`
`polling_frequency`	frekuensi yang direkomendasikan dalam milidetik untuk melakukan polling `metadata_url`. `POLLING_FREQUENCY`
`stream_id`	String yang digunakan untuk mengidentifikasi sesi streaming saat ini. `STREAM_ID`
`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 \
     -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 isi respons JSON.

Mengurai respons JSON dan menyimpan nilai yang relevan.

Membuat URI pemutaran sesi

Buat permintaan POST ke endpoint /livesessions API penggabung video untuk membuat sesi live baru. Sebagai gantinya, Anda akan menerima respons JSON yang berisi manifes streaming untuk dimuat ke pemutar video.

Endpoint API

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Parameter jalur

`PROJECT_NUMBER`	Nomor project project Google Cloud yang menggunakan Video Stitcher API: `PROJECT_NUMBER`
`LOCATION`	Region Google Cloud tempat konfigurasi live Anda dibuat: `LOCATION`

Parameter header otorisasi

OAUTH_TOKEN

Token OAuth berumur pendek akun layanan dengan peran pengguna Video Stitcher:

OAUTH_TOKEN

Parameter isi yang dienkode JSON

`liveConfig`	String yang berisi nomor project, lokasi, dan ID konfigurasi live dengan format berikut: `projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID`
`adTracking`	Tetapkan ke `"CLIENT"` untuk mengaktifkan pelacakan sisi klien.
`gamSettings`	Objek yang berisi ID streaming dengan format berikut: `{"streamId":"STREAM_ID"}`

Tanggapan JSON

`name`	Nama sesi live, yang berisi ID sesi.
`playUri`	URI manifes streaming yang digabungkan, untuk dimuat ke pemutar video Anda untuk diputar. `PLAY_URI`
`liveConfig`	String `liveConfig` yang sama yang dikirim ke API dalam isi permintaan Anda.
`gamSettings`	Objek `gamSettings` yang sama yang dikirim ke API dalam isi permintaan Anda.

Contoh permintaan (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions

request.json

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "adTracking": "CLIENT",
  "gamSettings": {
    "streamId": "STREAM_ID"
  }
}

Contoh Respons

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": PLAY_URI,
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
  "gamSettings": {
    "streamId": STREAM_ID
  }
}

Setelah respons diterima, Anda dapat memutar live stream yang digabungkan dengan iklan dengan mereferensikan URI pemutaran sesi dari kolom playUri objek respons.

Video Stitcher API menghasilkan ID sesi unik untuk setiap permintaan, yang dapat diambil dari bagian terakhir kolom name objek respons.

Sesi tidak ada aktivitas akan berakhir setelah 5 menit. Sesi dianggap tidak ada aktivitas jika belum ada pengambilan manifes dalam jangka waktu tertentu.

Mengadakan polling untuk metadata AdBreak baru

Aplikasi bertanggung jawab untuk mengambil metadata untuk setiap jeda iklan, sehingga mengetahui tayangan iklan yang perlu dipicu. Untuk melakukannya, Anda akan menetapkan timer untuk melakukan polling secara berkala pada metadata_url DAI API untuk mendapatkan informasi iklan baru. Interval untuk polling ditentukan di kolom polling_frequency dalam respons pendaftaran streaming.

Sebagai gantinya, Anda akan menerima objek JSON yang berisi parameter berikut:

`tags`	Kumpulan key-value pair yang mendeskripsikan peristiwa media iklan yang akan terjadi dalam streaming. Setiap kunci terdiri dari 17 karakter pertama ID media iklan yang akan muncul di metadata ID3 streaming atau, dalam kasus peristiwa `progres`, seluruh ID media iklan. Setiap nilai adalah objek dengan properti berikut: `ad`: ID iklan yang berisi peristiwa media iklan. `ad_break_id`: ID jeda iklan yang berisi peristiwa media iklan. `type`: Jenis peristiwa media iklan. Nilainya adalah salah satu dari berikut: `start` - Iklan telah dimulai `firstquartile` - Iklan telah selesai 25%. `midpoint` - Iklan telah selesai 50%. `thirdquartile` - Iklan sudah selesai 75%. `complete` - Iklan telah berakhir. `progress` - diaktifkan setiap detik saat iklan diputar.
`ads`	Serangkaian pasangan nilai kunci yang mendeskripsikan iklan yang akan muncul dalam streaming. Setiap kunci adalah ID iklan. Setiap nilai adalah objek dengan properti berikut: `ad_break_id`: ID jeda iklan yang berisi peristiwa media iklan. `position`: posisi iklan dalam jeda iklan. Perhatikan bahwa iklan pertama dalam jeda memiliki posisi `1`. `duration`: durasi iklan dalam detik floating point. `title`: judul iklan, seperti yang ditentukan dalam VAST. `description`: deskripsi iklan, seperti yang ditentukan dalam VAST. `ad_system`: sistem iklan, seperti yang ditentukan dalam VAST. `ad_system`: ID iklan, seperti yang ditentukan dalam VAST. `ad_system`: ID materi iklan, seperti yang ditentukan dalam VAST. `clickthrough_url`: URL yang akan dibuka saat pengguna berinteraksi dengan iklan. `universal_ad_id`: objek yang mewakili ID iklan universal, seperti yang ditentukan dalam VAST.
`ad_breaks`	Kumpulan key-value pair yang mendeskripsikan jeda iklan yang akan terjadi dalam streaming. Setiap kunci adalah ID jeda iklan. Setiap nilai adalah objek dengan properti berikut: `type`: Jenis jeda iklan. Nilai akan berupa salah satu dari berikut: `pre`: Mewakili iklan pre-roll. `mid`: Mewakili iklan mid-roll. `post`: Mewakili iklan di akhir video. `duration`: Durasi jeda iklan dalam detik floating point. `expected_duration`: Durasi jeda iklan yang diharapkan dalam detik floating point. `ads`: Jumlah iklan yang terdapat dalam jeda iklan.

Simpan nilai ini setelah setiap polling untuk mengaitkan peristiwa metadata berwaktu dalam streaming video Anda.

Contoh permintaan (cURL)

curl https://dai.google.com/.../metadata/

Contoh 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/...",
         "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
      },
      ...
   }
}

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:

Simpan peristiwa media dalam antrean, dengan menyimpan setiap ID media beserta stempel waktunya, jika ditampilkan oleh pemutar.
Pada setiap pembaruan waktu dari pemutar atau pada frekuensi yang ditetapkan (direkomendasikan 500 md), periksa antrean peristiwa media untuk peristiwa yang baru diputar dengan membandingkan stempel waktu peristiwa ke playhead.
Untuk peristiwa media yang Anda konfirmasi telah diputar, periksa jenisnya dengan mencari ID media di tag jeda iklan yang disimpan. Perlu diingat bahwa objek tag jeda iklan hanya berisi versi ID media yang terpotong, yang dibatasi hingga 10 digit pertama setelah awalan google_, sehingga tidak ada kecocokan langsung antara ID verifikasi media ID3 dan kunci dalam objek tag. Hal ini untuk mencegah ping verifikasi peristiwa dikirim sebelum peristiwa ID3 tiba. Untuk membuat URL verifikasi media lengkap dari peristiwa iklan, tambahkan ID peristiwa iklan lengkap ke nilai media_verification_url dari respons pembuatan streaming.
Gunakan peristiwa "progress" untuk melacak apakah pengguna berada di dalam jeda iklan. Jangan kirim peristiwa ini ke endpoint verifikasi media untuk menghindari kode error HTTP. Untuk jenis peristiwa lainnya, tambahkan ID media ke URL verifikasi media dan buat permintaan GET untuk melacak pemutaran.
Hapus peristiwa media dari antrean.

Endpoint API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parameter jalur

`MEDIA_VERIFICATION_URL`	Nilai yang ditampilkan oleh endpoint pendaftaran streaming, di kolom `media_verification_url`: `MEDIA_VERIFICATION_URL`
`AD_MEDIA_ID`	ID media iklan lengkap, seperti yang muncul di metadata ID3 streaming: `AD_MEDIA_ID`

Nilai harapan pengembalian

`HTTP/1.1 204 No Content`	Respons kosong yang berhasil.
`HTTP/1.1 404 Not Found`	ID verifikasi media tidak dikenal.
`HTTP/1.1 409 Conflict`	ID verifikasi media telah dikirim.

Contoh permintaan (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Contoh respons

HTTP/1.1 204 No Content

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 fungsi fitur berikut:
- Pembatasan frekuensi
- Rotasi iklan berurutan
- Segmentasi dan penargetan audiens