Interfejs API VOD do dynamicznego wstawiania reklam

Interfejs API dynamicznego wstawiania reklam umożliwia wysyłanie żądań i śledzenie strumieni wideo na żądanie (VOD) z dynamicznym wstawianiem reklam. Strumienie HLS i DASH są obsługiwane.

Usługa: dai.google.com

Ścieżka metody stream jest względna wobec elementu https://dai.google.com

Metoda: stream

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

Tworzy strumień HLS z dynamicznym wstawianiem reklam dla danego źródła treści i identyfikatora filmu.

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

Tworzy strumień DAI w postaci strumienia DASH dla danego źródła treści i identyfikatora filmu.

Żądanie HTTP

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

Nagłówek żądania

Parametry
api‑key string

Klucz interfejsu API podany podczas tworzenia strumienia musi być prawidłowy w sieci wydawcy.

Zamiast podawać go w treści żądania, klucz interfejsu API można przekazać w nagłówku autoryzacji HTTP w następującym formacie:

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

Parametry ścieżki

Parametry
content-source string

Identyfikator CMS strumienia.

video-id string

Identyfikator wideo strumienia.

Treść żądania

Treść żądania jest typu application/x-www-form-urlencoded i zawiera te parametry:

Parametry
dai-ssb Opcjonalny

Ustaw wartość true, aby utworzyć strumień z sygnalizowaniem po stronie serwera. Domyślna wartość to false. Śledzenie domyślnego strumienia jest inicjowane przez klienta i wysłane za pomocą polecenia ping po stronie serwera.
Parametry kierowania DFP Opcjonalny Dodatkowe parametry kierowania.
Zastąp parametry strumienia Opcjonalny Zastąp domyślne wartości parametru tworzenia strumienia.
Uwierzytelnianie HMAC Opcjonalny Uwierzytelnij się za pomocą tokena opartego na HMAC.

Treść odpowiedzi

Jeśli operacja się uda, treść odpowiedzi będzie zawierała nowy element Stream. W przypadku strumieni z sygnalizowaniem po stronie serwera ta wartość Stream zawiera tylko pola stream_id i stream_manifest.

Open Measurement

Pole Verifications zawiera informacje na temat weryfikacji Open Measurement w przypadku strumieni spoza serwera. Element Verifications zawiera co najmniej 1 element Verification, który zawiera listę zasobów i metadanych potrzebnych do zweryfikowania odtwarzania kreacji za pomocą kodu pomiarowego firmy zewnętrznej. Obsługiwana jest tylko wartość JavaScriptResource. Więcej informacji znajdziesz w IAB Tech Lab i w specyfikacji VAST 4.1.

Metoda: weryfikacja mediów

Gdy podczas odtwarzania zobaczysz identyfikator multimediów reklamy, natychmiast wyślij żądanie, korzystając z metody media_verification_url z punktu końcowego stream. media_verification_url jest ścieżką bezwzględną. Żądania weryfikacji mediów nie są konieczne w przypadku strumieni sygnalizowania po stronie serwera, gdy serwer inicjuje weryfikację.

Żądania do punktu końcowego media verification są idempotentne.

Metody
media verification GET {media_verification_url}/{ad_media_id}

Informuje interfejs API o zdarzeniu weryfikacji multimediów.

Żądanie HTTP

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

Treść odpowiedzi

media verification zwraca te odpowiedzi:

  • HTTP/1.1 204 No Content, jeśli weryfikacja multimediów się powiedzie, a wszystkie pingi zostaną wysłane.
  • HTTP/1.1 404 Not Found, jeśli żądanie nie może zweryfikować mediów z powodu nieprawidłowego formatowania adresu URL lub jego daty ważności.
  • HTTP/1.1 404 Not Found, jeśli poprzednia prośba o weryfikację dotyczącą tego dokumentu została zrealizowana.
  • HTTP/1.1 409 Conflict, jeśli inne żądanie wysyła już pingi w tym samym czasie.

Identyfikatory mediów reklam (HLS)

Identyfikatory multimediów reklam będą kodowane w metadanych czasowych HLS za pomocą klucza TXXX, zarezerwowane dla ramek „informacji tekstowych zdefiniowanych przez użytkownika”. Zawartość ramki będzie niezaszyfrowana i zawsze będzie zaczynać się od tekstu "google_".

Cała zawartość ramki powinna być dołączana do parametru media_verification_url w przypadku każdego żądania weryfikacji reklam.

Identyfikatory mediów reklam (DASH)

Identyfikatory mediów reklam są wstawiane do pliku manifestu za pomocą elementu EventStream DASH.

Każdy element EventStream będzie miał identyfikator URI identyfikatora schematu o wartości urn:google:dai:2018. Będą one zawierać zdarzenia z atrybutem messageData i identyfikatorem mediów reklamy zaczynającym się od “google_”. Cała zawartość atrybutu messageData powinna być dołączana do elementu media_verification_url w przypadku każdego żądania weryfikacji reklam.

Dane odpowiedzi

Strumień

Strumień służy do renderowania listy wszystkich zasobów nowo utworzonego strumienia w formacie JSON .
Zapis JSON
{
  "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)],
}
Pola
stream_id string

Identyfikator strumienia.
total_duration number

Czas trwania transmisji w sekundach.
content_duration number

Czas trwania treści bez reklam (w sekundach).
valid_for string

Czas trwania strumienia jest prawidłowy dla formatu „00h00m00s”.
valid_until string

Data ważności strumienia do dnia, w formacie RFC 3339.
subtitles [object(Subtitle)]

Lista napisów. Pomiń, jeśli pole jest puste. Tylko HLS.
hls_master_playlist string

(WYCOFANY) URL playlisty reklamy nadrzędnej HLS. Użyj parametru stream_manifest. Tylko HLS.
stream_manifest string

Plik manifestu strumienia. Odpowiada playliście reklamy nadrzędnej w HLS i MPD w DASH. Jest to jedyne pole oprócz „stream_id”, które znajduje się w odpowiedzi podczas tworzenia strumienia z sygnalizowaniem po stronie serwera.
media_verification_url string

URL do weryfikacji mediów.
apple_tv object(AppleTV)

Opcjonalne informacje dotyczące urządzeń Apple TV. Tylko HLS.
ad_breaks [object(AdBreak)]

Lista przerw na reklamę. Pomiń, jeśli pole jest puste.

AppleTV

AppleTV zawiera informacje dotyczące urządzeń Apple TV.
Zapis JSON
{
  "interstitials_url": string,
}
Pola
interstitials_url string

Adres URL reklam pełnoekranowych.

AdBreak

Przerwa na reklamę opisuje pojedynczą przerwę w strumieniu. Zawiera ona pozycję, czas trwania, typ (w trakcie/przed/po) oraz listę reklam.
Zapis JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Pola
type string

Prawidłowe typy przerw: w trakcie filmu, przed i po.
start number

Pozycja w strumieniu, w której rozpoczyna się przerwa (w sekundach).
duration number

Czas trwania przerwy na reklamę w sekundach.
ads [object(Ad)]

Lista reklam. Pomiń, jeśli pole jest puste.
Reklama opisuje reklamę w strumieniu. Zawiera on pozycję reklamy w przerwie, czas jej trwania i opcjonalne metadane.
Zapis JSON
{
  "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),
}
Pola
seq number

Pozycja reklamy w przerwie.
start number

Pozycja w strumieniu, na której reklama się uruchamia, (w sekundach).
duration number

Czas trwania reklamy w sekundach.
title string

Opcjonalny tytuł reklamy.
description string

Opcjonalny opis reklamy.
advertiser string

Opcjonalny identyfikator reklamodawcy.
ad_system string

Opcjonalny system reklamowy.
ad_id string

Opcjonalny identyfikator reklamy.
creative_id string

Opcjonalny identyfikator kreacji.
creative_ad_id string

Opcjonalny identyfikator reklamy kreacji.
deal_id string

Opcjonalny identyfikator umowy.
clickthrough_url string

Opcjonalny docelowy URL.
icons [object(Icon)]

Lista ikon, pomijana, jeśli jest pusta.
wrappers [object(Wrapper)]

Lista kodów towarzyszących Pomiń, jeśli pole jest puste.
events [object(Event)]

Lista zdarzeń występujących w reklamie.
verifications [object(Verification)]

Opcjonalne wpisy weryfikacyjne Open Measurement, które zawierają listę zasobów i metadanych wymaganych do wykonania zewnętrznego kodu pomiarowego w celu weryfikacji odtwarzania kreacji.
universal_ad_id object(UniversalAdID)

Opcjonalny uniwersalny identyfikator reklamy.
companions [object(Companion)]

Opcjonalne elementy towarzyszące, które mogą się wyświetlać razem z tą reklamą.
interactive_file object(InteractiveFile)

Opcjonalna kreacja interaktywna (SIMID), która powinna się wyświetlać podczas odtwarzania reklamy.
skip_metadata object(SkipMetadata)

Opcjonalne metadane reklam możliwych do pominięcia. Jeśli jest skonfigurowana, wskazuje, że reklama jest możliwą do pominięcia oraz zawiera instrukcje obsługi interfejsu pominięcia i zdarzenia śledzenia.

Zdarzenie

Wydarzenie zawiera typ wydarzenia oraz czas jego prezentacji.
Zapis JSON
{
  "time": number,
  "type": string,
}
Pola
time number

Czas prezentacji tego wydarzenia.
type string

Typ tego wydarzenia.

Podtytuł

Napisy opisują ścieżkę napisów dla strumienia wideo. Przechowuje 2 formaty napisów: TTML i WebVTT. Atrybut TTMLPath zawiera adres URL pliku pomocniczego TTML, a atrybut WebVTTPath zawiera adres URL podobny do pliku pomocniczego WebVTT.
Zapis JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Pola
language string

Kod języka, np. „pl” lub „de”.
language_name string

Opisowa nazwa języka. Rozróżnia on konkretny zestaw napisów, jeśli dla tego samego języka istnieje wiele zestawów.
ttml string

Opcjonalny adres URL pliku pomocniczego TTML.
webvtt string

Opcjonalny adres URL pliku pomocniczego WebVTT.

SkipMetadata

Parametr PomińMetadata dostarcza informacji potrzebnych klientom do obsługi zdarzeń pominięcia w reklamach możliwych do pominięcia.
Zapis JSON
{
  "offset": number,
  "tracking_url": string,
}
Pola
offset number

Przesunięcie wskazuje czas (w sekundach), przez jaki odtwarzacz powinien czekać na wyrenderowanie przycisku pominięcia. Parametr pomijany, jeśli nie został podany w szablonie VAST.
tracking_url string

TrackingURL zawiera adres URL, który powinien zostać wywołany pingiem w przypadku zdarzenia pominięcia.

Ikona

Ikona zawiera informacje o ikonie VAST.
Zapis JSON
{
  "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,
}
Pola
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 zawiera informacje o kliknięciu ikony.
Zapis JSON
{
  "url": string,
}
Pola
url string

FallbackImage

Obraz zastępczy zawiera informacje o obrazie zastępczym VAST.
Zapis JSON
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Pola
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Kod zawiera informacje o reklamie towarzyszącej. Nie zawiera identyfikatora umowy, jeśli nie istnieje.
Zapis JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Pola
system string

Identyfikator systemu reklamowego.
ad_id string

Identyfikator reklamy użyty na potrzeby reklamy z kodem.
creative_id string

Identyfikator kreacji używany na potrzeby reklamy towarzyszącej.
creative_ad_id string

Identyfikator reklamy z kreacją używaną na potrzeby reklamy z kodem.
deal_id string

Opcjonalny identyfikator umowy dla reklamy z kodem.

Weryfikacja

Funkcja Weryfikacja zawiera informacje na potrzeby Open Measurement, które ułatwiają zewnętrznym pomiarom widoczność i weryfikację. Obecnie obsługiwane są tylko zasoby JavaScript. Więcej informacji: https://iabtechlab.com/standards/open-measurement-sdk/
Zapis JSON
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Pola
vendor string

Dostawca weryfikacji.
java_script_resources [object(JavaScriptResource)]

Lista zasobów JavaScript do weryfikacji.
tracking_events [object(TrackingEvent)]

Lista zdarzeń śledzenia do weryfikacji.
parameters string

Nieprzejrzysty ciąg znaków przekazany do kodu weryfikacyjnego wczytywania.

JavaScriptResource

JavaScriptResource zawiera informacje do weryfikacji za pomocą JavaScriptu.
Zapis JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Pola
script_url string

Identyfikator URI do ładunku JavaScript.
api_framework string

APIFramework to nazwa platformy wideo, w której jest wykorzystywany kod weryfikacyjny.
browser_optional boolean

Określa, czy ten skrypt może być uruchamiany poza przeglądarką.

TrackingEvent

Tag TrackingEvent zawiera adresy URL, które w określonych sytuacjach powinny zostać wysłane przez klienta za pomocą polecenia ping.
Zapis JSON
{
  "event": string,
  "uri": string,
}
Pola
event string

Typ zdarzenia śledzenia.
uri string

Zdarzenie śledzenia do sprawdzenia.

UniversalAdID

Unikalny identyfikator kreacji jest używany w różnych systemach reklamowych.
Zapis JSON
{
  "id_value": string,
  "id_registry": string,
}
Pola
id_value string

Uniwersalny identyfikator wybranej kreacji w reklamie
id_registry string

Ciąg znaków określający adres URL witryny rejestru, w której znajduje się uniwersalny identyfikator reklamy wybranej kreacji.

Reklama towarzysząca

Zawiera informacje o reklamach towarzyszących, które mogą się wyświetlać razem z reklamą.
Zapis JSON
{
  "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)],
}
Pola
click_data object(ClickData)

Dane o kliknięciach związane z tą reklamą towarzyszącą.
creative_type string

Atrybut CreativeType w węźle <StaticResource> w tagu VAST, jeśli jest to reklama towarzysząca typu statycznego.
height int32

Wysokość w pikselach kreacji towarzyszącej.
width int32

Szerokość reklamy towarzyszącej w pikselach.
resource string

W przypadku elementów towarzyszących w elementach statycznych i elementów iframe będzie to adres URL do wczytania i wyświetlenia. W przypadku elementów towarzyszących HTML jest to fragment kodu HTML, który powinien być wyświetlany jako reklama towarzysząca.
type string

Typ kreacji towarzyszącej. Może być statyczny, iframe lub HTML.
ad_slot_id string

Identyfikator boksu kreacji towarzyszącej.
api_framework string

Platforma API dla tej aplikacji towarzyszącej.
tracking_events [object(TrackingEvent)]

Lista zdarzeń śledzenia dla tej kreacji towarzyszącej.

InteractiveFile

Plik InteractiveFile zawiera informacje o kreacji interaktywnej (np. SIMID), które powinny się wyświetlać podczas odtwarzania reklamy.
Zapis JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Pola
resource string

Adres URL kreacji interaktywnej.
type string

Typ MIME pliku dostarczonego jako zasób.
variable_duration boolean

Określa, czy kreacja może poprosić o wydłużenie czasu trwania.
ad_parameters string

Wartość węzła <AdParameters> w tagu VAST.