Interfejs API dynamicznego wstawiania reklam umożliwia wysyłanie żądań i śledzenie strumieni wideo na żądanie (VOD) z funkcją DAI. Obsługiwane są strumienie HLS i DASH.
Usługa: dai.google.com
Ścieżka metody stream
jest względna wobec ścieżki 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 wideo.
Tworzy strumień z dynamicznym wstawianiem reklam DASH 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 podczas tworzenia strumienia musi być prawidłowy dla sieci wydawcy. Zamiast podawać go w treści żądania, klucz interfejsu API można przekazać w nagłówku autoryzacji HTTP w takim 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 |
Opcjonalnie | Aby utworzyć strumień z sygnalizowaniem po stronie serwera, ustaw wartość |
Parametry kierowania DFP | Opcjonalnie | Dodatkowe parametry kierowania. |
Zastąp parametry strumienia | Opcjonalnie | Zastąp domyślne wartości parametru tworzenia strumienia. |
Uwierzytelnianie HMAC | Opcjonalnie | 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 Stream
zawiera tylko pola stream_id
i stream_manifest
.
Open Measurement
Pole Verifications
zawiera informacje na potrzeby weryfikacji Open Measurement w przypadku strumieni z sygnalizowaniem po stronie innego niż serwer.
Verifications
zawiera co najmniej 1 element Verification
z 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
Po znalezieniu identyfikatora multimediów reklamy podczas odtwarzania od razu wyślij żądanie za pomocą media_verification_url
z punktu końcowego stream
. Element media_verification_url
jest ścieżką bezwzględną.
Żądania weryfikacji mediów nie są konieczne w przypadku transmisji strumieniowych po stronie serwera, gdy serwer inicjuje 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 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 i wysłane będą wszystkie pingi.HTTP/1.1 404 Not Found
, jeśli żądanie nie może zweryfikować multimediów z powodu nieprawidłowego formatowania adresu URL lub daty wygaśnięcia.HTTP/1.1 404 Not Found
, jeśli poprzednia prośba o weryfikację tego identyfikatora została zrealizowana.HTTP/1.1 409 Conflict
, jeśli inne żądanie wysyła już pingi w tym czasie.
Identyfikatory mediów reklamowych (HLS)
Identyfikatory mediów reklamowych będą kodowane w metadanych zsynchronizowanych z częstotliwością HLS za pomocą klucza TXXX
i rezerwowane na potrzeby ramek „informacji tekstowych zdefiniowanych przez użytkownika”. Zawartość ramki nie będzie zaszyfrowana i zawsze będzie zaczynać się od tekstu "google_"
.
Cała zawartość tekstowa ramki powinna być dołączana do elementu media_verification_url w przypadku każdego żądania weryfikacji reklam.
Identyfikatory mediów reklam (DASH)
Identyfikatory mediów reklamowych zostaną wstawione 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
zawierającym identyfikator mediów reklamy zaczynający 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
Transmisja
Strumień jest używany 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 w sekundach. |
content_duration |
number Czas trwania treści bez reklam, w sekundach. |
valid_for |
string Czas trwania strumienia jest prawidłowy dla: w formacie „00h00m00s”. |
valid_until |
string Data ważności strumienia do dnia podana w formacie RFC 3339. |
subtitles |
[object(Subtitle)] Lista napisów. Pomijana, jeśli jest pusta. Tylko HLS. |
hls_master_playlist |
string (WYCOFANE) 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ę Pominięta, 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ę na reklamę w strumieniu. Zawiera pozycję, czas trwania, typ (w trakcie trwania/przed/post) i listę reklam.Zapis JSON |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
Pola | |
---|---|
type |
string Prawidłowe typy przerwy na reklamę to: w trakcie dnia, przed i po. |
start |
number Pozycja w strumieniu (w sekundach), od której rozpoczyna się przerwa. |
duration |
number Czas trwania przerwy na reklamę w sekundach. |
ads |
[object(Ad)] Lista reklam. Pominięta, jeśli pole jest puste. |
Reklama
Reklama opisuje reklamę w strumieniu. Zawiera pozycję reklamy w przerwie i czas jej trwania oraz 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), } |
Pola | |
---|---|
seq |
number Pozycja reklamy w przerwie. |
start |
number Pozycja w strumieniu, na której zaczyna 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 kreacji. |
deal_id |
string Opcjonalny identyfikator umowy. |
clickthrough_url |
string Opcjonalny docelowy URL. |
icons |
[object(Icon)] Lista ikon pomijanych, jeśli jest pusta. |
wrappers |
[object(Wrapper)] Lista kodów towarzyszących Pominięta, jeśli pole jest puste. |
events |
[object(Event)] Lista zdarzeń występujących w reklamie. |
verifications |
[object(Verification)] Opcjonalne wpisy weryfikacyjne Open Measurement zawierające listę zasobów i metadanych wymaganych do wykonania kodu pomiarowego firmy zewnętrznej w celu zweryfikowania odtwarzania kreacji. |
universal_ad_id |
object(UniversalAdID) Opcjonalny uniwersalny identyfikator reklamy. |
companions |
[object(Companion)] Opcjonalne elementy towarzyszące, które mogą wyświetlać się razem z tą reklamą. |
interactive_file |
object(InteractiveFile) Opcjonalna kreacja interaktywna (SIMID), która powinna wyświetlać się podczas odtwarzania reklamy. |
Zdarzenie
Wydarzenie zawiera typ wydarzenia i czas jego prezentacji.Zapis JSON |
---|
{ "time": number, "type": string, } |
Pola | |
---|---|
time |
number Czas prezentacji tego wydarzenia. |
type |
string Typ tego wydarzenia. |
Podtytuł
Napisy opisują pomocniczą ścieżkę napisów ze strumienia wideo. Zapisuje on 2 formaty napisów: TTML i WebVTT. Atrybut TTMLPath zawiera adres URL pliku pomocniczego TTML, a atrybut WebVTTPath – podobnie jak adres URL pliku pomocniczego WebVTT.Zapis JSON |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
Pola | |
---|---|
language |
string Kod języka, na przykład „pl” lub „de”. |
language_name |
string Opisowa nazwa języka. Pozwala rozróżnić 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. |
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
Element ClickData zawiera informacje o kliknięciu ikony.Zapis JSON |
---|
{ "url": string, } |
Pola | |
---|---|
url |
string |
FallbackImage
Obraz 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
Kod zawiera informacje o reklamie. 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żyty w reklamie towarzyszącej. |
creative_ad_id |
string Identyfikator reklamy z kreacją używaną na potrzeby reklamy towarzyszącej. |
deal_id |
string Opcjonalny identyfikator umowy dla reklamy z kodem. |
Weryfikacja
Funkcja Weryfikacja zawiera informacje na potrzeby Open Measurement, które ułatwiają zewnętrzne pomiary widoczności i weryfikacji. 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 usługi weryfikacji. |
java_script_resources |
[object(JavaScriptResource)] Lista zasobów JavaScript do weryfikacji. |
tracking_events |
[object(TrackingEvent)] Lista zdarzeń śledzenia na potrzeby weryfikacji. |
parameters |
string Nieprzejrzysty ciąg 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 JavaScriptu. |
api_framework |
string APIFramework to nazwa platformy wideo, w której stosuje się kod weryfikacyjny. |
browser_optional |
boolean Czy ten skrypt może być uruchamiany poza przeglądarką. |
TrackingEvent
TrackingEvent zawiera adresy URL, które w określonych sytuacjach powinny zostać pingowane przez klienta.Zapis JSON |
---|
{ "event": string, "uri": string, } |
Pola | |
---|---|
event |
string Typ zdarzenia śledzenia. Obecnie jedyną dostępną opcją jest „verificationNotExecuted” zgodnie ze specyfikacją VAST 4.1. |
uri |
string Zdarzenie śledzenia do sprawdzenia za pomocą polecenia ping. |
UniversalAdID
Identyfikator UniversalAdID służy do dostarczania unikalnego identyfikatora kreacji, który jest obsługiwany 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 służący do identyfikacji adresu 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ą wyświetlać się razem z reklamą.Zapis JSON |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, } |
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 kreacja towarzysząca typu statycznego. |
height |
int32 Wysokość reklamy towarzyszącej w pikselach. |
width |
int32 Szerokość reklamy towarzyszącej w pikselach. |
resource |
string W przypadku statycznych elementów towarzyszących i elementów iframe będzie to adres URL, który zostanie wczytany i wyświetlony. W przypadku towarzyszących elementów 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. |
InteractiveFile
Plik InteractiveFile zawiera informacje na temat kreacji interaktywnej (tj. SIMID), które należy wyświetlić 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 udostępnionego jako zasób. |
variable_duration |
boolean Czy kreacja może prosić o wydłużenie czasu trwania. |
ad_parameters |
string Wartość węzła <AdParameters> w tagu VAST. |