Interfejs Dynamic Ad Insertion API umożliwia zgłaszanie żądań strumieni DAI do filmów na żądanie i śledzenie ich dostępności. 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.
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 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 transmisji. |
video-id |
string Identyfikator filmu w strumieniu. |
Treść żądania
Treść żądania jest typu application/x-www-form-urlencoded
i zawiera te parametry:
Parametry | ||
---|---|---|
dai-ssb |
Opcjonalny | Ustaw jako |
Parametry kierowania w 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 obiekt Stream
. W przypadku strumieni z sygnalizowaniem po stronie serwera ta kolumna Stream
zawiera tylko pola stream_id
i stream_manifest
.
Open Measurement
Pole Verifications
zawiera informacje potrzebne do weryfikacji w ramach Open Measurement w przypadku strumieni z sygnalizowaniem innym niż po stronie serwera.
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 na stronie IAB Tech Lab i w specyfikacji VAST 4.1.
Metoda: weryfikacja multimediów
Gdy podczas odtwarzania natrafisz na identyfikator multimediów reklamowych, natychmiast wyślij żądanie za pomocą pola 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 z sygnalizowaniem po stronie serwera, gdy serwer inicjuje 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 te 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 reklam będą kodowane w metadanych czasowych HLS za pomocą klucza TXXX
, zarezerwowanego na potrzeby ramek „zdefiniowane przez użytkownika”. Zawartość ramki nie będzie zaszyfrowana i zawsze będzie się zaczynała od tekstu "google_"
.
Cały tekst ramki powinien być dołączony do parametru media_verification_url w przypadku każdego żądania weryfikacji reklamy.
Identyfikatory mediów reklamowych (DASH)
Identyfikatory mediów reklam będą 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
zawierającym identyfikator mediów reklamowych zaczynający się od “google_”
. Do każdego żądania weryfikacji reklam należy dołączyć całą zawartość atrybutu messageData
do media_verification_url.
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 Strumień o czasie trwania jest prawidłowy w przypadku formatu „00h00m00s”. |
valid_until |
string Data ważności strumienia do tego czasu podana w formacie RFC 3339. |
subtitles |
[object(Subtitle)] Lista napisów. Pomijany, jeśli pole jest puste. Dotyczy tylko HLS. |
hls_master_playlist |
string (WYCOFANY) 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. Jest to jedyne pole oprócz „stream_id”, które występuje w odpowiedzi podczas tworzenia 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 Adres URL reklamy pełnoekranowej. |
AdBreak
AdBreak opisuje pojedynczą przerwę na reklamę w strumieniu. Zawiera informacje o pozycji, czasie trwania, typie (połowa lub przed datą) oraz listę 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 strumieniu, w której rozpoczyna się przerwa (w sekundach). |
duration |
number Czas trwania przerwy na reklamę w sekundach. |
ads |
[object(Ad)] Lista reklam. Pomijany, jeśli pole jest puste. |
Reklama
Reklama opisuje reklamę w strumieniu. Zawiera on pozycję reklamy w przerwie, czas trwania reklamy 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 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 z kreacją. |
deal_id |
string Opcjonalny identyfikator umowy. |
clickthrough_url |
string Opcjonalny docelowy URL. |
icons |
[object(Icon)] Lista ikon, jeśli jest pusta. |
wrappers |
[object(Wrapper)] Lista kodów towarzyszących kreacji. Pomijany, jeśli pole jest puste. |
events |
[object(Event)] Lista zdarzeń w reklamie. |
verifications |
[object(Verification)] Opcjonalne wpisy weryfikacyjne Open Measurement zawierające zasoby 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. |
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 zdarzenia. |
Podtytuł
Podtytuł opisuje dodatkową ścieżkę napisów do strumienia wideo. Przechowuje napisy w 2 formatach: TTML i WebVTT. Atrybut TTMLPath zawiera adres URL pliku pomocniczego języka 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, np. „en” lub „de”. |
language_name |
string Opisowa nazwa języka. Pozwalają rozróżnić konkretny zestaw napisów, jeśli istnieje wiele zestawów napisów dla tego samego języka. |
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
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 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 z kodem towarzyszącym. |
creative_id |
string Identyfikator kreacji używany na potrzeby reklamy z kodem towarzyszącym. |
creative_ad_id |
string Identyfikator reklamy z kreacją używany na potrzeby reklamy z kodem. |
deal_id |
string Opcjonalny identyfikator umowy dla reklamy z kodem towarzyszącym. |
Weryfikacja
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 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ług weryfikacyjnych. |
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 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, która uruchamia kod weryfikacyjny. |
browser_optional |
boolean Określenie, czy ten 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 do pingowania. |
UniversalAdID
UniversalAdID służy do podawania unikalnego identyfikatora kreacji, używanego 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 jest katalogowany uniwersalny identyfikator reklamy wybranej kreacji. |
Reklama towarzysząca
Element towarzyszący 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 tej reklamy towarzyszącej. |
creative_type |
string Atrybut CreativeType w węźle <StaticResource> w VAST, jeśli jest elementem towarzyszącym 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 adres URL do wczytania i wyświetlania. W przypadku kreacji towarzyszących HTML będzie to fragment kodu HTML, który powinien być wyświetlany jako kreacja towarzysząca. |
type |
string Typ tej kreacji towarzyszącej. 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
Plik InteractiveFile zawiera informacje o kreacji interaktywnej (tj. 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 kreacji interaktywnej. |
type |
string Typ MIME pliku dostarczonego jako zasób. |
variable_duration |
boolean Określenie, czy kreacja może poprosić o wydłużenie czasu trwania. |
ad_parameters |
string Wartość węzła <AdParameters> w VAST. |