L'API d'insertion dynamique d'annonce permet d'accéder aux flux monétisés sur les plates-formes qui n'acceptent pas le SDK IMA (par exemple, les Smart TV). Le SKD IMA est obligatoire sur les plates-formes où il est disponible. L'API est compatible avec toutes les fonctionnalités existantes d'insertion dynamique d'annonce, mais celles-ci nécessitent une intégration de la part de l'éditeur.
Exigences concernant l'utilisation de l'API
Les fonctionnalités suivantes nécessitent une implémentation par l'éditeur lorsque vous utilisez l'API:
- Accès au flux d'insertion dynamique d'annonce via le point de terminaison HTTP et traitement des réponses JSON
- Ajustement des paramètres d'API et ciblage des clés-valeurs
- Mise en œuvre des expériences utilisateur (par exemple, les zones cliquables et les icônes)
- Écoute des événements ID3 dans le lecteur pour mettre en œuvre les commandes de lecteur et le suivi/la mesure des performances des annonces pour le contenu linéaire en direct et les vidéos à la demande
- Intégration des comportements d'utilisation de la barre de lecture, des snapbacks (retours rapides) et des favoris
- Sélection des formats de streaming : HLS ou DASH
Vous pouvez utiliser les informations suivantes pour savoir comment demander et traiter des flux via l'API pour les flux linéaires en direct ou les vidéos à la demande.
Vidéo à la demande
L'API pour les vidéos à la demande suit un cycle de vie simple allant de la création du flux à la vérification de la lecture d'annonces. Procédez comme suit :
-
Demandez un flux avec une requête HTTP POST à l'aide de l'ID de la source du contenu (
cmsid) et de l'ID vidéo (vid), avec la clé API ou le jeton HMAC, ainsi que les paramètres de ciblage des annonces.https://dai.google.com/ondemand/v1/hls/content/<contentId>/vid/<vid>/stream -
Traitez la réponse pour le manifeste de lecture du contenu, les sous-titres, la coupure publicitaire, et les informations de synchronisation du contenu.
{"content_duration": 123.451,"stream_manifest": "https://dai.google.com/.../master.m3u8","media_verification_url": "https://dai.google.com/.../media/","stream_id": "9ca0c62a-3291-4f95-986f-d1721f8b96f0","total_duration": 163.451,"valid_for": "8h0m0s","valid_until": "2018-05-16T23:21:16.558053292-07:00","ad_breaks": [...]} -
Pour chaque coupure publicitaire, traitez les détails des annonces individuelles pour les éléments d'annonce tels que les clics, les annonces associées et la durée de la coupure publicitaire pour le rendu dans l'interface utilisateur.
{"clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400","description": "Example pre-roll ad","duration": 10,"seq": 1,"title": "Example pre-roll"} -
Pour chaque annonce, déclenchez l'événement
media_verification_urlavec la valeur ID3 associée depuis le lecteur d'annonces.https://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/
Les événements de type Progress permettent uniquement de différencier les lectures au sein et en dehors d'une coupure publicitaire, et ne jouent aucun autre rôle dans le suivi des annonces.
Pour identifier les événements de type Progress, recherchez l'identifiant de média dans le fichier de métadonnées JSON, puis vérifiez que le champ type est défini sur progress. L'événement ID3 de type Progress permet par exemple de bloquer les commandes vidéo.
Flux linéaires en direct
L'API pour le contenu linéaire suit un cycle de vie simple allant de la création du flux à la vérification de la lecture d'annonces. Procédez comme suit :
-
Demandez un flux avec une requête HTTP POST à l'aide de l'ID d'événement, avec la clé API ou le jeton HMAC, ainsi que les paramètres de ciblage des annonces.
https://dai.google.com/linear/v1/hls/event/<eventid>/stream
https://dai.google.com/linear/v1/dash/event/<eventid>/stream -
Traitez la réponse pour le manifeste de lecture du contenu, les sous-titres, la coupure publicitaire, et les informations de synchronisation du contenu.
{"stream_manifest": "https://dai.google.com/linear/.../master.m3u8","media_verification_url": "https://dai.google.com/linear/.../media/","metadata_url": "https://dai.google.com/linear/.../metadata","polling_frequency": 10,"stream_id": "793bf10c-2323-404d-b23b-0a529d96e651:MRN",} -
Demandez les métadonnées d'annonce à la fréquence définie par le mécanisme de sondage ou pour chaque ID d'annonce multimédia ID3, en associant celui-ci à l'URL de métadonnées dans un paramètre de requête.
{"ad_breaks": {"0001127859": {"ads": 3,"duration": 30,"type": "mid"}},"ads": {"0001127859_ad2": {"ad_break_id": "0001127859","ad_id": "39135088","ad_system": "GDFP","clickthrough_url": "http://pubads.g.doubleclick.net/pcs/click?...","creative_id": "103990016608","description": "Example linear 10s ad","duration": 10,"position": 2,"title": "Example linear ad"}},"tags": {"google_0028792773": {"ad": "0001127859_ad2","ad_break_id": "0001127859","type": "firstquartile"}, ...}} -
Pour chaque annonce, déclenchez l'événement
media_verification_urlavec la valeur ID3 associée depuis le lecteur d'annonces.https://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/
Les événements de type Progress permettent uniquement de différencier les lectures au sein et en dehors d'une coupure publicitaire, et ne jouent aucun autre rôle dans le suivi des annonces.
Pour identifier les événements de type Progress, recherchez l'identifiant de média dans le fichier de métadonnées JSON, puis vérifiez que le champ type est défini sur progress. L'événement ID3 de type Progress permet par exemple de bloquer les commandes vidéo.
Détecter quand une coupure publicitaire a commencé ou s'est terminée dans le flux à l'aide de l'API d'insertion dynamique d'annonce
L'insertion dynamique d'annonces intègre des métadonnées ID3 pour les événements de quart (comme "Début", "Premier quart", "Première moitié", "Troisième quart" et "Terminé") dans les segments d'annonces et les événements de progression (toutes les secondes) dans les segments d'annonces et d'écran. Lorsqu'un tag ID3 est détecté pour la première fois, l'événement "Coupure publicitaire démarrée" peut être déclenché. Ensuite, lorsqu'aucun tag ID3 n'est détecté pendant 2,5 secondes, l'événement "Coupure publicitaire terminée" est déclenché. Les tags ID3 intégrés pour l'insertion dynamique d'annonces sont identifiés par leur préfixe google_ et leur présence dans le fichier JSON de métadonnées.
Mettre à jour le ciblage et/ou les clés-valeurs de façon dynamique pour chaque flux d'utilisateur
Vous pouvez utiliser la valeur session_update_url afin de remplacer l'ensemble des paramètres de tag d'emplacement publicitaire utilisés dans les demandes d'annonces à valider pour un flux en direct (le rôle de cette valeur est semblable à celui de l'élément replaceAdTagParameters). Cette valeur est particulièrement utile lorsque vous avez besoin de mettre à jour les informations de ciblage pour chaque programme et chaque utilisateur (par exemple, pour les vidéos de sport en direct où le ciblage peut ne pas être connu à l'avance).