Interfejs API dynamicznego wstawiania reklam

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.
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 Opcjonalny

Ustaw jako true, aby utworzyć strumień sygnalizowany po stronie serwera. Domyślna wartość to false. Śledzenie strumienia domyślnego jest inicjowane przez klienta i pingowane po stronie serwera.
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 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.