Interfejs API VOD do dynamicznego wstawiania reklam

Interfejs Dynamic Ad Insertion API umożliwia wysyłanie żądań dotyczących strumieni wideo na żądanie (VOD) w dynamicznym wstawianiu reklam (DAI) i śledzenie ich. Obsługiwane są strumienie HLS i DASH.

Usługa: dai.google.com

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

Metoda: stream

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

Tworzy strumień HLS DAI dla danego źródła treści i identyfikatora filmu.

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

Tworzy strumień DASH DAI 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ć ważny w sieci wydawcy.

Klucz interfejsu API można przekazać w nagłówku autoryzacji HTTP w tym formacie, zamiast podawać go w treści żądania:

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

Parametry ścieżki

Parametry
content-source string

Identyfikator CMS strumienia.

video-id string

Identyfikator filmu 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ń sygnalizacji po stronie serwera. Domyślna wartość to false. Śledzenie domyślnego strumienia jest inicjowane przez klienta i pingowane po stronie serwera.
Parametry kierowania DFP Opcjonalny Dodatkowe parametry kierowania.
Zastępowanie parametrów strumienia Opcjonalny Zastąp domyślne wartości parametru tworzenia strumienia.
Uwierzytelnianie HMAC Opcjonalny Uwierzytelnianie za pomocą tokena opartego na HMAC.

Treść odpowiedzi

Jeśli operacja się uda, treść odpowiedzi będzie zawierała nowy obiekt Stream. W przypadku strumieni z sygnalizacją po stronie serwera ten parametr Stream zawiera tylko pola stream_id i stream_manifest.

Open Measurement

Pole Verifications zawiera informacje na potrzeby weryfikacji Open Measurement w przypadku strumieni, które nie korzystają z beaconów po stronie serwera. Verifications zawiera co najmniej 1 element Verification, który zawiera listę zasobów i metadanych potrzebnych do weryfikacji odtwarzania kreacji za pomocą kodu pomiarowego innej firmy. Obsługiwana jest tylko wartość JavaScriptResource. Więcej informacji znajdziesz na stronie IAB Tech Lab i w specyfikacji VAST 4.1.

Metoda: weryfikacja mediów

Gdy podczas odtwarzania napotkasz identyfikator nośnika reklamy, natychmiast wyślij żądanie za pomocą parametru media_verification_url z punktu końcowego stream. media_verification_url to ścieżka bezwzględna. W przypadku strumieni z sygnalizacją po stronie serwera, w których serwer inicjuje weryfikację multimediów, nie są wymagane prośby o weryfikację multimediów.

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

Metody
media verification GET {media_verification_url}/{ad_media_id}

Powiadamia interfejs API o zdarzeniu weryfikacji multimediów.

Żądanie HTTP

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

Treść odpowiedzi

media verificationzwraca te odpowiedzi:

  • HTTP/1.1 204 No Content jeśli weryfikacja multimediów zakończy się powodzeniem i wszystkie pingi zostaną wysłane.
  • HTTP/1.1 404 Not Found, jeśli żądanie nie może zweryfikować multimediów z powodu nieprawidłowego formatowania adresu URL lub wygaśnięcia.
  • HTTP/1.1 404 Not Found – jeśli poprzednia prośba o weryfikację tego dokumentu tożsamości została rozpatrzona pozytywnie.
  • HTTP/1.1 409 Conflict jeśli w tym czasie jest już wysyłane inne żądanie pingów.

Identyfikatory mediów reklamowych (HLS)

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

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

Identyfikatory mediów reklamowych (DASH)

Identyfikatory multimediów reklamowych będą wstawiane do pliku manifestu za pomocą elementu EventStream DASH.

Każdy element EventStream będzie miał identyfikator URI schematu urn:google:dai:2018. Będą one zawierać zdarzenia z atrybutem messageData, który zawiera identyfikator multimediów reklamy zaczynający się od "google_". Cała zawartość atrybutu messageData powinna być dołączana do parametru media_verification_url w przypadku każdego żądania weryfikacji reklamy.

Dane odpowiedzi

Strumień

Strumień służy do renderowania listy wszystkich zasobów dla 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 strumieniowej w sekundach.
content_duration number

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

Czas trwania strumienia w formacie „00h00m00s”.
valid_until string

Data, do której strumień jest ważny, w formacie RFC 3339.
subtitles [object(Subtitle)]

Lista napisów. Pomijane, jeśli jest puste. Tylko HLS.
hls_master_playlist string

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

Plik manifestu transmisji. Odpowiada playlistom głównym w HLS i MPD w DASH. Jest to jedyne pole oprócz „stream_id”, które występuje w odpowiedzi podczas tworzenia strumienia sygnalizującego po stronie serwera.
media_verification_url string

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

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

Lista przerw na reklamę. Pomijane, jeśli 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

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

Prawidłowe typy przerw to: mid, pre i post.
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. Pomijane, jeśli jest puste.
Reklama opisuje reklamę w strumieniu. Zawiera pozycję reklamy w przerwie, czas trwania reklamy i niektóre 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),
  "extensions": [],
}
Pola
seq number

Pozycja reklamy w przerwie.
start number

Pozycja w strumieniu, w której rozpoczyna się reklama (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 powiązanej z kreacją.
deal_id string

Opcjonalny identyfikator umowy.
clickthrough_url string

Opcjonalny docelowy URL.
icons [object(Icon)]

Lista ikon. Jeśli jest pusta, zostaje pominięta.
wrappers [object(Wrapper)]

Lista elementów opakowujących. Pomijane, jeśli jest puste.
events [object(Event)]

Lista zdarzeń w reklamie.
verifications [object(Verification)]

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

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

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

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

Opcjonalne metadane reklam możliwych do pominięcia. Jeśli jest ustawiony, oznacza, że reklamę można pominąć, i zawiera instrukcje dotyczące obsługi interfejsu pomijania i zdarzenia śledzenia.
extensions string

Opcjonalna lista wszystkich węzłów <Extension> w VAST.

Zdarzenie

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

Czas prezentacji tego wydarzenia.
type string

Typ tego wydarzenia.

Podtytuł

Podtytuł opisuje ścieżkę napisów dodatkowych do strumienia wideo. Przechowuje 2 formaty napisów: TTML i WebVTT. Atrybut TTMLPath zawiera adres URL pliku dodatkowego TTML, a atrybut WebVTTPath zawiera adres URL pliku dodatkowego 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

Nazwa opisowa języka. Pozwala odróżnić konkretny zestaw napisów, jeśli dla danego języka istnieje kilka zestawów.
ttml string

Opcjonalny adres URL pliku pomocniczego TTML.
webvtt string

Opcjonalny adres URL pliku pomocniczego WebVTT.

SkipMetadata

SkipMetadata zawiera informacje potrzebne klientom do obsługi zdarzeń pominięcia w przypadku reklam, które można pominąć.
Zapis JSON
{
  "offset": number,
  "tracking_url": string,
}
Pola
offset number

Opóźnienie wskazuje czas w sekundach, przez jaki odtwarzacz powinien czekać na wyrenderowanie przycisku pominięcia. Pomijany, jeśli nie został podany w VAST.
tracking_url string

TrackingURL zawiera adres URL, pod który należy wysłać ping 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

FallbackImage zawiera informacje o zastępczym obrazie 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

Element opakowujący zawiera informacje o reklamie opakowują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żywany w reklamie opakowującej.
creative_id string

Identyfikator kreacji użyty w reklamie z kodem towarzyszącym.
creative_ad_id string

Identyfikator reklamy powiązanej z kreacją używany w reklamie w kodzie towarzyszącym.
deal_id string

Opcjonalny identyfikator umowy dotyczący reklamy opakowującej.

Weryfikacja

Weryfikacja zawiera informacje o Open Measurement, które ułatwiają pomiar widoczności i weryfikacji przez podmioty zewnętrzne. Obecnie obsługiwane są tylko zasoby JavaScript. Więcej informacji znajdziesz na stronie 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 systemu weryfikacji.
java_script_resources [object(JavaScriptResource)]

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

Lista zdarzeń śledzenia weryfikacji.
parameters string

Nieprzezroczysty ciąg znaków przekazywany do kodu weryfikacyjnego rozruchu.

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, która używa kodu weryfikacyjnego.
browser_optional boolean

Określa, czy ten skrypt można uruchomić poza przeglądarką.

TrackingEvent

TrackingEvent zawiera adresy URL, do których klient powinien wysyłać pingi w określonych sytuacjach.
Zapis JSON
{
  "event": string,
  "uri": string,
}
Pola
event string

Typ zdarzenia śledzenia.
uri string

Zdarzenie śledzenia, które ma zostać wysłane.

UniversalAdID

Identyfikator UniversalAdID służy do podawania unikalnego identyfikatora kreacji, który jest zachowywany w różnych systemach reklamowych.
Zapis JSON
{
  "id_value": string,
  "id_registry": string,
}
Pola
id_value string

Uniwersalny identyfikator reklamy wybranej kreacji reklamy.
id_registry string

Ciąg znaków służący do identyfikacji adresu URL witryny rejestru, w której katalogowany jest uniwersalny identyfikator reklamy wybranej kreacji.

Reklama towarzysząca

Element towarzyszący zawiera informacje o reklamach towarzyszących, które mogą się wyświetlać obok reklamy.
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 tej kreacji towarzyszącej.
creative_type string

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

Wysokość tego elementu towarzyszącego w pikselach.
width int32

Szerokość tego elementu towarzyszącego w pikselach.
resource string

W przypadku statycznych i iframe’owych reklam towarzyszących będzie to adres URL, który ma zostać wczytany i  wyświetlony. W przypadku reklam towarzyszących w formacie HTML będzie to fragment kodu HTML, który powinien być wyświetlany jako reklama towarzysząca.
type string

Typ tego urządzenia towarzyszącego. Może to być statyczny kod HTML, kod iframe lub kod HTML.
ad_slot_id string

Identyfikator miejsca docelowego tego elementu towarzyszącego.
api_framework string

Platforma interfejsu API tego komponentu.
tracking_events [object(TrackingEvent)]

Lista zdarzeń śledzenia w przypadku tego komponentu towarzyszącego.

InteractiveFile

InteractiveFile zawiera informacje o interaktywnej kreacji (np. SIMID), która powinna być wyświetlana podczas odtwarzania reklamy.
Zapis JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Pola
resource string

Adres URL interaktywnej kreacji.
type string

Typ MIME pliku podanego jako zasób.
variable_duration boolean

Czy w przypadku tej kreacji można poprosić o przedłużenie czasu trwania.
ad_parameters string

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