Przygotowanie klienta do przekierowania bloku reklamowego

Ten przewodnik zawiera informacje o tworzeniu aplikacji klienckiej do wczytywania transmisji na żywo HLS lub DASH za pomocą interfejsu Pod Serving API i manipulatora pliku manifestu.

Wymagania wstępne

Zanim przejdziesz dalej, musisz mieć:

Przesyłanie prośby o strumień

Gdy użytkownik wybierze strumień, wykonaj te czynności:

  1. Wyślij żądanie POST do metody usługi transmisji na żywo. Więcej informacji znajdziesz w sekcji Metoda: stream.

  2. Przekaż parametry kierowania reklam w formatach application/x-www-form-urlencoded lub application/json. To żądanie rejestruje sesję strumienia w usłudze Google DAI.

    Ten przykład wysyła żądanie strumieniowe:

    Kodowanie formularza

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

    Kodowanie JSON

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

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

    {
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

  3. W odpowiedzi JSON znajdź identyfikator sesji strumienia i zapisz inne dane na potrzeby kolejnych kroków.

Metadane reklamy z ankietą

Aby sprawdzić metadane reklamy:

  1. Odczytaj wartość metadata_url z odpowiedzi na rejestrację strumienia.

  2. 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 nagrywania cyfrowego (DVR) to przedział czasu, w którym transmisja jest dostępna dla widza do przewijania i odtwarzania. Odpowiedź zawiera pole next_delta_token.

  3. Aby zoptymalizować przepustowość, przechowuj wartość next_delta_token z najnowszej odpowiedzi.

  4. W kolejnym żądaniu wyślij tę wartość jako parametr zapytania delta_token. Serwer zwraca tylko metadane, które uległy zmianie od czasu wygenerowania tego tokena. Zawsze wysyłaj najnowszy otrzymany token. Nie próbuj analizować, modyfikować ani tworzyć tokena. Więcej informacji znajdziesz w sekcji Metoda: metadata.

    Ten przykład pobiera metadane reklamy:

    // Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

    Jeśli operacja się uda, otrzymasz odpowiedź PodMetadata. Jeśli podasz parametr delta_token, odpowiedź będzie zawierać tylko reklamy, przerwy na reklamy i tagi, które serwer dodał lub zaktualizował od momentu wygenerowania tokena. Odpowiedź zawiera też nową wartość next_delta_token. Jeśli któreś z przerw na reklamy są nieaktualne, odpowiedź zawiera też obsolete_ad_break_ids listę przerw na reklamy do usunięcia z pamięci podręcznej.

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

  5. Zapisz obiekt tags i scal aktualizacje w lokalnej pamięci podręcznej. Jeśli parametr obsolete_ad_break_ids jest obecny, usuń z pamięci podręcznej te przerwy na reklamę oraz powiązane z nimi reklamy i tagi.

  6. Ustaw timer za pomocą wartości polling_frequency, aby regularnie wysyłać żądania metadanych. W każdym zapytaniu wysyłaj wartość next_delta_token zwróconą w najnowszej odpowiedzi metadanych jako parametr zapytania delta_token.

Wczytaj strumień do odtwarzacza wideo

Po uzyskaniu identyfikatora sesji z odpowiedzi rejestracyjnej przekaż go do manipulatora pliku manifestu lub utwórz adres URL pliku manifestu, aby załadować strumień do odtwarzacza wideo.

Informacje o przekazywaniu identyfikatora sesji znajdziesz w dokumentacji narzędzia do manipulowania plikiem manifestu. Jeśli tworzysz manipulator pliku manifestu, zapoznaj się z sekcją Manipulator pliku manifestu w przypadku transmisji na żywo.

W tym przykładzie pokazujemy, jak utworzyć adres URL pliku manifestu:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

Gdy odtwarzacz będzie gotowy, rozpocznij odtwarzanie.

Nasłuchiwanie zdarzeń reklamowych

Sprawdź format kontenera strumienia pod kątem metadanych czasowych:

  • Strumienie HLS z kontenerami Transport Stream (TS) używają znaczników ID3 z określonym czasem, aby przenosić metadane z określonym czasem. Więcej informacji znajdziesz w artykule Informacje o formacie Common Media Application Format z transmisją na żywo przez HTTP (HLS).

  • Strumienie DASH używają elementów EventStream do określania zdarzeń w pliku manifestu.

  • Strumienie DASH używają elementów InbandEventStream, gdy segmenty zawierają pola wiadomości o zdarzeniu (emsg) z danymi ładunku, w tym tagami ID3. Więcej informacji znajdziesz w sekcji InbandEventStream.

  • Strumienie CMAF, w tym DASH i HLS, używają emsg zawierających tagi ID3.

Aby pobrać tagi ID3 z transmisji, zapoznaj się z przewodnikiem odtwarzacza wideo. Więcej informacji znajdziesz w przewodniku dotyczącym obsługi metadanych z określonym czasem.

Aby pobrać identyfikator zdarzenia reklamy z tagów ID3:

  1. Filtruj zdarzenia według kategorii scheme_id_uri za pomocą opcji urn:google:dai:2018 lub https://aomedia.org/emsg/ID3.

  2. Wyodrębnij tablicę bajtów z pola message_data.

    Poniższy przykład dekoduje dane emsg do formatu JSON:

    {
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1022389921",
  ...
}

  3. Filtruj tagi ID3 w formacie TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921

Wyświetlanie danych o zdarzeniach reklamowych

Aby znaleźć obiekt TagSegment:

  1. Pobierz obiekt metadanych reklamy tags z obiektu Poll ad metadata. Obiekt tags to tablica obiektów TagSegment.

  2. Użyj pełnego identyfikatora zdarzenia reklamowego, aby znaleźć obiekt TagSegment o typie progress.

  3. Użyj pierwszych 17 znaków identyfikatora zdarzenia reklamowego, aby znaleźć obiekt TagSegment innego typu.

    Aplikacja klienta okresowo odpytuje metadane reklamy, 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 aplikacja kliencka nie znajdzie w przechowywanych tagach tagu ID3, umieść go w kolejce i przetwórz ponownie po następnym pobraniu metadanych. Pozostaw tag w kolejce do momentu zakończenia przetwarzania.

  4. Po uzyskaniu wartości TagSegment użyj właściwości ad_break_id jako klucza, aby znaleźć obiekt AdBreak w obiekcie metadanych reklamy ad_breaks.

    Ten przykład wyszukuje obiekt AdBreak:

    {
  "type":"mid",
  "duration":15,
  "ads":1
}

  5. Użyj danych TagSegment i AdBreak, aby wyświetlić informacje o pozycji reklamy w przerwie na reklamę. Na przykład: Ad 1 of 3.

Wysyłanie pingów weryfikacyjnych dotyczących multimediów

W przypadku każdego zdarzenia reklamowego, z wyjątkiem zdarzenia typu progress, wyślij ping weryfikacji multimediów. Google DAI odrzuca zdarzenia progress, a częste wysyłanie tych zdarzeń może mieć wpływ na wydajność aplikacji.

Aby wygenerować pełny URL do weryfikacji multimediów zdarzenia reklamowego, wykonaj te czynności:

  1. Z odpowiedzi strumienia dołącz pełny identyfikator zdarzenia reklamy do wartości media_verification_url.

  2. Prześlij żądanie GET z pełnym adresem URL:

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

    Jeśli operacja się uda, otrzymasz odpowiedź ze stanem kodu 202. W przeciwnym razie otrzymasz kod błędu 404.

Możesz użyć narzędzia do monitorowania aktywności w transmisji na żywo (SAM), aby sprawdzić historyczny dziennik wszystkich zdarzeń związanych z reklamami. Więcej informacji znajdziesz w artykule Monitorowanie transmisji na żywo i rozwiązywanie problemów z nią.