Cette page a été traduite par l'API Cloud Translation.

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

Ce guide explique comment insérer des pauses publicitaires à l'aide de la méthode des métadonnées de minutage des blocs d'annonces (ATM, Ad pod Timing Metadata) pour récupérer le minutage et la durée précis des pauses publicitaires, y compris des annonces pre-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 Ad pod Timing Metadata (ATM) : interrogez les résultats des décisions concernant les séries d'annonces, y compris les durées des annonces et des écrans noirs.
Point de terminaison du segment d'annonce : demandez des segments d'annonces ou de slate avec la possibilité de mettre fin au bloc d'annonces actuel.

Si vous le souhaitez, pour les événements en direct à forte simultanéité, nous vous recommandons d'appeler l'API EABN (Early Ad Break Notification) 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 (DAI) Redirection de la diffusion de séries d'annonces. Sélectionnez l'une des méthodes suivantes :

Interface utilisateur Ad Manager : configurer un livestream pour l'insertion dynamique d'annonces
API Ad Manager : utilisez une bibliothèque cliente (options disponibles) pour appeler la méthode LiveStreamEventService.createLiveStreamEvents. 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 de diffusion 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 et les métadonnées Google DAI à inclure dans la requête de fichier manifeste du flux.

L'exemple suivant transmet un ID de session Google DAI à un outil de manipulation 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'insertion d'annonces.

Récupérer les métadonnées de timing du bloc d'annonces

Pour récupérer le timing du bloc d'annonces, procédez comme suit :

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

Générer un jeton HMAC signé

Pour authentifier vos demandes, procédez comme suit :

Créez une chaîne de jeton en concaténant les paramètres suivants par ordre alphabétique, séparés par un tilde ~ :

Paramètre	Obligatoire ou facultatif	Description
`ad_break_id`	Obligatoire	Chaîne que vous spécifiez pour identifier l'emplacement publicitaire, par exemple `ad-break-1`. Pour les annonces pré-roll, utilisez `preroll`.
`custom_asset_key`	Obligatoire	Clé d'élément personnalisée de l'événement de diffusion en direct.
`cust_params`	Facultatif	Paramètres de ciblage personnalisé. Pour en savoir plus, consultez Indiquer des paramètres de ciblage dans votre flux.
`exp`	Obligatoire	Heure d'expiration de ce jeton, mesurée en nombre total de secondes écoulées depuis l'époque Unix.
`network_code`	Obligatoire	Votre code de réseau Google Ad Manager. Pour en savoir plus, consultez Rechercher des informations de compte Ad Manager.
`pd`	Obligatoire	Durée de la coupure publicitaire en millisecondes. Pour les annonces pré-roll, Google DAI remplace ce paramètre par les paramètres de votre événement de diffusion en direct.
`scte35`	Facultatif	Signal SCTE-35 encodé en base64. Vérifiez que le signal est correct. Si elle est incorrecte, un message est envoyé à l'en-tête HTTP `X-Ad-Manager-Dai-Warning` dans la réponse, et le signal est toujours propagé pour créer un point d'insertion publicitaire. Pour en savoir plus sur les repères d'insertion d'annonces compatibles, consultez Intégration HLS.

Téléchargez votre clé d'authentification Google DAI de type HMAC. Pour en savoir plus, consultez Authentifier les demandes de flux vidéo d'insertion dynamique d'annonce.
Utilisez la clé HMAC que vous avez téléchargée pour générer la signature SHA256 de la chaîne de jetons.
Concaténez la chaîne de jeton et la signature générée.
Appliquez l'encodage d'URL à la chaîne concaténée. La chaîne encodée est le jeton HMAC signé permettant d'authentifier les requêtes de l'API Ad pod Timing Metadata (ATM).

L'exemple suivant génère un jeton HMAC signé pour les annonces pré-roll :

custom_asset_key="CUSTOM_ASSET_KEY"
exp="1750700000" # Expired on Mon Jun 23 2025 13:33:20 GMT-0400 (Eastern Daylight Time)
network_code="NETWORK_CODE"
ad_break_id="preroll"
pd="0" # Pod duration value is overridden by the livestream event settings.

# The HMAC authentication key associated with your livestream event in Google Ad Manager.
secret_key="24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C"

# Concatenate the parameters, keep the parameters alphabetically ordered by name.
token_string="ad_break_id=${ad_break_id}~custom_asset_key=${custom_asset_key}~exp=${exp}~network_code=${network_code}~pd=${pd}"

# Calculate the SHA256 signature of the token_string.
hmac_signature=$(echo -n "$token_string" | openssl dgst -sha256 -hmac "$secret_key" | awk '{print $2}')

# Concatenate the token string and the signature.
signed_token="${token_string}~hmac=${hmac_signature}"

url_encode() {
    local string="${1}"
    local strlen=${#string}
    local encoded=""
    local pos c
    for (( pos=0 ; pos<strlen ; pos++ )); do
        c=${string:$pos:1}
        case "$c" in
            [-_.~a-zA-Z0-9] ) o="${c}" ;;
            *   ) printf -v o '%%%02x' "'$c"
        esac
        encoded+="${o}"
    done
    echo "${encoded}"
}

# Apply URL encoding to the concatenated string.
url_encoded_signed_token=$(url_encode "$signed_token")

echo "Signed HMAC token:"
echo "${url_encoded_signed_token}"

# Example output:
# ad_break_id%3Dpreroll~custom_asset_key%3DiYdOkYZdQ1KFULXSN0Gi7g~exp%3D1489680000~network_code%3D21775744923~pd%3D180000~pod_id%3D5~hmac%3D24E96382584C328087546B0E8454F26158564E8466FD2BE3D8A996B38445876C

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

Vérifiez les paramètres des pré-rolls pour votre événement en direct à l'aide des options suivantes :

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

L'exemple suivant effectue une demande 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 du bloc d'annonces pour les mid-rolls, 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 du bloc d'annonces et de la slate. L'API renvoie un objet JSON contenant les résultats de la décision du pod 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
          ]
        }
      }
    }
  }
}

Insérer des annonces dans le fichier manifeste du 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 tags EXT-X-CUE-IN et EXT-X-CUE-OUT dans votre flux, qui indiquent le début et la fin d'un bloc d'annonces.

Remplacez les tags 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 illustre 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 bloc d'annonces. À la fin de la coupure publicitaire, réactivez le chiffrement en insérant un EXT-X-KEY approprié.

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

Créer des URL de segments publicitaires

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

Pour mettre fin à un ad pod de manière anticipée lorsque vous détectez un tag EXT-X-CUE-IN, ajoutez le paramètre d= à l'URL du dernier segment d'annonce. Ce paramètre raccourcit le segment pour éviter d'affecter la timeline du lecteur vidéo du client.

L'exemple suivant assemble une URL de segment d'annonce préroll au 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 au 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'ardoise

Pour combler l'espace entre l'annonce et le contenu, insérez des segments d'écran. 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 de slate. Répétez la séquence des durées de segment si nécessaire pour remplir toute la coupure publicitaire.

L'exemple suivant assemble un segment de slate :

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'ardoise. Consultez la compatibilité et la capacité de mise en cache du lecteur vidéo de votre client pour déterminer si vous devez commencer à 0 et incrémenter ce nombre pour chaque boucle de la slate, ou le laisser à 0 pour toutes les itérations.

Gérer le retour au contenu

Une fois que vous avez inséré tous les segments du bloc d'annonces, choisissez l'une des méthodes suivantes pour revenir à votre flux de contenu :

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

Facultatif : Programmer une coupure publicitaire

Pour améliorer votre taux de remplissage, envoyez une notification de coupure publicitaire anticipée (EABN) avec la durée du bloc 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 anticipées pour les pauses publicitaires.