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 modułu modyfikującego manifest.

Wymagania wstępne

Zanim przejdziesz dalej, musisz mieć:

Wysyłanie żądania strumienia

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 artykule Metoda: stream.

  2. Przekazuj parametry kierowania reklam w formacie application/x-www-form-urlencoded lub application/json. To żądanie rejestruje sesję strumienia w Google DAI.

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

    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 odpytać 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. Dzięki temu serwer może zwrócić pełne metadane okna DVR transmisji. Okno DVR zawiera przedział czasu transmisji, który widz może przewinąć i odtworzyć. Odpowiedź zawiera pole next_delta_token.
  3. Aby zoptymalizować przepustowość, zapisz wartość next_delta_token z ostatniej odpowiedzi.

  4. W następnym żą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. Szczegółowe informacje znajdziesz w artykule Metoda: metadane.

    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ę powiedzie, otrzymasz odpowiedź PodMetadata. Jeśli podasz parametr delta_token, odpowiedź będzie zawierać tylko reklamy, przerwy na reklamę i tagi, które serwer dodał lub zaktualizował od czasu wygenerowania tokena. Odpowiedź zawiera też nową wartość next_delta_token. Jeśli jakieś przerwy na reklamę są nieaktualne, odpowiedź zawiera też listę obsolete_ad_break_ids przerw na reklamę, które należy usunąć 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ń te przerwy na reklamę oraz powiązane z nimi reklamy i tagi z pamięci podręcznej.

  6. Ustaw minutnik, używając wartości polling_frequency, aby regularnie wysyłać żądania metadanych. W każdym zapytaniu wyślij wartość next_delta_token zwróconą w ostatniej odpowiedzi metadanych jako parametr zapytania delta_token.

Wczytywanie transmisji do odtwarzacza

Gdy otrzymasz identyfikator sesji z odpowiedzi na rejestrację, przekaż go do modułu modyfikującego manifest lub utwórz adres URL manifestu, aby wczytać strumień do odtwarzacza wideo.

Aby przekazać identyfikator sesji, zapoznaj się z dokumentacją modułu modyfikującego manifest. Jeśli tworzysz moduł modyfikujący manifest, zapoznaj się z artykułem Moduł modyfikujący manifest na potrzeby transmisji na żywo.

Poniższy przykład przedstawia 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 transmisji pod kątem metadanych czasowych:

  • Strumienie HLS z kontenerami Transport Stream (TS) używają tagów ID3 z sygnaturą czasową do przenoszenia metadanych z sygnaturą czasową. Więcej informacji znajdziesz w artykule na temat formatu 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 Event Message (emsg) z danymi ładunku, w tym tagami ID3. Więcej informacji znajdziesz w artykule InbandEventStream.

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

Aby pobrać tagi ID3 ze strumienia, zapoznaj się z przewodnikiem po odtwarzaczu. Więcej informacji znajdziesz w przewodniku po obsłudze metadanych z sygnaturą czasową.

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

  1. Filtruj zdarzenia według scheme_id_uri z urn:google:dai:2018 lub https://aomedia.org/emsg/ID3.
  2. Wyodrębnij tablicę bajtów z pola message_data.

    W tym przykładzie dane emsg są dekodowane 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
    

Pokaż dane zdarzeń związanych z reklamami

Aby znaleźć obiekt TagSegment, wykonaj te czynności:

  1. Pobierz obiekt metadanych reklamy tags z metadanych reklamy z ankietą. Obiekt tags to tablica obiektów TagSegment.

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

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

    Aplikacja kliencka okresowo odpytuje metadane reklamy, dlatego może wystąpić opóźnienie między momentem, gdy odtwarzacz wideo napotka tag ID3 w strumieniu, a momentem, gdy powiązane metadane staną się dostępne. Jeśli aplikacja kliencka nie znajdzie tagu ID3 w zapisanych tagach, zachowaj go w kolejce i ponownie przetwórz po kolejnym odpytaniu o metadane. Pozostaw tag w kolejce do czasu zakończenia przetwarzania.

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

    W tym przykładzie wyszukiwany jest 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 weryfikacji multimediów

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

Aby wygenerować pełny adres URL do weryfikacji multimediów dla zdarzenia reklamowego:

  1. Z odpowiedzi dotyczącej transmisji dołącz pełny identyfikator zdarzenia reklamowego do wartości media_verification_url.

  2. Wyś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ę powiedzie, otrzymasz odpowiedź z kodem stanu 202. W przeciwnym razie pojawi się 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. Szczegółowe informacje znajdziesz w artykule na temat monitorowania transmisji na żywo i rozwiązywania związanych z nią problemów.