Application cliente du lecteur vidéo pour les flux de vidéo à la demande

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 du 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. Vous recevez à son tour 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:

ad ID d'une annonce qui correspond à une clé dans l'objet ads.
ad_break_id ID d'une coupure publicitaire correspondant à une clé dans l'objet ad_breaks.
type Type d'événement d'annonce. Les types d'événements d'annonce sont les suivants:
start Déclenché au début de l'annonce.
firstquartile Déclenché à la fin du premier quartile.
midpoint Déclenché au milieu de l'annonce.
thirdquartile Déclenché à la fin du troisième quartile.
complete Déclenché à la fin de l'annonce.
progress Déclenché régulièrement tout au long de l'annonce pour avertir l'application qu'une coupure publicitaire est en cours de lecture.
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_break_id ID d'une coupure publicitaire correspondant à une clé dans l'objet ad_breaks.
position Position à laquelle l'annonce apparaît dans l'ensemble d'annonces dans la coupure publicitaire, en secondes à virgule flottante.
duration Durée de l'annonce en secondes à virgule flottante.
clickthrough_url URL qui s'ouvre lorsqu'un utilisateur interagit avec cette annonce (si compatible).
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:
type Type de coupure publicitaire. Les coupures publicitaires sont de type pre (annonce vidéo pré-roll), mid (annonce vidéo mid-roll) et post (annonce vidéo post-roll).
duration Durée de la coupure publicitaire en secondes à virgule flottante.
ads Nombre d'annonces dans cette coupure publicitaire.

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:

  1. 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 objets ad et ad_break associés. Ces événements doivent être de type progress.

    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 objets ad et ad_break associés. Vous devriez ainsi récupérer tous les événements de type autre que progress.

  2. Utilisez ces informations récupérées pour mettre à jour l'interface utilisateur de votre joueur. Par exemple, lorsque vous recevez un événement start ou le premier événement progress, 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 à votre tour 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

Ressources supplémentaires