Menggunakan API Pemantauan Aktivitas Streaming

Dengan API Pemantauan Aktivitas Streaming (SAM) Penyisipan Iklan Dinamis (DAI), Anda dapat mengambil log diagnostik dan hasil penayangan untuk sesi livestream dan video on demand (VOD).

Panduan ini membahas cara mengonfigurasi autentikasi, mengambil resource DaiSession level teratas, dan meminta resource yang diidentifikasi dalam kolom sesi.

Prasyarat

Untuk menggunakan SAM API, Anda memerlukan hal berikut:

Meminta resource DaiSession

Untuk memeriksa sesi DAI, kirim permintaan GET HTTP ke endpoint networks.daiSessions.get dengan ID sesi DAI atau kunci debug streaming DAI.

Mengambil resource DaiSession berdasarkan ID

Saat Anda mendaftarkan sesi streaming menggunakan IMA DAI SDK, DAI API layanan lengkap, atau DAI API penayangan Pod, DAI Google akan menampilkan ID sesi DAI.

Contoh berikut mengambil resource DaiSession menggunakan ID sesi:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Ganti kode berikut:

  • NETWORK_CODE: kode jaringan Google Ad Manager Anda
  • SESSION_ID: ID sesi DAI yang ditampilkan saat membuat sesi streaming
  • OAUTH_TOKEN: token akses OAuth 2.0 Anda

Menggunakan kunci debug untuk sesi DAI

Saat mendaftarkan sesi streaming, Anda dapat menetapkan kunci debug kustom menggunakan parameter dai-sam-id atau parameter sam_id dalam permintaan VOD penayangan Pod. Anda dapat meneruskan kunci debug ini langsung di jalur resource DaiSession.

Contoh berikut mengambil resource DaiSession menggunakan kunci debug:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/DEBUG_KEY" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Ganti DEBUG_KEY dengan kunci debug kustom yang ditentukan dalam permintaan pembuatan streaming Anda.

Kedua permintaan menampilkan respons JSON DaiSession yang berisi konteks sesi, pilihan iklan, pod iklan yang diputuskan, jeda iklan, dan temuan diagnostik. Outputnya mirip dengan hal berikut ini:

{
  "name": "networks/21775744923/daiSessions/9587e2c1-d745-4bf1-9f6a-e9092127cb48:ATL",
  "creationContext": {
    "streamCreateRequest": {
      "requestTime": "2026-10-16T19:59:57.365124Z",
      "latency": "0.045s",
      "url": "/ssai/event/c-rArva4ShKVIAkNfy6HUQ/streams",
      "userAgent": "Mozilla/5.0",
      "responseCode": 201
    },
    "linearInfo": {
      "liveStream": "networks/21775744923/liveStreams/20000016294786",
      "assetKey": "c-rArva4ShKVIAkNfy6HUQ",
      "prefetchEnabled": false,
      "podTrimmingEnabled": true,
      "podTrimTolerance": "2s",
      "eventStartTime": "2020-06-09T20:00:00Z",
      "eventEndTime": "2037-01-01T08:00:00Z"
    },
    "debugKey": "my-custom-debug-key-001",
    "contentTitle": "IMA sample HLS live stream",
    "stitchingType": "STITCHED",
    "reportingType": "CLIENT",
    "interstitialEnabled": false
  },
  "slate": {
    "idType": "CREATIVE_ID",
    "idValue": "138544327419",
    "adSystem": "GDFP",
    "duration": "10s"
  },
  "adSelections": {
    "2021043961286562353": {
      "type": "VAST",
      "adRequest": {
        "adRequestKey": "2021043961286562353",
        "adTag": "https://pubads.g.doubleclick.net/gampad/live/ads?iu=/21775744923/external/vmap_ads_for_dai&cust_params=sample_ar%3Dstreammidonly&output=xml_vast4&pmxd=30000",
        "httpRequest": {
          "requestTime": "2026-10-16T19:59:57.177283526Z",
          "latency": "0.138s",
          "url": "https://pubads.g.doubleclick.net/gampad/live/ads?iu=/21775744923/external/vmap_ads_for_dai&cust_params=sample_ar%3Dstreammidonly&output=xml_vast4&pmxd=30000",
          "responseCode": 200,
          "responseBody": "<VAST version=\"4.0\"><Ad id=\"5937252921\" sequence=\"1\"><InLine><AdSystem>GDFP</AdSystem><AdTitle>External - Pod Midroll 1</AdTitle><Creatives><Creative id=\"138383221557\" sequence=\"1\"><Linear><Duration>00:00:10</Duration></Linear></Creative></Creatives></InLine></Ad></VAST>"
        },
        "childRequests": []
      }
    }
  },
  "adPods": {
    "9204525715521575580": {
      "requestedBreakType": "MIDROLL",
      "adRequestKey": "2021043961286562353",
      "prefetchStage": "DISABLED",
      "adBreakId": "-3821178632466845617",
      "label": "3196133",
      "creatives": {
        "6086226973783046639": {
          "idType": "GOOGLE_VIDEO_REGISTRY_ID",
          "idValue": "tVFdo4-fFVE",
          "adSystem": "GDFP",
          "duration": "10.010s",
          "podSequence": 1,
          "adBuffet": false,
          "vastInfos": [
            {
              "adSystem": "GDFP",
              "adTitle": "External - Pod Midroll 1",
              "creativeId": "138383221557"
            }
          ]
        }
      }
    }
  },
  "adBreaks": {
    "-3821178632466845617": {
      "podKeys": [
        "9204525715521575580"
      ],
      "adBreakId": "-3821178632466845617",
      "breakType": "MIDROLL",
      "breakSequence": "3196133",
      "servedAdsDuration": "30.999999999s",
      "executedBreakDuration": "30.999999999s",
      "linear": {
        "breakStartTime": "2026-10-16T20:22:28.130329Z",
        "expectedBreakDuration": "31s",
        "slateDuration": "0s",
        "underlyingDuration": "0s"
      },
      "trackingPings": {
        "3641994172850159057": {
          "originalTrackingEventId": "google_4445276280058090123",
          "request": {
            "requestTime": "2026-10-16T20:22:29.393993Z",
            "latency": "0.030s",
            "url": "https://dai.google.com/view/p/service/linear/impression/stream/1dccd632-5028-45be-a68a-6c90645cd237:ATL/network/21775744923/event/xDte1UxoSxmtRrB6lqHdmg/media/7083951761/stream_ad_id/EfzeSEQzFPU",
            "responseCode": 200
          }
        }
      }
    }
  },
  "findings": [
    {
      "severity": "INFO",
      "description": "Minimum slate inserted into underfilled ad break.",
      "slateFinding": {
        "type": "SLATE_STATUS_MINIMUM_INSERTED"
      }
    },
    {
      "severity": "INFO",
      "description": "Ad break was decisioned, but not served during playback.",
      "adBreakFinding": {
        "type": "UNSERVED_BREAK",
        "breakKey": "-3821178632466845617"
      }
    }
  ],
  "sessionDuration": "31.453022s"
}

Setelah mengidentifikasi sesi, Anda dapat mengkueri kolom sesi tertentu di resource DaiSession, menavigasi kunci entity dari temuan sesi, atau membuat permintaan lanjutan ke referensi terkait di Ad Manager API.

Memfilter kolom sesi dengan mask kolom

Respons DaiSession lengkap mencakup isi XML VAST dan VMAP mentah serta semua peristiwa jeda historis. Untuk mengurangi ukuran payload dan hanya mengambil kolom sesi yang Anda perlukan, teruskan mask baca di parameter kueri fields atau header HTTP X-Goog-FieldMask. Untuk mengetahui detailnya, lihat Masker Kolom.

Untuk memeriksa apakah sesi mengalami error, minta hanya konteks pembuatan sesi dan temuan diagnostik:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID?fields=name,creationContext,findings" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Untuk hanya mengambil kolom adBreaks dan adPods tanpa mendownload respons iklan XML mentah di kolom adSelections, gunakan header X-Goog-FieldMask:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/daiSessions/SESSION_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN" \
    -H "X-Goog-FieldMask: name,adBreaks,adPods"

Memeriksa temuan sesi

Setiap entri dalam daftar findings menyertakan objek temuan yang diketik dengan kunci yang mengarah ke entity tertentu dalam resource DaiSession. Tabel berikut menunjukkan cara me-resolve kunci temuan ke kolom sesi:

Menemukan jalur kunci Lokasi target di DaiSession
adBreakFinding.breakKey adBreaks[breakKey]
adRequestFinding.adSelectionKey, adRequestFinding.adRequestKey adSelections[adSelectionKey].adRequest dan childRequests[] bertingkat
creativeFinding.creativeKey Cocokkan creativeKey di seluruh entri di adPods[podKey].creatives[creativeKey]
podFinding.podKey adPods[podKey]
slateFinding slate
trackingFinding.trackingPingKey Cocokkan trackingPingKey di seluruh entri di adBreaks[breakKey].trackingPings[trackingPingKey]

Untuk melacak hubungan di seluruh koleksi, lakukan hal berikut:

  1. Mulai dari entri dalam array adBreaks.
  2. Baca daftar podKeys untuk menemukan entri yang sesuai dalam array adPods.
  3. Gunakan kolom adPod.adRequestKey pada pod untuk menemukan AdRequest.adRequestKey yang cocok dalam array adSelections.
  4. Periksa permintaan HTTP asal dan respons VAST di objek adRequest yang cocok atau array childRequests bertingkatnya.

Meminta resource konten dan livestream

Resource DaiSession berisi nama resource yang ditautkan ke resource livestream dan konten di Google Ad Manager API pada endpoint admanager.googleapis.com. Untuk memverifikasi konfigurasi streaming dan metadata konten, Anda dapat membuat permintaan GET HTTP ke resource berikut:

Contoh berikut mengambil resource LiveStream tertaut yang direferensikan di kolom creationContext.linearInfo.liveStream:

curl -X GET \
    "https://admanager.googleapis.com/v1/networks/NETWORK_CODE/liveStreams/LIVE_STREAM_ID" \
    -H "Authorization: Bearer OAUTH_TOKEN"

Ganti LIVE_STREAM_ID dengan ID livestream di resource DaiSession Anda.

Outputnya mirip dengan hal berikut ini:

{
  "name": "networks/21775744923/liveStreams/20000016294786",
  "displayName": "IMA sample HLS live stream",
  "status": "ACTIVE",
  "createTime": "2020-06-09T20:00:07Z",
  "updateTime": "2026-08-18T15:37:05Z",
  "startTime": "2020-06-09T20:00:00Z",
  "endTime": "2037-01-01T08:00:00Z",
  "endTimeUnlimited": true,
  "contentUrls": [
    "https://contentsim.sandbox.google.com/content/590f95c5-c3ee-4a56-a10c-0cc660e91faa/linear/multivariant.m3u8"
  ],
  "adTags": [
    "https://pubads.g.doubleclick.net/gampad/live/ads?sz=640x480&output=xml_vast3&iu=/21775744923/external/vmap_ads_for_dai&env=vp&impl=s&gdfp_req=1&unviewed_position_start=1&ad_rule=0&cust_params=sample_ar%3Dstreammidonly&lseco=%%ASSET_KEY%%"
  ],
  "assetKey": "c-rArva4ShKVIAkNfy6HUQ",
  "slate": "networks/21775744923/slates/138544327419",
  "enableDaiAuthenticationKeys": false,
  "adBreakFillType": "SLATE",
  "underfillAdBreakFillType": "SLATE",
  "adHolidayDuration": "0s",
  "enableMaxFillerDuration": false,
  "enableDurationlessAdBreaks": false,
  "hlsSettings": {
    "playlistType": "LIVE",
    "masterPlaylistSettings": {
      "refreshType": "AUTOMATIC"
    }
  },
  "allowlistedIpsEnabled": false,
  "dynamicAdInsertionType": "LINEAR",
  "relativePlaylistDeliveryEnabled": false,
  "streamingFormat": "HLS",
  "prefetchEnabled": false,
  "forcedCueInEnabled": false,
  "shortSegmentDroppingEnabled": false,
  "adBreakMarkupTypesEnabled": false,
  "earlyBreakNotificationMultiBreakSchedulingEnabled": false,
  "dvrWindowDuration": "60s"
}