Avant de commencer
Ce guide ne couvre que les instructions de lecture en l'absence du SDK IMA DAI.
Assurez-vous d'avoir déjà suivi les étapes décrites dans la section Intégrer Google Ad Manager (GAM) aux diffusions en direct.
Si le SDK IMA n'est pas disponible pour la plate-forme de votre choix, votre application devra appeler les API requises et déclencher elle-même les impressions d'annonces.
Pour ce faire, vous avez besoin des informations suivantes:
| Emplacement |
La
Région Google Cloud
dans laquelle votre configuration en production a été créée :
LOCATION
|
| Numéro du projet |
Numéro du projet Google Cloud utilisant l'API Video Stitcher :
PROJECT_NUMBER
|
| Jeton OAuth |
Jeton OAuth de courte durée d'un compte de service avec le rôle utilisateur Video Stitcher :OAUTH_TOKEN En savoir plus sur la création de jetons OAuth éphémères |
| Code réseau |
Code de réseau Ad Manager pour demander des annonces :
NETWORK_CODE
|
| ID de la configuration en direct |
L'ID de configuration en direct que vous avez spécifié lors de la création de votre événement en direct :
LIVE_CONFIG_ID
|
| Clé d'élément personnalisée |
Clé d'élément personnalisé Ad Manager générée lors du processus de
création d'une configuration pour un événement en direct
avec l'API Video Stitcher :
CUSTOM_ASSET_KEY
|
Envoyer une demande d'enregistrement de flux à Ad Manager
Envoyez une requête POST au point de terminaison d'enregistrement du flux. En retour, vous recevez une réponse JSON contenant l'ID de flux à envoyer à l'API de montage vidéo.
point de terminaison de l'API
POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
Paramètres de chemin d'accès
NETWORK_CODE |
Votre code de réseau Google Ad Manager 360 :
NETWORK_CODE
|
CUSTOM_ASSET_KEY |
Identifiant personnalisé associé à cet événement dans Google Ad Manager :
CUSTOM_ASSET_KEY
|
Paramètres de corps encodés en formulaire
Ensemble facultatif de paramètres de ciblage encodés en formulaire.
Réponse JSON
media_verification_url |
URL de base pour envoyer des requêtes ping aux événements de suivi de la lecture. Pour obtenir une URL de validation des contenus multimédias complète, ajoutez un ID d'événement d'annonce à cette URL de base.
MEDIA_VERIFICATION_URL
|
metadata_url |
URL permettant de demander les métadonnées de séries d'annonces.
METADATA_URL
|
polling_frequency |
Fréquence recommandée en millisecondes pour interroger l'URL de métadonnées.
POLLING_FREQUENCY
|
stream_id |
Chaîne utilisée pour identifier la session de streaming actuelle.
STREAM_ID
|
valid_for |
Durée restante avant l'expiration de la session de streaming 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 streaming actuelle expire, sous la forme d'une chaîne de date/heure ISO 8601 au format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.
|
Exemple de requête (cURL)
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/streamExemple de réponse
{
"stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
"media_verification_url":"https://dai.google.com/.../media/",
"metadata_url":"https://dai.google.com/.../metadata",
"session_update_url":"https://dai.google.com/.../session",
"polling_frequency":10
}
En cas d'erreur, des codes d'erreur HTTP standards sont renvoyés sans corps de réponse JSON.
Analysez la réponse JSON et stockez les valeurs pertinentes.
Générer l'URI de lecture de la session
Envoyez une requête POST au point de terminaison /livesessions de l'API de montage vidéo pour créer une session en direct. En retour, vous recevez une réponse JSON contenant le fichier manifeste de flux à charger dans votre lecteur vidéo.
point de terminaison de l'API
POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json
Paramètres de chemin d'accès
PROJECT_NUMBER |
Numéro du projet Google Cloud utilisant l'API Video Stitcher :
PROJECT_NUMBER
|
LOCATION |
La
Région Google Cloud
dans laquelle votre configuration en production a été créée :
LOCATION
|
Paramètre d'en-tête d'autorisation
OAUTH_TOKEN |
Jeton OAuth de courte durée d'un compte de service avec le rôle utilisateur Video Stitcher :OAUTH_TOKEN |
Paramètres du corps encodés au format JSON
liveConfig |
Chaîne contenant votre numéro de projet, votre emplacement et votre ID de configuration en direct au format suivant :
projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
|
adTracking |
Définissez la valeur sur "CLIENT" pour activer le suivi côté client. |
gamSettings |
Objet contenant l'ID de flux au format suivant :
{"streamId":"STREAM_ID"}
|
Réponse JSON
name |
Nom de la session en direct, contenant l'ID de session. |
playUri |
URI du fichier manifeste de flux assemblé à charger dans votre lecteur vidéo pour la lecture.
PLAY_URI
|
liveConfig |
Même chaîne liveConfig envoyée à l'API dans le corps de votre requête.
|
gamSettings |
Même objet gamSettings envoyé à l'API dans le corps de votre requête.
|
Exemple de requête (cURL)
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer OAUTH_TOKEN" \
-d '@request.json' \
https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessionsrequest.json
{
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
"adTracking": "CLIENT",
"gamSettings": {
"streamId": "STREAM_ID"
}
}
Exemple de réponse
{
"name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
"playUri": PLAY_URI,
"liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
"gamSettings": {
"streamId": STREAM_ID
}
}
Une fois la réponse reçue, vous pouvez lire la diffusion en direct tronquée par publicité en référençant l'URI de lecture de la session à partir du champ playUri de l'objet de réponse.
L'API Video Stitcher génère un ID de session unique pour chaque requête, qui peut être récupéré dans la dernière section du champ name de l'objet de réponse.
Une session inactive expire au bout de cinq minutes. Une session est considérée comme inactive si aucune récupération de fichier manifeste n'a été effectuée au cours d'une période donnée.
Interroger les nouvelles métadonnées AdBreak
L'application est chargée de récupérer les métadonnées pour chaque coupure publicitaire afin de savoir quelles impressions doivent être déclenchées. Pour ce faire, vous devez définir un minuteur pour interroger régulièrement les API DAI metadata_url afin d'obtenir de nouvelles informations sur les annonces. L'intervalle d'interrogation est spécifié dans le champ polling_frequency de la réponse d'enregistrement du flux.
Vous recevez en retour un objet JSON contenant les paramètres suivants:
tags |
Ensemble de paires clé-valeur décrivant les événements multimédias d'annonces qui se produiront dans le flux. Chaque clé se compose des 17 premiers caractères d'un ID multimédia d'annonce qui apparaîtra dans les métadonnées ID3 du flux ou, dans le cas des événements de progression, de l'ID multimédia d'annonce complet. Chaque valeur est un objet avec les propriétés suivantes :
|
ads |
Ensemble de paires clé-valeur décrivant les annonces qui s'afficheront dans le flux. Chaque clé correspond à un ID d'annonce. Chaque valeur est un objet avec les propriétés suivantes :
|
ad_breaks |
Ensemble de paires clé-valeur décrivant les coupures publicitaires qui se produiront dans le flux. Chaque clé correspond à un ID de coupure publicitaire. Chaque valeur est un objet avec les propriétés suivantes :
|
Stockez ces valeurs après chaque requête pour associer des événements de métadonnées temporelles dans votre flux vidéo.
Exemple de requête (cURL)
curl https://dai.google.com/.../metadata/Exemple 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/...",
"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
},
...
}
}
Écouter les événements ID3 et suivre les événements de lecture
Pour vérifier que des événements spécifiques se sont produits dans un flux vidéo, suivez ces étapes pour 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, le cas échéant.
- À chaque mise à jour de l'heure du lecteur ou à une fréquence définie (500 ms recommandé), recherchez les événements récemment lus dans la file d'attente des événements multimédias en comparant les codes temporels des événements à la tête de lecture.
- Pour les événements multimédias que vous confirmez avoir lus, vérifiez le type en recherchant l'ID multimédia dans les tags de coupure publicitaire stockés. N'oubliez pas que l'objet "tags de coupure publicitaire" ne contient qu'une version tronquée de l'ID multimédia, limitée aux 10 premiers chiffres après le préfixe "google_". Il n'y a donc pas de correspondance directe entre les ID de validation multimédia ID3 et les clés de l'objet "tags". Cela permet d'éviter que des pings de validation d'événement ne soient envoyés avant l'arrivée de l'événement ID3. Pour générer l'URL de validation des médias 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 de création de flux.
- Utilisez des événements "progress" pour savoir si un utilisateur se trouve dans une coupure publicitaire. N'envoyez pas ces événements au point de terminaison de validation des contenus multimédias pour éviter un code d'erreur HTTP. Pour les autres types d'événements, ajoutez l'ID multimédia à l'URL de validation des contenus multimédias et envoyez une requête GET pour suivre la lecture.
- Supprimez l'événement multimédia de la file d'attente.
point de terminaison de l'API
GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com
Paramètres de chemin d'accès
MEDIA_VERIFICATION_URL |
Valeur renvoyée par le point de terminaison d'enregistrement du flux, dans le champ media_verification_url :
MEDIA_VERIFICATION_URL
|
AD_MEDIA_ID |
ID multimédia de l'annonce complet, tel qu'il apparaît dans les métadonnées ID3 du flux :
AD_MEDIA_ID
|
Valeurs de rendement attendues
HTTP/1.1 204 No Content |
Réponse vide réussie. |
HTTP/1.1 404 Not Found |
L'ID de validation multimédia n'a pas été reconnu. |
HTTP/1.1 409 Conflict |
L'ID de validation des contenus multimédias a déjà été envoyé. |
Exemple de requête (cURL)
curl MEDIA_VERIFICATION_URLAD_MEDIA_IDExemple de réponse
HTTP/1.1 204 No Content
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