Pour activer l'API Video Stitcher pour votre projet, veuillez contacter votre responsable de compte ou le service commercial pour en savoir plus.

Cette page a été traduite par l'API Cloud Translation.

Utiliser une intégration personnalisée

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à effectué les étapes de Intégrer Google Ad Manager (GAM) aux diffusions en direct au préalable.

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 aurez 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'assembleur vidéo API: `PROJECT_NUMBER`
Jeton OAuth	Jeton OAuth de courte durée d'un compte de service avec l'utilisateur Video Stitcher rôle: `OAUTH_TOKEN` En savoir plus sur en créant des jetons OAuth de courte durée. Important: Le jeton OAuth peut être réutilisé pour plusieurs requêtes tant qu'il n'a pas expiré.
Code réseau	Code de réseau Ad Manager pour les demandes d'annonces: `NETWORK_CODE`
ID de configuration active	ID de configuration du 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 d'assemblage 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

un ensemble facultatif de formats encodés paramètres de ciblage

Réponse JSON

`media_verification_url`	URL de base permettant d'envoyer un 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 pour demander les métadonnées de la série d'annonces. `METADATA_URL`
`polling_frequency`	la fréquence recommandée (en millisecondes) pour interroger "metadata_url" ; `POLLING_FREQUENCY`
`stream_id`	Chaîne utilisée pour identifier la session de diffusion en cours. `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 d'expiration de la session en cours, au format ISO 8601. Chaîne de date et heure dans `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/stream

Exemple 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'erreurs, les codes d'erreur HTTP standards sont renvoyés sans réponse JSON .

Analyser la réponse JSON et stocker 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 où votre configuration active a été créée: `LOCATION`

Paramètre d'en-tête d'autorisation

OAUTH_TOKEN

Le jeton OAuth de courte durée d'un compte de service avec le rôle utilisateur Video Stitcher :

OAUTH_TOKEN

Paramètres de corps encodés en 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`	Un objet contenant l'ID de flux avec les éléments suivants : format: `{"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`	La même chaîne `liveConfig` envoyée à l'API dans votre requête .
`gamSettings`	Le même objet `gamSettings` envoyé à l'API dans 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/liveSessions

request.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 avec des coupures publicitaires 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 extraite de 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é comme inactif si aucune récupération de fichier manifeste n'a été effectuée dans un délai de en temps réel.

Interroger les nouvelles métadonnées de coupure publicitaire

L'application est chargée de récupérer les métadonnées pour chaque coupure publicitaire. 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`	Un ensemble de paires clé-valeur décrivant les événements de médias publicitaires 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 avec les propriétés suivantes: `ad` : ID de l'annonce contenant l'événement multimédia de l'annonce. `ad_break_id` : ID de la coupure publicitaire contenant l'événement multimédia de la publicité. `type` : type d'événement multimédia publicitaire. Les valeurs peuvent être l'une des suivantes : `start` : l'annonce a commencé `firstquartile` : l'annonce est terminée à 25 %. `midpoint` : l'annonce est à 50 % terminée. `thirdquartile` : l'annonce est complète à 75 %. `complete` : l'annonce a pris fin. `progress` : déclenché toutes les secondes pendant la lecture d'une annonce.
`ads`	Un ensemble de paires clé-valeur décrivant les annonces qui apparaîtront dans les flux. Chaque clé correspond à un ID d'annonce. Chaque valeur est un objet avec les propriétés suivantes : `ad_break_id` : ID de la coupure publicitaire contenant l'événement multimédia de la publicité. `position`: position de l'annonce dans la coupure publicitaire. notez que la première annonce d'une coupure publicitaire occupe la position `1` `duration`: durée de l'annonce en virgule flottante secondes. `title`: titre de l'annonce, tel que défini dans le fichier VAST. `description` : description de l'annonce, telle que définie dans le VAST. `ad_system`: système publicitaire, tel que défini dans le fichier VAST. `ad_system` : ID de l'annonce, tel que défini dans le VAST. `ad_system` : ID de la création, tel que défini dans le VAST. `clickthrough_url`: URL à ouvrir lorsqu'un utilisateur interagit avec l'annonce. avec l'annonce. `universal_ad_id` : objet représentant l'ID d'annonce universel, tel que défini dans le VAST.
`ad_breaks`	Un ensemble de paires clé-valeur décrivant les coupures publicitaires qui seront diffusées dans le flux. Chaque clé correspond à un ID de coupure publicitaire. Chaque valeur est un avec les propriétés suivantes: `type` : type de coupure publicitaire. Les valeurs peuvent être l'une des suivantes : `pre` : représente une annonce pré-roll. `mid`: représente une annonce mid-roll. `post` : représente une annonce post-roll. `duration`: durée de la coupure publicitaire dans secondes à virgule flottante. `expected_duration` : durée attendue de la coupure publicitaire en secondes à virgule flottante. `ads` : nombre d'annonces contenues dans la coupure publicitaire.

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 dont la lecture est confirmée, leur type apparaît en recherchant l'ID multimédia dans les tags de coupure publicitaire stockés. N'oubliez pas que les tags de coupure publicitaire ne contient qu'une version tronquée de l'identifiant multimédia, limitée au les 10 premiers chiffres après le préfixe google_, il n'y a donc pas de correspondance directe entre les ID3 de validation de média ID3 et les clés dans 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 multimédia complète d'un événement d'annonce, ajoutez l'ID d'événement d'annonce complet à la valeur media_verification_url figurant dans réponse de création de flux.
Utiliser "progression" pour déterminer 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`	La 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 renvoyées attendues

`HTTP/1.1 204 No Content`	Réponse vide réussie.
`HTTP/1.1 404 Not Found`	L'ID de validation du média n'a pas été reconnu.
`HTTP/1.1 409 Conflict`	L'ID de validation du média a déjà été envoyé.

Exemple de requête (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Exemple de réponse

HTTP/1.1 204 No Content

Limites

Si vous utilisez l'API dans des WebViews, les limitations 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

tvOS

Nettoyage