Aplikacja odtwarzacza wideo klienckiego do strumieni VOD

Interfejs Google DAI Pod Serving API umożliwia wstawianie reklam po stronie serwera za pomocą Google Ads przy jednoczesnym zachowaniu kontroli nad własnym łączeniem treści.

Ten przewodnik pokazuje, jak korzystać z interfejsu API do wyświetlania bloków reklamowych i uzyskać podobne funkcje za pomocą pakietu IMA DAI SDK. Jeśli masz pytania dotyczące obsługiwanych funkcji, skontaktuj się ze swoim opiekunem klienta w Google.

Interfejs Pod Serving API obsługuje strumienie podów w protokolach strumieniowania HLS lub MPEG-DASH. Ten przewodnik skupia się na strumieniowaniu HLS i w konkretnych krokach wskazuje główne różnice między HLS a MPEG-DASH.

Aby zintegrować interfejs Pod Serving API z aplikacją na potrzeby strumieniowania VOD, wykonaj te czynności:

Przesyłanie do Ad Managera żądania rejestracji strumienia

Wyślij żądanie POST do punktu końcowego rejestracji strumienia. Otrzymasz odpowiedź JSON z identyfikatorem strumienia, który należy wysłać do serwera manipulacji manifestem i powiązanych punktów końcowych interfejsu Pod Serving API.

punkt końcowy API

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Parametry ścieżki

{network_code} Twój kod sieci Google Ad Managera 360

Parametry treści w formacie JSON

targeting_parameters Obiekt JSON zawierający parametry kierowania reklamy. Wymagany

Odpowiedź JSON

media_verification_url Podstawowy adres URL do pingowania zdarzeń śledzenia odtwarzania. Pełny adres URL weryfikacji multimediów jest tworzony przez dodanie do tego adresu URL podstawowego identyfikatora zdarzenia reklamy.
metadata_url Adres URL do żądania metadanych bloku reklamowego.
stream_id Ciąg znaków służący do identyfikacji bieżącej sesji strumieniowania.
valid_for Czas pozostały do wygaśnięcia bieżącej sesji strumieniowego przesyłania danych w formacie dhms (dni, godziny, minuty, sekundy). Na przykład: 2h0m0.000s wskazuje czas trwania 2 godziny.
valid_until Czas wygaśnięcia bieżącej sesji strumieniowego przesyłania danych podany jako ciąg znaków daty i godziny w formacie ISO 8601 w formacie yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

Przykładowe żądanie (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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 w formacie JSON.

Przeanalizuj odpowiedź JSON i przechowuj odpowiednie wartości.

Poproś o plik manifestu strumienia z manipulatora pliku manifestu

Każdy manipulator pliku manifestu ma inny format żądania i odpowiedzi. Skontaktuj się z dostawcą manipulatora, aby poznać jego wymagania. Jeśli wdrażasz własny manipulator pliku manifestu, przeczytaj przewodnik po manipulatorze pliku manifestu, aby poznać wymagania dotyczące tego komponentu.

Ogólnie musisz przekazać identyfikator strumienia zwrócony przez punkt końcowy rejestracji do manipulatora pliku manifestu, aby mógł on tworzyć pliki manifestu dotyczące konkretnej sesji. O ile nie jest to wyraźnie określone przez manipulatora manifestu, odpowiedź na żądanie manifestu to strumień wideo zawierający zarówno treści, 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

Załaduj manifest otrzymany z serwera manipulacji manifestem do odtwarzacza wideo i rozpocznij odtwarzanie.

Prośba o metadane podelementu reklamy z Ad Managera

Prześlij prośbę o GET do metadata_url, który został podany w kroku 1. Ten krok musi zostać wykonany po otrzymaniu zszytego pliku manifestu od manipulatora. W zamian otrzymasz obiekt JSON zawierający te parametry:

tags Zestaw par klucz-wartość zawierający wszystkie zdarzenia reklamy, które pojawiają się w strumieniu. Klucze to pierwsze 17 znaków identyfikatora zdarzenia reklamy, które pojawiają się w czasowych metadanych strumienia lub, w przypadku zdarzeń typu progress, pełny identyfikator zdarzenia reklamy.

Każda wartość to obiekt zawierający te parametry:

ad Identyfikator reklamy pasujący do klucza w obiekcie ads.
ad_break_id Identyfikator przerwy na reklamę, który pasuje do klucza w obiekcie ad_breaks.
type Typ zdarzenia reklamowego. Typy zdarzeń reklamowych:
start Uruchamiane na początku reklamy.
firstquartile Wyzwalane na końcu pierwszego kwartyla.
midpoint Uruchamiane w środku reklamy.
thirdquartile Wyzwalany na końcu trzeciego kwartyla.
complete Uruchamiane na końcu reklamy.
progress Uruchamiane okresowo podczas reklamy, aby powiadomić aplikację o tym, że trwa przerwa na reklamę.
ads Zestaw par klucz-wartość opisujących wszystkie reklamy wyświetlane w strumieniu. Klucze to identyfikatory reklam pasujące do wartości znalezionych w wymienionym powyżej obiekcie tags. Każda wartość to obiekt zawierający te parametry:
ad_break_id Identyfikator przerwy na reklamę, który pasuje do klucza w obiekcie ad_breaks.
position Pozycja, na której reklama pojawia się w zestawie reklam w przerwie na reklamę, w sekundach z dokładnością do miejsc po przecinku.
duration Długość reklamy w postaci liczby zmiennoprzecinkowej w sekundach.
clickthrough_url Adres URL, który powinien się otworzyć, gdy użytkownik wejdzie w interakcję z tą reklamą (jeśli jest obsługiwany).
ad_breaks Zestaw par klucz-wartość opisujących wszystkie przerwy na reklamy, które pojawiają się w strumieniu. Klucze to identyfikatory przerw w reklamie, które pasują do wartości znalezionych w wymienionych powyżej obiektach tags i ads. Każda wartość to obiekt zawierający te parametry:
type Typ przerwy na reklamę. Typy przerw na reklamę: pre (przed filmem), mid (w trakcie filmu) i post (po filmie).
duration Długość przerwy na reklamę w sekundach z dokładnością do 6 cyfr po przecinku.
ads Liczba reklam w tej przerwie na reklamę.

Przechowuj te wartości, aby powiązać je ze zdarzeniami metadanych w czasie strumienia 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
    },
    ...
  }
}

Nasłuchiwanie zdarzeń reklamowych

Odsłuchiwanie zsynchronizowanych metadanych za pomocą wywoływanych zdarzeń reklamy w strumieniu audio lub wideo odtwarzacza.

W przypadku strumieni MPEG-TS metadane są widoczne jako tagi ID3 w wersji 2.3 w paśmie. Każdy tag metadanych ma identyfikator TXXX, a wartość zaczyna się od ciągu google_, po którym następuje seria znaków. Ta wartość to identyfikator zdarzenia związanego z reklamą.

Wartość XXX w pozycji TXXX nie jest zmienną. Ciąg TXXX to identyfikator tagu ID3 zarezerwowany na potrzeby „tekstu zdefiniowanego przez użytkownika”.

Przykład tagu 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 pole emsg ma wartość scheme_id_uri, która jest albo https://aomedia.org/emsg/ID3, albo https://developer.apple.com/streaming/emsg-id3, oraz wartość message_data, która zaczyna się od ID3TXXXgoogle_. Ta wartość message_data bez prefiksu ID3TXXX to identyfikator zdarzenia reklamy.

Przykład pola wiadomości e-mail

Struktura danych może się różnić w zależności od biblioteki odtwarzacza multimediów.

Jeśli identyfikator zdarzenia reklamy to google_1234567890123456789, odpowiedź będzie 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 multimediów automatycznie przedstawiają zdarzenia emsg, które emulują znaczniki ID3, jako natywne znaczniki ID3. W takim przypadku strumienie MP4 zawierają identyczne tagi ID3 jak MPEG_TS.

Aktualizacja interfejsu aplikacji odtwarzacza wideo

Każdy identyfikator zdarzenia reklamowego można dopasować do klucza w obiekcie tags z kroku 4. Dopasowywanie tych wartości to 2 etapy:

  1. W obiekcie tags sprawdź, czy klucz odpowiada pełnemu identyfikatorowi zdarzenia reklamy. Jeśli zostanie znalezione dopasowanie, pobierz typ zdarzenia i powiązane z nim obiekty ad i ad_break. Te zdarzenia powinny mieć typ progress.

    Jeśli nie uda się znaleźć dopasowania do pełnego identyfikatora zdarzenia reklamy, sprawdź w obiekcie tags klucz odpowiadający pierwszym 17 znakom identyfikatora zdarzenia reklamy. Pobierz typ zdarzenia oraz powiązane obiekty ad i ad_break. W ten sposób możesz pobrać wszystkie zdarzenia o typach innych niż progress.

  2. Użyj tych informacji, aby zaktualizować interfejs odtwarzacza. Gdy na przykład otrzymasz zdarzenie start lub pierwsze zdarzenie progress, ukryj elementy sterujące przesuwaniem odtwarzacza i wyświetl nakładkę z opisem pozycji bieżącej reklamy w przerwie na reklamę, np. „Reklama 1 z 3”.

Przykładowe identyfikatory zdarzeń reklamy

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łanie pingów weryfikacyjnych multimediów

Za każdym razem, gdy otrzymasz zdarzenie reklamy o typie innym niż progress, musisz wysłać do Ad Managera sygnał ping weryfikacji mediów.

Aby wygenerować pełny adres URL weryfikacji multimediów zdarzenia reklamy, dodaj pełny identyfikator zdarzenia reklamy do wartości media_verification_url z odpowiedzi na rejestrację strumienia.

Wyślij żądanie GET z pełnym adresem URL. Jeśli weryfikacja się powiedzie, otrzymasz odpowiedź HTTP z kodem stanu 202. W przeciwnym razie pojawi się kod błędu HTTP 404.

Przykładowe żądanie (cURL)

curl https://{...}/media/google_5555555555123456789

Przykład odpowiedzi pomyślnej

HTTP/1.1 202 Accepted

Dodatkowe materiały