Interfejs Dynamic Ad Insertion API pozwala wysyłać żądania linearnych transmisji DAI i śledzić je.
Usługa: dai.google.com
Wszystkie identyfikatory URI wymienione poniżej odnoszą się do elementu https://dai.google.com
Metoda: strumień
Metody | |
---|---|
stream |
POST /linear/v1/hls/event/{assetKey}/stream
Tworzy strumień z dynamicznym wstawianiem reklam dla podanego identyfikatora zdarzenia. |
Żądanie HTTP
POST https://dai.google.com/linear/v1/hls/event/{assetKey}/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ący sposób: Authorization: DCLKDAI key="<api-key>" |
Parametry ścieżki
Parametry | |
---|---|
assetKey |
string Identyfikator zdarzenia strumienia. |
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
Interfejs DAI API zawiera informacje potrzebne do weryfikacji w ramach Open Measurement w polu Verifications
. To pole zawiera co najmniej 1 element Verification
podający zasoby i metadane wymagane do wykonania kodu pomiarowego firmy zewnętrznej w celu zweryfikowania odtwarzania kreacji. 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 natrafisz na identyfikator multimediów reklamy podczas odtwarzania, natychmiast wyślij żądanie, używając parametru media_verification_url uzyskanego z punktu końcowego stream powyżej. Nie są one konieczne w przypadku strumieni sygnalizowania po stronie serwera, w których to 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 https://{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 dla 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 weryfikacyjnego adresu URL przed wysłaniem każdego żądania weryfikacji reklamy.
Metoda: metadane
Punkt końcowy metadanych w domenie metadata_url
zwraca informacje użyte do utworzenia interfejsu reklamy. Punkt końcowy metadanych nie jest dostępny w przypadku strumieni beaconing po stronie serwera, gdzie to serwer odpowiada za rozpoczęcie weryfikacji multimediów reklam.
Metody | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
Pobiera informacje o metadanych reklam. |
Żądanie HTTP
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
Treść odpowiedzi
Jeśli operacja się uda, odpowiedź zwróci instancję PodMetadata
.
Praca z metadanymi
Metadane składają się z 3 oddzielnych sekcji: tags
, ads
i reklamy breaks
. Punktem wejścia do danych jest sekcja tags
. Następnie przejrzyj tagi, by znaleźć pierwszy wpis, którego nazwa jest prefiksem identyfikatora mediów reklamowych znalezionego w strumieniu wideo. Możesz na przykład mieć identyfikator multimediów reklamy podobny do tego:
google_1234567890
Następnie znajdziesz obiekt tagu o nazwie google_12345
. W tym przypadku jest on zgodny
z identyfikatorem mediów w reklamie. Gdy znajdziesz odpowiedni obiekt prefiksu mediów reklamowych, możesz wyszukać identyfikatory reklam, identyfikatory przerw na reklamę i typ zdarzenia. Identyfikatory reklam służą do indeksowania obiektów ads
, a identyfikatory przerw na reklamę do indeksowania obiektów breaks
.
Dane odpowiedzi
Strumień
Strumień jest używany do renderowania listy zasobów nowo utworzonego strumienia w formacie JSON.Zapis JSON |
---|
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, } |
Pola | |
---|---|
stream_id |
string Identyfikator strumienia GAM. |
stream_manifest |
string Adres URL pliku manifestu strumienia używany do pobierania playlisty z wieloma wariantami w formacie HLS lub MPD w DASH. |
hls_master_playlist |
string (WYCOFANY) URL playlisty z wieloma wariantami HLS. Zamiast niego użyj parametru „stream_manifest”. |
media_verification_url |
string Adres URL do weryfikacji multimediów używany jako podstawowy punkt końcowy do śledzenia zdarzeń odtwarzania. |
metadata_url |
string Adres URL metadanych używany do okresowego ankietowania informacji o nadchodzących zdarzeniach reklamowych w strumieniu. |
session_update_url |
string Adres URL aktualizacji sesji używany do zaktualizowania parametrów kierowania w tym strumieniu. Pierwotne wartości parametrów kierowania są przechwytywane podczas wstępnego żądania utworzenia strumienia. |
polling_frequency |
number Częstotliwość odpytywania (w sekundach) podczas żądania metadata_url z adresu lub heartbeat_url. |
PodMetadata
Metadane PodMetadata zawierają informacje o reklamach, przerwach na reklamy i tagach identyfikatorów multimediów.Zapis JSON |
---|
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], } |
Pola | |
---|---|
tags |
map[string, object(TagSegment)] Mapa segmentów tagów indeksowanych według prefiksu tagu. |
ads |
map[string, object(Ad)] Mapa reklam zindeksowanych według identyfikatora reklamy. |
ad_breaks |
map[string, object(AdBreak)] Mapa przerw na reklamę zindeksowanych według identyfikatora przerwy na reklamę. |
TagSegment
TagSegment zawiera odwołanie do reklamy, jej przerwy na reklamę i typu zdarzenia. TagSegment z typem="progress" nie powinien być wywoływany pingiem do punktu końcowego weryfikacji mediów reklam.Zapis JSON |
---|
{ "ad": string, "ad_break_id": string, "type": string, } |
Pola | |
---|---|
ad |
string Identyfikator reklamy z tym tagiem. |
ad_break_id |
string Identyfikator przerwy na reklamę w tym tagu. |
type |
string Typ zdarzenia tego tagu. |
AdBreak
AdBreak opisuje pojedynczą przerwę na reklamę w strumieniu. Zawiera czas trwania, typ (połowa/przed/po) i liczbę reklam.Zapis JSON |
---|
{ "type": string, "duration": number, "expected_duration": number, "ads": number, } |
Pola | |
---|---|
type |
string Prawidłowe typy przerw na reklamy to: przed, w środku i po. |
duration |
number Łączny czas trwania tej przerwy na reklamę (w sekundach). |
expected_duration |
number Oczekiwany czas trwania przerwy na reklamę (w sekundach) z uwzględnieniem wszystkich reklam i plansz. |
ads |
number Liczba reklam w przerwie na reklamę. |
Reklama
Reklama opisuje reklamę w strumieniu.Zapis JSON |
---|
{ "ad_break_id": string, "position": 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, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
Pola | |
---|---|
ad_break_id |
string Identyfikator przerwy na reklamę w tej reklamie. |
position |
number Pozycja tej reklamy w przerwie na reklamę, zaczynając od 1. |
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. |
click_tracking_urls |
string Opcjonalne linki monitorujące kliknięcia. |
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. |
slate |
boolean Opcjonalna wartość logiczna wskazująca, że bieżący wpis to Slate. |
icons |
[object(Icon)] Lista ikon, jeśli jest pusta. |
wrappers |
[object(Wrapper)] Lista kodów towarzyszących tagów, pomijana, jeśli jest pusta. |
universal_ad_id |
object(UniversalAdID) Opcjonalny uniwersalny identyfikator reklamy. |
extensions |
string Opcjonalna lista wszystkich węzłów <Extension> w szablonie VAST. |
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. |
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. |