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

L'API Google DAI Pod Serving vous permet d'effectuer une insertion d'annonces côté serveur optimisée par Google Ads tout en conservant le contrôle de votre propre assemblage vidéo.

Ce guide vous explique comment interagir avec l'API Pod Serving et obtenir des fonctionnalités similaires avec le SDK IMA DAI. Pour toute question spécifique sur les fonctionnalités compatibles, contactez votre responsable de compte Google.

L'API Pod Serving est compatible avec les flux de diffusion de séries d'annonces 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 à chaque étape.

Pour intégrer l'API Pod Serving à votre application pour les flux VOD, procédez comme suit:

Envoyer une demande d'enregistrement de flux à Ad Manager

Envoyez une requête POST au point de terminaison d'enregistrement du flux. Vous recevez ensuite 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 du corps JSON

targeting_parameters Objet JSON contenant les paramètres de ciblage des annonces. Obligatoire

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.
metadata_url URL permettant de demander les métadonnées de séries d'annonces.
stream_id Chaîne utilisée pour identifier la session de streaming actuelle.
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 \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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'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.

Demander le fichier manifeste de flux à l'outil de manipulation du fichier manifeste

Chaque manipulateur de fichier manifeste utilise un format de requête et de réponse différent. Contactez votre fournisseur de bras robotisé pour connaître ses exigences spécifiques. Si vous implémentez votre propre manipulateur de fichier manifeste, consultez le guide du manipulateur de fichier manifeste pour connaître les exigences de ce composant.

En règle générale, vous devez transmettre l'ID de flux renvoyé par le point de terminaison d'enregistrement ci-dessus à votre manipulateur de fichier manifeste pour qu'il crée des fichiers manifestes spécifiques à la session. Sauf indication explicite de votre manipulateur de fichier manifeste, la réponse à votre demande 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 de fichiers manifestes dans un lecteur vidéo et lancez la lecture.

Demander des métadonnées de séries d'annonces à Ad Manager

Envoyez une requête GET à l'metadata_url que vous avez reçue à l'étape 1. Cette étape doit être effectuée après avoir reçu le fichier manifeste assemblé à partir de votre manipulateur de fichiers manifestes. En retour, vous recevez un objet JSON contenant les paramètres suivants:

tags Ensemble de paires clé-valeur contenant tous les événements publicitaires qui apparaissent dans le flux. Les clés correspondent aux 17 premiers caractères d'un ID d'événement d'annonce qui apparaissent dans les métadonnées temporelles du flux, ou, dans le cas d'événements de type progress, à l'ID d'événement d'annonce complet.

Chaque valeur est un objet contenant les paramètres suivants:

ad ID d'une annonce correspondant à 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 pendant l'annonce pour avertir l'application qu'une coupure publicitaire est en cours.
ads Ensemble de paires clé-valeur décrivant toutes les annonces qui s'affichent dans le flux. Les clés sont des ID d'annonce qui correspondent aux valeurs trouvées dans l'objet tags listé 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 cette annonce s'affiche dans l'ensemble des annonces de la coupure publicitaire, en secondes à virgule flottante.
duration Durée de l'annonce en secondes à virgule flottante.
clickthrough_url URL qui doit s'ouvrir lorsqu'un utilisateur interagit avec cette annonce, le cas échéant.
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 coupure publicitaire qui correspondent aux valeurs trouvées dans les objets tags et ads listés ci-dessus. Chaque valeur est un objet contenant les paramètres suivants:
type Type de coupure publicitaire. Les types de coupures publicitaires sont pre (pré-roll), mid (mid-roll) et post (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 à 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_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 temporelles via les événements d'annonces 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 ID3 v2.3 en bande. Chaque balise de métadonnées a l'ID TXXX, et la valeur commence par la chaîne google_, suivie d'une série de caractères. Cette valeur correspond à l'ID de l'événement de l'annonce.

XXX dans TXXX n'est pas un espace réservé. La chaîne TXXX est l'ID de la balise ID3 réservé au "texte défini par l'utilisateur".

Exemple de balise ID3

TXXXgoogle_1234567890123456789

Pour les flux MP4, ils sont envoyés en tant qu'événements emsg en bande qui émulent les balises ID3 v2.3. Chaque zone de message électronique pertinente a une valeur scheme_id_uri de 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 de l'événement de l'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 des balises ID3 en tant que balises ID3 natives. Dans ce cas, les flux MP4 présentent des balises ID3 identiques à MPEG_TS.

Mettre à jour l'interface utilisateur de l'application de lecteur vidéo client

Chaque ID d'événement d'annonce peut être associé à une clé dans l'objet tags de l'étape 4. La mise en correspondance de ces valeurs se fait en deux étapes:

  1. Recherchez dans l'objet tags une clé correspondant à l'ID complet de l'événement d'annonce. Si une correspondance est trouvée, récupérez le type d'événement et ses 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 publicitaire complet, recherchez dans l'objet tags une clé correspondant aux 17 premiers caractères de l'ID d'événement publicitaire. Récupérez le type d'événement et les objets ad et ad_break associés. Tous les événements de type autre que progress devraient être récupérés.

  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 un calque décrivant la position de l'annonce actuelle dans la coupure publicitaire (par exemple, "Annonce 1 sur 3").

Exemples d'ID d'événements d'annonce

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

Exemple d'objet 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 validation des éléments multimédias

Un ping de validation des médias doit être envoyé à Ad Manager chaque fois qu'un événement d'annonce d'un type autre que progress est reçu.

Pour générer l'URL de validation des médias complète d'un événement publicitaire, ajoutez l'ID d'événement publicitaire complet à la valeur media_verification_url de la réponse d'enregistrement du flux.

Envoyez une requête GET avec l'URL complète. Si la requête de validation aboutit, vous recevez une réponse HTTP avec le code d'état 202. Sinon, le code d'erreur HTTP 404 s'affiche.

Exemple de requête (cURL)

curl https://{...}/media/google_5555555555123456789

Exemple de réponse réussie

HTTP/1.1 202 Accepted

Ressources supplémentaires