Interfejs API VOD do dynamicznego wstawiania reklam

Interfejs Dynamic Ad Insertion API umożliwia zgłaszanie żądań związanych z DAI i ich śledzenie strumieni wideo na żądanie (VOD). Obsługiwane są strumienie HLS i DASH.

Usługa: dai.google.com

Ścieżka metody stream jest podawana w kierunku https://dai.google.com

Metoda: strumień

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

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

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

Tworzy strumień DASH DAI dla podanego ź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 przy tworzeniu strumienia musi być prawidłowy w sieci wydawcy.

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

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

Parametry ścieżki

Parametry
content-source string

Identyfikator CMS transmisji.

video-id string

Identyfikator filmu w strumieniu.

Treść żądania

Treść żądania jest typu application/x-www-form-urlencoded i zawiera następujące parametry:

Parametry
dai-ssb Opcjonalnie

Ustaw jako true, aby utworzyć strumień sygnalizowany po stronie serwera. Domyślna wartość to false. Śledzenie strumienia domyślnego jest inicjowany przez klienta i sprawdzany po stronie serwera.
Parametry kierowania w DFP Opcjonalnie Dodatkowe parametry kierowania.
Zastąp parametry strumienia Opcjonalnie Zastąp wartości domyślne parametru tworzenia strumienia.
Uwierzytelnianie HMAC Opcjonalnie Uwierzytelnij przy użyciu tokena opartego na HMAC.

Treść odpowiedzi

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

Open Measurement

Pole Verifications zawiera informacje o polu Otwórz Weryfikacja pomiarów w przypadku strumieni z sygnalizowaniem innym niż po stronie serwera. Verifications zawiera co najmniej 1 element Verification z listą zasobów i metadanych, które są potrzebne do zweryfikowania odtwarzania kreacji za pomocą kodu pomiarowego firmy zewnętrznej. Obsługiwana jest tylko wartość JavaScriptResource. Aby dowiedzieć się więcej, odwiedź IAB Tech Lab i specyfikacja VAST 4.1.

Metoda: weryfikacja multimediów

Gdy natrafisz na identyfikator multimediów podczas odtwarzania, od razu wykonaj za pomocą żądania media_verification_url z stream punktu końcowego. media_verification_url jest ścieżką bezwzględną. W przypadku strumieni beaconing po stronie serwera żądania weryfikacji mediów nie są konieczne. gdy serwer rozpoczyna weryfikację multimediów.

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

Metody
media verification GET {media_verification_url}/{ad_media_id}

Powiadamia API o zdarzeniu weryfikacji multimediów.

Żądanie HTTP

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

Treść odpowiedzi

media verification zwraca następujące odpowiedzi:

  • HTTP/1.1 204 No Content, jeśli weryfikacja mediów się uda i wysłane zostaną wszystkie pingi.
  • HTTP/1.1 404 Not Found, jeśli nie można zweryfikować multimediów z powodu nieprawidłowego formatowania adresu URL lub wygaśnięcia ważności.
  • HTTP/1.1 404 Not Found, jeśli wcześniejsza prośba o weryfikację została zrealizowana.
  • HTTP/1.1 409 Conflict, jeśli inne żądanie wysyła w tej chwili pingi.

Identyfikatory mediów reklamowych (HLS)

Identyfikatory mediów reklamowych będą kodowane w metadanych czasowych HLS za pomocą klucza TXXX, zarezerwowane na „informacje tekstowe zdefiniowane przez użytkownika” ramki. Zawartość ramki nie będą zaszyfrowane i zawsze będą się zaczynać od tekstu "google_".

Cała zawartość tekstowa ramki powinna być dodana do sekcji media_verification_url do każdego żądania weryfikacji reklam.

Identyfikatory mediów reklamowych (DASH)

Identyfikatory mediów reklam będą wstawiane do pliku manifestu za pomocą polecenia Element EventStream na stronie 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 zawierającym identyfikator multimediów reklamy zaczynający się od “google_”. Cała treść pliku messageData należy dołączyć atrybut media_verification_url do każdej reklamy o weryfikację.

Dane odpowiedzi

Strumień

Strumień jest używany do renderowania listy wszystkich zasobów nowo utworzonych zasobów 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

Strumień czasu trwania jest prawidłowy dla zakresu „00h00m00s” .
valid_until string

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

Lista napisów. Pomijany, jeśli pole jest puste. Dotyczy tylko HLS.
hls_master_playlist string

(WYCOFANO) URL playlisty reklamy nadrzędnej HLS. Użyj parametru stream_manifest. Dotyczy tylko HLS.
stream_manifest string

Plik manifestu strumienia. Odpowiada playlisty reklamy nadrzędnej w HLS i MPD w DASH. To jest jedyne pole oprócz „stream_id” znajduje się w odpowiedzi, gdy przez utworzenie strumienia sygnalizowania po stronie serwera.
media_verification_url string

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

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

Lista przerw na reklamy. Pomijany, jeśli pole jest puste.

AppleTV

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

URL reklam pełnoekranowych.

AdBreak

AdBreak opisuje pojedynczą przerwę na reklamę w strumieniu. Zawiera ona pozycję, czas trwania, rodzaj (połowa/przed/po) i lista reklam.
Zapis JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Pola
type string

Prawidłowe typy przerw na reklamy to: w trakcie, przed i po.
start number

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

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

Lista reklam. Pomijany, jeśli pole jest puste.
Reklama opisuje reklamę w strumieniu. Zawiera ona pozycję reklamy na przerwę, czas trwania reklamy i kilka opcjonalnych metadanych.
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 sekundach) w strumieniu, w której rozpoczyna się reklama.
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. Pomijany, jeśli pole jest puste.
events [object(Event)]

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

Opcjonalne wpisy weryfikacyjne Open Measurement zawierające listę zasobów i metadane wymagane 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 z tą reklamą.
interactive_file object(InteractiveFile)

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

Opcjonalne metadane reklam możliwych do pominięcia. Jeśli jest ustawiony, oznacza, że reklama jest możliwy do pominięcia i zawiera instrukcje dotyczące obsługi tego interfejsu. i śledzenie zdarzenia.

Zdarzenie

Wydarzenie zawiera typ wydarzenia i godzinę jego prezentacji.
Zapis JSON
{
  "time": number,
  "type": string,
}
Pola
time number

Czas prezentacji tego wydarzenia.
type string

Typ tego wydarzenia.

Podtytuł

Podtytuł opisuje dodatkową ścieżkę napisów do strumienia wideo. Magazyny w dwóch formatach: TTML i WebVTT. Atrybut TTMLPath zawiera adres URL do pliku pomocniczego TTML, a atrybut WebVTTPath ma podobnie do pliku pomocniczego WebVTT.
Zapis JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Pola
language string

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

Opisowa nazwa języka. Wyróżnia on określony zestaw napisy w przypadku kilku zestawów wersji dla tego samego języka.
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 reklamach możliwych do pominięcia.
Zapis JSON
{
  "offset": number,
  "tracking_url": string,
}
Pola
offset number

Przesunięcie wskazuje czas (w sekundach) odtwarzania reklamy przez odtwarzacz. powinien poczekać na wyrenderowanie przycisku pominięcia. Pomijany, jeśli nie podano go w VAST.
tracking_url string

Link monitorujący zawiera adres URL, który należy wysłać pingowi do 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

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

Paczka zawiera informacje o reklamie z kodem. Nie zawiera ona Identyfikator 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 z kodem.
creative_id string

Identyfikator kreacji używany na potrzeby reklamy z kodem.
creative_ad_id string

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

Opcjonalny identyfikator umowy dotyczącej reklamy z kodem towarzyszącym.

Weryfikacja

Weryfikacja zawiera informacje do Open Measurement, zewnętrzne pomiary widoczności i weryfikacji. Obecnie obsługiwane są tylko zasoby JavaScript. Więcej informacji znajdziesz na 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 usługi weryfikacyjnej.
java_script_resources [object(JavaScriptResource)]

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

Lista zdarzeń śledzenia na potrzeby weryfikacji.
parameters string

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

JavaScriptResource

JavaScriptResource zawiera informacje potrzebne do weryfikacji przez JavaScript.
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 działa kod weryfikacyjny.
browser_optional boolean

Czy ten skrypt można uruchomić poza w przeglądarce.

TrackingEvent

TrackingEvent zawiera adresy URL, które klient powinien wysłać ping na określonych w różnych sytuacjach.
Zapis JSON
{
  "event": string,
  "uri": string,
}
Pola
event string

Typ zdarzenia śledzenia.
uri string

Zdarzenie śledzenia do sprawdzenia.

UniversalAdID

UniversalAdID jest używany do przekazywania unikalnego identyfikatora kreacji, który jest i zachowane w różnych systemach reklamowych.
Zapis JSON
{
  "id_value": string,
  "id_registry": string,
}
Pola
id_value string

Uniwersalny identyfikator reklamy wybranej dla reklamy.
id_registry string

Ciąg znaków identyfikujący adres URL witryny rejestru, w której znajduje się parametr uniwersalnego identyfikatora reklamy wybranej kreacji.

Reklama towarzysząca

Kreacja towarzysząca zawiera informacje o reklamach towarzyszących, które mogą być wyświetlane 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 reklamy towarzyszącej.
creative_type string

Atrybut CreativeType w elemencie <StaticResource> węzła w VAST, jeśli jest to reklama towarzysząca typu statycznego.
height int32

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

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

W przypadku statycznych i towarzyszących elementów iframe będzie to URL do załadowania wyświetlenie. W przypadku reklam towarzyszących HTML jest to fragment kodu HTML, który powinien będzie wyświetlana jako kreacja towarzysząca.
type string

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

Identyfikator boksu towarzyszącego.
api_framework string

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

Lista zdarzeń śledzenia tej reklamy towarzyszącej.

InteractiveFile

Element InteractiveFile zawiera informacje o kreacji interaktywnej (np.identyfikator 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

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

Wartość parametru <AdParameters> w tagu VAST.