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ğlanmak 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

İ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şaretleme akışı oluşturmak için true değerine 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ılma.
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'si, Verifications alanında Open Measurement doğrulaması için bilgiler içerir. Bu alan, reklam öğesinin oynatıldığını 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 spesifikasyonunu inceleyin.

Yöntem: medya doğrulaması

Oynatma sırasında bir reklam medya tanımlayıcısıyla karşılaştıktan sonra, yukarıda belirtilen akış uç noktasından elde edilen media_verification_url'yi kullanarak hemen bir istekte bulunun. 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 eşgüçlüdür.

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

API'yi bir medya doğrulama etkinliğiyle ilgili bilgilendirir.

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 süre sonu nedeniyle medyayı doğrulayamıyorsa HTTP/1.1 404 Not Found.
  • Bu kimlik için daha önce gönderilen 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 medya tanımlayıcıları, "kullanıcı tanımlı metin bilgileri" çerçeveleri için ayrılmış olan TXXX anahtarı kullanılarak HLS Zamanlanmış Meta Verilerinde kodlanacaktır. Çerçevenin içeriği şifrelenmez ve her zaman "google_" metniyle başlar.

Çerçevedeki metin içeriğinin tamamı, her reklam doğrulama isteğinde bulunmadan önce reklam doğrulama URL'sine eklenmelidir.

Yöntem: meta veri

metadata_url konumundaki meta veri uç noktası, reklam kullanıcı arayüzü oluşturmak için kullanılan bilgileri döndürür. Reklam medyası doğrulamasını başlatmaktan sunucunun sorumlu olduğu sunucu tarafı işaretleme akışları için meta veri uç noktası 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, PodMetadata öğesinin bir örneğini döndürür.

Meta verilerle çalışma

Meta verilerin üç ayrı bölümü vardır: tags, ads ve reklam breaks. Verilere giriş noktası tags bölümüdür. Buradan, etiketleri yineleyin ve adı video akışında bulunan reklam medya kimliği için ön ek olan ilk girişi bulun. Örneğin, aşağıdaki gibi bir reklam medya kimliğiniz olabilir:

google_1234567890

Ardından google_12345 adlı bir etiket nesnesi görürsünüz. Bu örnekte, reklam medyası kimliğinizle eşleşir. Doğru reklam medyası ön ek 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ışla ilgili kaynakların listesini JSON biçiminde oluşturmak için 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

Akış tanımlayıcısı.
stream_manifest string

HLS'deki ana oynatma listesine veya DASH'teki MPD'ye karşılık gelen akış manifestidir. Bu, sunucu tarafı işaretleme akışı oluştururken yanıtta "stream_id" haricinde bulunan tek alandır.
hls_master_playlist string

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

Medya doğrulama URL'si.
metadata_url string

Reklam medyası meta veri URL'si.
session_update_url string

Oturum güncelleme URL'si.
polling_frequency number

Saniye cinsinden önerilen meta veri URL'si yoklama sıklığıdır.

PodMetadata

PodMetadata reklamlar, reklam araları ve medya kimliği etiketleriyle ilgili meta veri bilgileri 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ı haritası.

TagSegment

TagSegment, bir reklama, reklam arasına ve etkinlik türüne yönelik bir referans içerir. type="progress" değerine sahip TagSegment, reklam medya doğrulaması uç noktasına pinglenmemelidir.
JSON gösterimi
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Alanlar
ad string

Bu etikete ait reklamı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ı ifade eder. Bu raporda süre, tür (orta/ön/yayın) ve reklam sayısı belirtilir.
JSON gösterimi
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Alanlar
type string

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

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

Tüm reklamlar ve seçenek listeleri 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 arasının kimliği.
position number

Bu reklamın reklam arasındaki konumu (1'den başlayarak).
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 öğesinin oynatıldığını 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ı Bool.
icons [object(Icon)]

Simgelerin bir listesi (boşsa atlanır).
wrappers [object(Wrapper)]

Sarmalayıcıların listesi (boşsa atlanır).
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örüntülenmesi gereken isteğe bağlı etkileşimli reklam öğesi (SIMID).

Simge

Simge, VAST simgesi hakkında bilgi 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

Yedek Resim, 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ı, sarmalayıcı reklamla ilgili bilgiler içerir. Mevcut değilse anlaşma kimliğini 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ına bakın
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ğrulamayla ilgili izleme etkinliklerinin listesi.
parameters string

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

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üne URI.
api_framework string

APIFramework, doğrulama kodunu uygulayan 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

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

İzleme etkinliğinin türü, şu anda tek seçenek olan "verificationNotExecuted" (VAST 4.1 spesifikasyonunda belirtildiği gibi).
uri string

Pinglenecek izleme etkinliği.

UniversalAdID

UniversalAdID, reklam sistemleri genelinde 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 kataloga dahil edildiği kayıt otoritesinin web sitesinin URL'sini tanımlamak için kullanılan dize.

Tamamlayıcı

Tamamlayıcı reklamlar, reklamla birlikte görüntülenebilecek tamamlayıcı reklamlarla ilgili bilgiler içerir.
JSON gösterimi
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
}
Alanlar
click_data object(ClickData)

Bu tamamlayıcının tıklama verileri.
creative_type string

Statik türde bir tamamlayıcıysa VAST'taki <StaticResource> düğümünde 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 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'i olacaktır.
type string

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

InteractiveFile

InteractiveFile, reklam oynatma sırasında görüntülenmesi gereken etkileşimli reklam öğesi (ör. SIMID) için bilgiler 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üre uzatılmasını isteyip istemediği.
ad_parameters string

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