Blok reklamowy dynamicznego wstawiania reklam wyświetlający aktywny interfejs API

Interfejs Dynamic Ad Insertion API umożliwia zgłaszanie żądań transmisji na żywo z DAI i ich śledzenie.

Usługa: dai.google.com

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

Metoda: strumień

Metody
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Rejestruje blok DAI z dynamicznym wstawianiem reklam w sesji transmisji na żywo.

Żądanie HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Parametry ścieżki

Parametry
network_code string

Kod sieci Google Ad Managera wydawcy.

custom_asset_key string

Niestandardowy identyfikator powiązany z tym zdarzeniem w usłudze Google Ad Manager.

Treść żądania

Treść żądania jest typu application/x-www-form-urlencoded i zawiera następujące parametry:

Parametry
Parametry kierowania DFP Opcjonalnie Dodatkowe parametry kierowania.
Zastąp parametry strumienia Opcjonalnie Zastąp wartości domyślne parametru tworzenia strumienia.
Uwierzytelnianie HMAC Opcjonalnie Uwierzytelnij przy użyciu tokena opartego na HMAC.

Treść odpowiedzi

Jeśli operacja się uda, treść odpowiedzi będzie zawierała nowy obiekt Stream.

Open Measurement

Interfejs DAI API zawiera informacje potrzebne do weryfikacji Open Measurement w Verifications. To pole zawiera co najmniej jedno pole Elementy Verification zawierające listę zasobów i metadanych wymaganych do wykonania za pomocą kodu pomiarowego firmy zewnętrznej, by sprawdzić odtwarzanie kreacji. Tylko JavaScriptResource jest obsługiwany. Więcej informacji: IAB Tech Lab i Specyfikacja VAST 4.1.

Metoda: segment bloku reklamowego

Metody
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Tworzy strumień z dynamicznym wstawianiem reklam dla podanego identyfikatora zdarzenia.

Żądanie HTTP

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Parametry ścieżki

Parametry
network_code string

Kod sieci Google Ad Managera wydawcy.

custom_asset_key string

Niestandardowy identyfikator powiązany z tym zdarzeniem w usłudze Google Ad Manager.

pod_id integer

Identyfikator numeryczny bieżącej przerwy na reklamę. Obecne identyfikatory bloków reklamowych jest przypisywany stopniowo dla każdego zdarzenia, począwszy od 1.
profile_name string

nazwa z żądanych Profil kodowania DAI w usłudze Google Ad Manager. Profil kodujący musi być jednym ze skonfigurowanych profili kodowania dla wybrane zdarzenie.

segment_number integer

Indeks żądanego segmentu w bieżącym bloku reklamowym, zaczynając od zero.
segment_format string

Rozszerzenie pliku powiązane z żądanym formatem segmentu. Akceptowane rozszerzenia: ts, mp4, vtt, aac, ac3 lub eac3.

Parametry zapytania

Parametry
stream_id wymagane string

Identyfikator strumienia bieżącego użytkownika w sesji bieżącego użytkownika. Ta wartość jest zwracana przez funkcję pomyślne żądanie do punktu końcowego stream.
sd required1 integer

Czas trwania żądanego segmentu w milisekundach.
so opcjonalnie

Przesunięcie żądanego segmentu w bloku reklamowym (w milisekundach). Jeśli pominiesz parametr so, zostanie on obliczony przez mnożąc czas trwania segmentu przez jego numer.
pd wymagane2 integer

Czas trwania bloku reklamowego w milisekundach.
auth-token wymagane string

Podpisany, zakodowany w adresie URL Token HMAC w bieżącym bloku reklamowym.
last opcjonalnie boolean

Wskazuje ostatni segment przerwy na reklamę. Pomiń ten parametr we wszystkich z innych segmentów.
scte35 opcjonalnie string

Sygnał SCTE-35 zakodowany w Base64 na potrzeby tej przerwy na reklamę.
cust_params opcjonalnie string

Zestaw par klucz-wartość używanych do kierowania kampanii w usłudze Ad Manager. Te pary muszą być reprezentowane jako ciąg zapytania zakodowany w adresie URL.

Przykład:
Parametry
  • sekcja = sports
  • strona = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Przypisy

  1. Element sd nie jest wymagany do segmentów inicjowania. ↩
  2. Parametr pd nie jest wymagany w przypadku wydarzeń z reklamami bezterminowymi włączono przerwy. ↩

Treść odpowiedzi

Jeśli operacja się uda, treścią odpowiedzi będzie fragment strumienia z możliwością odtwarzania pasującą do format i parametry określone w żądaniu.

Metoda: szablon okresu bloku reklamowego DASH

Metody
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Wysyłam prośbę o szablon okresu DASH z Google Ad Managera. Ten szablon zawiera makra, które należy wypełnić parametrami strumienia. Jednorazowo gdy te makra są wypełnione, szablon staje się okresem przerwy na reklamę, możesz dołączyć do pliku manifestu DASH.

Żądanie HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Parametry ścieżki

Parametry
network_code string

Kod sieci Google Ad Managera wydawcy.

custom_asset_key string

Niestandardowy identyfikator powiązany z tym zdarzeniem w usłudze Google Ad Manager.

Parametry zapytania

Parametry
stream_id wymagane string

Identyfikator strumienia bieżącego użytkownika w sesji bieżącego użytkownika. Ta wartość jest zwracana przez funkcję pomyślne żądanie do punktu końcowego stream.

Treść odpowiedzi

Jeśli operacja się uda, treść odpowiedzi będzie zawierała nowy PodTemplateResponse.

Metoda: weryfikacja multimediów

Po napotkaniu identyfikatora multimediów podczas odtwarzania natychmiast wykonaj żądania przy użyciu parametru media_verification_url uzyskanego ze stream punktu końcowego powyżej. Te żądania nie są niezbędne do sygnalizowania po stronie serwera gdzie to serwer rozpoczyna 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 następujące odpowiedzi:

  • HTTP/1.1 204 No Content, jeśli weryfikacja multimediów zakończy się powodzeniem, a wszystkie pingi będą wysłano.
  • HTTP/1.1 404 Not Found, jeśli żądanie nie może zweryfikować multimediów z powodu błędu niepoprawny format adresu URL lub jego data wygaśnięcia.
  • HTTP/1.1 404 Not Found, jeśli została wysłana poprzednia prośba o weryfikację dla tego dokumentu udało się.
  • HTTP/1.1 409 Conflict, jeśli inna prośba wysyła już pingi w tym czasie obecnie się znajdujesz.

Identyfikatory mediów reklamowych

Identyfikatory mediów reklamowych będą zakodowane na osobnej ścieżce metadanych – z określonym opóźnieniem metadane strumienia transportu HLS lub emsg w przypadku plików mp4. Identyfikatory mediów reklamowych zawsze będzie się zaczynać ciągiem google_.

Cała zawartość tekstowa wpisu metadanych powinna być dołączana do reklamy adres URL do weryfikacji przed wysłaniem każdego żądania weryfikacji reklamy.

Metoda: metadane

Punkt końcowy metadanych w domenie metadata_url zwraca informacje użyte do utworzenia reklamy Interfejs. Punkt końcowy metadanych jest niedostępny w przypadku strumieni beaconing po stronie serwera. na której serwer jest odpowiedzialny za zainicjowanie weryfikacji mediów reklamowych.

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 wystąpienie PodMetadata

Analiza metadanych

Metadane składają się z 3 oddzielnych sekcji: tags, ads i reklamy breaks. Wpis do danych jest sekcja tags. Następnie przejrzyj tagi, i znajdź pierwszy wpis, którego nazwa jest prefiksem ad media ID znaleziony w strumieniu wideo. Na przykład: może mieć identyfikator multimediów reklamy, który wygląda tak:

google_1234567890

Następnie znajdziesz obiekt tagu o nazwie google_12345. W tym przypadku jest ona zgodna z identyfikator multimediów reklamy. Po znalezieniu właściwego obiektu prefiksu mediów reklamowych możesz wyszukać identyfikatory reklam, identyfikatory przerw na reklamę i typ zdarzenia. Identyfikatory reklam są następnie używane do indeksowania Obiekty ads i identyfikatory przerwy na reklamę są używane do indeksowania obiektów breaks.

Dane odpowiedzi

Strumień

Strumień jest używany do renderowania listy zasobów dla nowo utworzonego strumienia w Format JSON.
Zapis JSON
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
Pola
stream_id string

Identyfikator strumienia GAM.
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 służący do okresowego sprawdzania informacji o nadchodzących zdarzeniach reklamowych w transmisji.
session_update_url string

Adres URL aktualizacji sesji użyty do zaktualizowania parametrów kierowania w tym strumieniu. Pierwotne wartości parametrów kierowania są przechwytywane podczas wstępnego żądania utworzenia strumienia.
heartbeat_url string

adres URL pakietów podtrzymujących, używany do utrzymywania aktywności strumienia sygnalizowania po stronie serwera należy go sprawdzać co {Pollingfrequency} s. Wartość wypełniana w przypadku strumieni z sygnalizowaniem po stronie serwera.
polling_frequency number

Częstotliwość odpytywania (w sekundach) podczas żądania metadata_url lub heartbeat_url.
pod_manifest_url string

Szablon adresu URL pliku manifestu poda służy do generowania adresu URL służącego do pobierania pliku manifestu poda strumienia. odpowiadający adresowi URL playlisty z wieloma wariantami w pliku HLS lub MPD w DASH. Wartość wypełniana w przypadku wydarzeń transmitowanych na żywo typu POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

Format pliku manifestu to format pliku manifestu pobranego z pod_manifest_url. dash lub hls.

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 wartością type="progress" nie powinny być wywoływane do mediów reklamowych punktu końcowego weryfikacji.
Zapis JSON
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Pola
ad string

Identyfikator reklamy zawierającej ten tag.
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, typu (połowa/przed/po) i liczby reklam.
Zapis JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Pola
type string

Prawidłowe typy przerw na reklamy to: 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 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 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 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 pomijana, 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 elementów <Extension> i węzły w ramach 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.

PodTemplateResponse

PodTemplateResponse reprezentuje ładunek JSON zwrócony do VTP na potrzeby łączenia podów.
Zapis JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Pola
dash_period_template string

DashPeriodTemplate to szablon XML z okresem, w którym należy wstawić odpowiednie dane przed zszyciem.
segment_duration_ms int64

SegmentDurationMS to czas trwania segmentów okresów w milisekundach.

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 ona Identyfikator 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żywanej w reklamie z kodem.
creative_id string

Identyfikator kreacji używany na potrzeby reklamy z kodem.
creative_ad_id string

Identyfikator reklamy z kreacją używany na potrzeby reklamy z kodem.
deal_id string

Opcjonalny identyfikator umowy dotyczącej reklamy z kodem towarzyszącym.

Weryfikacja

Weryfikacja zawiera informacje do Open Measurement, 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ługi weryfikacyjnej.
java_script_resources [object(JavaScriptResource)]

Lista zasobów JavaScript na potrzeby 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, w której działa kod weryfikacyjny.
browser_optional boolean

Czy ten skrypt można uruchomić poza w przeglądarce.

TrackingEvent

TrackingEvent zawiera adresy URL, które klient powinien wysłać ping na określonych w różnych sytuacjach.
Zapis JSON
{
  "event": string,
  "uri": string,
}
Pola
event string

Typ zdarzenia śledzenia.
uri string

Zdarzenie śledzenia do sprawdzenia.

UniversalAdID

UniversalAdID jest używany do przekazywania unikalnego identyfikatora kreacji, który jest i zachowane 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 znajduje się parametr uniwersalnego identyfikatora reklamy wybranej kreacji.

Reklama towarzysząca

Kreacja towarzysząca 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 reklamy towarzyszącej.
creative_type string

Atrybut CreativeType w elemencie <StaticResource> węzła w VAST, jeśli jest to reklama towarzysząca 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 URL do załadowania wyświetlenie. W przypadku reklam towarzyszących HTML jest to fragment kodu HTML, który powinien będzie wyświetlana jako kreacja towarzysząca.
type string

Typ elementu towarzyszącego. 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

Element InteractiveFile zawiera informacje o kreacji interaktywnej (np.identyfikator SIMID). które powinny się wyświetlać 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

Czy ta kreacja może prosić o wydłużenie czasu trwania.
ad_parameters string

Wartość parametru <AdParameters> w tagu VAST.