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:
Ein benutzerdefinierter Asset-Schlüssel für ein Livestream-Ereignis, das mit dem DAI-Typ
Pod serving redirectkonfiguriert ist. So rufen Sie diesen Schlüssel ab:Livestream für die dynamische Anzeigenbereitstellung einrichten
Verwenden Sie eine SOAP API-Clientbibliothek, um die Methode
LiveStreamEventService.createLiveStreamEventsmit einemLiveStreamEvent-Objekt aufzurufen, wobei das AttributdynamicAdInsertionTypeauf den Enum-WertPOD_SERVING_REDIRECTfestgelegt ist. Alle Clientbibliotheken finden Sie unter Clientbibliotheken und Beispielcode.
Prüfen Sie, ob das Interactive Media Ads (IMA) SDK für Ihre Plattform verfügbar ist. Wir empfehlen, das IMA SDK zu verwenden, um den Umsatz zu steigern. Weitere Informationen finden Sie unter IMA SDK für die dynamische Anzeigenbereitstellung einrichten.
Streamanfrage stellen
Wenn der Nutzer einen Stream auswählt, gehen Sie so vor:
Stellen Sie eine
POST-Anfrage an die Livestream-Dienstmethode. Weitere Informationen finden Sie unter Methode: stream.Übergeben Sie Anzeigen-Targeting-Parameter im Format
application/x-www-form-urlencodedoderapplication/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 }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:
Lesen Sie den Wert
metadata_urlaus der Antwort auf die Streamregistrierung.Senden Sie eine erste
GET-Anfrage an den Endpunktmetadata_url.- Lassen Sie den Abfrageparameter
delta_tokenweg. 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 Feldnext_delta_token.
- Lassen Sie den Abfrageparameter
Speichern Sie den Wert
next_delta_tokenaus der letzten Antwort, um die Bandbreite zu optimieren.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_tokenangeben, 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 neuennext_delta_token-Wert. Wenn Werbeunterbrechungen veraltet sind, enthält die Antwort auch eineobsolete_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 }, ... } }Speichern Sie das
tags-Objekt und führen Sie die Aktualisierungen mit Ihrem lokalen Cache zusammen. Wenn der Parameterobsolete_ad_break_idsvorhanden ist, entfernen Sie diese Werbeunterbrechungen und die zugehörigen Anzeigen und Tags aus dem Cache.Legen Sie einen Timer mit dem Wert
polling_frequencyfest, um regelmäßig Metadaten anzufordern. Senden Sie bei jeder Abfrage den Wertnext_delta_token, der in der letzten Metadatenantwort zurückgegeben wurde, als Suchparameterdelta_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:
- Filtern Sie die Ereignisse nach
scheme_id_urimiturn:google:dai:2018oderhttps://aomedia.org/emsg/ID3. 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", ... }Filtern Sie die ID3-Tags im Format
TXXXgoogle_{ad_event_ID}:TXXXgoogle_1022389921
Anzeigenereignisdaten einblenden
So finden Sie das TagSegment-Objekt:
Rufen Sie das Anzeigenmetadatenobjekt
tagsaus Anzeigenmetadaten abfragen ab. Dastags-Objekt ist ein Array vonTagSegment-Objekten.Verwenden Sie die vollständige Anzeigenereignis-ID, um ein
TagSegment-Objekt mit dem Typprogresszu finden.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.
Wenn Sie die
TagSegmenthaben, verwenden Sie die Propertyad_break_idals Schlüssel, um das ObjektAdBreakim Objektad_breaksfür Anzeigenmetadaten zu finden.Im folgenden Beispiel wird ein
AdBreak-Objekt gesucht:{ "type":"mid", "duration":15, "ads":1 }Verwenden Sie die Daten
TagSegmentundAdBreak, 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:
Hängen Sie die vollständige Anzeigenereignis-ID aus der Streamantwort an den Wert
media_verification_urlan.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 Fehlercode404.
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.