Aplikacja odtwarzacza wideo klienckiego do strumieni VOD

Interfejs Google DAI Pod Serving API umożliwia wstawianie reklam po stronie serwera przez Google Ads, zachowując kontrolę nad własnymi filmami.

Z tego przewodnika dowiesz się, jak korzystać z interfejsu Pod Serving API i osiągnąć o podobnej funkcjonalności dostępne w pakiecie IMA DAI SDK. Aby uzyskać szczegółowe informacje na temat: obsługiwane funkcje, skontaktuj się ze swoim opiekunem klienta w Google.

Interfejs Pod Serving API obsługuje strumienie wyświetlania podów w formacie HLS lub MPEG-DASH. protokoły streamingowe. Ten przewodnik skupia się na transmisjach HLS i wyróżnia najważniejsze różnic między HLS a MPEG-DASH w konkretnych krokach.

Aby zintegrować interfejs Pod Serving API z aplikacją na potrzeby strumieni VOD, wykonaj następujące kroki:

Przesyłanie prośby o rejestrację transmisji na żywo do Ad Managera

Wyślij żądanie POST do punktu końcowego rejestracji strumienia. Otrzymujesz z kolei Odpowiedź JSON zawierająca identyfikator strumienia, który ma zostać wysłany do manipulowania plikiem manifestu serwera 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 w usłudze Google Ad Manager 360

Parametry treści JSON

targeting_parameters Obiekt JSON zawierający identyfikator źródła treści (cmsid), identyfikator filmu (vid) kierowanie reklam . Wymagany

Plik JSON odpowiedzi

media_verification_url Podstawowy adres URL do pingowania zdarzeń śledzenia odtwarzania. Pełna weryfikacja mediów Adres URL powstaje, dołączając do niego identyfikator zdarzenia reklamowego.
metadata_url Adres URL żądania metadanych bloków reklamowych.
stream_id Ciąg tekstowy służący do identyfikacji bieżącej sesji strumienia.
valid_for Czas pozostały do wygaśnięcia bieżącej sesji strumieniowania (w języku angielskim) Format dhms (dni, godziny, minuty, sekundy). Przykład: 2h0m0.000s oznacza czas trwania wynoszący 2 godziny.
valid_until Godzina wygaśnięcia bieżącej sesji transmisji podana w formacie ISO 8601 ciąg daty i godziny w funkcji yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .

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 odpowiedzi JSON. .

Przeanalizuj odpowiedź JSON i zapisz odpowiednie wartości.

Zażądaj pliku manifestu strumienia za pomocą manipulatora pliku manifestu

Każdy manipulator manifestu ma różne formaty żądań i odpowiedzi. Kontakt z dostawcą manipulatora, aby poznać jego wymagania. Jeśli podczas implementowania własnego manipulatora manifestu, przeczytaj manipulator manifestu , aby poznać dla tego komponentu.

Zwykle musisz przekazać identyfikator strumienia, który został zwrócony przez powyższego punktu końcowego rejestracji do manipulatora pliku manifestu, aby został on skompilowany plików manifestu w konkretnych sesjach. O ile nie podano inaczej w pliku manifestu manipulatorem, odpowiedzią na żądanie pliku manifestu będzie strumień wideo zawierający treści i reklam.

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

Odtwórz transmisję

Wczytaj plik manifestu otrzymany z serwera manipulacji manifestu do pliku odtwarzacza wideo i rozpocznij odtwarzanie.

Żądanie metadanych bloku reklamowego do Ad Managera

Wyślij prośbę GET do: metadata_url otrzymane w kroku 1. Ten krok musi wystąpić po otrzymaniu połączonego pliku manifestu z pliku manifestu za pomocą manipulacji. W zamian otrzymasz obiekt JSON zawierający: parametry:

tags Zestaw par klucz-wartość zawierających wszystkie zdarzenia reklamowe widoczne w . Klucze to pierwsze 17 znaków zdarzenia reklamowego Identyfikator widoczny w metadanych ograniczonych czasowo strumienia lub w przypadku zdarzeń typu progress, czyli pełny identyfikator zdarzenia reklamowego.

Każda wartość jest obiektem zawierającym te parametry:

ad Identyfikator reklamy, który pasuje do klucza w obiekcie ads.
ad_break_id Identyfikator przerwy na reklamę pasujący do klucza w kolumnie ad_breaks obiektu.
type Typ zdarzenia reklamowego. Typy zdarzeń reklamowych:
start Uruchamiane na początku reklamy.
firstquartile Uruchamiane na końcu pierwszego kwartyla.
midpoint Uruchamiane w połowie reklamy.
thirdquartile Uruchomiono na końcu trzeciego kwartyla.
complete Uruchamiane na końcu reklamy.
progress Uruchamiane okresowo przez całą reklamę, aby powiadomić aplikację, że reklama trwa przerwa.
ads Zestaw par klucz-wartość opisujących wszystkie reklamy wyświetlane w strumieniu. Klucze to identyfikatory reklam pasujące do wartości w obiekcie tags wymienionych powyżej. Każda wartość jest obiektem zawierającym te parametry:
ad_break_id Identyfikator przerwy na reklamę pasujący do klucza w kolumnie ad_breaks obiektu.
position Pozycja, na której ta reklama pojawia się w zestawie reklam w sekundach w postaci zmiennoprzecinkowej.
duration Długość reklamy w sekundach zmiennoprzecinkowych.
clickthrough_url Adres URL, który powinien się otworzyć, gdy użytkownik wejdzie w interakcję z reklamą (jeśli jest obsługiwana).
ad_breaks Zestaw par klucz-wartość opisujących wszystkie przerwy na reklamy pojawiające się w strumieniu. Klucze to identyfikatory przerw na reklamę, które pasują do wartości w tabeli tags. i ads obiektów wymienionych powyżej. Każda wartość jest obiektem z następującymi parametrami:
type Typ przerwy na reklamę. Typy przerw na reklamę: pre (przed filmem), mid (reklama w trakcie filmu) i post (reklama po filmie).
duration Długość przerwy na reklamę wyrażona w sekundach jako liczba zmiennoprzecinkowa.
ads Liczba reklam w tej przerwie na reklamę.

Przechowuj te wartości, aby powiązać je ze zdarzeniami metadanych ujętych w czasie w Twoim filmie .

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łuchuj zdarzeń reklamowych

Nasłuchiwanie metadanych czasowych za pomocą wywołanych zdarzeń reklamy w strumieniu audio/wideo. odtwarzacza wideo.

W przypadku strumieni MPEG-TS metadane są wyświetlane w postaci tagów ID3 v2.3 wewnątrz zakresu. Każdy tag metadanych ma identyfikator TXXX, a wartość rozpoczyna się ciągiem google_ a po niej ciąg znaków. Ta wartość to identyfikator zdarzenia reklamowego.

Element XXX w obiekcie TXXX nie jest symbolem zastępczym. Ciąg TXXX jest identyfikatorem tagu ID3. zarezerwowane dla „tekstu definiowanego 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ą ID3 v2.3 . Każde odpowiednie pole wiadomości e-mail ma wartość scheme_id_uri równą https://aomedia.org/emsg/ID3 lub https://developer.apple.com/streaming/emsg-id3 i wartość message_data rozpoczyna się od ID3TXXXgoogle_. Wartość message_data, bez prefiksu Prefiks ID3TXXX to identyfikator zdarzenia reklamowego.

Przykładowe e-maile

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 to:

{
  "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 wyświetlają zdarzenia emsg, które emulują identyfikator 3 jako natywne tagi ID3. W tym przypadku strumienie MP4 mają identyczne tagi ID3. jako MPEG_TS.

Zaktualizuj interfejs użytkownika 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 zgodny z pełnym identyfikatorem zdarzenia reklamowego. Jeśli znajdzie dopasowanie, pobierz typ zdarzenia i powiązane z nim ad oraz ad_break obiektów. Powinny one być typu progress.

    Jeśli nie znajdzie dopasowania do pełnego identyfikatora zdarzenia reklamowego, sprawdź tags dla klucza pasującego do pierwszych 17 znaków identyfikatora zdarzenia reklamy. Pobierz typ zdarzenia i powiązane z nim obiekty ad i ad_break. Powinno to pobrać wszystkie zdarzenia o typach innych niż progress.

  2. Wykorzystaj je, aby zaktualizować interfejs odtwarzacza. Na przykład, gdy otrzymasz zdarzenie start lub pierwsze progress, ukryj przewijanie przez gracza i wyświetl nakładkę z opisem bieżącej pozycji reklamy w przerwę na reklamę, na przykład „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 dotyczące weryfikacji multimediów

Ping dotyczący weryfikacji mediów musi być wysyłany do Ad Managera za każdym razem, gdy zdarzenie związane z reklamą o typie innym niż progress.

Aby wygenerować pełny URL do weryfikacji multimediów zdarzenia reklamowego, dołącz pełny adres URL identyfikator zdarzenia reklamowego na wartość media_verification_url z rejestracji strumienia .

Utwórz żądanie GET z pełnym adresem URL. Jeśli prośba o weryfikację to powodzenie, odpowiedź HTTP z kodem stanu 202. W przeciwnym razie zobaczysz kod błędu HTTP 404.

Przykładowe żądanie (cURL)

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

Przykładowa odpowiedź o powodzeniu

HTTP/1.1 202 Accepted

Dodatkowe materiały