Dinamik Reklam Ekleme Doğrusal API'si

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

Hizmet: dai.google.com

Aşağıdaki tüm URI'ler https://dai.google.com ile ilgilidir

Yöntem: akış

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ştururken sağlanan API anahtarı, yayıncının ağı için geçerli olmalıdır.

API anahtarı, istek gövdesinde sağlamak yerine HTTP Yetkilendirmesi başlığında aşağıdaki biçimde iletilebilir:

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

Yol parametreleri

Parametreler
assetKey string

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

İstek içeriği

İsteğin 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şaretleme akışı oluşturmak için true olarak ayarlayın. Varsayılan olarak false değerine ayarlanır. Varsayılan akışın izleme işlemi, istemci tarafından başlatılır ve sunucu tarafında pinglenir.
DFP Hedefleme Parametreleri İsteğe bağlı Ek hedefleme parametreleri.
Akış Parametrelerini Geçersiz Kıl İsteğe bağlı Akış oluşturma parametresinin varsayılan değerlerini geçersiz kılın.
HMAC Kimlik Doğrulaması İsteğe bağlı HMAC tabanlı bir jeton kullanarak kimlik doğrulayın.

Yanıt gövdesi

Başarılı olursa yanıt gövdesi yeni bir Stream içerir. Sunucu tarafı işaretleme akışları için bu Stream yalnızca stream_id ve stream_manifest alanlarını içerir.

Open Measurement

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

Yöntem: Medya doğrulaması

Oynatma sırasında bir reklam medya tanımlayıcısıyla karşılaştıktan sonra, yukarıdaki akış uç noktasından alınan media_verification_url adresini kullanarak hemen bir istek gönderin. Bu istekler, sunucunun medya doğrulamasını başlattığı sunucu tarafı işaretleme akışları için gerekli değildir.

media verification uç noktasına yapılan istekler idempotenttir.

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

API'ye bir medya doğrulama etkinliği bildirir.

HTTP isteği

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

Yanıt gövdesi

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

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

Reklam medyası kimlikleri (HLS)

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

Her reklam doğrulama isteğinde bulunmadan önce çerçevenin metin içeriğinin tamamı reklam doğrulama URL'sine eklenmelidir.

Yöntem: meta veriler

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ı, reklam medyası doğrulamasını başlatmaktan sunucunun sorumlu olduğu sunucu tarafı işaretleme akışları için kullanılamaz.

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

GET /{metadata_url}

Reklam meta veri bilgilerini alır.

HTTP isteği

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

GET https://{metadata_url}

Yanıt gövdesi

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

Meta verilerle çalışma

Meta veriler üç ayrı bölümden oluşur: tags, ads ve reklam breaks. Verilere giriş noktası tags bölümüdür. Ardından etiketleri tekrarlayın ve adı, video akışında bulunan reklam medya kimliğinin öneki olan ilk girişi bulun. Örneğin, şöyle bir reklam medya kimliğiniz olabilir:

google_1234567890

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

Yanıt verileri

Yayın yap

Akış, yeni oluşturulan bir akış için kaynakların listesini JSON biçiminde oluşturmak amacıyla 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

Akışın manifest URL'si. HLS'de çok değişkenli oynatma listesini veya DASH'te MPD'yi almak için kullanılır.
hls_master_playlist string

(KULLANIMDAN KALDIRILDI) HLS çok değişkenli oynatma listesi URL'si. Bunun yerine "stream_manifest" ifadesini 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 reklamı etkinlikleri hakkında düzenli bilgileri anket yapmak için kullanılan meta veri URL'si.
session_update_url string

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

Metadata_url from veya cardbeat_url istenirken saniye cinsinden yoklama sıklığı.

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)],
}
Alanlar
tags map[string, object(TagSegment)]

Etiket ön ekine göre dizine eklenen 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 eklenen reklam aralarının haritası.

TagSegment

TagSegment bir reklama, reklama ait reklam arası ve etkinlik türü için referans içeriyor. type="progress" içeren TagSegmenti, 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, yayındaki tek bir reklam arasını tanımlar. Raporda süre, tür (orta/öncesi/sonrası) ve reklam sayısı bulunur.
JSON gösterimi
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Alanlar
type string

Geçerli ara türleri şunlardır: öncesi, ortası ve sonrası.
duration number

Bu reklam arası için saniye cinsinden toplam reklam süresi.
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, akıştaki bir reklamı açıklar.
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 1'den başlayan konumu.
duration number

Reklamın saniye cinsinden süresi.
title string

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

Reklamın isteğe bağlı açıklaması.
advertiser string

İsteğe bağlı reklamveren tanımlayıcısı.
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)]

Reklam öğesi oynatmayı doğrulamak amacıyla üçü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.
slate boolean

Geçerli girişin seçenek listesi olduğunu belirten isteğe bağlı Boole.
icons [object(Icon)]

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

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

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

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

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

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

Simge

Simge, VAST simgesi hakkında bilgiler içeriyor.
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 bilgiler içerir.
JSON gösterimi
{
  "url": string,
}
Alanlar
url string

FallbackImage

FallbackImage, VAST yedek resmiyle ilgili bilgiler 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ı, bir sarmalayıcı reklamla ilgili bilgileri içerir. Varsa 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 bilgilerini içerir. Şu anda yalnızca JavaScript kaynakları desteklenmektedir. https://iabtechlab.com/standards/open-measurement-sdk/ sayfasını inceleyin.
JSON gösterimi
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Alanlar
vendor string

Doğrulama tedarikçi firması.
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 iletilmiş opak bir dize.

JavaScriptResource

JavaScriptResource, JavaScript aracılığıyla doğrulama yapmaya yönelik 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 bir tarayıcının dışında çalıştırılıp çalıştırılamayacağı.

TrackingEvent

İzleme Etkinliği, belirli durumlarda istemci tarafından pinglenmesi gereken URL'ler içerir.
JSON gösterimi
{
  "event": string,
  "uri": string,
}
Alanlar
event string

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

Pinglenecek izleme etkinliği.

UniversalAdID

UniversalAdID, reklam sistemleri arasında yönetilen 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ı, 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ı için tıklama verileri.
creative_type string

Statik türündeki bir tamamlayıcıysa VAST'taki <StaticResource> düğümündeki CreativeType özelliği.
height int32

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

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

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

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

Bu tamamlayıcının alan kimliği.
api_framework string

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

Bu tamamlayıcı için izleme etkinliklerinin listesi.

InteractiveFile

InteractiveFile, reklam oynatma sırasında görüntülenmesi gereken etkileşimli reklam öğesi (SIMID) ile ilgili bilgileri 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 isteymeyeceği.
ad_parameters string

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