Interfejs API VOD do dynamicznego wstawiania reklam

Interfejs Dynamic Ad Insertion API umożliwia żądanie i śledzenie strumieni wideo na żądanie (VOD) z dynamicznym wstawianiem reklam. Obsługiwane są strumienie HLS i DASH.

Usługa: dai.google.com

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

Metoda: strumień

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ć prawidłowy w przypadku sieci wydawcy.

Zamiast podawać go w treści żądania, możesz przekazać klucz interfejsu API w nagłówku HTTP Authorization w takim formacie:

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 ma typ application/x-www-form-urlencoded i zawiera te parametry:

Parametry
dai-ssb Opcjonalny

Ustaw na true, aby utworzyć strumień beaconów po stronie serwera. Domyślna wartość to false. Śledzenie domyślnego strumienia jest inicjowane przez klienta i wywoływane po stronie serwera.
Parametry kierowania DFP Opcjonalny Dodatkowe parametry kierowania.
Zastępowanie parametrów strumienia Opcjonalny Zastępowanie domyślnych wartości parametru tworzenia strumienia.
Uwierzytelnianie HMAC Opcjonalny Uwierzytelnianie za pomocą tokena opartego na HMAC.

Treść odpowiedzi

Jeśli operacja się powiedzie, treść odpowiedzi będzie zawierać nowy obiekt Stream. W przypadku strumieni z beaconami po stronie serwera pole Stream zawiera tylko pola stream_id i stream_manifest.

Open Measurement

Pole Verifications zawiera informacje o weryfikacji Open Measurement w przypadku strumieni danych, 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, których potrzebujesz do weryfikacji odtwarzania kreacji za pomocą kodu pomiarowego innej firmy. Obsługiwana jest tylko wartość JavaScriptResource. Więcej informacji znajdziesz w IAB Tech Lab i specyfikacji VAST 4.1.

Metoda: weryfikacja mediów

Gdy podczas odtwarzania pojawi się identyfikator mediów reklamy, natychmiast wyślij żądanie za pomocą media_verification_url z urządzenia końcowego stream. media_verification_url to ścieżka bezwzględna. W przypadku strumieniowania z beaconami po stronie serwera, gdzie weryfikację multimediów inicjuje serwer, nie trzeba wysyłać próśb o weryfikację multimediów.

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

Metody
media verification GET {media_verification_url}/{ad_media_id}

powiadamia interfejs API o zdarzeniu weryfikacji medió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 mediów się powiedzie i wszystkie pingi zostaną wysłane.
  • HTTP/1.1 404 Not Found, jeśli nie można zweryfikować mediów z powodu nieprawidłowego formatowania lub wygaśnięcia adresu URL.
  • HTTP/1.1 404 Not Found, jeśli poprzednia prośba o weryfikację tego dokumentu została zrealizowana;
  • HTTP/1.1 409 Conflict jeśli w tym samym czasie jest już wysyłana inna prośba.

Identyfikatory mediów reklamowych (HLS)

Identyfikatory multimediów reklamowych zostaną zakodowane w metadanych HLS z użyciem klucza TXXX zarezerwowanego dla klatek „zdefiniowanych przez użytkownika informacji tekstowych”. Zawartość ramki będzie niezaszyfrowana i zawsze rozpocznie się od tekstu "google_".

Cały tekst w ramce powinien zostać dołączony do parametru media_verification_url w przypadku każdego żądania weryfikacji reklamy.

Identyfikatory mediów reklamy (DASH)

Identyfikatory multimediów reklamy zostaną wstawione do pliku manifestu za pomocą elementu EventStream w DASH.

Każdy element EventStream będzie mieć identyfikator URI schematu o postaci urn:google:dai:2018. Będą one zawierać zdarzenia z atrybutem messageData, w którym podany jest identyfikator reklamy zawierający ciąg znaków zaczynający się od “google_”. Cała zawartość atrybutu messageData powinna zostać dołączona 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 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 strumienia w sekundach.
content_duration number

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

Czas trwania strumienia jest prawidłowy w formacie „00h00m00s”.
valid_until string

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

Lista napisów. Jeśli jest puste, pomiń. Tylko HLS.
hls_master_playlist string

(WYCOFANE) URL listy odtwarzania głównej HLS. Użyj pliku stream_manifest. Tylko HLS.
stream_manifest string

Plik manifestu strumienia. Odpowiada głównej playlistzie w HLS i MPD w DASH. To jedyne pole oprócz pola „stream_id”, które jest obecne w odpowiedzi podczas tworzenia strumienia z beaconem po stronie serwera.
media_verification_url string

URL 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ę. Jeśli jest puste, pomiń.

AppleTV

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

Adres URL kreacji interstii.

AdBreak

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

Dozwolone typy przerw to: w środku, przed i po.
start number

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

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

Lista reklam. Jeśli jest puste, pomiń.
Reklama – opis reklamy w strumieniu. Zawiera on 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

Identyfikator kreacji (opcjonalnie).
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, pomijana, jeśli jest pusta.
wrappers [object(Wrapper)]

Lista Wrappers. Jeśli jest puste, pomiń.
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 kreacje 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 w przypadku reklam możliwych do pominięcia. Jeśli jest ustawiona, oznacza to, że reklama jest możliwa do pominięcia i zawiera instrukcje dotyczące obsługi interfejsu pominięcia oraz zdarzenia śledzenia.
extensions string

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

Zdarzenie

Zdarzenie zawiera typ zdarzenia i czas jego wyświetlania.
Zapis JSON
{
  "time": number,
  "type": string,
}
Pola
time number

Czas prezentacji tego wydarzenia.
type string

Typ tego zdarzenia.

Podtytuł

Napisy – opisują ścieżkę z napisami do filmu. Przechowuje ona 2 formaty napisów: TTML i WebVTT. Atrybut TTMLPath zawiera adres URL pliku 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 'en'.
language_name string

Nazwa opisowa języka. pozwala odróżnić konkretny zestaw napisów, jeśli w przypadku tego samego języka istnieje ich więcej;
ttml string

Opcjonalny URL do pliku pomocniczego TTML.
webvtt string

Opcjonalny URL do pliku pomocniczego WebVTT.

SkipMetadata

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

Opóźnienie wskazuje czas w sekundach, przez jaki odtwarzacz powinien czekać na renderowanie przycisku pomijania. Pomijany, jeśli nie został podany w pliku 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 wrapper zawiera informacje o reklamie typu wrapper. Nie zawiera identyfikatora oferty, 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żytej w reklamie w ramce.
creative_ad_id string

Identyfikator reklamy kreacji użytej w reklamie z kodem towarzyszącym
deal_id string

Opcjonalny identyfikator umowy dla reklamy opakowującej.

Weryfikacja

Weryfikacja zawiera informacje dotyczące Open Measurement, które ułatwiają pomiar widoczności i weryfikację przez zewnętrznych dostawców. Obecnie obsługiwane są tylko zasoby JavaScript. Informacje 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 służących do weryfikacji
parameters string

Nieprzezroczysty ciąg znaków przekazany do kodu weryfikacyjnego bootstrapa.

JavaScriptResource

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

Identyfikator URI ładunku JavaScript.
api_framework string

APIFramework to nazwa platformy wideo, która wykonuje kod weryfikacyjny.
browser_optional boolean

Czy skrypt można uruchomić poza przeglądarką.

TrackingEvent

TrackingEvent zawiera adresy URL, które w określonych sytuacjach powinny być pingowane przez klienta.
Zapis JSON
{
  "event": string,
  "uri": string,
}
Pola
event string

Typ zdarzenia śledzenia.
uri string

Zdarzenie śledzenia, które ma być pingowane.

UniversalAdID

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

Uniwersalny identyfikator reklamy wybranej kreacji.
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ą wyświetlać się 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 tej kreacji towarzyszącej.
creative_type string

Atrybut CreativeType w węźle <StaticResource> w pliku VAST, jeśli jest to kreacja towarzysząca typu static.
height int32

Wysokość tego elementu w pikselach.
width int32

Szerokość tego elementu w pikselach.
resource string

W przypadku elementów towarzyszących statycznych i iframe będzie to adres URL, który ma być wczytywany i wyświetlany. W przypadku elementów towarzyszących w formacie HTML będzie to fragment kodu HTML, który powinien być wyświetlany jako element towarzyszący.
type string

Typ tego elementu towarzyszącego. Może być statyczny, iframe lub HTML.
ad_slot_id string

Identyfikator slotu dla tego urządzenia towarzyszącego.
api_framework string

Platforma interfejsu API dla tego urządzenia.
tracking_events [object(TrackingEvent)]

Lista zdarzeń śledzenia dla tego urządzenia towarzyszącego.

InteractiveFile

Plik InteractiveFile zawiera informacje o interaktywnych kreacjach (np. identyfikator SIMID), które powinny być wyświetlane 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 podawanego jako zasób.
variable_duration boolean

Czy ta kreacja może poprosić o przedłużenie czasu trwania.
ad_parameters string

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