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 document 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 assets VOD.

Si le SDK IMA n'est pas disponible pour la plate-forme que vous souhaitez utiliser, votre application devra appeler les API requises et déclencher elle-même les validations des médias publicitaires.

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'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 la création de jetons OAuth éphémères 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 demander des annonces : `NETWORK_CODE`
ID de configuration de la vidéo à la demande	ID de configuration VOD que vous avez spécifié lors de la création de votre événement Vod Stream: `VOD_CONFIG_ID`

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 à votre serveur de manipulation de fichier manifeste et aux points de terminaison de l'API Pod Serving associés.

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 de corps encodés en JSON

targeting_parameters: Ensemble de paramètres de ciblage facultatifs encodés au format JSON.

Réponse JSON

`media_verification_url`	URL de base permettant d'envoyer un ping aux événements de suivi de la lecture. Une validation multimédia complète L'URL est formée en ajoutant 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`
`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/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

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 réponse JSON .

Analyser la réponse JSON et stocker les valeurs pertinentes

Générer une session de vidéo à la demande d'assembleur vidéo Cloud

Envoyez une requête POST au point de terminaison d'inscription de la session VOD. En retour, vous recevez une réponse JSON contenant l'URI du fichier manifeste de flux et les métadonnées concernant les coupures publicitaires, les annonces et les événements publicitaires.

point de terminaison de l'API

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Paramètres de chemin d'accès

`PROJECT_NUMBER`	Numéro de votre projet Google Cloud.
`LOCATION`	Votre région Google Cloud.
`NETWORK CODE`	Votre code de réseau Google Ad Manager 360.

Paramètres de corps encodés en JSON

`vodConfig`	Chaîne contenant votre numéro de projet, votre emplacement et votre ID de configuration VOD au format suivant : `projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID`
`adTracking`	Définissez la valeur sur `"CLIENT"` pour activer le suivi côté client.
`gamSettings`	Objet contenant le code réseau et l'ID de flux au format suivant : { "networkCode":"`NETWORK_CODE`", "streamId":"`STREAM_ID`" }

Réponse JSON

`name`	Nom de la session de vidéo à la demande, contenant l'ID de session.
`playUri`	URI du fichier manifeste du flux assemblé à charger dans votre lecteur vidéo pour la lecture. `SESSION_PLAYBACK_URI`
`adTracking`	La même valeur `adTracking` envoyée à l'API dans votre requête .
`vodConfig`	La même chaîne `vodConfig` envoyée à l'API dans 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/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

Exemple de réponse

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

Une fois la réponse reçue, vous pouvez lire la diffusion en direct assemblée en tant que en référençant l'URI à partir du champ playUri de l'objet de réponse.

Demander les métadonnées de la série d'annonces à Ad Manager

Envoyez une demande GET à metadata_url que vous avez reçue lors de votre inscription. votre flux avec Ad Manager. Cette étape doit être effectuée après avoir reçu le fichier manifeste assemblé à partir de l'URI de lecture.

Vous recevez alors un objet JSON décrivant les coupures publicitaires, les annonces et les événements publicitaires du flux.

Point de terminaison de l'API

GET: METADATA_URL
Host: dai.google.com

Réponse JSON

`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 : `ad`: ID de l'annonce contenant l'événement mé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 média de l'annonce. Les valeurs sont 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 terminée à 75 %. `complete` : l'annonce a pris fin. `progress` : déclenché toutes les secondes pendant la lecture d'une annonce.
`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_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. Veuillez noter que la première annonce d'une coupure a la position `1`. `duration`: durée de l'annonce en virgule flottante secondes. `title` : titre de l'annonce, tel que défini dans le VAST. `description` : description de l'annonce, telle que définie dans le VAST. `ad_system` : système publicitaire, tel que défini dans le VAST. `ad_system`: identifiant de l'annonce, tel que défini dans le fichier 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'universel l'identifiant de l'annonce, tel qu'il est défini dans la norme VAST.
`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 : `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.

Exemple de requête (cURL)

curl METADATA_URL

Exemple de réponse JSON

{
  "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
    },
    ...
  }
}

Stockez ces valeurs pour les associer à des événements de métadonnées temporelles dans votre flux vidéo.

Écouter des é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 ses code temporel, s'il est présenté par le joueur.
À 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 dans l'objet "tags". C'est pour Empêcher l'envoi de pings de validation de l'événement avant l'événement ID3 arrive. 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 médias afin d'éviter code d'erreur. 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 du support publicitaire 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 transmis correctement. limite le fonctionnement des fonctionnalités suivantes:
- Limitation de la fréquence d'exposition
- Rotation séquentielle des annonces
- Segmentation et ciblage de l'audience

Aperçu