Menggunakan integrasi kustom

Sebelum memulai

Dokumen ini hanya mencakup petunjuk pemutaran tanpa IMA DAI SDK.

Pastikan Anda telah menyelesaikan langkah-langkah dalam artikel Mengintegrasikan Google Ad Manager (GAM) dengan aset VOD sebelumnya.

Catatan: Sebaiknya gunakan IMA DAI SDK di platform yang mendukungnya.

Jika IMA SDK tidak tersedia untuk platform yang diinginkan, Anda harus meminta aplikasi untuk memanggil API yang diperlukan dan memicu verifikasi media 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 VOD	ID konfigurasi VOD yang Anda tentukan saat membuat peristiwa streaming VOD: VOD_CONFIG_ID

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 server manipulasi manifes dan endpoint Pod Serving API terkait.

Endpoint API

POST: /ondemand/pods/api/v1/network/NETWORK_CODE/stream_registration
Host: dai.google.com
Content-Type: application/json

Parameter jalur

NETWORK_CODE

Kode jaringan Google Ad Manager 360 Anda

Parameter isi yang dienkode JSON

targeting_parameters

Serangkaian parameter penargetan opsional yang dienkode JSON.

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
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/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

Contoh respons

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

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

Mengurai respons JSON dan menyimpan nilai yang relevan.

Tips: URL yang diberikan dalam respons API dapat berubah sewaktu-waktu tanpa pemberitahuan. Oleh karena itu, gunakan URL seperti yang diberikan dalam respons API, bukan membuatnya sendiri. Hal ini membantu memastikan bahwa kode Anda terus berfungsi dengan benar saat URL berubah.

Membuat sesi VOD Cloud Video Stitcher

Buat permintaan POST ke endpoint pendaftaran sesi VOD. Sebagai gantinya, Anda akan menerima respons JSON yang berisi URI manifes streaming dan metadata terkait jeda iklan, iklan, dan peristiwa iklan.

Endpoint API

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

Parameter jalur

PROJECT_NUMBER	Nomor project Google Cloud Anda.
LOCATION	Region Google Cloud Anda.
NETWORK CODE	Kode jaringan Google Ad Manager 360 Anda.

Parameter isi yang dienkode JSON

vodConfig	String yang berisi nomor project, lokasi, dan ID konfigurasi VOD dengan format berikut: projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking	Tetapkan ke "CLIENT" untuk mengaktifkan pelacakan sisi klien.
gamSettings	Objek yang berisi kode jaringan dan ID streaming dengan format berikut: { "networkCode":"NETWORK_CODE", "streamId":"STREAM_ID" }

Tanggapan JSON

name	Nama sesi VOD, yang berisi ID sesi.
playUri	URI manifes streaming yang digabungkan, untuk dimuat ke pemutar video Anda untuk diputar. SESSION_PLAYBACK_URI
adTracking	Nilai adTracking yang sama yang dikirim ke API dalam isi permintaan Anda.
vodConfig	String vodConfig 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/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

Contoh Respons

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

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

Meminta metadata pod iklan dari Ad Manager

Buat permintaan GET ke metadata_url yang Anda terima saat mendaftarkan streaming ke Ad Manager. Langkah ini harus dilakukan setelah Anda menerima manifes yang digabungkan dari URI pemutaran.

Selanjutnya, Anda akan menerima objek JSON yang menjelaskan jeda iklan, iklan, dan peristiwa iklan streaming.

Endpoint API

GET: METADATA_URL
Host: dai.google.com

Tanggapan JSON

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.

Contoh permintaan (cURL)

curl METADATA_URL

Contoh respons JSON

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

Simpan nilai ini untuk dikaitkan dengan peristiwa metadata berwaktu dalam streaming video Anda.

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, dengan menyimpan 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 diputar dengan membandingkan stempel waktu peristiwa ke playhead.
3. 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.
4. 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.
5. 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