Ce guide explique comment développer une application cliente pour charger un flux en direct HLS ou DASH avec l'API de diffusion de séries d'annonces et votre outil de manipulation de fichier manifeste.
Prérequis
Avant de continuer, vous devez disposer des éléments suivants :
Clé d'élément personnalisée pour un événement de diffusion en direct configuré avec le type d'insertion dynamique d'annonce
Pod serving redirect. Pour obtenir cette clé, procédez comme suit :Configurez une diffusion en direct pour l'insertion dynamique d'annonce.
Utilisez une bibliothèque cliente de l'API SOAP pour appeler la méthode
LiveStreamEventService.createLiveStreamEventsavec un objetLiveStreamEventet la propriétédynamicAdInsertionTypedéfinie sur la valeur d'énumérationPOD_SERVING_REDIRECT. Pour toutes les bibliothèques clientes, consultez Bibliothèques clientes et exemple de code.
Déterminez si le SDK Interactive Media Ads (IMA) est disponible pour votre plate-forme. Nous vous recommandons d'utiliser le SDK IMA pour augmenter vos revenus. Pour en savoir plus, consultez Configurer le SDK IMA pour l'insertion dynamique d'annonce.
Envoyer une requête de flux
Lorsque l'utilisateur sélectionne un flux, procédez comme suit :
Envoyez une requête
POSTà la méthode du service Livestream. Pour en savoir plus, consultez Méthode : stream.Transmettez les paramètres de ciblage des annonces aux formats
application/x-www-form-urlencodedouapplication/json. Cette requête enregistre une session de flux auprès de Google DAI.L'exemple suivant envoie une requête de flux :
Encodage du formulaire
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());Encodage 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());Si l'opération réussit, un résultat semblable à celui-ci s'affiche :
{ "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 }Dans la réponse JSON, recherchez l'ID de session du flux et stockez d'autres données pour les étapes suivantes.
Métadonnées des annonces de sondage
Pour interroger les métadonnées d'annonce, procédez comme suit :
Lisez la valeur
metadata_urlà partir de la réponse d'enregistrement du flux.Envoyez une requête
GETinitiale au point de terminaisonmetadata_url.- Omettez le paramètre de requête
delta_token. Ce processus permet au serveur de renvoyer les métadonnées complètes de la fenêtre de l'enregistreur vidéo numérique (DVR) du flux. La fenêtre DVR contient la période de la diffusion que le spectateur peut rembobiner et lire. La réponse inclut un champnext_delta_token.
- Omettez le paramètre de requête
Pour optimiser la bande passante, stockez la valeur
next_delta_tokende la réponse la plus récente.Lors de votre prochaine requête, envoyez cette valeur en tant que paramètre de requête
delta_token. Le serveur ne renvoie que les métadonnées qui ont changé depuis la génération de ce jeton. Envoyez toujours le dernier jeton que vous avez reçu. N'essayez pas d'analyser, de modifier ni de construire le jeton. Pour en savoir plus, consultez Méthode : metadata.L'exemple suivant récupère les métadonnées de l'annonce :
// 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; }Si l'opération réussit, vous recevez la réponse PodMetadata. Si vous fournissez le paramètre
delta_token, la réponse ne contient que les annonces, les coupures publicitaires et les tags que le serveur a ajoutés ou mis à jour depuis qu'il a généré le jeton. La réponse contient également une nouvelle valeurnext_delta_token. Si des coupures publicitaires sont obsolètes, la réponse inclut également une listeobsolete_ad_break_idsdes coupures publicitaires à supprimer de votre cache.{ "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 }, ... } }Enregistrez l'objet
tagset fusionnez les mises à jour dans votre cache local. Si le paramètreobsolete_ad_break_idsest présent, supprimez ces coupures publicitaires ainsi que les annonces et les tags associés de votre cache.Définissez un minuteur à l'aide de la valeur
polling_frequencypour demander régulièrement des métadonnées. Dans chaque interrogation, envoyez la valeurnext_delta_tokenrenvoyée dans la réponse de métadonnées la plus récente en tant que paramètre de requêtedelta_token.
Charger le flux dans votre lecteur vidéo
Une fois que vous avez obtenu l'ID de session à partir de la réponse d'enregistrement, transmettez-le à votre outil de manipulation de fichier manifeste ou créez une URL de fichier manifeste pour charger le flux dans un lecteur vidéo.
Pour transmettre l'ID de session, consultez la documentation de votre outil de manipulation de fichier manifeste. Si vous développez un outil de manipulation de fichier manifeste, consultez Outil de manipulation de fichier manifeste pour la diffusion en direct.
L'exemple suivant assemble une URL de fichier manifeste :
https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"
Lorsque votre lecteur est prêt, lancez la lecture.
Écouter les événements d'annonce
Vérifiez le format de conteneur de votre flux pour les métadonnées temporelles :
Les flux HLS avec des conteneurs Transport Stream (TS) utilisent des balises ID3 temporelles pour transporter des métadonnées temporelles. Pour en savoir plus, consultez À propos du format CMAF (Common Media Application Format) avec HTTP Live Streaming (HLS).
Les flux DASH utilisent des éléments
EventStreampour spécifier des événements dans le fichier manifeste.Les flux DASH utilisent des éléments
InbandEventStreamlorsque les segments contiennent des zones de message d'événement (emsg) pour les données de charge utile, y compris les tags ID3. Pour en savoir plus, consultez InbandEventStream.Les flux CMAF, y compris DASH et HLS, utilisent des cases
emsgcontenant des tags ID3.
Pour récupérer les tags ID3 de votre flux, consultez le guide de votre lecteur vidéo. Pour en savoir plus, consultez le guide Gérer les métadonnées temporelles.
Pour récupérer l'ID d'événement d'annonce à partir des tags ID3, procédez comme suit :
- Filtrez les événements par
scheme_id_uriavecurn:google:dai:2018ouhttps://aomedia.org/emsg/ID3. Extrayez le tableau d'octets du champ
message_data.L'exemple suivant décode les données
emsgau format JSON :{ "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3", "presentation_time": 27554, "timescale": 1000, "message_data": "ID3TXXXgoogle_1022389921", ... }Filtrez les tags ID3 au format
TXXXgoogle_{ad_event_ID}:TXXXgoogle_1022389921
Afficher les données d'événement d'annonce
Pour trouver l'objet TagSegment, procédez comme suit :
Récupérez l'objet de métadonnées d'annonce
tagsà partir de Interroger les métadonnées d'annonce. L'objettagsest un tableau d'objetsTagSegment.Utilisez l'ID d'événement d'annonce complet pour trouver un objet
TagSegmentde typeprogress.Utilisez les 17 premiers caractères de l'ID d'événement d'annonce pour trouver un objet
TagSegmentd'autres types.Étant donné que votre application cliente interroge régulièrement les métadonnées d'annonce, un délai peut s'écouler entre le moment où votre lecteur vidéo rencontre un tag ID3 dans le flux et celui où les métadonnées associées sont disponibles. Si votre application cliente ne trouve pas de tag ID3 dans les tags stockés, conservez le tag dans une file d'attente et traitez-le à nouveau après l'interrogation suivante des métadonnées. Conservez la balise dans la file d'attente jusqu'à la fin du traitement.
Une fois que vous disposez de
TagSegment, utilisez la propriétéad_break_idcomme clé pour trouver l'objetAdBreakdans l'objetad_breaksdes métadonnées de l'annonce.L'exemple suivant recherche un objet
AdBreak:{ "type":"mid", "duration":15, "ads":1 }Utilisez les données
TagSegmentetAdBreakpour afficher des informations sur la position de l'annonce dans la coupure publicitaire. Par exemple,Ad 1 of 3.
Envoyer des pings de suivi publicitaire
Pour chaque événement d'annonce, à l'exception du type progress, envoyez un ping de suivi publicitaire.
L'insertion dynamique d'annonce Google supprime les événements progress. L'envoi fréquent de ces événements peut avoir un impact sur les performances de votre application.
Pour générer l'URL complète de validation du média d'un événement d'annonce, procédez comme suit :
À partir de la réponse du flux, ajoutez l'ID complet de l'événement d'annonce à la valeur
media_verification_url.Envoyez une requête
GETavec l'URL complète :// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/" const completeUrl = `${media_verification_url}google_1022389921`; const response = await fetch(completeUrl);Si l'opération réussit, vous recevez une réponse avec le code d'état
202. Sinon, vous recevrez un code d'erreur404.
Vous pouvez utiliser le contrôle de l'activité des flux (SAM) pour inspecter un journal d'historique de tous les événements d'annonce. Pour en savoir plus, consultez Surveiller et dépanner une diffusion en direct.