Zarządzanie transmisjami na żywo z dynamicznym wstawianiem reklam

Interfejs Google DAI API umożliwia wdrażanie strumieni obsługujących Google DAI w środowiskach, w których wdrożenie pakietu IMA SDK nie jest obsługiwane. Zalecamy, aby nadal używać IMA na platformach, na których pakiet IMA SDK jest obsługiwany.

Zalecamy używanie interfejsu DAI API na tych platformach:

  • Samsung Smart TV (Tizen)
  • LG TV
  • HbbTV
  • Xbox (aplikacje JavaScript)
  • KaiOS

Interfejs API obsługuje podstawowe funkcje pakietu IMA DAI SDK. Jeśli masz konkretne pytania dotyczące zgodności lub obsługiwanych funkcji, skontaktuj się ze swoim opiekunem klienta w Google.

Implementowanie interfejsu DAI API w przypadku transmisji na żywo

Interfejs DAI API obsługuje linearne transmisje (na żywo) korzystające z protokołów HLS i DASH. Kroki opisane w tym przewodniku dotyczą obu protokołów.

Aby zintegrować interfejs API z aplikacją w przypadku transmisji na żywo, wykonaj te czynności:

1. Przesyłanie żądania transmisji

Aby poprosić o transmisję na żywo z interfejsu DAI API, wyślij wywołanie POST do punktu końcowego strumienia. Odpowiedź JSON zawiera manifest strumienia oraz powiązane punkty końcowe i wartości interfejsu DAI API.

Przykładowa treść żądania

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Przykładowa treść odpowiedzi

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Odpowiedź o błędzie

W przypadku błędów zwracane są standardowe kody błędów HTTP bez treści odpowiedzi JSON.

Przeanalizuj odpowiedź w formacie JSON i zapisz te wartości:

stream_id
Ta wartość może służyć do identyfikowania zwróconego strumienia.
stream_manifest
Ten adres URL jest przekazywany do odtwarzacza multimediów w celu odtworzenia strumienia.
media_verification_url
Ten URL to podstawowy punkt końcowy do śledzenia zdarzeń odtwarzania.
metadata_url
Ten adres URL służy do okresowego sprawdzania informacji o nadchodzących wydarzeniach w strumieniu.
session_update_url
Ten adres URL służy do aktualizowania parametrów żądania strumienia wysyłanych podczas wstępnego żądania strumienia. Pamiętaj, że parametry tego żądania zastępują wszystkie parametry ustawione dla wcześniejszego strumienia.
polling_frequency
Częstotliwość w sekundach, z jaką wysyłane są żądania zaktualizowanych metadanych przerwy na reklamę z interfejsu DAI API.

2. Sprawdzanie nowych metadanych przerw na reklamy

Ustaw czasomierz, aby odpytywać o nowe metadane przerwy na reklamę z częstotliwością odpytywania, używając adresu URL metadanych. Jeśli nie jest określony w odpowiedzi strumienia, domyślny zalecany interwał wynosi 10 sekund.

Aby zoptymalizować przepustowość:

  1. Wyślij początkowe żądanie GET do punktu końcowego metadata_url.
    • Pomiń parametr zapytania delta_token. Ten proces umożliwia serwerowi zwrócenie pełnych metadanych okna DVR strumienia. Okres DVR to przedział czasu transmisji, który jest dostępny dla widza do przewijania i odtwarzania. Odpowiedź zawiera pole obiektu next_delta_token.
  2. przechowywać metadane po stronie klienta,
  3. Wykonuj kolejne wywołania, używając wartości next_delta_token, którą zwraca ostatnia odpowiedź. Każda odpowiedź zawiera wartość next_delta_token. Zawsze wysyłaj ostatnią otrzymaną wartość.
  4. Zaktualizuj zapisane metadane, aby scalić zmiany i usunąć przestarzałe przerwy na reklamy.

Nie próbuj analizować, tworzyć ani modyfikować tokena delta. Format tokena może się zmienić. Zapisz token w otrzymanej postaci i przekaż go bez zmian w kolejnym żądaniu.

Przykładowe żądanie początkowe

Początkowe żądanie nie przyjmuje parametrów zapytania i zwraca pełne metadane:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Przykładowe kolejne żądanie

Każde kolejne żądanie przekazuje wartość next_delta_token z poprzedniej odpowiedzi jako parametr delta_token. Odpowiedź zawiera te elementy:

  • Reklamy
  • Przerwy na reklamy
  • tagi dodane lub zaktualizowane przez serwer od czasu wydania tokena;
  • obsolete_ad_break_ids lista przerw na reklamy do usunięcia z przechowywanych metadanych;

Serwer pomija przerwy na reklamy, które nie uległy zmianie. W tym przykładzie pokazujemy kolejne sondowanie z użyciem tokena delta, aby pobrać tylko te ostatnie zmiany:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Jeśli operacja się powiedzie, zobaczysz dane wyjściowe podobne do tych:

{
   "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",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. Odsłuchiwanie zdarzeń ID3 i śledzenie zdarzeń odtwarzania

Aby sprawdzić, czy w strumieniu wideo wystąpiły określone zdarzenia, wykonaj te czynności w przypadku zdarzeń ID3:

  1. Zapisuj zdarzenia związane z multimediami w kolejce, zapisując każdy identyfikator multimediów wraz z jego sygnaturą czasową (jeśli jest udostępniana przez odtwarzacz).
  2. Przy każdej aktualizacji czasu odtwarzania lub z ustaloną częstotliwością (zalecana wartość to 500 ms) sprawdzaj kolejkę zdarzeń multimedialnych pod kątem ostatnio odtworzonych zdarzeń, porównując sygnatury czasowe zdarzeń z pozycją odtwarzania.
  3. W przypadku zdarzeń związanych z multimediami, które na pewno zostały odtworzone, sprawdź typ, wyszukując identyfikator multimediów w przechowywanych tagach przerw na reklamy. Pamiętaj, że zapisane tagi zawierają tylko prefiks identyfikatora multimediów, więc dokładne dopasowanie nie jest możliwe.
  4. Aplikacja odtwarzacza wideo okresowo odpytuje adres URL metadanych, więc może wystąpić opóźnienie między momentem, w którym odtwarzacz wideo napotka tag ID3 w strumieniu, a momentem, w którym powiązane metadane staną się dostępne. Jeśli w przechowywanych tagach nie ma tagu ID3, zachowaj go w kolejce i przetwórz ponownie po następnym odpytaniu metadanych. Zachowaj zdarzenie w kolejce do momentu zakończenia przetwarzania.
  5. Po znalezieniu tagu w metadanych sprawdź pole type w porównaniu z typami zdarzeń reklamowych wymienionymi w następnej sekcji. Aby śledzić, czy odtwarzacz wideo odtwarza przerwę na reklamy, używaj zdarzeń z wartością progress w polu type. Nie wysyłaj tych zdarzeń do punktu końcowego weryfikacji multimediów. W przypadku wszystkich innych typów zdarzeń dodaj identyfikator multimediów do punktu końcowego weryfikacji multimediów i wyślij GET żądanie śledzenia odtwarzania.
  6. Usuń wydarzenie multimedialne z kolejki.

Typy zdarzeń reklamowych

Każdy tag w obiekcie metadanych tags ma jeden z tych typów zdarzeń:

Typ zdarzenia Opis
start Wyświetla się na początku reklamy.
firstquartile Wyświetla się na końcu pierwszego kwartyla reklamy.
midpoint Wyświetla się w środku reklamy.
thirdquartile Uruchamia się pod koniec trzeciego kwartyla reklamy.
complete Wyświetla się na końcu reklamy.
progress Uruchamia się okresowo podczas przerwy na reklamę, aby zasygnalizować, że jest ona odtwarzana. Nie wysyłaj tych zdarzeń do punktu końcowego weryfikacji mediów.

Przykładowe żądanie

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Przykładowe odpowiedzi

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Zdarzenia śledzenia możesz sprawdzić w narzędziu do monitorowania strumienia aktywności.

4. Aktualizowanie parametrów sesji transmisji na żywo

Po utworzeniu strumienia możesz dostosować parametry sesji. Aby to zrobić, wyślij żądanie na adres URL aktualizacji sesji.

Przykładowa treść żądania

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Przykładowa treść odpowiedzi

Successful response would be to look for - HTTP/1.1 200

Ograniczenia

Jeśli używasz interfejsu API w widokach internetowych, w przypadku kierowania obowiązują te ograniczenia:

  • UserAgent: parametr klienta użytkownika jest przekazywany jako wartość specyficzna dla przeglądarki, a nie dla platformy bazowej.
  • rdid, idtype, is_lat: Identyfikator urządzenia nie jest prawidłowo przekazywany, co ogranicza możliwości tych funkcji:
    • Ograniczenie liczby wyświetleń
    • Sekwencyjna rotacja reklam
    • Podział odbiorców na segmenty i kierowanie na nie reklam

Sprawdzone metody

Pamiętaj, że punkt końcowy metadanych indeksów transmisji na żywo jest oparty na prefiksie odpowiedniego tagu ID3. Jest to celowe działanie, które ma zapobiegać używaniu punktu końcowego metadanych do natychmiastowego pingowania wszystkich węzłów weryfikacyjnych.

Dodatkowe materiały