L'API d'insertion dynamique d'annonce de Google vous permet d'implémenter des flux pour lesquels l'insertion dynamique d'annonce est activée dans les environnements où la mise en œuvre du SDK IMA n'est pas prise en charge. Nous vous recommandons de continuer à utiliser IMA sur les plates-formes compatibles avec le SDK IMA.
Nous vous recommandons d'utiliser l'API d'insertion dynamique d'annonce sur les plates-formes suivantes:
- Smart TV Samsung (Tizen)
- LG TV
- HbbTV
- Xbox (applications JavaScript)
- KaiOS
L'API est compatible avec les fonctionnalités de base fournies par le SDK IMA DAI. Pour toute question concernant la compatibilité ou les fonctionnalités compatibles, contactez votre responsable de compte Google.
Implémenter l'API d'insertion dynamique d'annonce pour les diffusions EN DIRECT
L'API d'insertion dynamique d'annonce accepte les flux linéaires (EN DIRECT) qui utilisent les protocoles HLS et DASH. Les étapes décrites dans ce guide s'appliquent aux deux protocoles.
Pour intégrer l'API à votre application pour les diffusions EN DIRECT, procédez comme suit:
1. Demander une diffusion
Pour demander une diffusion en direct à partir de l'API d'insertion dynamique d'annonce, effectuez un appel POST au point de terminaison du flux. La réponse JSON contient le fichier manifeste du flux, ainsi que les valeurs et les points de terminaison associés à l'API d'insertion dynamique d'annonce.
Exemple de corps de requête
https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream
{
key1 : "value1",
stream_parameter1 : "value2"
}
Exemple de corps de réponse
{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}
Réponse d'erreur
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 suivantes:
- stream_id
- Cette valeur peut être utilisée pour identifier le flux renvoyé.
- stream_manifest
- Cette URL est transmise à votre lecteur multimédia pour la lecture du flux.
- media_verification_url
- Cette URL est le point de terminaison de base pour le suivi des événements de lecture.
- metadata_url
- Cette URL permet d'obtenir régulièrement des informations sur les événements de diffusion à venir.
- session_update_url
- Cette URL permet de mettre à jour les paramètres de requête de flux envoyés lors de la requête de flux initiale. Notez que les paramètres de cette requête remplacent tous les paramètres définis pour le flux précédent.
- polling_frequency
- Fréquence, en secondes, de la demande de métadonnées AdBreak mises à jour à partir de l'API d'insertion dynamique d'annonce.
2. Interroger les nouvelles métadonnées de coupure publicitaire
Définissez un minuteur pour rechercher les nouvelles métadonnées AdBreak à la fréquence d'interrogation, à l'aide de l'URL des métadonnées. S'il n'est pas spécifié dans la réponse du flux, l'intervalle recommandé par défaut est de 10 secondes.
Exemple de corps de requête
https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata
Exemple de corps de réponse
{
"tags":{
"google_0492266569":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"firstquartile"
},
"google_1560331148":{
"ad":"0000229836_ad1",
"ad_break_id":"0000229836",
"type":"thirdquartile"
},
"google_1877686714378797835":{
"ad":"0000229836_slate",
"ad_break_id":"0000229836",
"type":"progress"
},
"google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"progress"
},
"google_2032765498":{
"ad":"0000229835_ad1",
"ad_break_id":"0000229835",
"type":"midpoint"
},......
"google_5646900623":{
"ad":"0000229837_ad1",
"ad_break_id":"0000229837",
"type":"complete"
}
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15.01,
"title":"truman-e2e-creativeset4",
"description":"truman-e2e-creativeset4 ad",
"ad_system":"GDFP",
"ad_id":"39066884",
"creative_id":"58092079124",
"clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
"universal_ad_id":{
"id_value":"58092079124",
"id_registry":"GDFP"
}
},
"0000229834_slate":{
"ad_break_id":"0000229834",
"position":-1,
"duration":14.974977777,
"slate":true
},...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15.01,
"expected_duration":29.984977776999997,
"ads":1
},....
}
}
3. Écoutez des événements ID3 et suivez les événements de lecture
Pour vérifier que des événements spécifiques se sont produits dans un flux vidéo, procédez comme suit afin de gérer les événements ID3:
- Stockez les événements multimédias dans une file d'attente, en enregistrant chaque ID multimédia avec son code temporel (s'il est présenté par le lecteur).
- À chaque mise à jour à partir du lecteur, ou à une fréquence définie (recommandée 500 ms), consultez les événements multimédias lus dans la file d'attente en comparant les horodatages des événements à ceux de la tête de lecture.
- Pour les événements multimédias qui ont été lus, vérifiez leur type en recherchant l'ID de l'élément multimédia dans les tags de coupure publicitaire stockés. N'oubliez pas que les tags stockés ne contiennent qu'un préfixe de l'ID multimédia. Une correspondance exacte n'est donc pas possible.
- Les événements "progression" permettent de savoir si un utilisateur se trouve dans une coupure publicitaire. N'envoyez pas ces événements au point de terminaison de validation multimédia. Pour les autres types d'événements, ajoutez l'ID multimédia au point de terminaison de validation multimédia et envoyez une requête GET pour suivre la lecture.
- Supprimez l'événement multimédia de la file d'attente.
Exemple de corps de requête
https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/
Exemples de réponses
Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict
Vous pouvez vérifier les événements de suivi dans la surveillance de l'activité des flux.
4. Mettre à jour les paramètres de la session de diffusion en direct
Vous pouvez ajuster les paramètres de votre session après la création d'un flux. Pour ce faire, envoyez une requête à l'URL de mise à jour de session.
Exemple de corps de requête
https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session
{
key1 : "value1",
stream_parameter1 : "value2"
}
Exemple de corps de réponse
Successful response would be to look for - HTTP/1.1 200
Limites
Si vous utilisez l'API dans des WebViews, les limites suivantes s'appliquent au ciblage:
- UserAgent: le paramètre user-agent est transmis en tant que valeur spécifique au navigateur au lieu de la plate-forme sous-jacente.
rdid,idtype,is_lat: l'ID de l'appareil n'est pas correctement transmis, ce qui limite les fonctionnalités des fonctionnalités suivantes :- Limitation de la fréquence d'exposition
- Rotation séquentielle des annonces
- Segmentation et ciblage de l'audience
Bonnes pratiques
N'oubliez pas que le point de terminaison des métadonnées des index de diffusion en direct est basé sur le préfixe de la balise ID3 correspondante. Cette approche est conçue pour éviter d'utiliser le point de terminaison des métadonnées pour pinguer immédiatement tous les nœuds de validation.