Client für die Weiterleitung für die Pod-Auslieferung vorbereiten

In diesem Leitfaden wird beschrieben, wie Sie eine Clientanwendung entwickeln, um einen HLS- oder DASH-Livestream mit der Pod Serving API und Ihrem Manifestbearbeitung zu laden.

Vorbereitung

Bevor Sie fortfahren, benötigen Sie Folgendes:

Streamanfrage stellen

Wenn der Nutzer einen Stream auswählt, gehen Sie so vor:

  1. Stellen Sie eine POST-Anfrage an die Livestream-Dienstmethode. Weitere Informationen finden Sie unter Methode: stream.

  2. Übergeben Sie Anzeigen-Targeting-Parameter im Format application/x-www-form-urlencoded oder application/json. Mit dieser Anfrage wird eine Streamsitzung bei Google DAI registriert.

    Im folgenden Beispiel wird eine Streamanfrage gestellt:

    Formularcodierung

    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());
    

    JSON-Codierung

    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());
    

    Bei erfolgreicher Ausführung erhalten Sie eine Ausgabe ähnlich der folgenden:

    {
    "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. Suchen Sie in der JSON-Antwort nach der Streamsitzungs-ID und speichern Sie andere Daten für die nachfolgenden Schritte.

Metadaten der Umfrageanzeige

So rufen Sie Anzeigenmetadaten ab:

  1. Lesen Sie den Wert metadata_url aus der Antwort auf die Streamregistrierung.

  2. Senden Sie eine erste GET-Anfrage an den Endpunkt metadata_url.

    • Lassen Sie den Abfrageparameter delta_token weg. Dadurch kann der Server die vollständigen Metadaten für das DVR-Fenster (Digital Video Recorder) des Streams zurückgeben. Das DVR-Fenster enthält den Zeitraum der Übertragung, den ein Zuschauer zurückspulen und wiedergeben kann. Die Antwort enthält ein Feld next_delta_token.
  3. Speichern Sie den Wert next_delta_token aus der letzten Antwort, um die Bandbreite zu optimieren.

  4. Senden Sie diesen Wert bei Ihrer nächsten Anfrage als Suchparameter delta_token. Der Server gibt nur die Metadaten zurück, die sich seit der Generierung dieses Tokens geändert haben. Senden Sie immer das neueste Token, das Sie erhalten haben. Versuchen Sie nicht, das Token zu parsen, zu ändern oder zu erstellen. Weitere Informationen finden Sie unter Methode: Metadaten.

    Im folgenden Beispiel werden Anzeigenmetadaten abgerufen:

    // 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;
    }
    

    Bei erfolgreicher Ausführung erhalten Sie die Antwort PodMetadata. Wenn Sie den Parameter delta_token angeben, enthält die Antwort nur die Anzeigen, Werbeunterbrechungen und Tags, die der Server seit der Generierung des Tokens hinzugefügt oder aktualisiert hat. Die Antwort enthält auch einen neuen next_delta_token-Wert. Wenn Werbeunterbrechungen veraltet sind, enthält die Antwort auch eine obsolete_ad_break_ids-Liste der Werbeunterbrechungen, die aus dem Cache entfernt werden sollen.

    {
      "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. Speichern Sie das tags-Objekt und führen Sie die Aktualisierungen mit Ihrem lokalen Cache zusammen. Wenn der Parameter obsolete_ad_break_ids vorhanden ist, entfernen Sie diese Werbeunterbrechungen und die zugehörigen Anzeigen und Tags aus dem Cache.

  6. Legen Sie einen Timer mit dem Wert polling_frequency fest, um regelmäßig Metadaten anzufordern. Senden Sie bei jeder Abfrage den Wert next_delta_token, der in der letzten Metadatenantwort zurückgegeben wurde, als Suchparameter delta_token.

Stream in den Videoplayer laden

Nachdem Sie die Sitzungs-ID aus der Registrierungsantwort erhalten haben, übergeben Sie die ID an Ihren Manifestbearbeitung oder erstellen Sie eine Manifest-URL, um den Stream in einen Videoplayer zu laden.

Informationen zum Übergeben der Sitzungs-ID finden Sie in der Dokumentation zur Manifestbearbeitung. Wenn Sie einen Manifestbearbeiter entwickeln, lesen Sie den Abschnitt Manifestbearbeiter für Livestream.

Im folgenden Beispiel wird eine Manifest-URL zusammengestellt:

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

Wenn der Player bereit ist, starten Sie die Wiedergabe.

Auf Anzeigenereignisse warten

Prüfe das Containerformat deines Streams auf zeitgesteuerte Metadaten:

  • HLS-Streams mit Transport Stream-Containern (TS) verwenden zeitgesteuerte ID3-Tags, um zeitgesteuerte Metadaten zu übertragen. Weitere Informationen finden Sie unter Informationen zum Common Media Application Format mit HTTP Live Streaming (HLS).

  • In DASH-Streams werden EventStream-Elemente verwendet, um Ereignisse im Manifest anzugeben.

  • DASH-Streams verwenden InbandEventStream-Elemente, wenn die Segmente Event Message-Boxen (emsg) für Nutzlastdaten enthalten, einschließlich ID3-Tags. Weitere Informationen finden Sie unter InbandEventStream.

  • CMAF-Streams, einschließlich DASH und HLS, verwenden emsg-Boxen, die ID3-Tags enthalten.

Informationen zum Abrufen von ID3-Tags aus Ihrem Stream finden Sie in der Anleitung Ihres Videoplayers. Weitere Informationen finden Sie im Leitfaden zum Umgang mit zeitgesteuerten Metadaten.

So rufen Sie die Anzeigenereignis-ID aus ID3-Tags ab:

  1. Filtern Sie die Ereignisse nach scheme_id_uri mit urn:google:dai:2018 oder https://aomedia.org/emsg/ID3.
  2. Extrahieren Sie das Byte-Array aus dem Feld message_data.

    Im folgenden Beispiel werden die emsg-Daten in JSON decodiert:

    {
      "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
      "presentation_time": 27554,
      "timescale": 1000,
      "message_data": "ID3TXXXgoogle_1022389921",
      ...
    }
    
  3. Filtern Sie die ID3-Tags im Format TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921
    

Anzeigenereignisdaten einblenden

So finden Sie das TagSegment-Objekt:

  1. Rufen Sie das Anzeigenmetadatenobjekt tags aus Anzeigenmetadaten abfragen ab. Das tags-Objekt ist ein Array von TagSegment-Objekten.

  2. Verwenden Sie die vollständige Anzeigenereignis-ID, um ein TagSegment-Objekt mit dem Typ progress zu finden.

  3. Verwenden Sie die ersten 17 Zeichen der Anzeigenereignis-ID, um ein TagSegment-Objekt anderer Typen zu finden.

    Da Ihre Client-App regelmäßig Anzeigenmetadaten abruft, kann es zu einer Verzögerung zwischen dem Zeitpunkt, an dem Ihr Videoplayer ein ID3-Tag im Stream findet, und dem Zeitpunkt, an dem die zugehörigen Metadaten verfügbar sind, kommen. Wenn die Client-App kein ID3-Tag in den gespeicherten Tags findet, behalten Sie das Tag in einer Warteschlange und verarbeiten Sie es nach der nächsten Metadatenabfrage noch einmal. Behalten Sie das Tag in der Warteschlange, bis die Verarbeitung abgeschlossen ist.

  4. Wenn Sie die TagSegment haben, verwenden Sie die Property ad_break_id als Schlüssel, um das Objekt AdBreak im Objekt ad_breaks für Anzeigenmetadaten zu finden.

    Im folgenden Beispiel wird ein AdBreak-Objekt gesucht:

    {
      "type":"mid",
      "duration":15,
      "ads":1
    }
    
  5. Verwenden Sie die Daten TagSegment und AdBreak, um Informationen zur Anzeigenposition in der Werbeunterbrechung anzuzeigen. Beispiel: Ad 1 of 3

Media-Bestätigungs-Pings senden

Senden Sie für jedes Anzeigenereignis, mit Ausnahme des Typs progress, einen Media-Bestätigungs-Ping. Google DAI verwirft progress-Ereignisse. Wenn diese Ereignisse häufig gesendet werden, kann sich das auf die App-Leistung auswirken.

So generieren Sie die vollständige URL für die Medienbestätigung eines Anzeigenereignisses:

  1. Hängen Sie die vollständige Anzeigenereignis-ID aus der Streamantwort an den Wert media_verification_url an.

  2. Stellen Sie eine GET-Anfrage mit der vollständigen 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);
    

    Bei erfolgreicher Ausführung erhalten Sie die Antwort 202. Andernfalls erhalten Sie den Fehlercode 404.

Mit der Überprüfung der Streamingaktivitäten (Stream Activity Monitor, SAM) können Sie ein Protokoll aller bisherigen Anzeigenereignisse einsehen. Weitere Informationen finden Sie unter Livestream überwachen und Fehler beheben.