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 w 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: |
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 |
||||
sd |
required1
|
integer
Czas trwania żądanego segmentu w milisekundach. |
||||
so |
opcjonalnie |
Przesunięcie żądanego segmentu w bloku reklamowym (w milisekundach).
Jeśli pominiesz parametr |
||||
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:
|
Przypisy
-
Element
sd
nie jest wymagany do segmentów inicjowania. ↩ -
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 |
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 typu „heartbeat” 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
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żywany 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. |