Przygotowanie klienta do przekierowania bloku reklamowego

Ten przewodnik opisuje tworzenie 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ć:

Wysyłanie żądania strumienia

Gdy użytkownik wybierze strumień:

  1. Wyślij żądanie POST do metody usługi transmisji na żywo. Więcej informacji znajdziesz w artykule 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 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ę uda, zobaczysz dane wyjściowe podobne do tych:

    {
"stream_id": "8d2b2292-6356-4c0e-94be-cece01d2df2e: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.

Sprawdzanie metadanych reklamy

Aby sprawdzić metadane reklamy:

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

  2. Wyślij żądanie GET do punktu końcowego. Więcej informacji znajdziesz w artykule Metoda: metadata.

    Ten przykład pobiera metadane reklamy:

    const response = await fetch(metadata_url);
console.log(await response.json());

    Jeśli operacja się uda, otrzymasz odpowiedź PodMetadata dotyczącą bieżących i nadchodzących przerw na reklamę:

    {
  "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
    },
    ...
  }
}

  3. Zapisz obiekt tags na potrzeby kolejnych kroków.

  4. Ustaw timer z wartością polling_frequency, aby regularnie wysyłać żądania metadanych dla wszystkich kolejnych przerw na reklamę.

Wczytywanie strumienia do odtwarzacza wideo

Gdy uzyskasz identyfikator sesji z odpowiedzi na rejestrację, przekaż go do manipulatora pliku manifestu lub utwórz adres URL pliku manifestu, aby wczytać strumień do odtwarzacza wideo.

Aby przekazać identyfikator sesji, zapoznaj się z dokumentacją manipulatora pliku manifestu. Jeśli tworzysz manipulator pliku manifestu, zapoznaj się z artykułem Manipulator pliku manifestu w przypadku transmisji na żywo.

Ten przykład tworzy 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 z sygnaturą czasową:

  • 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 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 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 wideo. Więcej informacji znajdziesz w przewodniku Obsługa metadanych z sygnaturą czasową guide.

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

  1. Filtruj zdarzenia według scheme_id_uri z wartością urn:google:dai:2018 lub https://aomedia.org/emsg/ID3.

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

    Ten 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_1234567890123456789",
  ...
}

  3. Filtruj tagi ID3 według formatu TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1234567890123456789

Wyświetlanie danych zdarzenia reklamowego

Aby znaleźć obiekt TagSegment:

  1. Pobierz obiekt metadanych reklamy tags z sekcji Sprawdzanie metadanych reklamy. 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 innych typów.

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

    Ten przykład znajduje 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, wyślij ping weryfikacji multimediów. Usługa 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:

  1. Z odpowiedzi strumienia 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_5555555555123456789`;

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ń reklamowych. Więcej informacji znajdziesz w artykule Monitorowanie transmisji na żywo i rozwiązywanie związanych z nią problemów .