Untuk mengaktifkan Video Stitcher API untuk project Anda, hubungi Perwakilan Akun atau hubungi Penjualan untuk mempelajari lebih lanjut.

Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan integrasi kustom

Sebelum memulai

Panduan ini hanya mencakup petunjuk pemutaran jika IMA DAI SDK.

Pastikan Anda telah menyelesaikan langkah-langkah yang Mengintegrasikan Google Ad Manager (GAM) dengan live stream terlebih dahulu.

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

Untuk melakukannya, Anda memerlukan informasi berikut:

Location	Tujuan 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 akun layanan yang aktif singkat dengan pengguna Penggabung Video peran: `OAUTH_TOKEN` Baca selengkapnya tentang membuat token OAuth berumur pendek. Poin Penting: Token OAuth dapat digunakan kembali pada beberapa permintaan selama token masih berlaku.
Kode jaringan	Kode jaringan Ad Manager untuk meminta iklan: `NETWORK_CODE`
ID konfigurasi live	ID konfigurasi live yang Anda tentukan saat membuat acara livestream: `LIVE_CONFIG_ID`
Kunci aset kustom	Kunci aset kustom Ad Manager yang dibuat selama proses membuat konfigurasi untuk acara livestream dengan Video Stitcher API: `CUSTOM_ASSET_KEY`

Membuat permintaan pendaftaran streaming ke Ad Manager

Buat permintaan POST ke endpoint pendaftaran streaming. Sebagai imbalannya, Anda akan menerima respons JSON yang berisi ID streaming yang akan dikirim ke API penggabungan 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 terkait dengan peristiwa ini di Google Ad Manager: `CUSTOM_ASSET_KEY`

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

Membuat URI pemutaran sesi

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

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`	Tujuan Region Google Cloud tempat konfigurasi live Anda dibuat: `LOCATION`

Parameter header otorisasi

OAUTH_TOKEN

Token OAuth akun layanan yang berumur pendek dengan pengguna Penggabung Video peran:

OAUTH_TOKEN

Parameter isi yang dienkode JSON

`liveConfig`	String yang berisi nomor project, location, dan live config id 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 hal berikut format: `{"streamId":"STREAM_ID"}`

Tanggapan JSON

`name`	Nama sesi live, yang berisi ID sesi.
`playUri`	URI manifes streaming yang digabungkan, yang akan dimuat ke pemutar video Anda untuk pemutaran. `PLAY_URI`
`liveConfig`	String `liveConfig` yang sama dikirim ke API dalam permintaan Anda {i>body <i}itu.
`gamSettings`	Objek `gamSettings` yang sama dikirim ke API dalam permintaan Anda {i>body <i}itu.

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 merujuk ke URI pemutaran sesi dari kolom playUri pada 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 adalah dianggap tidak ada aktivitas jika tidak ada pengambilan manifes dalam jangka waktu baik.

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`	Serangkaian pasangan nilai kunci yang menjelaskan peristiwa media iklan yang akan terjadi dalam aliran data. Setiap kunci terdiri dari 17 karakter pertama dari ID media iklan yang akan muncul di metadata ID3 streaming atau, di kasus peristiwa `progress`, seluruh ID media iklan. Setiap nilai adalah dengan properti berikut: `ad`: ID iklan yang berisi peristiwa media iklan. `ad_break_id`: ID jeda iklan yang berisi iklan peristiwa media. `type`: Jenis peristiwa media iklan. Nilai merupakan salah satu berikut ini: `start` - Iklan telah dimulai `firstquartile` - Iklan telah 25% selesai. `midpoint` - Iklan telah 50% selesai. `thirdquartile` - Iklan telah 75% selesai. `complete` - Iklan telah berakhir. `progress` - diaktifkan setiap detik saat iklan diputar.
`ads`	Serangkaian pasangan nilai kunci yang mendeskripsikan iklan yang akan muncul dalam feed Anda. Setiap kunci adalah ID iklan. Setiap nilai adalah objek dengan properti: `ad_break_id`: ID jeda iklan yang berisi iklan peristiwa media. `position`: posisi iklan dalam jeda iklan. perhatikan bahwa iklan pertama dalam jeda memiliki posisi `1`. `duration`: durasi iklan dalam floating point detik. `title`: judul iklan, seperti yang didefinisikan dalam VAST. `description`: deskripsi iklan, seperti yang didefinisikan dalam VAST. `ad_system`: sistem iklan, seperti yang dijelaskan 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 elemen universal ID iklan, seperti yang ditentukan dalam VAST.
`ad_breaks`	Serangkaian pasangan nilai kunci yang menjelaskan jeda iklan yang akan terjadi dalam aliran data. Setiap kunci adalah ID jeda iklan. Setiap nilai adalah dengan properti berikut: `type`: Jenis jeda iklan. Nilai akan menjadi salah satu berikut ini: `pre`: Mewakili iklan pre-roll. `mid`: Mewakili iklan mid-roll. `post`: Mewakili iklan post-roll. `duration`: Durasi jeda iklan masuk detik floating point. `expected_duration`: Perkiraan durasi iklan dalam hitungan detik floating point. `ads`: Jumlah iklan yang ada dalam jeda iklan.

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_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 langkah-langkah untuk menangani peristiwa ID3:

Simpan peristiwa media dalam antrean, yang menyimpan setiap ID media beserta tanda waktu, jika ditampilkan oleh pemutar.
Pada setiap kali update dari pemutar atau pada frekuensi yang ditetapkan (500 md disarankan), periksa antrean peristiwa media untuk peristiwa yang baru diputar dengan membandingkan stempel waktu acara dengan titik pemutaran.
Untuk peristiwa media yang Anda konfirmasi telah diputar, periksa jenisnya dengan mencari ID media di tag jeda iklan yang disimpan. Perlu diingat bahwa tag jeda iklan hanya berisi versi ID media yang terpotong, yang terbatas pada 10 digit pertama setelah awalan google_, sehingga tidak ada kecocokan langsung antara ID verifikasi media ID3 dan kunci di objek tag. 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.
Menggunakan "progres" peristiwa untuk melacak apakah pengguna berada dalam jeda iklan. Jangan kirim peristiwa ini ke endpoint verifikasi media untuk menghindari permintaan HTTP pada kode error Anda. Untuk jenis peristiwa lainnya, tambahkan ID media ke media URL verifikasi 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 hasil yang diharapkan

`HTTP/1.1 204 No Content`	Respons kosong berhasil.
`HTTP/1.1 404 Not Found`	ID verifikasi media tidak dikenali.
`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 sesuai dengan ke penargetan:

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