Menggunakan integrasi kustom

Sebelum memulai

Dokumen ini hanya mencakup petunjuk pemutaran jika tidak ada IMA DAI SDK.

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

Catatan: Kami sangat menyarankan Anda menggunakan IMA DAI SDK di platform tempatnya didukung.

Jika IMA SDK tidak tersedia untuk platform yang diinginkan, Anda memerlukan aplikasi untuk memanggil API yang diperlukan dan memicu verifikasi media 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 berumur pendek dengan pengguna Penggabung Video peran: OAUTH_TOKEN Baca selengkapnya tentang membuat token OAuth berumur pendek. Poin Penting: Token OAuth dapat digunakan kembali di beberapa permintaan selama token masih berlaku.
Kode jaringan	Kode jaringan Ad Manager untuk meminta iklan: NETWORK_CODE
ID konfigurasi VOD	ID konfigurasi VOD yang Anda tentukan saat membuat acara streaming vod: VOD_CONFIG_ID

Membuat permintaan pendaftaran streaming ke Ad Manager

Buat permintaan POST ke endpoint pendaftaran streaming. Sebagai imbalannya, Anda akan menerima respons JSON yang berisi ID aliran data yang akan dikirim ke manipulasi manifes Anda server 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 opsional yang dienkode dengan json 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
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/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 respons JSON {i>body <i}itu.

Mengurai respons JSON dan menyimpan nilai yang relevan.

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

Membuat sesi VOD Cloud Video Stitcher

Buat permintaan POST ke endpoint pendaftaran sesi VOD. Sebagai imbalannya, Anda menerima respons JSON yang berisi URI manifes streaming dan metadata mengenai 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, location, dan VOD config id 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 stream id 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, yang akan dimuat ke pemutar video Anda untuk pemutaran. SESSION_PLAYBACK_URI
adTracking	Nilai adTracking yang sama dikirimkan ke API dalam permintaan Anda {i>body <i}itu.
vodConfig	String vodConfig 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/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 merujuk ke URI dari kolom playUri objek respons.

Meminta metadata pod iklan dari Ad Manager

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

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

Endpoint API

GET: METADATA_URL
Host: dai.google.com

Tanggapan JSON

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.

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 dengan waktu dalam video Anda feed Anda.

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:

1. Simpan peristiwa media dalam antrean, yang menyimpan setiap ID media beserta tanda waktu, jika ditampilkan oleh pemutar.
2. 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.
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 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.
4. 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.
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 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