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

L'API d'insertion dynamique de séries d'annonces de Google vous permet d'insérer des annonces côté serveur par Google Ads tout en gardant le contrôle de 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 DAI. Pour les questions spécifiques concernant fonctionnalités compatibles, contactez votre responsable de compte Google.

L'API Pod Serving est compatible avec les flux de diffusion de pods HLS ou MPEG-DASH protocoles de flux de données. Ce guide se concentre sur les flux HLS et met en évidence les différences entre HLS et MPEG-DASH à des étapes spécifiques.

Pour intégrer l'API Pod Serving à votre application pour les flux de vidéo à la demande, effectuez la 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 à tour de rôle Réponse JSON contenant l'ID de flux à envoyer à la manipulation du fichier manifeste et les points de terminaison de l'API de diffusion de pods 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 Un objet JSON contenant l'ID de la source du contenu (cmsid), l'ID vidéo (vid) et ciblage des annonces paramètres. Obligatoire

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.
metadata_url URL pour demander les métadonnées de la série 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 en cours, dans 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 \
     -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 réponse JSON .

Analyser la réponse JSON et stocker les valeurs pertinentes

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

Chaque outil de manipulation du fichier manifeste présente des formats de requête et de réponse différents. Contact le fournisseur de votre manipulateur pour comprendre ses exigences spécifiques. Si vous utilisez implémentant votre propre outil de manipulation du fichier manifeste, consultez le manipulateur du fichier manifeste ; guide pour mieux comprendre pour ce composant.

En général, vous devez transmettre l'ID de flux renvoyé par la le point de terminaison d'inscription ci-dessus à votre outil de manipulation du fichier manifeste afin qu'il soit compilé des fichiers manifestes spécifiques à la session. Sauf indication contraire dans votre fichier manifeste manipulation, la réponse à votre demande de fichier manifeste est un flux vidéo contenant pour le contenu et les 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 des fichiers manifestes dans un et lancer la lecture.

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

Envoyez une requête GET au metadata_url que vous avez reçu à l'étape 1. Ce doit avoir lieu une fois que vous avez reçu le fichier manifeste assemblé à partir de votre fichier manifeste. un manipulateur. En retour, vous recevez un objet JSON contenant les éléments suivants : paramètres:

tags Un ensemble de paires clé-valeur contenant tous les événements d'annonce qui apparaissent dans flux. Les clés correspondent aux 17 premiers caractères d'un événement d'annonce. Identifiant qui apparaît dans les métadonnées associées à des codes temporels de la diffusion ou dans le cas d'événements de type progress, qui correspond à 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é de l'objet ads.
ad_break_id ID d'une coupure publicitaire correspondant à une clé dans 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 quart.
midpoint Déclenché au milieu de l'annonce.
thirdquartile Déclenché à la fin du troisième quart.
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 annonce de pause.
ads Ensemble de paires clé-valeur décrivant toutes les annonces diffusées dans le flux. La Les clés sont des identifiants d'annonces correspondant aux valeurs trouvées dans l'objet tags. comme 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 ad_breaks .
position Position à laquelle cette annonce apparaît dans l'ensemble des annonces qu'elle contient 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, si elle est 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 coupure publicitaire correspondant aux valeurs trouvées dans le tags et ads des objets 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 les suivants : 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 aux événements de métadonnées programmés dans votre vidéo. flux.

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

écouter les métadonnées minuté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 ID3 v2.3 intégrés à la bande. Chaque La balise de métadonnées est associée à l'ID TXXX, et sa valeur commence par la chaîne google_. suivi d'une série de caractères. Cette valeur correspond à l'identifiant d'événement d'annonce.

Le XXX dans TXXX n'est pas un espace réservé. La chaîne TXXX correspond à 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 sous forme d'événements d'e-mails dans la bande qui émulent ID3 v2.3 . Chaque zone emsg pertinente a une valeur scheme_id_uri de l'une des valeurs suivantes : 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 ID3TXXX correspond à l'ID d'événement d'annonce.

Exemple de zone emsg

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 : ceci:

{
  "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 d'e-mails qui émulent ID3 en tant que tags ID3 natifs. Dans ce cas, les flux MP4 contiennent des tags ID3 identiques. comme 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 dans l'objet tags une clé correspondant à l'ID d'événement d'annonce complet. Si une correspondance est trouvée, récupérez le type d'événement et le ad associé, puis Objets ad_break. Ces événements doivent être de type progress.

    Si aucune correspondance n'est trouvée pour l'ID d'événement d'annonce complet, vérifiez le tags. associé à une clé correspondant aux 17 premiers caractères de l'ID d'événement de l'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 types autres que progress.

  2. Utilisez ces informations récupérées pour mettre à jour l'interface utilisateur de votre joueur. Par exemple, lorsque si vous recevez un événement start ou le premier événement progress, masquez la recherche du joueur et affiche une superposition décrivant la position de l'annonce actuelle dans 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 "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 multimédia

Un ping de validation du média doit être envoyé à Ad Manager chaque fois qu'un événement d'annonce dont le type n'est pas progress est reçue.

Pour générer l'URL de validation multimédia complète d'un événement d'annonce, ajoutez la l'ID d'événement d'annonce à la valeur media_verification_url à partir de l'enregistrement du flux de réponse.

Envoyez une requête GET avec l'URL complète. Si la demande de validation est réussi, vous recevez une réponse HTTP avec le code d'état 202. Sinon, vous obtenez 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