Ten przewodnik zawiera informacje o tworzeniu aplikacji klienckiej do wczytywania transmisji na żywo HLS lub DASH za pomocą interfejsu Pod Serving API i modułu modyfikującego manifest.
Wymagania wstępne
Zanim przejdziesz dalej, musisz mieć:
Niestandardowy klucz zasobu dla wydarzenia transmitowanego na żywo skonfigurowanego z typem DAI
Pod serving redirect. Aby uzyskać ten klucz, wykonaj te czynności:Użyj biblioteki klienta interfejsu SOAP API, aby wywołać metodę
LiveStreamEventService.createLiveStreamEventsz obiektemLiveStreamEventi właściwościądynamicAdInsertionTypeustawioną na wartość typu wyliczeniowegoPOD_SERVING_REDIRECT. Wszystkie biblioteki klienta znajdziesz w artykule Biblioteki klienta i przykładowy kod.
Sprawdź, czy pakiet Interactive Media Ads (IMA) SDK jest dostępny na Twojej platformie. Aby zwiększyć przychody, zalecamy korzystanie z pakietu IMA SDK. Szczegółowe informacje znajdziesz w artykule Konfigurowanie pakietu IMA SDK na potrzeby DAI.
Wysyłanie żądania strumienia
Gdy użytkownik wybierze strumień, wykonaj te czynności:
Wyślij żądanie
POSTdo metody usługi transmisji na żywo. Więcej informacji znajdziesz w artykule Metoda: stream.Przekazuj parametry kierowania reklam w formacie
application/x-www-form-urlencodedlubapplication/json. To żądanie rejestruje sesję strumienia w Google DAI.Ten przykład wysyła żądanie strumienia:
Kodowanie formularza
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const params = new URLSearchParams({ cust_params: 'section=sports&page=golf,tennis' }).toString(); const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: params }); console.log(await response.json());Kodowanie JSON
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ cust_params: { section: 'sports', page: 'golf,tennis' } }) }); console.log(await response.json());Jeśli operacja się powiedzie, zobaczysz dane wyjściowe podobne do tych:
{ "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS", "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/", "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata", "session_update_url": "https://dai.google.com/linear/.../session", "polling_frequency": 10 }W odpowiedzi JSON znajdź identyfikator sesji strumienia i zapisz inne dane na potrzeby kolejnych kroków.
Metadane reklamy z ankietą
Aby odpytać metadane reklamy:
Odczytaj wartość
metadata_urlz odpowiedzi na rejestrację strumienia.Wyślij początkowe żądanie
GETdo punktu końcowegometadata_url.- Pomiń parametr zapytania
delta_token. Dzięki temu serwer może zwrócić pełne metadane okna DVR transmisji. Okno DVR zawiera przedział czasu transmisji, który widz może przewinąć i odtworzyć. Odpowiedź zawiera polenext_delta_token.
- Pomiń parametr zapytania
Aby zoptymalizować przepustowość, zapisz wartość
next_delta_tokenz ostatniej odpowiedzi.W następnym żądaniu wyślij tę wartość jako parametr zapytania
delta_token. Serwer zwraca tylko metadane, które uległy zmianie od czasu wygenerowania tego tokena. Zawsze wysyłaj najnowszy otrzymany token. Nie próbuj analizować, modyfikować ani tworzyć tokena. Szczegółowe informacje znajdziesz w artykule Metoda: metadane.Ten przykład pobiera metadane reklamy:
// Initial request (returns full metadata and next_delta_token) let response = await fetch(metadata_url); let metadata = await response.json(); let deltaToken = metadata.next_delta_token; // Subsequent request (returns only changes since deltaToken) if (deltaToken) { const url = new URL(metadata_url); url.searchParams.append('delta_token', deltaToken); response = await fetch(url.toString()); const deltaMetadata = await response.json(); // Merge deltaMetadata into your local cache mergeMetadata(metadata, deltaMetadata); deltaToken = deltaMetadata.next_delta_token; }Jeśli operacja się powiedzie, otrzymasz odpowiedź PodMetadata. Jeśli podasz parametr
delta_token, odpowiedź będzie zawierać tylko reklamy, przerwy na reklamę i tagi, które serwer dodał lub zaktualizował od czasu wygenerowania tokena. Odpowiedź zawiera też nową wartośćnext_delta_token. Jeśli jakieś przerwy na reklamę są nieaktualne, odpowiedź zawiera też listęobsolete_ad_break_idsprzerw na reklamę, które należy usunąć z pamięci podręcznej.{ "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0", "obsolete_ad_break_ids": ["0003069407"], "tags":{ "google_1022389921":{ "ad":"0003069408_ad1", "ad_break_id":"0003069408", "type":"start" }, ... }, "ads":{ "0003069408_ad1":{ "ad_break_id":"0003069408", "position":1, "duration":10.01, "title":"External - Pod Midroll 1", "clickthrough_url":"https://.../", ... }, ... }, "ad_breaks":{ "0003069408":{ "type":"mid", "duration":30, "ads":3 }, ... } }Zapisz obiekt
tagsi scal aktualizacje w lokalnej pamięci podręcznej. Jeśli parametrobsolete_ad_break_idsjest obecny, usuń te przerwy na reklamę oraz powiązane z nimi reklamy i tagi z pamięci podręcznej.Ustaw minutnik, używając wartości
polling_frequency, aby regularnie wysyłać żądania metadanych. W każdym zapytaniu wyślij wartośćnext_delta_tokenzwróconą w ostatniej odpowiedzi metadanych jako parametr zapytaniadelta_token.
Wczytywanie transmisji do odtwarzacza
Gdy otrzymasz identyfikator sesji z odpowiedzi na rejestrację, przekaż go do modułu modyfikującego manifest lub utwórz adres URL manifestu, aby wczytać strumień do odtwarzacza wideo.
Aby przekazać identyfikator sesji, zapoznaj się z dokumentacją modułu modyfikującego manifest. Jeśli tworzysz moduł modyfikujący manifest, zapoznaj się z artykułem Moduł modyfikujący manifest na potrzeby transmisji na żywo.
Poniższy przykład przedstawia adres URL pliku manifestu:
https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"
Gdy odtwarzacz będzie gotowy, rozpocznij odtwarzanie.
Nasłuchiwanie zdarzeń reklamowych
Sprawdź format kontenera transmisji pod kątem metadanych czasowych:
Strumienie HLS z kontenerami Transport Stream (TS) używają tagów ID3 z sygnaturą czasową do przenoszenia metadanych z sygnaturą czasową. Więcej informacji znajdziesz w artykule na temat formatu Common Media Application Format z transmisją na żywo przez HTTP (HLS).
Strumienie DASH używają elementów
EventStreamdo określania zdarzeń w pliku manifestu.Strumienie DASH używają elementów
InbandEventStream, gdy segmenty zawierają pola Event Message (emsg) z danymi ładunku, w tym tagami ID3. Więcej informacji znajdziesz w artykule InbandEventStream.Strumienie CMAF, w tym DASH i HLS, używają pól
emsgzawierających tagi ID3.
Aby pobrać tagi ID3 ze strumienia, zapoznaj się z przewodnikiem po odtwarzaczu. Więcej informacji znajdziesz w przewodniku po obsłudze metadanych z sygnaturą czasową.
Aby pobrać identyfikator zdarzenia reklamowego z tagów ID3:
- Filtruj zdarzenia według
scheme_id_urizurn:google:dai:2018lubhttps://aomedia.org/emsg/ID3. Wyodrębnij tablicę bajtów z pola
message_data.W tym przykładzie dane
emsgsą dekodowane do formatu JSON:{ "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3", "presentation_time": 27554, "timescale": 1000, "message_data": "ID3TXXXgoogle_1022389921", ... }Filtruj tagi ID3 w formacie
TXXXgoogle_{ad_event_ID}:TXXXgoogle_1022389921
Pokaż dane zdarzeń związanych z reklamami
Aby znaleźć obiekt TagSegment, wykonaj te czynności:
Pobierz obiekt metadanych reklamy
tagsz metadanych reklamy z ankietą. Obiekttagsto tablica obiektówTagSegment.Użyj pełnego identyfikatora zdarzenia reklamowego, aby znaleźć obiekt
TagSegmenttypuprogress.Użyj pierwszych 17 znaków identyfikatora zdarzenia reklamowego, aby znaleźć obiekt
TagSegmentinnego typu.Aplikacja kliencka okresowo odpytuje metadane reklamy, dlatego może wystąpić opóźnienie między momentem, gdy odtwarzacz wideo napotka tag ID3 w strumieniu, a momentem, gdy powiązane metadane staną się dostępne. Jeśli aplikacja kliencka nie znajdzie tagu ID3 w zapisanych tagach, zachowaj go w kolejce i ponownie przetwórz po kolejnym odpytaniu o metadane. Pozostaw tag w kolejce do czasu zakończenia przetwarzania.
Gdy masz już
TagSegment, użyj właściwościad_break_idjako klucza, aby znaleźć obiektAdBreakw obiekcie metadanych reklamyad_breaks.W tym przykładzie wyszukiwany jest obiekt
AdBreak:{ "type":"mid", "duration":15, "ads":1 }Użyj danych
TagSegmentiAdBreak, aby wyświetlić informacje o pozycji reklamy w przerwie na reklamę. Na przykład:Ad 1 of 3.
Wysyłanie pingów weryfikacji multimediów
W przypadku każdego zdarzenia reklamowego, z wyjątkiem typu progress, wysyłaj ping weryfikacji multimediów.
Dynamiczne wstawianie reklam Google odrzuca zdarzenia progress, a częste wysyłanie tych zdarzeń może mieć wpływ na wydajność aplikacji.
Aby wygenerować pełny adres URL do weryfikacji multimediów dla zdarzenia reklamowego:
Z odpowiedzi dotyczącej transmisji dołącz pełny identyfikator zdarzenia reklamowego do wartości
media_verification_url.Wyślij żądanie
GETz pełnym adresem URL:// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/" const completeUrl = `${media_verification_url}google_1022389921`; const response = await fetch(completeUrl);Jeśli operacja się powiedzie, otrzymasz odpowiedź z kodem stanu
202. W przeciwnym razie pojawi się kod błędu404.
Możesz użyć narzędzia do monitorowania aktywności w transmisji na żywo (SAM), aby sprawdzić historyczny dziennik wszystkich zdarzeń związanych z reklamami. Szczegółowe informacje znajdziesz w artykule na temat monitorowania transmisji na żywo i rozwiązywania związanych z nią problemów.