Interfejs API dynamicznego wstawiania reklam

Interfejs Dynamicznego wstawiania reklam umożliwia wysyłanie żądań dotyczących linearnych transmisji DAI (na żywo) i śledzenie ich.

Usługa: dai.google.com

Wszystkie identyfikatory URI są względne względem https://dai.google.com

Metoda: stream

Metody
stream POST /linear/v1/hls/event/{assetKey}/stream

Tworzy strumień DAI dla podanego identyfikatora wydarzenia.

Żą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ć ważny w sieci wydawcy.

Klucz interfejsu API można przekazać w nagłówku autoryzacji HTTP w tym formacie, zamiast podawać go w treści żądania:

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

Parametry ścieżki

Parametry
assetKey string

Identyfikator zdarzenia strumienia.
Uwaga: klucz pliku strumienia to identyfikator, który można też znaleźć w  interfejsie Ad Managera.

Treść żądania

Treść żądania jest typu application/x-www-form-urlencoded i zawiera te parametry:

Parametry
dai-ssb Opcjonalny

Ustaw wartość true, aby utworzyć strumień z beaconowaniem po stronie serwera. Domyślna wartość to false. Śledzenie domyślnego strumienia jest inicjowane przez klienta i pingowane po stronie serwera.
Parametry kierowania DFP Opcjonalny Dodatkowe parametry kierowania.
Zastępowanie parametrów strumienia Opcjonalny Zastąp domyślne wartości parametru tworzenia strumienia.
Uwierzytelnianie HMAC Opcjonalny Uwierzytelnianie 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 sygnalizacją po stronie serwera ten parametr Stream zawiera tylko pola stream_id i stream_manifest.

Open Measurement

Interfejs DAI API zawiera informacje do weryfikacji Open Measurement w polu Verifications. To pole zawiera co najmniej 1 elementVerification, który zawiera listę zasobów i metadanych wymaganych do wykonania kodu pomiarowego innej firmy w celu weryfikacji 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 mediów

Po napotkaniu identyfikatora multimediów reklamy podczas odtwarzania natychmiast wyślij żądanie za pomocą parametru media_verification_url uzyskanego z punktu końcowego stream. Te żądania nie są potrzebne w przypadku strumieni sygnalizacji po stronie serwera, w których 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 interfejs API o zdarzeniu weryfikacji multimediów.

Żądanie HTTP

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

Treść odpowiedzi

media verificationzwraca te odpowiedzi:

  • HTTP/1.1 204 No Content jeśli weryfikacja multimediów zakończy się powodzeniem i wszystkie pingi zostaną wysłane.
  • 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.
  • HTTP/1.1 404 Not Found – jeśli poprzednia prośba o weryfikację tego dokumentu tożsamości została rozpatrzona pozytywnie.
  • HTTP/1.1 409 Conflict – jeśli w tym czasie inne żądanie już wysyła pingi.

Identyfikatory mediów reklamowych (HLS)

Identyfikatory multimediów reklamowych będą kodowane w metadanych czasowych HLS za pomocą kluczaTXXX, zarezerwowanego dla ramek „informacji tekstowych zdefiniowanych przez użytkownika”. Zawartość ramki będzie niezaszyfrowana i zawsze będzie się zaczynać od tekstu "google_".

Przed wysłaniem każdego żądania weryfikacji reklamy do adresu URL weryfikacji reklamy należy dołączyć całą zawartość tekstową ramki.

Metoda: metadane

Punkt końcowy metadanych pod adresem metadata_url zwraca informacje używane do tworzenia interfejsu reklamy. Punkt końcowy metadanych nie jest dostępny w przypadku strumieni z sygnalizacją po stronie serwera, w których serwer jest odpowiedzialny za inicjowanie weryfikacji multimediów reklamowych.

Metody
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Pobiera informacje o metadanych reklamy.

Żądanie HTTP

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

Parametry zapytania

Parametry
delta_token opcjonalnie string

Nieprzezroczysty token reprezentujący bieżący stan synchronizacji klienta. Jeśli zostanie podany, serwer zwraca w odpowiedzi tylko metadane, które uległy zmianie od czasu wygenerowania tokena, oraz nowy token next_delta_token. Jeśli zostanie pominięty, serwer zwróci pełne metadane dla całego okna DVR.

Treść odpowiedzi

Jeśli operacja się uda, odpowiedź będzie zawierała instancję obiektu PodMetadata.

Praca z metadanymi

Metadane składają się z 3 osobnych sekcji: tags, ads i reklamy breaks. Punktem wejścia do danych jest sekcja tags. Następnie przejrzyj tagi i znajdź pierwszy wpis, którego nazwa jest prefiksem identyfikatora multimediów reklamy znalezionego w strumieniu wideo. Możesz na przykład mieć identyfikator multimediów reklamy, który wygląda tak:

google_1234567890

Następnie znajdź obiekt tagu o nazwie google_12345. W tym przypadku jest on zgodny z identyfikatorem multimediów reklamy. Gdy znajdziesz odpowiedni obiekt z prefiksem multimediów reklamy, możesz wyszukać identyfikatory reklam, identyfikatory przerw na reklamę i typ zdarzenia. Identyfikatory reklam są następnie używane do indeksowania obiektów ads, a identyfikatory przerw na reklamy – do indeksowania obiektów breaks.

Dane odpowiedzi

Strumień

Strumień służy do renderowania listy zasobów dla 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, który służy do pobierania playlisty z wieloma wariantami w HLS lub pliku MPD w DASH.
hls_master_playlist string

(WYCOFANY) Adres URL playlisty HLS z wieloma wariantami. Zamiast niego użyj parametru „stream_manifest”.
media_verification_url string

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 sprawdzania informacji o nadchodzących zdarzeniach reklam w strumieniu.
session_update_url string

Adres URL aktualizacji sesji używany do aktualizowania parametrów kierowania w przypadku tej transmisji. Oryginalne wartości parametrów kierowania są rejestrowane podczas początkowego żądania utworzenia strumienia.
polling_frequency number

Częstotliwość odpytywania w sekundach podczas wysyłania żądania metadata_url lub heartbeat_url.

PodMetadata

PodMetadata zawiera metadane dotyczące reklam, przerw reklamowych i tagów identyfikatorów multimediów.
Zapis JSON
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
Pola
tags map[string, object(TagSegment)]

Mapa segmentów tagów indeksowanych według prefiksu tagu.
ads map[string, object(Ad)]

Mapa reklam indeksowanych według identyfikatora reklamy.
ad_breaks map[string, object(AdBreak)]

Mapa przerw na reklamy indeksowanych według identyfikatora przerwy na reklamę.
next_delta_token string

Nieprzejrzysty token, którego klient może użyć podczas następnego sondowania.
obsolete_ad_break_ids string

Lista identyfikatorów przerw na reklamy, które są przestarzałe i powinny zostać usunięte z pamięci podręcznej klienta.

TagSegment

TagSegment zawiera odniesienie do reklamy, przerwy na reklamę i typu zdarzenia. Do punktu końcowego weryfikacji multimediów reklamy nie należy wysyłać pingów do elementu TagSegment z atrybutem type="progress".
Zapis JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Pola
ad string

Identyfikator reklamy tego tagu.
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 (w trakcie, przed lub po) i liczbę reklam.
Zapis JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Pola
type string

Prawidłowe typy podziału to: pre, mid i post.
duration number

Łączny czas trwania reklam w tej przerwie na reklamę (w sekundach).
expected_duration number

Przewidywany czas trwania przerwy na reklamę (w sekundach), obejmujący wszystkie reklamy i plansze.
ads number

Liczba reklam w przerwie na reklamę.
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ę tej reklamy.
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 powiązanej 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 weryfikacji Open Measurement, które zawierają listę zasobów i metadanych wymaganych do wykonania kodu pomiarowego firmy zewnętrznej w celu weryfikacji odtwarzania kreacji.
slate boolean

Opcjonalna wartość logiczna wskazująca, że bieżący wpis jest tablicą.
icons [object(Icon)]

Lista ikon, pominięta, jeśli jest pusta.
wrappers [object(Wrapper)]

Lista elementów opakowujących, pominięta, jeśli jest pusta.
universal_ad_id object(UniversalAdID)

Opcjonalny uniwersalny identyfikator reklamy.
extensions string

Opcjonalna lista wszystkich węzłów <Extension> w VAST.
companions [object(Companion)]

Opcjonalne elementy 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.

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 opakowujący zawiera informacje o reklamie opakowującej. 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żywany w reklamie opakowującej.
creative_id string

Identyfikator kreacji użyty w reklamie w kodzie towarzyszącym.
creative_ad_id string

Identyfikator reklamy powiązanej z kreacją używany w reklamie w kodzie towarzyszącym.
deal_id string

Opcjonalny identyfikator umowy dotyczący reklamy opakowującej.

Weryfikacja

Weryfikacja zawiera informacje o Open Measurement, które ułatwiają pomiar widoczności i weryfikacji przez firmy zewnętrzne. Obecnie obsługiwane są tylko zasoby JavaScript. Więcej informacji 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 weryfikacji.
parameters string

Nieprzezroczysty ciąg znaków przekazywany do kodu weryfikacyjnego rozruchu.

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 JavaScript.
api_framework string

APIFramework to nazwa platformy wideo, która używa kodu weryfikacyjnego.
browser_optional boolean

Określa, czy ten skrypt można uruchomić poza przeglądarką.

TrackingEvent

TrackingEvent zawiera adresy URL, do których klient powinien wysyłać pingi w określonych sytuacjach.
Zapis JSON
{
  "event": string,
  "uri": string,
}
Pola
event string

Typ zdarzenia śledzenia.
uri string

Zdarzenie śledzenia, które ma zostać wysłane.

UniversalAdID

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

Uniwersalny identyfikator reklamy wybranej kreacji reklamy.
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ą się wyświetlać obok reklamy.
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 tagu VAST, jeśli jest to reklama towarzysząca typu statycznego.
height int32

Wysokość tego elementu towarzyszącego w pikselach.
width int32

Szerokość tego elementu towarzyszącego w pikselach.
resource string

W przypadku statycznych reklam towarzyszących i reklam towarzyszących w ramce iframe będzie to adres URL, który ma zostać wczytany i wyświetlony. W przypadku reklam towarzyszących w formacie HTML będzie to fragment kodu HTML, który powinien być wyświetlany jako reklama towarzysząca.
type string

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

Identyfikator miejsca na reklamy towarzyszące.
api_framework string

Platforma interfejsu API tego komponentu.
tracking_events [object(TrackingEvent)]

Lista zdarzeń śledzenia w przypadku tego komponentu towarzyszącego.

InteractiveFile

InteractiveFile zawiera informacje o interaktywnej kreacji (np. SIMID), która powinna być wyświetlana 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 podanego jako zasób.
variable_duration boolean

Czy w przypadku tej kreacji można poprosić o przedłużenie czasu trwania.
ad_parameters string

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