Dinamik Reklam Ekleme Doğrusal API'si

Dinamik Reklam Ekleme API'si, DAI doğrusal (CANLI) yayınlarını istemenize ve izlemenize olanak tanır.

Hizmet: dai.google.com

Tüm URI'ler https://dai.google.com ile ilgilidir.

Yöntem: stream

Yöntemler
stream POST /linear/v1/hls/event/{assetKey}/stream

Belirtilen etkinlik kimliği için bir DAI akışı oluşturur.

HTTP isteği

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

İstek başlığı

Parametreler
api‑key string

Akış oluşturulurken sağlanan API anahtarı, yayıncının ağı için geçerli olmalıdır.

API anahtarı, istek gövdesinde sağlanmak yerine aşağıdaki biçimde HTTP Yetkilendirme üstbilgisinde iletilebilir:

Authorization: DCLKDAI key="<api-key>"

Yol parametreleri

Parametreler
assetKey string

Akışın etkinlik kimliği.
Not: Yayın öğesi anahtarı, Ad Manager kullanıcı arayüzünde de bulunabilen bir tanımlayıcıdır.

İstek metni

İstek gövdesi application/x-www-form-urlencoded türündedir ve aşağıdaki parametreleri içerir:

Parametreler
dai-ssb İsteğe bağlı

Sunucu tarafı işaret akışı oluşturmak için true olarak ayarlayın. Varsayılan olarak false değerine ayarlanır. Varsayılan akışın izlemesi, istemci tarafından başlatılır ve sunucu tarafında ping işlemi yapılır.
DFP Hedefleme Parametreleri İsteğe bağlı Ek hedefleme parametreleri.
Akış parametrelerini geçersiz kılma İsteğe bağlı Akış oluşturma parametresinin varsayılan değerlerini geçersiz kılma.
HMAC Kimlik Doğrulaması İsteğe bağlı HMAC tabanlı bir jeton kullanarak kimlik doğrulama.

Yanıt metni

Başarılı olursa yanıt gövdesi yeni bir Stream içerir. Sunucu tarafı sinyal gönderimi yapılan yayınlarda bu Stream yalnızca stream_id ve stream_manifest alanlarını içerir.

Open Measurement

DAI API'si, Verifications alanında Open Measurement doğrulamasıyla ilgili bilgiler içerir. Bu alan, reklam öğesi oynatmayı doğrulamak için üçüncü taraf ölçüm kodunu yürütmek üzere gereken kaynakları ve meta verileri listeleyen bir veya daha fazla Verification öğesi içerir. Yalnızca JavaScriptResource desteklenir. Daha fazla bilgi için IAB Tech Lab ve VAST 4.1 spesifikasyonunu inceleyin.

Yöntem: medya doğrulaması

Oynatma sırasında bir reklam medyası tanımlayıcısıyla karşılaştıktan sonra stream uç noktasından alınan media_verification_url kullanılarak hemen bir istekte bulunun. Bu istekler, sunucunun medya doğrulaması başlattığı sunucu tarafı sinyal akışları için gerekli değildir.

media verification uç noktasına yapılan istekler idempotent'tır.

Yöntemler
media verification GET /{media_verification_url}/{ad_media_id}

API'yi bir medya doğrulama etkinliği hakkında bilgilendirir.

HTTP isteği

GET https://{media-verification-url}/{ad-media-id}

Yanıt metni

media verification aşağıdaki yanıtları döndürür:

  • HTTP/1.1 204 No Content Medya doğrulaması başarılı olursa ve tüm ping'ler gönderilirse
  • İstek, yanlış URL biçimlendirmesi veya süresi dolması nedeniyle medyayı doğrulayamıyorsa HTTP/1.1 404 Not Found.
  • HTTP/1.1 404 Not Found Bu kimlik için önceki bir doğrulama isteği başarılı olduysa
  • HTTP/1.1 409 Conflict Şu anda başka bir istek zaten ping gönderiyorsa

Reklam medyası kimlikleri (HLS)

Reklam medyası tanımlayıcıları, "kullanıcı tanımlı metin bilgisi" çerçeveleri için ayrılmış olan TXXX anahtarı kullanılarak HLS Zamanlanmış Meta Verileri'nde kodlanır. Çerçevenin içeriği şifrelenmez ve her zaman "google_" metniyle başlar.

Çerçevenin tüm metin içerikleri, her reklam doğrulama isteği yapılmadan önce reklam doğrulama URL'sine eklenmelidir.

Yöntem: metadata

metadata_url adresindeki meta veri uç noktası, reklam kullanıcı arayüzü oluşturmak için kullanılan bilgileri döndürür. Meta veri uç noktası, sunucunun reklam medyası doğrulamasını başlatmaktan sorumlu olduğu sunucu tarafı sinyal yayınlama akışlarında kullanılamaz.

Yöntemler
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Reklam meta verileri bilgilerini alır.

HTTP isteği

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

Sorgu parametreleri

Parametreler
delta_token isteğe bağlı string

İstemcinin mevcut senkronizasyon durumunu temsil eden opak bir jeton. Sağlanırsa sunucu, yalnızca jeton oluşturulduktan sonra değişen meta verileri ve yanıtta yeni bir next_delta_token döndürür. Atlanırsa sunucu, DVR aralığının tamamı için tam meta verileri döndürür.

Yanıt metni

Başarılı olursa yanıt, PodMetadata öğesinin bir örneğini döndürür.

Meta Verilerle Çalışma

Meta veriler üç ayrı bölümden oluşur: tags, ads ve breaks. Verilere giriş noktası tags bölümüdür. Buradan etiketler arasında ilerleyin ve adının video akışında bulunan reklam medyası kimliğinin öneki olduğu ilk girişi bulun. Örneğin, reklam medyası kimliğiniz şu şekilde olabilir:

google_1234567890

Ardından, google_12345 adlı bir etiket nesnesi bulursunuz. Bu durumda, reklam medya kimliğinizle eşleşir. Doğru reklam medyası önek nesnesini bulduktan sonra reklam kimliklerini, reklam arası kimliklerini ve etkinlik türünü arayabilirsiniz. Reklam kimlikleri daha sonra ads nesnelerini dizine eklemek için, reklam arası kimlikleri ise breaks nesnelerini dizine eklemek için kullanılır.

Yanıt verileri

Akış

Stream, yeni oluşturulan bir akış için kaynak listesini JSON biçiminde oluşturmak üzere kullanılır.
JSON gösterimi
{
  "stream_id": string,
  "stream_manifest": string,
  "hls_master_playlist": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "polling_frequency": number,
}
Alanlar
stream_id string

GAM akış tanımlayıcısı.
stream_manifest string

HLS'de çok varyantlı oynatma listesini veya DASH'te MPD'yi almak için kullanılan akışın manifest URL'si.
hls_master_playlist string

(KULLANIMDAN KALDIRILDI) HLS çok formatlı oynatma listesi URL'si. Bunun yerine "stream_manifest" kullanın.
media_verification_url string

Oynatma etkinliklerini izlemek için temel uç nokta olarak kullanılan medya doğrulama URL'si.
metadata_url string

Yaklaşan yayın içi reklam etkinlikleri hakkında düzenli olarak bilgi almak için kullanılan meta veri URL'si.
session_update_url string

Bu akışın hedefleme parametrelerini güncellemek için kullanılan oturumun güncelleme URL'si. Hedefleme parametrelerinin orijinal değerleri, ilk akış oluşturma isteği sırasında yakalanır.
polling_frequency number

metadata_url veya heartbeat_url istenirken anket sıklığı (saniye cinsinden).

PodMetadata

PodMetadata, reklamlar, reklam araları ve medya kimliği etiketleriyle ilgili meta veri bilgilerini içerir.
JSON gösterimi
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
Alanlar
tags map[string, object(TagSegment)]

Etiket ön ekine göre dizine eklenmiş etiket segmentlerinin haritası.
ads map[string, object(Ad)]

Reklam kimliğine göre dizine eklenen reklamların haritası.
ad_breaks map[string, object(AdBreak)]

Reklam arası kimliğine göre dizine eklenmiş reklam aralarının haritası.
next_delta_token string

İstemcinin bir sonraki yoklamada kullanacağı opak jeton.
obsolete_ad_break_ids string

Eskimiş ve istemcinin önbelleğinden kaldırılması gereken reklam arası kimliklerinin listesi.

TagSegment

TagSegment, bir reklama, reklam arasına ve etkinlik türüne referans içerir. TagSegment with type="progress" (tür="ilerleme") reklam medyası doğrulama uç noktasına pinglenmemelidir.
JSON gösterimi
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Alanlar
ad string

Bu etiketin reklamının kimliği.
ad_break_id string

Bu etiketin reklam arasının kimliği.
type string

Bu etiketin etkinlik türü.

AdBreak

AdBreak, akıştaki tek bir reklam arasını tanımlar. Süre, tür (orta/ön/son) ve reklam sayısı bilgilerini içerir.
JSON gösterimi
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Alanlar
type string

Geçerli reklam arası türleri şunlardır: pre, mid ve post.
duration number

Bu reklam arası için toplam reklam süresi (saniye).
expected_duration number

Tüm reklamlar ve seçenek listesi dahil olmak üzere reklam arasının beklenen süresi (saniye cinsinden).
ads number

Reklam arasındaki reklam sayısı.
Reklam, yayın içindeki bir reklamı tanımlar.
JSON gösterimi
{
  "ad_break_id": string,
  "position": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "click_tracking_urls": [],
  "verifications": [object(Verification)],
  "slate": boolean,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "universal_ad_id": object(UniversalAdID),
  "extensions": [],
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
Alanlar
ad_break_id string

Bu reklamın reklam arasının kimliği.
position number

Bu reklamın reklam arasındaki konumu (1'den başlar).
duration number

Reklamın süresi (saniye).
title string

Reklamın isteğe bağlı başlığı.
description string

İsteğe bağlı reklam açıklaması.
advertiser string

İsteğe bağlı reklamveren kimliği.
ad_system string

İsteğe bağlı reklam sistemi.
ad_id string

İsteğe bağlı reklam kimliği.
creative_id string

İsteğe bağlı reklam öğesi kimliği.
creative_ad_id string

İsteğe bağlı reklam öğesi reklam kimliği.
deal_id string

İsteğe bağlı anlaşma kimliği.
clickthrough_url string

İsteğe bağlı tıklama URL'si.
click_tracking_urls string

İsteğe bağlı tıklama izleme URL'leri.
verifications [object(Verification)]

Üçüncü taraf ölçüm kodunu yürütmek için gereken kaynakları ve meta verileri listeleyen, isteğe bağlı Open Measurement doğrulama girişleri. Bu girişler, reklam öğesi oynatmayı doğrulamak için kullanılır.
slate boolean

Geçerli girişin slate olup olmadığını belirten isteğe bağlı boole değeri.
icons [object(Icon)]

Boşsa atlanan simge listesi.
wrappers [object(Wrapper)]

Boşsa atlanan sarmalayıcıların listesi.
universal_ad_id object(UniversalAdID)

İsteğe bağlı evrensel reklam kimliği.
extensions string

VAST'taki tüm <Extension> düğümlerinin isteğe bağlı listesi.
companions [object(Companion)]

Bu reklamla birlikte gösterilebilecek isteğe bağlı tamamlayıcılar.
interactive_file object(InteractiveFile)

Reklam oynatma sırasında gösterilmesi gereken isteğe bağlı etkileşimli reklam öğesi (SIMID).

Simge

Icon, VAST simgesiyle ilgili bilgileri içerir.
JSON gösterimi
{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}
Alanlar
click_data object(ClickData)

creative_type string

click_fallback_images [object(FallbackImage)]

height int32

width int32

resource string

type string

x_position string

y_position string

program string

alt_text string

ClickData

ClickData, bir simge tıklamasıyla ilgili bilgileri içerir.
JSON gösterimi
{
  "url": string,
}
Alanlar
url string

FallbackImage

FallbackImage, bir VAST yedek resmiyle ilgili bilgileri içerir.
JSON gösterimi
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Alanlar
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Sarmalayıcı, sarmalayıcı reklamla ilgili bilgileri içerir. Mevcut değilse bir anlaşma kimliği içermez.
JSON gösterimi
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Alanlar
system string

Reklam sistemi tanımlayıcısı.
ad_id string

Sarmalayıcı reklam için kullanılan reklam kimliği.
creative_id string

Sarmalayıcı reklam için kullanılan reklam öğesi kimliği.
creative_ad_id string

Sarmalayıcı reklam için kullanılan reklam öğesi reklam kimliği.
deal_id string

Sarmalayıcı reklam için isteğe bağlı anlaşma kimliği.

Doğrulama

Doğrulama, üçüncü taraf görüntülenebilirlik ve doğrulama ölçümünü kolaylaştıran Open Measurement ile ilgili bilgileri içerir. Şu anda yalnızca JavaScript kaynakları desteklenmektedir. https://iabtechlab.com/standards/open-measurement-sdk/ adresine göz atın.
JSON gösterimi
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Alanlar
vendor string

Doğrulama tedarikçisi.
java_script_resources [object(JavaScriptResource)]

Doğrulama için JavaScript kaynaklarının listesi.
tracking_events [object(TrackingEvent)]

Doğrulama için izleme etkinliklerinin listesi.
parameters string

Önyükleme doğrulama koduna iletilen opak bir dize.

JavaScriptResource

JavaScriptResource, JavaScript aracılığıyla doğrulama için bilgiler içerir.
JSON gösterimi
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Alanlar
script_url string

JavaScript yükü için URI.
api_framework string

APIFramework, doğrulama kodunu kullanan video çerçevesinin adıdır.
browser_optional boolean

Bu komut dosyasının tarayıcı dışında çalıştırılıp çalıştırılamayacağı.

TrackingEvent

TrackingEvent, belirli durumlarda istemci tarafından ping gönderilmesi gereken URL'ler içerir.
JSON gösterimi
{
  "event": string,
  "uri": string,
}
Alanlar
event string

İzleme etkinliğinin türü.
uri string

Ping gönderilecek izleme etkinliği.

UniversalAdID

UniversalAdID, reklam sistemlerinde korunan benzersiz bir reklam öğesi tanımlayıcısı sağlamak için kullanılır.
JSON gösterimi
{
  "id_value": string,
  "id_registry": string,
}
Alanlar
id_value string

Reklam için seçilen reklam öğesinin Evrensel Reklam Kimliği.
id_registry string

Seçilen reklam öğesinin Evrensel Reklam Kimliğinin kataloglandığı kayıt otoritesi web sitesinin url'sini tanımlamak için kullanılan bir dize.

Tamamlayıcı

Tamamlayıcı öğe, reklamla birlikte görüntülenebilecek tamamlayıcı reklamlarla ilgili bilgileri içerir.
JSON gösterimi
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}
Alanlar
click_data object(ClickData)

Bu tamamlayıcıya ait tıklama verileri.
creative_type string

Bu, statik türde bir tamamlayıcı ise VAST'taki <StaticResource> düğümünde CreativeType özelliği.
height int32

Bu tamamlayıcı öğenin piksel cinsinden yüksekliği.
width int32

Bu tamamlayıcının piksel cinsinden genişliği.
resource string

Statik ve iframe eşlikçiler için bu, yüklenecek ve görüntülenecek URL'dir. HTML tamamlayıcılar için bu, tamamlayıcı olarak gösterilmesi gereken HTML snippet'idir.
type string

Bu tamamlayıcının türü. Statik, iframe veya HTML olabilir.
ad_slot_id string

Bu eşlik eden öğenin yer kimliği.
api_framework string

Bu tamamlayıcı için API çerçevesi.
tracking_events [object(TrackingEvent)]

Bu eşlikçiyle ilgili izleme etkinliklerinin listesi.

InteractiveFile

InteractiveFile, reklam oynatımı sırasında gösterilmesi gereken etkileşimli reklam öğesi (ör. SIMID) bilgilerini içerir.
JSON gösterimi
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Alanlar
resource string

Etkileşimli reklam öğesinin URL'si.
type string

Kaynak olarak sağlanan dosyanın MIME türü.
variable_duration boolean

Bu reklam öğesinin sürenin uzatılmasını isteyip istemediği.
ad_parameters string

VAST'taki <AdParameters> düğümünün değeri.