Yayın Etkinliği İzleyicisi API'sini kullanma

Dinamik Reklam Ekleme (DAI) Akış Etkinliği İzleyicisi (SAM) API'si, canlı yayın ve seç-izle video (VOD) oturumlarınız için teşhis günlüklerini ve yayınlama sonuçlarını almanıza olanak tanır.

Bu kılavuzda, kimlik doğrulamanın nasıl yapılandırılacağı, üst düzey bir DaiSession kaynağının nasıl alınacağı ve oturumun alanlarında tanımlanan kaynakların nasıl isteneceğine dair bilgiler yer alır.

Ön koşullar

SAM API'yi kullanmak için aşağıdakilere ihtiyacınız vardır:

DaiSession kaynağı isteğinde bulunma

Bir DAI oturumunu incelemek için DAI oturum kimliği veya DAI akışı hata ayıklama anahtarı ile networks.daiSessions.get uç noktasına bir HTTP GET isteği gönderin.

Kimliğe göre DaiSession kaynağı alma

IMA DAI SDK'sı, tam hizmet DAI API'si veya kapsül yayınlama DAI API'sini kullanarak bir akış oturumu kaydettiğinizde Google DAI, bir DAI oturum kimliği döndürür.

Aşağıdaki örnekte, oturum kimliği kullanılarak bir DaiSession kaynağı alınmaktadır:

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

Aşağıdakini değiştirin:

  • NETWORK_CODE: Google Ad Manager ağ kodunuz
  • SESSION_ID: Akış oturumu oluşturulurken döndürülen DAI oturum kimliği
  • OAUTH_TOKEN: OAuth 2.0 erişim jetonunuz

DAI oturumu için hata ayıklama anahtarı kullanma

Bir akış oturumu kaydettiğinizde, kapsül sunma VOD isteklerinde dai-sam-id parametresini veya sam_id parametresini kullanarak özel bir hata ayıklama anahtarı atayabilirsiniz. Bu hata ayıklama anahtarını doğrudan DaiSession kaynak yolunda iletebilirsiniz.

Aşağıdaki örnekte, hata ayıklama anahtarı kullanılarak bir DaiSession kaynağı alınmaktadır:

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

DEBUG_KEY değerini, akış oluşturma isteğinizde belirtilen özel bir hata ayıklama anahtarıyla değiştirin.

Her iki istek de oturum bağlamını, reklam seçimlerini, karar verilen reklam kapsüllerini, reklam aralarını ve teşhis bulgularını içeren bir DaiSession JSON yanıtı döndürür. Çıkış şuna benzer:

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

Bir oturumu tanımladıktan sonra DaiSession kaynağındaki belirli oturum alanlarını sorgulayabilir, oturum bulgularından varlık anahtarlarında gezinebilir veya Ad Manager API'deki ilgili kaynaklara ek istekler gönderebilirsiniz.

Oturum alanlarını alan maskeleriyle filtreleme

Tam bir DaiSession yanıtı, ham VAST ve VMAP XML gövdelerini ve tüm geçmiş ara etkinliklerini içerir. Yük boyutunu azaltmak ve yalnızca ihtiyacınız olan oturum alanlarını getirmek için fields sorgu parametresinde veya X-Goog-FieldMask HTTP üstbilgisinde bir okuma maskesi iletin. Ayrıntılar için Alan Maskeleri başlıklı makaleyi inceleyin.

Bir oturumda hata olup olmadığını kontrol etmek için yalnızca oturum oluşturma bağlamını ve teşhis bulgularını isteyin:

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

adSelections alanındaki ham XML reklam yanıtlarını indirmeden yalnızca adBreaks ve adPods alanlarını almak için X-Goog-FieldMask başlığını kullanın:

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"

Oturum bulgularını inceleme

findings listesindeki her giriş, DaiSession kaynağındaki belirli bir varlığı işaret eden anahtara sahip, yazılı bir bulgu nesnesi içerir. Aşağıdaki tabloda, bulma anahtarlarının oturum alanlarına nasıl çözümleneceği gösterilmektedir:

Anahtar yolu bulunuyor DaiSession içindeki hedef konum
adBreakFinding.breakKey adBreaks[breakKey]
adRequestFinding.adSelectionKey, adRequestFinding.adRequestKey adSelections[adSelectionKey].adRequest ve iç içe yerleştirilmiş childRequests[]
creativeFinding.creativeKey adPods[podKey].creatives[creativeKey] içindeki girişlerde creativeKey ile eşleşiyor
podFinding.podKey adPods[podKey]
slateFinding slate
trackingFinding.trackingPingKey adBreaks[breakKey].trackingPings[trackingPingKey] içindeki girişlerde trackingPingKey ile eşleşiyor

Koleksiyonlar arasındaki ilişkileri izlemek için aşağıdakileri yapın:

  1. adBreaks dizisindeki bir girişten başlayın.
  2. adPods dizisindeki ilgili girişleri bulmak için podKeys listesini okuyun.
  3. adSelections dizisindeki eşleşen AdRequest.adRequestKey değerini bulmak için kapsüldeki adPod.adRequestKey alanını kullanın.
  4. Eşleşen adRequest nesnesinde veya iç içe yerleştirilmiş childRequests dizisinde kaynak HTTP isteğini ve VAST yanıtını inceleyin.

Canlı yayın ve içerik kaynaklarını isteme

DaiSession kaynağı, admanager.googleapis.com uç noktasındaki Google Ad Manager API'de livestream ve content kaynaklarına bağlanan kaynak adlarını içerir. Yayın yapılandırmasını ve içerik meta verilerini doğrulamak için şu kaynaklara HTTP GET istekleri gönderebilirsiniz:

Aşağıdaki örnekte, creationContext.linearInfo.liveStream alanında referans verilen bağlı LiveStream kaynağı alınmaktadır:

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

LIVE_STREAM_ID değerini DaiSession kaynağınızdaki canlı yayın kimliğiyle değiştirin.

Çıkış şuna benzer:

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