Interfejs API dynamicznego wstawiania reklam

Interfejs API dynamicznego wstawiania reklam umożliwia wysyłanie żądań i śledzenie żądań linearnych transmisji na żywo z funkcją DAI.

Usługa: dai.google.com

Wszystkie identyfikatory URI wymienione poniżej odnoszą się do elementu https://dai.google.com

Metoda: stream

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

Tworzy strumień z dynamicznym wstawianiem reklam dla danego 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 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
assetKey string

Identyfikator zdarzenia strumienia.
Uwaga: klucz zasobu 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 Opcjonalnie

Aby utworzyć strumień z sygnalizowaniem po stronie serwera, ustaw wartość true. Domyślna wartość to false. Śledzenie strumienia jest inicjowane przez klienta i wysyłane przy użyciu polecenia ping po stronie serwera.
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

Interfejs DAI API zawiera w polu Verifications informacje potrzebne do weryfikacji Open Measurement. To pole zawiera co najmniej 1 element Verification, który zawiera listę zasobów i metadanych wymaganych do wykonania kodu pomiarowego firmy zewnętrznej w celu zweryfikowania odtwarzania kreacji. 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 przy użyciu parametru media_verification_url uzyskanego z punktu końcowego stream powyżej. Żądania te nie są konieczne w przypadku strumieni sygnału 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 https://{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 czasowych HLS za pomocą klucza TXXX, który jest zarezerwowany dla ramek „informacji tekstowych zdefiniowanych przez użytkownika”. Zawartość ramki będzie niezaszyfrowana i zawsze będzie zaczynać się od tekstu "google_".

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

Metoda: metadane

Punkt końcowy metadanych w witrynie metadata_url zwraca informacje użyte do utworzenia interfejsu reklamy. Punkt końcowy metadanych nie jest dostępny w przypadku strumieni śledzenia po stronie serwera, w przypadku których serwer odpowiada za zainicjowanie weryfikacji medió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}

Treść odpowiedzi

Jeśli operacja się uda, odpowiedź zwróci wystąpienie obiektu PodMetadata.

Praca z metadanymi

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

google_1234567890

Zobaczysz obiekt tagu o nazwie google_12345. W tym przypadku jest to identyfikator mediów reklamy. Po znalezieniu odpowiedniego obiektu prefiksu multimediów reklamowych 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 reklamę – do indeksowania obiektów breaks.

Dane odpowiedzi

Transmisja

Strumień jest używany 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.
stream_manifest string

Plik manifestu strumienia odpowiadający playliście reklamy nadrzędnej w HLS lub plikowi 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.
hls_master_playlist string

(WYCOFANE) URL playlisty reklamy nadrzędnej HLS. Zamiast niego użyj parametru „stream_manifest”.
media_verification_url string

URL do weryfikacji mediów.
metadata_url string

Adres URL metadanych multimediów reklam.
session_update_url string

URL aktualizacji sesji.
polling_frequency number

Zalecana częstotliwość odpytywania adresów URL metadanych w sekundach.

PodMetadata

PodMetadata zawiera informacje o reklamach, przerwach na reklamy i tagach identyfikatorów medió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 zindeksowanych 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 wartością type="progress" nie powinien być wywoływany pingiem do punktu końcowego weryfikacji mediów reklamowych.
Zapis JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Pola
ad string

Identyfikator reklamy powiązanej z tym tagiem.
ad_break_id string

Identyfikator przerwy na reklamę w tym tagu.
type string

Typ zdarzenia tego tagu.

AdBreak

Przerwa na reklamę opisuje pojedynczą przerwę na reklamę w strumieniu. Zawiera czas trwania, typ (w środku/przed/po) i liczbę reklam.
Zapis JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Pola
type string

Prawidłowe typy przerw: przed, w trakcie 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 każdej planszy.
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ę w danej 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 kreacji.
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 listę zasobów i metadanych wymaganych do wykonania kodu pomiarowego firmy zewnętrznej w celu zweryfikowania odtwarzania kreacji.
slate boolean

Opcjonalna wartość logiczna wskazująca, że obecny wpis to Slate.
icons [object(Icon)]

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

Lista kodów towarzyszących, pomijana, jeśli jest pusta.
universal_ad_id object(UniversalAdID)

Opcjonalny uniwersalny identyfikator reklamy.
extensions string

Opcjonalna lista wszystkich węzłów <rozszerzenia> w tagu VAST.
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.

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.