L'API Google d'insertion dynamique de séries d'annonces vous permet d'insérer des annonces côté serveur grâce à Google Ads, tout en gardant le contrôle sur l'assemblage de vos vidéos.
Ce guide vous explique comment interagir avec l'API Pod Serving et obtenir des fonctionnalités similaires avec le SDK IMA pour l'insertion dynamique d'annonce. Pour toute question concernant les fonctionnalités compatibles, contactez votre responsable de compte Google.
L'API Pod Serving est compatible avec les flux de diffusion de pods dans les protocoles de streaming HLS ou MPEG-DASH. Ce guide se concentre sur les flux HLS et met en évidence les principales différences entre HLS et MPEG-DASH dans des étapes spécifiques.
Pour intégrer l'API Pod Serving dans votre application pour les flux de vidéo à la demande, procédez comme suit:
Envoyer une demande d'enregistrement de flux à Ad Manager
Envoyez une requête POST au point de terminaison d'enregistrement de flux. Vous recevez à votre tour une réponse JSON contenant l'ID de flux à envoyer à votre serveur de manipulation du fichier manifeste et aux points de terminaison associés de l'API de diffusion de pods.
Point de terminaison de l'API
POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json
Paramètres de chemin d'accès
{network_code} |
Votre code de réseau Google Ad Manager 360 |
Paramètres du corps JSON
targeting_parameters |
Objet JSON contenant l'ID de la source du contenu (cmsid), l'ID vidéo (vid) et les paramètres de ciblage de l'annonce. Obligatoire |
Réponse JSON
media_verification_url |
URL de base pour pinguer les événements de suivi de lecture. Une URL de validation multimédia complète est constituée de l'ajout d'un ID d'événement d'annonce à cette URL de base. |
metadata_url |
URL de la demande de métadonnées de séries d'annonces. |
stream_id |
Chaîne utilisée pour identifier la session de diffusion en cours. |
valid_for |
Temps restant avant l'expiration de la session de diffusion en cours, au format dhms (jours, heures, minutes, secondes). Par exemple, 2h0m0.000s représente une durée de deux heures.
|
valid_until |
Heure à laquelle la session de flux en cours expire, sous la forme d'une chaîne de date et d'heure ISO 8601 au format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
Exemple de requête (cURL)
curl -X POST \
-d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
-H 'Content-Type: application/json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration
Exemple de réponse
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
En cas d'erreurs, les codes d'erreur HTTP standards sont renvoyés sans corps de réponse JSON.
Analysez la réponse JSON et stockez les valeurs appropriées.
Demander le fichier manifeste de flux à l'outil de manipulation du fichier manifeste
Chaque outil de manipulation du fichier manifeste utilise des formats de requête et de réponse différents. Contactez le fournisseur de votre outil de manipulation pour connaître ses exigences spécifiques. Si vous implémentez votre propre outil de manipulation du fichier manifeste, lisez le guide de l'outil de manipulation du fichier manifeste pour comprendre les exigences relatives à ce composant.
En général, vous devez transmettre l'ID de flux qui a été renvoyé par le point de terminaison d'inscription ci-dessus à votre outil de manipulation du fichier manifeste pour qu'il crée des fichiers manifestes spécifiques à la session. Sauf indication contraire explicite de votre outil de manipulation du fichier manifeste, la réponse à votre requête de fichier manifeste est un flux vidéo contenant à la fois du contenu et des annonces.
Exemple de requête (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
Exemple de réponse (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
Lire le flux
Chargez le fichier manifeste que vous avez reçu du serveur de manipulation du fichier manifeste dans un lecteur vidéo, puis démarrez la lecture.
Demander des métadonnées de séries d'annonces à Ad Manager
Envoyez une requête GET
au metadata_url
que vous avez reçu à l'étape 1. Cette étape doit avoir lieu après avoir reçu le fichier manifeste assemblé de la part de votre outil de manipulation du fichier manifeste. En retour, vous recevez un objet JSON contenant les paramètres suivants:
tags |
Un ensemble de paires clé-valeur contenant tous les événements d'annonce qui apparaissent dans le flux. Les clés correspondent soit aux 17 premiers caractères de l'ID d'événement d'annonce, qui apparaissent dans les métadonnées temporisées du flux, soit dans le cas d'événements de type progress , à l'ID complet de l'événement d'annonce.
Chaque valeur est un objet contenant les paramètres suivants:
|
||||||||||||||||||
ads |
Un ensemble de paires clé-valeur décrivant toutes les annonces qui apparaissent dans le flux. Les clés sont des identifiants d'annonces qui correspondent aux valeurs trouvées dans l'objet tags indiqué ci-dessus. Chaque valeur est un objet contenant les paramètres suivants:
|
||||||||||||||||||
ad_breaks |
Ensemble de paires clé-valeur décrivant toutes les coupures publicitaires qui apparaissent dans le flux.
Les clés sont des ID de coupures publicitaires qui correspondent aux valeurs trouvées dans les objets tags et ads répertoriés ci-dessus. Chaque valeur est un objet contenant les paramètres suivants:
|
Stockez ces valeurs pour les associer aux événements de métadonnées chronométrées dans votre flux vidéo.
Exemple de requête (cURL)
curl https://dai.google.com/.../metadata
Exemple de réponse
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
Écouter les événements d'annonce
Écoutez les métadonnées chronométrées via des événements d'annonce déclenchés dans le flux audio/vidéo de votre lecteur vidéo.
Pour les flux MPEG-TS, les métadonnées apparaissent sous la forme de tags intra-bandes ID3 v2.3. Chaque balise de métadonnées possède l'ID TXXX
. La valeur commence par la chaîne google_
suivie d'une série de caractères. Cette valeur correspond à l'ID d'événement de l'annonce.
Le XXX
dans TXXX
n'est pas un espace réservé. La chaîne TXXX
est l'ID de balise ID3 réservé au "texte défini par l'utilisateur".
Exemple de tag ID3
TXXXgoogle_1234567890123456789
Pour les flux MP4, ils sont envoyés en tant qu'événements d'e-mails en bande qui émulent les tags ID3 v2.3. Chaque zone de messagerie pertinente a une valeur scheme_id_uri
définie sur https://aomedia.org/emsg/ID3
ou https://developer.apple.com/streaming/emsg-id3
, et une valeur message_data
commençant par ID3TXXXgoogle_
. Cette valeur message_data
, sans le préfixe ID3TXXX
, correspond à l'ID d'événement d'annonce.
Exemple de zone de message
La structure des données peut varier en fonction de la bibliothèque de votre lecteur multimédia.
Si l'ID d'événement d'annonce est google_1234567890123456789
, la réponse se présente comme suit:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
Certaines bibliothèques de lecteurs multimédias présentent automatiquement des événements emsg qui émulent les tags ID3 en tant que tags ID3 natifs. Dans ce cas, les flux MP4 présentent des tags ID3 identiques à MPEG_TS.
Mettre à jour l'interface utilisateur de l'application de lecteur vidéo cliente
Chaque ID d'événement d'annonce peut être associé à une clé de l'objet tags
de l'étape 4.
La mise en correspondance de ces valeurs s'effectue en deux étapes:
Recherchez une clé correspondant à l'ID d'événement d'annonce complet dans l'objet
tags
. Si une correspondance est trouvée, récupérez le type d'événement et les objetsad
etad_break
associés. Ces événements doivent être de typeprogress
.Si aucune correspondance n'est trouvée pour l'ID d'événement d'annonce complet, recherchez dans l'objet
tags
une clé correspondant aux 17 premiers caractères de l'ID d'événement d'annonce. Récupérez le type d'événement et les objetsad
etad_break
associés. Vous devriez ainsi récupérer tous les événements de type autre queprogress
.Utilisez ces informations récupérées pour mettre à jour l'interface utilisateur de votre joueur. Par exemple, lorsque vous recevez un
start
ou le premier événementprogress
, masquez les commandes de recherche de votre lecteur et affichez une superposition décrivant la position actuelle de l'annonce dans la coupure publicitaire (par exemple: "Annonce 1 sur 3").
Exemples d'ID d'événement d'annonce
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
Exemple d'objet de tags
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
Envoyer des pings de vérification multimédia
Un ping de validation multimédia doit être envoyé à Ad Manager chaque fois qu'un événement d'annonce de type autre que progress
est reçu.
Pour générer l'URL de validation multimédia complète d'un événement d'annonce, ajoutez l'ID complet de l'événement d'annonce à la valeur media_verification_url
de la réponse d'enregistrement de flux.
Effectuez une requête GET avec l'URL complète. Si la requête de validation aboutit, vous recevez une réponse HTTP avec le code d'état 202
.
Sinon, vous obtiendrez le code d'erreur HTTP 404
.
Exemple de requête (cURL)
curl https://{...}/media/google_5555555555123456789
Exemple de réponse réussie
HTTP/1.1 202 Accepted