Gérer les diffusions en direct avec l'insertion dynamique d'annonces

L'API Google DAI vous permet d'implémenter des flux compatibles avec Google DAI dans des environnements où l'implémentation du SDK IMA n'est pas prise en charge. Nous vous recommandons de continuer à utiliser IMA sur les plates-formes compatibles avec le SDK IMA.

Nous vous recommandons d'utiliser l'API DAI sur les plates-formes suivantes :

  • Samsung Smart TV (Tizen)
  • LG TV
  • HbbTV
  • Xbox (applications JavaScript)
  • KaiOS

L'API est compatible avec les fonctionnalités de base fournies par le SDK IMA DAI. Pour toute question spécifique sur la compatibilité ou les fonctionnalités prises en charge, contactez votre responsable de compte Google.

Implémenter l'API DAI pour les diffusions en direct

L'API DAI est compatible avec les flux linéaires (EN DIRECT) utilisant les protocoles HLS et DASH. Les étapes décrites dans ce guide s'appliquent aux deux protocoles.

Pour intégrer l'API à votre application pour les diffusions en direct, procédez comme suit :

1. Demander une diffusion

Pour demander une diffusion en direct à partir de l'API DAI, effectuez un appel POST au point de terminaison du flux. La réponse JSON contient le fichier manifeste du flux, ainsi que les points de terminaison et les valeurs de l'API DAI associés.

Exemple de corps de requête

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Exemple de corps de réponse

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Réponse d'erreur

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

stream_id
Cette valeur peut être utilisée pour identifier le flux renvoyé.
stream_manifest
Cette URL est transmise à votre lecteur multimédia pour la lecture du flux.
media_verification_url
Cette URL est le point de terminaison de base pour le suivi des événements de lecture.
metadata_url
Cette URL est utilisée pour interroger des informations périodiques sur les prochains événements de diffusion.
session_update_url
Cette URL permet de mettre à jour les paramètres de demande de flux envoyés lors de la demande de flux initiale. Notez que les paramètres de cette requête remplacent tous les paramètres définis pour le flux précédent.
polling_frequency
Fréquence, en secondes, à laquelle les métadonnées de l'insertion publicitaire sont demandées à l'API DAI.

2. Interroger pour obtenir de nouvelles métadonnées AdBreak

Définissez un minuteur pour interroger les nouvelles métadonnées d'encart publicitaire à la fréquence d'interrogation, à l'aide de l'URL des métadonnées. Si elle n'est pas spécifiée dans la réponse du flux, l'intervalle recommandé par défaut est de 10 secondes.

Pour optimiser la bande passante, procédez comme suit :

  1. Envoyez une première requête GET au point de terminaison metadata_url.
    • Omettez le paramètre de requête delta_token. Ce processus permet au serveur de renvoyer les métadonnées complètes pour la fenêtre d'enregistreur vidéo numérique (DVR) du flux. La fenêtre DVR contient la période de diffusion pendant laquelle un spectateur peut revenir en arrière et lire la diffusion. La réponse inclut un champ d'objet next_delta_token.
  2. Stockez les métadonnées côté client.
  3. Effectuez les appels suivants en utilisant la valeur next_delta_token renvoyée par la réponse la plus récente. Chaque réponse contient une valeur next_delta_token. Envoyez toujours la dernière valeur que vous recevez.
  4. Mettez à jour les métadonnées stockées pour fusionner les modifications et supprimer les pauses publicitaires obsolètes.

N'essayez pas d'analyser, de construire ni de modifier le jeton delta. Le format du jeton peut changer. Stockez le jeton tel que vous l'avez reçu et renvoyez-le sans le modifier dans la prochaine requête.

Exemple de requête initiale

La requête initiale ne prend aucun paramètre de requête et renvoie les métadonnées complètes :

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Exemple de requête ultérieure

Chaque requête suivante transmet la valeur next_delta_token de la réponse précédente en tant que paramètre delta_token. La réponse contient les éléments suivants :

  • Annonces
  • Coupures publicitaires
  • Tags que le serveur a ajoutés ou mis à jour depuis qu'il a émis le jeton.
  • Liste obsolete_ad_break_ids des pauses publicitaires à supprimer de vos métadonnées stockées

Le serveur omet les pauses publicitaires qui n'ont pas changé. L'exemple suivant montre un sondage ultérieur utilisant le jeton delta pour n'extraire que ces modifications récentes :

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Si l'opération réussit, vous obtenez un résultat semblable à celui-ci :

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. É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 :

  1. Stockez les événements multimédias dans une file d'attente, en enregistrant chaque ID de contenu multimédia avec son code temporel (s'il est affiché par le lecteur).
  2. À chaque mise à jour du temps par le lecteur ou à une fréquence définie (500 ms recommandé), vérifiez la file d'attente des événements multimédias pour les événements récemment lus en comparant les codes temporels des événements à la tête de lecture.
  3. Pour les événements média dont vous avez confirmé la lecture, vérifiez le type en recherchant l'ID d'élément multimédia dans les tags de coupure publicitaire stockés. N'oubliez pas que les tags stockés ne contiennent qu'un préfixe de l'ID du contenu multimédia. Il n'est donc pas possible d'obtenir une correspondance exacte.
  4. Étant donné que votre application de lecteur vidéo interroge régulièrement l'URL des métadonnées, un délai peut s'écouler entre le moment où votre lecteur vidéo rencontre un tag ID3 dans le flux et le moment où les métadonnées associées sont disponibles. Si aucun tag ID3 n'est trouvé dans les tags stockés, conservez le tag dans une file d'attente et traitez-le à nouveau après la prochaine interrogation des métadonnées. Conservez l'événement dans la file d'attente jusqu'à la fin du traitement.
  5. Une fois que vous avez trouvé le tag dans les métadonnées, comparez le champ type du tag aux types d'événements d'annonce listés dans la section suivante. Pour savoir si le lecteur vidéo diffuse une coupure publicitaire, utilisez les événements dont la valeur progress est associée au champ type. N'envoyez pas ces événements au point de terminaison de validation du contenu multimédia. Pour tous les autres types d'événements, ajoutez l'ID du contenu multimédia au point de terminaison de validation du contenu multimédia et envoyez une requête GET pour suivre la lecture.
  6. Supprimez l'événement multimédia de la file d'attente.

Types d'événements d'annonce

Chaque tag de l'objet de métadonnées tags est associé à l'un des types d'événements suivants :

Type d'événement Description
start S'exécute au début de l'annonce.
firstquartile S'exécute à la fin du premier quartile de l'annonce.
midpoint S'exécute au milieu de l'annonce.
thirdquartile S'exécute à la fin du troisième quartile de l'annonce.
complete S'exécute à la fin de l'annonce.
progress S'exécute périodiquement pendant une coupure publicitaire pour signaler qu'une coupure publicitaire est en cours de lecture. N'envoyez pas ces événements au point de terminaison de validation du contenu multimédia.

Exemple de requête

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Exemples de réponses

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Vous pouvez vérifier les événements de suivi dans le contrôle de l'activité des flux.

4. Mettre à jour les paramètres de session de diffusion en direct

Vous pouvez ajuster les paramètres de session après la création d'un flux. Pour ce faire, envoyez une requête à l'URL de mise à jour de la session.

Exemple de corps de requête

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Exemple de corps de réponse

Successful response would be to look for - HTTP/1.1 200

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, ce qui limite les capacités des fonctionnalités suivantes :
    • Limitation de la fréquence d'exposition
    • Rotation séquentielle des annonces
    • Segmentation et ciblage de l'audience

Bonnes pratiques

N'oubliez pas que le point de terminaison des métadonnées pour les index de diffusion en direct est basé sur le préfixe de la balise ID3 correspondante. Cette fonctionnalité est conçue pour empêcher l'utilisation du point de terminaison des métadonnées afin d'envoyer immédiatement un ping à tous les nœuds de validation.

Ressources supplémentaires