Insérer des annonces avec des métadonnées de timing de blocs d'annonces

Ce guide explique comment insérer des coupures publicitaires à l'aide de la méthode ATM (Ad pod Timing Metadata) pour obtenir les codes temporels et la durée précis des coupures publicitaires, y compris les annonces pré-roll.

Pour insérer des annonces pré-roll et gérer le retour au contenu après les coupures publicitaires mid-roll, nous vous recommandons d'appeler les API suivantes :

API ATM (Ad pod Timing Metadata): interroge les résultats de décision des séries d'annonces, y compris les durées des annonces et des écrans de remplacement.
Point de terminaison des segments d'annonces: demande des segments d'annonces ou d'écrans de remplacement avec la possibilité de mettre fin au bloc d'annonces actuel.

Si vous le souhaitez, pour les événements de diffusion en direct à forte simultanéité, nous vous recommandons d'appeler Early Ad Break Notification (EABN) API pour planifier les décisions publicitaires avant le début de la coupure publicitaire.

Prérequis

Pour commencer, vous devez configurer un événement de diffusion en direct pour le type d'insertion dynamique d'annonces Redirection de la diffusion de blocs. Sélectionnez l'une des méthodes suivantes :

Interface utilisateur Ad Manager : configurez une diffusion en direct pour l'insertion dynamique d'annonce.
API Ad Manager : utilisez une bibliothèque cliente (options disponibles) pour appeler LiveStreamEventService.createLiveStreamEvents méthode. Définissez le paramètre LiveStreamEvent.dynamicAdInsertionType sur POD_SERVING_REDIRECT.

Récupérer le flux de contenu

Lorsqu'un utilisateur sélectionne un événement en direct, l'application cliente envoie une demande de flux à Google Ad Manager. Dans la réponse du flux, l'application extrait l'ID de session Google DAI et les métadonnées à inclure dans la demande de fichier manifeste du flux.

L'exemple suivant transmet un ID de session Google DAI à un manipulateur de fichier manifeste :

https://MANIFEST_MANIPULATOR_URL/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY

Lors du traitement de la demande de lecture de contenu vidéo, stockez l'ID de session Google DAI et CUSTOM_ASSET_KEY de la demande pour préparer l'assemblage des annonces.

Récupérer les métadonnées de timing des séries d'annonces

Pour récupérer les codes temporels des séries d'annonces, procédez comme suit :

Générez un jeton HMAC.
Appelez l'API ATM avec le jeton HMAC.

Demander des métadonnées de timing pour les annonces pré-roll

Vérifiez les paramètres pré-roll de votre diffusion en direct à l'aide des options suivantes :

Pour récupérer les résultats de décision des annonces pré-roll, envoyez une requête à l'API ATM.

L'exemple suivant effectue une requête ATM pour les annonces pré-roll :

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=preroll&auth-token=your_signed_HMAC_token"

Demander des métadonnées de timing pour les annonces mid-roll

Pour récupérer les métadonnées des séries d'annonces pour les annonces mid-roll, procédez comme suit :

Analysez le fichier manifeste de la diffusion en direct pour trouver les repères publicitaires qui contiennent le timing et la durée de chaque coupure publicitaire mid-roll.
Appelez le point de terminaison de l'API ATM pour demander la durée précise de la série d'annonces et du slate. L'API renvoie un objet JSON avec les résultats de décision du bloc d'annonces.

L'exemple suivant effectue une requête ATM pour les annonces mid-roll :

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=AD_BREAK_ID&pd=AD_BREAK_DURATION&auth-token=your_signed_HMAC_token"

Si l'opération réussit, vous obtenez un résultat semblable à l'objet JSON suivant :

{
  "status": "final",
  "ads": [
    {
      "duration_ms": 5046,
      "variants": {
        "devrel1428000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        },
        "devrel1928000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        }
      }
    }
  ],
  "slate": {
    "duration_ms": 0,
    "variants": {
      "devrel1428000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      },
      "devrel1928000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      }
    }
  }
}

Assembler des annonces dans le fichier manifeste de contenu

Les sections suivantes vous expliquent comment modifier le fichier manifeste de la diffusion en direct et ajouter les segments d'annonces.

Identifier les segments de coupure publicitaire et insérer des discontinuités

Lorsque vous traitez chaque fichier manifeste de variante, identifiez les balises EXT-X-CUE-IN et EXT-X-CUE-OUT dans votre flux, qui indiquent le début et la fin d'une coupure publicitaire.

Remplacez les balises EXT-X-CUE-IN et EXT-X-CUE-OUT par les éléments EXT-X-DISCONTINUITY pour que le lecteur vidéo client puisse basculer entre le contenu et les annonces.

L'exemple de fichier manifeste suivant remplace les balises EXT-X-CUE-IN et EXT-X-CUE-OUT :

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXT-X-CUE-OUT:15.000
#EXTINF:5.000,
contentorigin.com/3.ts
#EXTINF:5.000,
contentorigin.com/4.ts
#EXTINF:5.000,
contentorigin.com/5.ts
#EXT-X-CUE-IN
#EXTINF:5.000,
contentorigin.com/6.ts
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

L'exemple suivant montre un fichier manifeste remplacé :

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXTINF:5.000,
#EXT-X-DISCONTINUITY
{... Insert ad segments here ...}
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
contentorigin.com/6.mp4
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

Les segments d'annonces Google DAI ne sont pas chiffrés. Si votre contenu est chiffré, supprimez le chiffrement en insérant l'élément EXT-X-KEY:METHOD=NONE avant le premier segment d'annonce de chaque coupure publicitaire. À la fin de la coupure publicitaire, ajoutez à nouveau le chiffrement en insérant un élément EXT-X-KEY approprié.

Gardez une trace de l'heure de début, de la durée et de l'index de la prochaine coupure publicitaire.

Créer des URL de segments d'annonces

Remplacez les segments de contenu entre les balises EXT-X-DISCONTINUITY par des URL pour chaque segment d'annonce. Pour déterminer le nombre de segments d'annonces à insérer, utilisez les ads.segment_durations.values fournis dans la réponse JSON de l'API ATM.

Pour mettre fin à un bloc d'annonces de manière anticipée lors de la détection d'une balise EXT-X-CUE-IN, ajoutez le paramètre d= à l'URL du segment d'annonce final. Ce paramètre raccourcit le segment pour éviter d'affecter la chronologie du lecteur vidéo client.

L'exemple suivant assemble une URL de segment d'annonce pré-roll dans le fichier manifeste. Notez que les segments d'annonces utilisent un index basé sur zéro :

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/preroll/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

L'exemple suivant assemble une URL de segment d'annonce mid-roll dans le fichier manifeste :

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

L'exemple suivant insère des segments d'annonces dans le fichier manifeste :

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.00,
contentorigin.com/1.ts
#EXTINF:5.00,
contentorigin.com/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/1.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/2.ts?stream_id=SESSION_ID
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
contentorigin.com/6.mp4
#EXTINF:5.00,
contentorigin.com/7.mp4
#EXTINF:5.00,
contentorigin.com/8.mp4

Créer des segments d'écrans de remplacement

Pour combler le vide entre l'annonce et le contenu, insérez des segments d'écrans de remplacement. Utilisez le tableau slates.segment_durations.values de la réponse JSON de l'API ATM pour déterminer la durée de chaque segment d'écran de remplacement. Répétez la séquence des durées des segments si nécessaire pour remplir l'intégralité de la coupure publicitaire.

L'exemple suivant assemble un segment d'écran de remplacement :

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/slate/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

Le slate/0 de l'exemple représente le numéro d'itération de l'écran de remplacement. Consultez la compatibilité et la capacité de mise en cache de votre lecteur vidéo client pour déterminer s'il faut commencer par 0 et incrémenter ce nombre pour chaque boucle de l'écran de remplacement, ou le laisser à 0 pour toutes les itérations.

Gérer le retour au contenu

Après avoir inséré tous les segments de la série d'annonces, choisissez l'une des méthodes suivantes pour revenir à votre flux de contenu :

Méthode	Description	Effets sur le lecteur vidéo client
Remplir avec des segments d'écrans de remplacement	Insère les segments d'écrans de remplacement et les répète. Remplit la durée et insère des éléments `EXT-X-DISCONTINUITY` entre chaque itération de l'écran de remplacement.	Aucun effet. Le lecteur vidéo revient au contenu sans modifier la chronologie.
Réaligner avec un seul segment d'écran de remplacement	Insère un seul segment d'écran de remplacement. Utilise le paramètre `d=` pour remplir la durée jusqu'au début du contenu.	Aucun effet. Le lecteur vidéo revient au contenu sans modifier la chronologie.
Retour immédiat	Insérer des segments de contenu.	La chronologie du lecteur vidéo est modifiée. Votre lecteur vidéo client doit gérer la chronologie modifiée.

Facultatif : Planifier une coupure publicitaire

Pour améliorer votre taux de remplissage, envoyez une notification EABN (Early Ad Break Notification) avec la durée de la série d'annonces, les paramètres de ciblage personnalisés et les données de signal SCTE-35. Pour en savoir plus, consultez Envoyer des notifications de coupure publicitaire anticipées.