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 Manifest-Manipulator zu laden.

Vorbereitung

Bevor Sie fortfahren, benötigen Sie Folgendes:

Streaminganfrage stellen

Wenn Ihr 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 Parameter für das Anzeigen-Targeting im Format application/x-www-form-urlencoded oder application/json. Mit dieser Anfrage wird eine Streamingsitzung 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 Stream-Sitzungs-ID und speichern Sie andere Daten für die nachfolgenden Schritte.

Anzeigenmetadaten abrufen

So rufen Sie Anzeigenmetadaten ab:

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

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

    • Lassen Sie den Abfrageparameter delta_token weg. So 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, der für Zuschauer zum Zurückspulen und Abspielen verfügbar ist. Die Antwort enthält ein Feld next_delta_token.

  3. Um die Bandbreite zu optimieren, speichern Sie den next_delta_token-Wert aus der letzten Antwort.

  4. Senden Sie diesen Wert in Ihrer nächsten Anfrage als Abfrageparameter delta_token. Der Server gibt nur die Metadaten zurück, die sich seit der Generierung des Tokens geändert haben. Senden Sie immer das letzte 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 Erfolg erhalten Sie die PodMetadata-Antwort. 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 Ihrem Cache entfernt werden müssen.

    {
  "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 in Ihren lokalen Cache ein. Wenn der Parameter obsolete_ad_break_ids vorhanden ist, entfernen Sie diese Werbeunterbrechungen sowie die zugehörigen Anzeigen und Tags aus Ihrem Cache.

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

Stream in den Videoplayer laden

Nachdem Sie die Sitzungs-ID aus der Registrierungsantwort erhalten haben, übergeben Sie die ID an Ihren Manifest-Manipulator 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 zu Ihrem Manifest-Manipulator. Wenn Sie einen Manifest-Manipulator entwickeln, lesen Sie den Abschnitt Manifest-Manipulator 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, starte 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 Common Media Application Format (CMAF) 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 emsg-Felder für Nutzlastdaten, einschließlich ID3-Tags, enthalten. Weitere Informationen finden Sie unter InbandEventStream.

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

Informationen zum Abrufen von ID3-Tags aus deinem Stream findest du in der Anleitung deines Videoplayers. Weitere Informationen finden Sie im Leitfaden zum Verarbeiten von Zeitmetadaten.

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 mit dem Format TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921

Werbeereignisdaten anzeigen

So finden Sie das TagSegment-Objekt:

  1. Rufen Sie das tags-Objekt für Anzeigenmetadaten aus Poll ad metadata 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, zu dem Ihr Videoplayer ein ID3-Tag im Stream erkennt, und dem Zeitpunkt, zu dem die zugehörigen Metadaten verfügbar sind, kommen. Wenn Ihre Client-App kein ID3-Tag in den gespeicherten Tags findet, behalten Sie das Tag in einer Warteschlange bei und verarbeiten Sie es nach dem nächsten Metadaten-Polling noch einmal. Lassen Sie das Tag in der Warteschlange, bis die Verarbeitung abgeschlossen ist.

  4. Nachdem Sie die TagSegment haben, verwenden Sie die Eigenschaft ad_break_id als Schlüssel, um das Objekt AdBreak im Objekt ad_breaks mit Anzeigenmetadaten zu finden.

    Im folgenden Beispiel wird ein AdBreak-Objekt gesucht:

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

  5. Mit den Daten TagSegment und AdBreak können Sie Informationen zur Anzeigenposition in der Werbeunterbrechung anzeigen. Beispiel: Ad 1 of 3

Media-Bestätigungs-Pings senden

Senden Sie für jedes Anzeigenereignis mit Ausnahme des Typs progress einen Media-Überprüfungs-Ping. Bei Google DAI werden progress-Ereignisse verworfen. Wenn Sie diese Ereignisse häufig senden, kann sich das auf die App-Leistung auswirken.

So generieren Sie die vollständige Media-Bestätigungs-URL eines Anzeigenereignisses:

  1. Hängen Sie aus der Streamantwort die vollständige Anzeigenereignis-ID 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 Erfolg erhalten Sie eine Antwort mit dem Codestatus 202. Andernfalls erhalten Sie den Fehlercode 404.

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