Interfejs API Google do wyświetlania bloków reklamowych z dynamicznym wstawianiem reklam umożliwia wstawianie reklam po stronie serwera za pomocą technologii Google Ads, a jednocześnie umożliwia kontrolę nad samodzielnym łączeniem filmów.
Z tego przewodnika dowiesz się, jak korzystać z interfejsu Pod Serving API i uzyskać podobne funkcje za pomocą pakietu IMA DAI SDK. Jeśli masz konkretne pytania na temat obsługiwanych funkcji, skontaktuj się ze swoim opiekunem klienta w Google.
Interfejs Pod Serving API obsługuje strumienie wyświetlania podów w protokołach strumieniowania HLS lub MPEG-DASH. Ten przewodnik skupia się na strumieniach HLS i przedstawia najważniejsze różnice między HLS a MPEG-DASH w poszczególnych krokach.
Aby zintegrować interfejs Pod Serving API z aplikacją na potrzeby strumieni VOD:
Przesyłanie do Ad Managera prośby o rejestrację strumienia
Wyślij żądanie POST do punktu końcowego rejestracji strumienia. Z kolei otrzymasz odpowiedź JSON zawierającą identyfikator strumienia, który należy wysłać do serwera manipulacji plikiem manifestu, i powiązanych punktów końcowych interfejsu Pod Serving API.
Punkt końcowy interfejsu API
POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
Parametry ścieżki
{network_code} |
Twój kod sieci Google Ad Managera 360 |
{custom_asset} |
Identyfikator niestandardowy powiązany z tym zdarzeniem w usłudze Google Ad Manager. |
Parametry treści zakodowane w formularzu
Opcjonalny zestaw parametrów kierowania zakodowanych w formacie formularza.
Plik JSON odpowiedzi
media_verification_url |
Podstawowy adres URL do pingowania zdarzeń śledzenia odtwarzania. Adres URL pełnej weryfikacji multimediów tworzy się, dołączając do tego podstawowego adresu URL identyfikator zdarzenia reklamowego. |
metadata_url |
Adres URL żądania metadanych bloku reklamowego. |
stream_id |
Ciąg tekstowy używany do identyfikacji bieżącej sesji strumienia. |
valid_for |
Czas pozostały do wygaśnięcia bieżącej sesji strumienia w formacie dhms (dni, godziny, minuty, sekundy). np. 2h0m0.000s oznacza czas trwania wynoszący 2 godziny.
|
valid_until |
Godzina, o której bieżąca sesja strumienia wygasa, w postaci ciągu znaków daty i godziny ISO 8601 w formacie yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
Przykładowe żądanie (cURL)
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded"
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\""
https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
Przykładowa odpowiedź
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
W przypadku błędów zwracane są standardowe kody błędów HTTP bez treści odpowiedzi JSON.
Przeanalizuj odpowiedź JSON i zapisz odpowiednie wartości.
Żądanie pliku manifestu strumienia dla manipulatora manifestu
Każdy manipulator pliku manifestu ma inne formaty żądań i odpowiedzi. Skontaktuj się z dostawcą manipulatora, aby poznać jego szczegółowe wymagania. Jeśli implementujesz własny manipulator pliku manifestu, przeczytaj przewodnik po tym manipulatorze, aby poznać wymagania dotyczące tego komponentu.
Ogólnie rzecz biorąc, musisz przekazać identyfikator strumienia zwrócony przez punkt końcowy rejestracji powyżej do manipulatora pliku manifestu, aby mógł on tworzyć pliki manifestu na potrzeby danej sesji. O ile manipulator manifestu wyraźnie nie zaznacza, odpowiedź na żądanie pliku manifestu to strumień wideo zawierający zarówno treść, jak i reklamy.
Przykładowe żądanie (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
Przykładowa odpowiedź (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
Odtwarzanie strumienia
Otwórz odtwarzacz wideo i rozpocznij odtwarzanie.
Wysyłanie do Ad Managera żądania metadanych bloku reklamowego
Wyślij prośbę o środki (GET
) na adres metadata_url
otrzymany w kroku 1. Ten krok musi zostać wykonany po otrzymaniu złączonego pliku manifestu z manipulatora pliku manifestu. W zamian otrzymujesz obiekt JSON zawierający te parametry:
tags |
Zbiór par klucz-wartość zawierających wszystkie zdarzenia reklamowe, które pojawiają się w strumieniu. Klucze to pierwsze 17 znaków identyfikatora zdarzenia reklamowego, który pojawia się w metadanych czasowych strumienia, lub pełny identyfikator zdarzenia reklamowego w przypadku zdarzeń typu progress .
Każda wartość to obiekt zawierający te parametry:
|
||||||||||||||||||
ads |
Zestaw par klucz-wartość opisujących wszystkie reklamy pojawiające się w strumieniu. Klucze to identyfikatory reklam, które pasują do wartości w obiekcie tags podanym powyżej. Każda wartość to obiekt zawierający te parametry:
|
||||||||||||||||||
ad_breaks |
Zbiór par klucz-wartość opisujących wszystkie przerwy na reklamy występujące w strumieniu.
Klucze to identyfikatory przerw na reklamę, które pasują do wartości w obiektach tags i ads wymienionych powyżej. Każda wartość to obiekt zawierający te parametry:
|
Przechowuj te wartości w celu powiązania ze zdarzeniami metadanych ograniczonymi czasowo w strumieniu wideo.
Przykładowe żądanie (cURL)
curl https://dai.google.com/.../metadata
Przykładowa odpowiedź
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
Wykrywaj zdarzenia reklamowe
Wykrywaj metadane z sygnaturą czasową w trakcie wywoływanych zdarzeń reklamy w strumieniu audio/wideo odtwarzacza.
W przypadku strumieni MPEG-TS metadane są wyświetlane jako tagi wewnątrz pasma ID3 v2.3. Każdy tag metadanych ma identyfikator TXXX
, a wartość rozpoczyna się ciągiem google_
, po którym następuje seria znaków. Ta wartość to identyfikator zdarzenia reklamowego.
Element XXX
w tabeli TXXX
nie jest wartością zastępczej. Ciąg TXXX
to identyfikator tagu ID3 zarezerwowany dla „tekstu zdefiniowanego przez użytkownika”.
Przykładowy tag ID3
TXXXgoogle_1234567890123456789
W przypadku strumieni MP4 są one wysyłane jako zdarzenia emsg w paśmie, które emulują tagi ID3 w wersji 2.3. Każde odpowiednie pole emsg ma wartość scheme_id_uri
o wartości https://aomedia.org/emsg/ID3
lub https://developer.apple.com/streaming/emsg-id3
oraz wartość message_data
rozpoczynającą się od ID3TXXXgoogle_
. Ta wartość message_data
(bez prefiksu ID3TXXX
) jest identyfikatorem zdarzenia reklamowego.
Przykładowe pole emsg
Struktura danych może się różnić w zależności od biblioteki odtwarzacza.
Jeśli identyfikator zdarzenia reklamowego to google_1234567890123456789
, odpowiedź wygląda tak:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
Niektóre biblioteki odtwarzaczy multimedialnych automatycznie przedstawiają zdarzenia emsg, które emulują tagi ID3 jako natywne tagi ID3. W tym przypadku strumienie MP4 mają identyczne tagi ID3 co w przypadku MPEG_TS.
Aktualizowanie interfejsu aplikacji odtwarzacza wideo klienta
Każdy identyfikator zdarzenia reklamowego można dopasować do klucza w obiekcie tags
z kroku 4.
Dopasowywanie tych wartości przebiega dwuetapowo:
Sprawdź, czy w obiekcie
tags
znajduje się klucz pasujący do pełnego identyfikatora zdarzenia reklamowego. Jeśli znaleziono dopasowanie, pobierz typ zdarzenia i powiązane z nim obiektyad
orazad_break
. Powinny one być typuprogress
.Jeśli nie znaleziono dopasowania do pełnego identyfikatora zdarzenia reklamowego, sprawdź w obiekcie
tags
klucz pasujący do pierwszych 17 znaków identyfikatora zdarzenia reklamowego. Pobierz typ zdarzenia oraz powiązane obiektyad
iad_break
. Powinno to spowodować pobranie wszystkich zdarzeń innych niżprogress
.Wykorzystaj pobrane informacje do aktualizacji UI odtwarzacza. Gdy np. otrzymasz zdarzenie
start
lub pierwszeprogress
, ukryj elementy sterujące przewijaniem w odtwarzaczu i wyświetl nakładkę z opisem bieżącej pozycji reklamy w przerwie na reklamę, np. „Reklama 1 z 3”.
Przykładowe identyfikatory zdarzeń reklamowych
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
Przykładowy obiekt tagów
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
Wysyłaj pingi weryfikacji multimediów
Za każdym razem, gdy odebrane zostanie zdarzenie reklamowe innego typu niż progress
, do Ad Managera musi być wysłany ping weryfikacji mediów.
Aby wygenerować pełny adres URL do weryfikacji mediów w przypadku zdarzenia reklamowego, dołącz pełny identyfikator zdarzenia reklamowego do wartości media_verification_url
w odpowiedzi na rejestrację strumienia.
Wyślij żądanie GET z pełnym adresem URL. Jeśli żądanie weryfikacji zakończy się powodzeniem, otrzymasz odpowiedź HTTP z kodem stanu 202
.
W przeciwnym razie wyświetli się kod błędu HTTP 404
.
Przykładowe żądanie (cURL)
curl https://{...}/media/google_5555555555123456789
Przykładowa odpowiedź udana
HTTP/1.1 202 Accepted