Aplikacja odtwarzacza wideo klienckiego do strumieni VOD

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: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Parametry ścieżki

Parametry treści JSON

Plik JSON odpowiedzi

Przykładowe żądanie (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

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. Otrzymasz wówczas obiekt JSON 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:

1. 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 obiekty ad oraz ad_break. Powinny one być typu progress.

   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 obiekty ad i ad_break. Powinno to spowodować pobranie wszystkich zdarzeń innych niż progress.

2. Wykorzystaj pobrane informacje do aktualizacji UI odtwarzacza. Gdy np. otrzymasz zdarzenie start lub pierwsze progress, 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 zostanie zrealizowane, 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

Dodatkowe materiały

• Dokumentacja pakietu IMA SDK
• Porównanie typów implementacji warstwy DAI