Dinamik Reklam Ekleme VOD API'si

Dinamik Reklam Ekleme API'si, DAI seç-izle video (VOD) akışlarını istemenizi ve izlemenizi sağlar. HLS ve DASH akışları desteklenir.

Hizmet: dai.google.com

stream yönteminin yolu https://dai.google.com'a görelidir

Yöntem: stream

Yöntemler
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

Belirtilen içerik kaynağı ve video kimliği için HLS DAI akışı oluşturur.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Belirtilen içerik kaynağı ve video kimliği için bir DASH DAI akışı oluşturur.

HTTP isteği

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/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çimle HTTP Yetkilendirme başlığında iletilebilir:

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

Yol parametreleri

Parametreler
content-source string

Akışın içerik yönetim sistemi kimliği.

video-id string

Yayının video kimliği.

İstek içeriği

İstek metni 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 yayının izlemesi istemci tarafından başlatılır ve sunucu tarafında ping'lenir.
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ılabilirsiniz.
HMAC Kimlik Doğrulaması İsteğe bağlı HMAC tabanlı bir jeton kullanarak kimlik doğrulama yapın.

Yanıt gövdesi

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

Open Measurement

Verifications alanı, sunucu tarafı işaretçi olmayan akışlar için Open Measurement doğrulamasıyla ilgili bilgileri içerir. Verifications, reklam öğesi oynatmayı üçüncü taraf ölçüm koduyla doğrulamak için ihtiyaç duyduğunuz 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'e ve VAST 4.1 spesifikasyonuna göz atın.

Yöntem: medya doğrulaması

Oynatma sırasında bir reklam medya tanımlayıcısı ile karşılaştıktan sonra hemen stream uç noktasından media_verification_url kullanarak istek gönderin. media_verification_url mutlak bir yoldur. Sunucunun medya doğrulamasını başlattığı sunucu tarafı işaretçi akışları için medya doğrulama istekleri gerekli değildir.

media verification uç noktasına gönderilen istekler idempotent'tir.

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

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

HTTP isteği

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

Yanıt gövdesi

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 geçerlilik süresi sona ermesi nedeniyle medyayı doğrulayamazsa HTTP/1.1 404 Not Found.
  • HTTP/1.1 404 Not Found değerini döndürür.
  • HTTP/1.1 409 Conflict ise başka bir istek şu anda ping gönderiyor demektir.

Reklam medya kimlikleri (HLS)

Reklam medya tanımlayıcıları, "kullanıcı tanımlı metin bilgileri" çerçeveleri için ayrılmış TXXX anahtarı kullanılarak HLS Zamanlanmış Meta Verileri'ne kodlanır. Çerçevenin içeriği şifresi çözülecek ve her zaman "google_" metniyle başlayacaktır.

Çerçevenin metin içeriğinin tamamı, her reklam doğrulama isteği için media_verification_url'ye eklenmelidir.

Reklam medya kimlikleri (DASH)

Reklam medya tanımlayıcıları, DASH'in EventStream öğesi kullanılarak manifest'e eklenir.

Her EventStream, urn:google:dai:2018 Scheme ID URI'sine sahip olacaktır. Bu raporlar, “google_” ile başlayan bir reklam medya kimliği içeren messageData özelliğine sahip etkinlikleri içerir. messageData özelliğinin içeriğinin tamamı, her reklam doğrulama isteği için media_verification_url'ye eklenmelidir.

Yanıt verileri

Akış

Akış, yeni oluşturulan bir yayının tüm kaynaklarının JSON biçiminde bir listesini oluşturmak için kullanılır .
JSON gösterimi
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
Alanlar
stream_id string

Akış tanımlayıcısı.
total_duration number

Saniye cinsinden yayın süresi.
content_duration number

Reklamlar olmadan içeriğin süresi (saniye cinsinden).
valid_for string

Süre akışı, "00sa00dk00sn" biçiminde geçerlidir.
valid_until string

Aktarımın geçerli olduğu tarih (RFC 3339 biçiminde).
subtitles [object(Subtitle)]

Altyazıların listesi. Boşsa atlanır. Yalnızca HLS.
hls_master_playlist string

(KULLANIMDAN KALDIRILDI) HLS ana oynatma listesi URL'si. stream_manifest parametresini kullanın. Yalnızca HLS.
stream_manifest string

Yayın manifesti. HLS'deki ana oynatma listesine ve DASH'teki MPD'ye karşılık gelir. Sunucu tarafı işaretleme akışı oluşturulurken yanıtta "stream_id" dışında bulunan tek alan budur.
media_verification_url string

Medya doğrulama URL'si.
apple_tv object(AppleTV)

AppleTV cihazlarına özel isteğe bağlı bilgiler. Yalnızca HLS.
ad_breaks [object(AdBreak)]

Reklam aralarının listesi. Boşsa atlanır.

AppleTV

AppleTV, Apple TV cihazlarına özgü bilgileri içerir.
JSON gösterimi
{
  "interstitials_url": string,
}
Alanlar
interstitials_url string

İnteraktif reklam URL'si.

AdBreak

AdBreak, yayındaki tek bir reklam arasını tanımlar. Bir konum, süre, tür (ortası/öncesi/sonrası) ve reklam listesini içerir.
JSON gösterimi
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Alanlar
type string

Geçerli ara türleri: orta, ön ve son.
start number

Aranızın başladığı yayındaki konum (saniye cinsinden).
duration number

Reklam arasının saniye cinsinden süresi.
ads [object(Ad)]

Reklamların listesi. Boşsa atlanır.
Reklam, yayındaki bir reklamı tanımlar. Reklamın aradaki konumunu, reklamın süresini ve bazı isteğe bağlı meta verileri içerir.
JSON gösterimi
{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
Alanlar
seq number

Reklamın aradaki konumu.
start number

Reklamın başladığı yayın konumu (saniye cinsinden).
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ı fırsat kimliği.
clickthrough_url string

İsteğe bağlı tıklama URL'si.
icons [object(Icon)]

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

Sarmalayıcıların listesi. Boşsa atlanır.
events [object(Event)]

Reklamdaki etkinliklerin listesi.
verifications [object(Verification)]

Reklam öğesi oynatmayı doğrulamak için üçüncü taraf ölçüm kodunu yürütmek üzere gereken kaynakları ve meta verileri listeleyen isteğe bağlı Open Measurement doğrulama girişleri.
universal_ad_id object(UniversalAdID)

İsteğe bağlı evrensel reklam kimliği.
companions [object(Companion)]

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

Reklam oynatımı sırasında gösterilmesi gereken isteğe bağlı etkileşimli reklam öğesi (SIMID).
skip_metadata object(SkipMetadata)

Atlanabilir reklamlar için isteğe bağlı meta veriler. Bu ayar, reklamın atlanabilir olduğunu gösterir ve atlama kullanıcı arayüzünün ve izleme etkinliğinin nasıl ele alınacağına dair talimatlar içerir.
extensions string

VAST'taki tüm <Extension> düğümlerinin isteğe bağlı listesi.

Etkinlik

Etkinlik, etkinlik türünü ve etkinliğin sunum zamanını içerir.
JSON gösterimi
{
  "time": number,
  "type": string,
}
Alanlar
time number

Bu etkinliğin sunum zamanı.
type string

Bu etkinliğin türü.

Alt başlık

Altyazı, video akışı için bir yan altyazı kanalını tanımlar. İki altyazı biçimini depolar: TTML ve WebVTT. TTMLPath özelliği, TTML yan dosyasındaki URL'yi içerir. WebVTTPath özelliği de benzer şekilde WebVTT yan dosyasındaki URL'yi içerir.
JSON gösterimi
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Alanlar
language string

"en" veya "de" gibi bir dil kodu.
language_name string

Dilin açıklayıcı adı. Aynı dil için birden fazla altyazı grubu varsa belirli altyazı grubunu ayırt eder
ttml string

TTML yardımcı dosyasının isteğe bağlı URL'si.
webvtt string

WebVTT yardımcı dosyasının isteğe bağlı URL'si.

SkipMetadata

SkipMetadata, müşterilerin atlanabilir reklamlar için atlama etkinliklerini işleyebilmesi için gereken bilgileri sağlar.
JSON gösterimi
{
  "offset": number,
  "tracking_url": string,
}
Alanlar
offset number

Ofset, oynatıcının atlama düğmesini oluşturmak için reklamın başından itibaren beklemesi gereken süreyi (saniye cinsinden) gösterir. VAST'ta sağlanmazsa atlanır.
tracking_url string

TrackingURL, atlama etkinliğinde pinglenmesi gereken bir URL içerir.

Simge

Simge, 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, simge tıklaması hakkında bilgi içerir.
JSON gösterimi
{
  "url": string,
}
Alanlar
url string

FallbackImage

FallbackImage, 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. Anlaşma kimliği yoksa 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 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

Başlangıç doğrulama koduna iletilen opak bir dize.

JavaScriptResource

JavaScriptResource, JavaScript aracılığıyla doğrulamayla ilgili bilgileri 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 yürüten 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ğını belirtir.

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ü.
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ği'nin kataloglandığı kayıt otoritesi web sitesinin URL'sini tanımlamak için kullanılan bir dize.

Companion

Tamamlayıcı, reklamla birlikte gösterilebilecek 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ının tıklama verileri.
creative_type string

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

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

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

Statik ve iframe tamamlayıcılar için bu, yüklenecek ve gösterilecek 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 arkadaşın slot kimliği.
api_framework string

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

Bu tamamlayıcı cihazla 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üresinin uzatılmasını isteyip istemeyeceğini belirtir.
ad_parameters string

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