Menggunakan DAI Ad Break API

DAI Ad Break API memungkinkan Anda membuat, mengelola waktu, dan menargetkan data iklan untuk jeda iklan di livestream.

Panduan ini membahas penggunaan DAI Ad Break API untuk membuat, memperbarui, dan menghapus jeda iklan untuk acara livestream Penyisipan Iklan Dinamis (DAI) Google.

Prasyarat

Untuk menggunakan DAI Ad Break API, Anda memerlukan hal berikut:

  • Project Google Cloud dengan layanan admanagervideo.googleapis.com yang diaktifkan. Untuk mengetahui informasi selengkapnya, lihat Membuat project Cloud.
  • Jaringan Google Ad Manager dengan acara live stream DAI Google. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan livestream untuk DAI.

Menyiapkan akses API

Untuk mengaktifkan API, selesaikan langkah-langkah berikut:

  1. Membuat akun layanan. Untuk mengetahui informasi selengkapnya, lihat Membuat akun layanan.
  2. Tambahkan akun layanan ke jaringan Google Ad Manager Anda. Untuk mengetahui informasi selengkapnya, lihat Menambahkan pengguna akun layanan untuk akses API.
  3. Berikan alamat email akun layanan dan kode jaringan Google Ad Manager Anda kepada pengelola akun Google Anda.
  4. Aktifkan Google Ad Manager Video API di project Google Cloud Anda. Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan "API & Layanan" untuk aplikasi Anda.

Melakukan autentikasi dengan OAuth2

Untuk mengizinkan permintaan API Anda, lakukan langkah-langkah berikut:

  1. Buat token akses dengan cakupan https://www.googleapis.com/auth/video-ads.
  2. Di setiap permintaan, sertakan token akses ke API sebagai nilai header HTTP Authorization Bearer. Untuk mengetahui informasi selengkapnya, lihat Memanggil Google API.

Contoh berikut menghasilkan token OAuth dengan cakupan DAI Ad Break API:

gcloud auth print-access-token --scopes='https://www.googleapis.com/auth/video-ads'

Jika berhasil, Anda akan melihat token akses berikut:

ya29.c.c0ASRK0GYUYU0...

Buat permintaan pertama

Untuk mengambil jeda iklan untuk acara livestream, gunakan metode GET untuk mencantumkan semua entity AdBreak berdasarkan kunci aset yang dibuat sistem untuk acara tersebut, atau kunci aset kustom Anda.

DAI Ad Break API hanya menampilkan entitas AdBreak yang dibuat melalui API, tidak termasuk jeda iklan yang dibuat dari manifes, permintaan segmen pod, atau permintaan manifes pod.

Contoh permintaan berikut mencantumkan entity AdBreak berdasarkan nilai assetKey:

curl -X GET "https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN"

Jika berhasil, Anda akan melihat respons JSON berikut:

{
 "adBreaks": []
}

Saat Anda membuat entitas AdBreak tambahan melalui API dan meminta daftar, Anda akan melihat respons JSON berikut:

{
 "adBreaks": [
    {
      "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T15:00:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_SCHEDULED",
    },
    {
      "name": "networks/.../assets/.../adBreaks/cc68b0df-0257-46e7-8193-254060b6256c",
      "breakSequence": "1",
      "expectedDuration": "30s",
      "expectedStartTime": "2025-06-03T14:30:00Z",
      "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
      "customParams": "param1=value1&param2=value2",
      "podTemplateName": "podtemplate"
      "breakState": "BREAK_STATE_COMPLETE",
    },
    …
  ],
  "nextPageToken": "ChAIARIMCNDn97IGEJbhhYUC"
}

Membuat entity AdBreak

Untuk memberi tahu Google DAI tentang jeda iklan mendatang untuk acara livestream, gunakan metode POST.

  • Untuk membuat entity AdBreak baru, Anda harus menunggu entity sebelumnya bertransisi ke status BREAK_STATE_COMPLETE.
  • Atau, Anda dapat menghapus entity AdBreak yang tertunda untuk membuat yang baru.
  • Untuk membuat lebih dari satu entitas AdBreak untuk satu acara livestream, hubungi Account Manager Anda untuk konfigurasi lanjutan.

Contoh permintaan berikut membuat jeda iklan yang diharapkan dimulai pada 3 Juni 2025, pukul 15.00.00 UTC:

curl -X POST "https://admanagervideo.googleapis.com/v1/adBreak/networks/{NETWORK_CODE}/assets/ASSET_KEY/adBreaks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer OAUTH_TOKEN" \
  -d '{
    "expectedDuration": "30s",
    "expectedStartTime": "2025-06-03T15:00:00Z",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
  }'

Jika berhasil, Anda akan melihat respons JSON berikut:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",  "expectedStartTime": "2025-06-03T15:00:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Hasilnya berisi ID jeda iklan yang diperlukan untuk mengambil, mengubah, atau menghapus jeda iklan. Dalam contoh respons, ID jeda iklan yang dibuat adalah bcc402a6-9880-4b8b-8e4a-a8cd3688f854.

Mengambil entity AdBreak

Gunakan metode GET untuk mengambil detail entity AdBreak tertentu, termasuk metadata waktu dan status jeda iklan.

curl -X GET \
'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

Jika berhasil, Anda akan melihat respons JSON berikut:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Memperbarui entity AdBreak

Untuk mengubah jeda iklan mendatang sebelum keputusan iklan dimulai, gunakan metode PATCH:

curl -X PATCH 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer OAUTH_TOKEN' \
  -d '{"expectedStartTime": "2025-06-03T15:10:00Z"}'

Jika berhasil, Anda akan melihat respons JSON berikut:

{
  "name": "networks/.../assets/.../adBreaks/bcc402a6-9880-4b8b-8e4a-a8cd3688f854",
  "expectedDuration": "30s",
  "expectedStartTime": "2025-06-03T15:10:00Z",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
  "breakState": "BREAK_STATE_SCHEDULED",
}

Menghapus entity AdBreak

Gunakan metode DELETE untuk membatalkan keputusan iklan untuk jeda iklan yang dibuat melalui API sebelum jeda iklan mulai ditayangkan.

Contoh permintaan berikut menghapus jeda iklan:

curl -X DELETE 'https://admanagervideo.googleapis.com/v1/adBreak/networks/NETWORK_CODE/assets/ASSET_KEY/adBreaks/AD_BREAK_ID' \
  -H 'Authorization: Bearer OAUTH_TOKEN'

Jika berhasil, Anda akan melihat respons HTTP/1.1 200 OK.

Mempelajari fitur jeda iklan lanjutan

Setelah membuat dan mengelola jeda iklan, pelajari fitur-fitur API Jeda Iklan DAI berikut: