Interfejs Dynamic Ad Insertion API dla transmisji na żywo

Interfejs Google DAI API pozwala wdrażać strumienie z włączoną usługą Google DAI w różnych środowiskach w przypadku których implementacja pakietu IMA SDK nie jest obsługiwana. Zalecamy użycie parametru IMA na platformach, na których obsługiwany jest ten pakiet.

Zalecamy korzystanie z interfejsu DAI API na tych platformach:

  • Telewizor smart TV firmy Samsung (Tizen)
  • LG TV
  • HbbTV
  • Xbox (aplikacje JavaScript)
  • KaiOS

Interfejs API obsługuje podstawowe funkcje zapewniane przez pakiet IMA DAI SDK. Dla: masz konkretne pytania na temat zgodności lub obsługiwanych funkcji, skontaktuj się z Twoim opiekunem klienta w Google.

Wdrażanie interfejsu DAI API w transmisjach na żywo

Interfejs DAI API obsługuje linearne transmisje (LIVE) zarówno w protokołach HLS, jak i DASH. Czynności opisane w tym przewodniku dotyczą obu protokołów.

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

1. Poproś o strumień

Aby zażądać transmisji na żywo z interfejsu DAI API, użyj wywołania POST do strumienia. punktu końcowego. Odpowiedź JSON zawiera plik manifestu 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":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

Odpowiedź na błąd

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

Przeanalizuj odpowiedź JSON i zapisz te wartości:

stream_id
Ta wartość może służyć do identyfikacji zwróconego strumienia.
stream_manifest
Ten adres URL jest przekazywany do odtwarzacza w celu odtwarzania strumieniowego.
media_verification_url
Ten URL jest podstawowym punktem końcowym do śledzenia zdarzeń odtwarzania.
metadata_url
Ten URL jest używany do okresowego sprawdzania informacji o nadchodzącej transmisji zdarzeń.
session_update_url
Ten URL jest używany do aktualizacji parametrów żądania strumienia wysyłanych w pierwszym etapie żądania strumieniowego przesyłania danych. Pamiętaj, że parametry tego żądania zastępują wszystkie parametry dla wcześniejszej transmisji.
polling_frequency
Częstotliwość (w sekundach) żądania zaktualizowanych metadanych przerwy na reklamę z narzędzia interfejs DAI API.

2. Ankieta dotycząca nowych metadanych przerwy na reklamę

Ustaw licznik czasu, aby sondować pod kątem nowych metadanych przerwy na reklamę z częstotliwością odpytywania. W tym celu użyj adresu URL metadanych. Jeśli nie podasz tych danych w odpowiedzi strumienia, domyślne zalecane ustawienie wynosi 10 sekund.

Przykładowa treść żądania

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

Przykładowa treść odpowiedzi

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

3. Słuchaj zdarzeń ID3 i śledź zdarzenia odtwarzania

Aby sprawdzić, czy w strumieniu wideo wystąpiły określone zdarzenia, postępuj zgodnie z tymi instrukcjami kroków do obsługi zdarzeń ID3:

  1. Zdarzenia multimediów zapisuj w kolejce, zapisując każdy identyfikator multimediów wraz z ich sygnatura czasowa (jeśli wyświetli się przez odtwarzacz);
  2. Za każdym razem, gdy informacje są przekazywane przez odtwarzacz lub w ustalonej częstotliwości (zalecane 500 ms), sprawdź kolejkę zdarzeń multimediów pod kątem ostatnio odtwarzanych zdarzeń przez porównanie sygnatur czasowych zdarzeń z suwakiem odtwarzania.
  3. W przypadku potwierdzonych zdarzeń związanych z multimediami, sprawdź ich typ, wyszukując identyfikatora mediów w zapisanych tagach przerw na reklamę. Pamiętaj, że przechowywane tagi zawierają tylko prefiks identyfikatora mediów, więc dopasowanie ścisłe nie jest możliwe.
  4. Użyj opcji „postęp” zdarzenia, które pozwalają śledzić, czy użytkownik ma brać udział w przerwie na reklamę. Nie wysyłaj tych zdarzeń do punktu końcowego weryfikacji multimediów. Inne wydarzenie należy dodać identyfikator mediów do punktu końcowego weryfikacji multimediów i utworzyć metodę GET żądania śledzenia odtwarzania.
  5. Usuń zdarzenie multimedialne z kolejki.

Przykładowa treść żądania

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

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 zweryfikować na stronie Aktywność w strumieniu Monitorowanie.

4. Zaktualizuj parametry sesji transmisji na żywo

Warto dostosować parametry sesji po zakończeniu transmisji Utworzono. 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/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

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

Przykładowa treść odpowiedzi

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

Ograniczenia

W przypadku korzystania z interfejsu API w komponentach WebView mają następujące ograniczenia do kierowania:

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

Sprawdzone metody

Pamiętaj, że punkt końcowy metadanych indeksów transmisji na żywo opiera się odpowiedniego tagu ID3. Ma to na celu uniemożliwienie korzystania punkt końcowy metadanych umożliwiający natychmiastowe pingowanie wszystkich węzłów weryfikacyjnych.

Dodatkowe materiały