Insertion d’annonces côté serveur (SSAI)

L’insertion d’annonces côté serveur (SSAI) Amazon IVS vous permet de monétiser vos flux avec des annonces vidéo. IVS SSAI s’intègre à AWS Elemental MediaTailor, ce qui vous donne accès à des fonctionnalités comme la prise de décision publicitaire, le ciblage d’audience et la personnalisation. IVS fournit une opération d’API pour insérer des pauses publicitaires dans votre diffusion en direct, ce qui vous permet de donner aux créateurs ou aux opérateurs le contrôle du moment où les annonces sont diffusées. IVS assemble les annonces directement dans le flux vidéo. Cela permet une expérience de visionnage fluide et évite une logique complexe côté client. Pour plus d’informations sur les coûts associés à SSAI, consultez Coûts IVS.

Mise en route avec SSAI

Ce didacticiel vous aide à vous familiariser avec l’insertion d’annonces côté serveur (SSAI) Amazon IVS. À la fin de ce didacticiel, vous disposerez d’un canal IVS configuré pour l’insertion d’annonces côté serveur, et vous saurez comment insérer des pauses publicitaires dans votre diffusion en direct. IVS SSAI s’intègre à AWS Elemental MediaTailor pour gérer la prise de décision publicitaire.

Étape 1 : créer un canal IVS

Créez un canal IVS. L’URL de lecture du canal est nécessaire pour configurer MediaTailor à l’étape suivante. Après avoir créé votre canal, enregistrez les valeurs suivantes :

Étape 2 : créer une configuration de lecture MediaTailor

Créez une configuration de lecture AWS Elemental MediaTailor. Cette configuration connecte votre serveur de décision publicitaire à IVS et active l’insertion d’annonces pour vos flux.

La configuration de lecture utilise le préfixe d’URL de lecture, qui est commun à tous les canaux IVS de votre compte et de votre région. Vous pouvez ainsi utiliser une seule configuration de lecture MediaTailor avec plusieurs canaux IVS.

Consultez Création d’une configuration de lecture MediaTailor dans le Guide de l’utilisateur AWS Elemental MediaTailor pour obtenir des instructions. Lors de la création de la configuration, les paramètres suivants sont requis pour IVS SSAI :

Étape 3 : créer une configuration publicitaire IVS

Une configuration publicitaire lie vos ressources IVS à votre configuration de lecture MediaTailor. Vous pouvez utiliser une configuration de lecture MediaTailor créée dans n’importe quelle région d’origine IVS avec une configuration publicitaire située dans n’importe quelle autre région d’origine IVS. Les régions d’origine IVS incluent us-west-2, us-east-1, eu-west-1, eu-central-1, ap-northeast-1, ap-northeast-2 et ap-south-1.

Vous pouvez réutiliser une même configuration publicitaire avec plusieurs canaux.

Pour créer une configuration publicitaire (AWS CLI) :

aws ivs create-ad-configuration --name "my-ad-config" --media-tailor-playback-configurations playbackConfigurationArn="arn:aws:mediatailor:us-west-2:123456789012:playbackConfiguration/my-mediatailor-config"

Enregistrez la valeur arn de la réponse. Vous en avez besoin à l’étape suivante.

Étape 4 : mettre à jour le canal avec la configuration publicitaire

Mettez à jour votre canal IVS pour l’associer à la configuration publicitaire que vous avez créée. Pour mettre à jour le canal (AWS CLI) :

aws ivs update-channel --arn "arn:aws:ivs:us-west-2:123456789012:channel/ABcdef12ghIJ" --ad-configuration-arn "arn:aws:ivs:us-west-2:123456789012:ad-configuration/ABcdef12ghIJ"

Étape 5 : démarrer la diffusion en continu

Utilisez le point de terminaison d’ingestion et la clé de flux de votre canal pour démarrer la diffusion en continu.

Étape 6 : insérer une pause publicitaire

Pendant que votre flux est en direct, appelez l’opération InsertAdBreak pour insérer une pause publicitaire. Spécifiez l’ARN du canal et la durée (en secondes) de la pause publicitaire.

Pour insérer une pause publicitaire (AWS CLI) :

aws ivs insert-ad-break --channel-arn "arn:aws:ivs:us-west-2:123456789012:channel/ABcdef12ghIJ" --duration-seconds 30

Une fois InsertAdBreak renvoyé avec succès, vous pouvez recevoir un événement EventBridge (IVS Ad Break State Change) contenant un horodatage qui indique l’heure prévue à laquelle la pause publicitaire sera insérée dans les listes de lecture des spectateurs. Il s’agit du moment où le diffuseur peut raisonnablement s’attendre à ce que les annonces commencent à remplacer le contenu. Si une annonce ne peut pas être fournie (p. ex., si votre serveur de décision publicitaire ne renvoie pas d’annonce ou si les annonces doivent être transcodées par MediaTailor), le contenu source s’affiche à la place.

Intégration d'EventBridge

Avec SSAI, un événement de changement d’état de pause publicitaire (appelé Pause publicitaire insérée) est ajouté, avec les champs suivants :

Étape 7 : événements du SDK du lecteur

Sur toutes les plateformes, le SDK du lecteur expose les événements lorsqu’une pause publicitaire est lue, avec des notifications lorsqu’une annonce démarre, progresse et s’arrête. Voici un résumé général des événements disponibles et de leur timing :

Pour connaître les noms des événements et données utiles propres à chaque plateforme, consultez la documentation du SDK du lecteur :

Voici un exemple d’utilisation des événements publicitaires dans le SDK Web pour créer un composant d’interface utilisateur simple de compte à rebours pendant une pause publicitaire :

// State 
let podLength = 0;  
let podIndex = 0; 
let remainingSeconds = 0; 
 
// Fired every second during the ad break 
player.addEventListener(PlayerEventType.AD_TIME_UPDATE, (payload) => { 
    podLength = payload.podLength; 
    podIndex = payload.podIndex; 
    remainingSeconds = Math.round(payload.creativeDuration - payload.creativeElapsed); 
    const text = `Ad ${podIndex} of ${podLength} · ${remainingSeconds}s remaining` 
    // Ad 1 of 2 · 20s remaining 
    console.log('Ad countdown text', text); 
    UpdateAdOverlay(text); 
}); 

// Fired when the ad break ends  
player.addEventListener(PlayerEventType.AD_BREAK_ENDED, (payload) => { 
    hideAdOverlay(); 
});

Marqueurs publicitaires dans le contenu enregistré

Lorsqu’une diffusion en direct est enregistrée avec l’enregistrement automatique dans Amazon S3, IVS génère et écrit une liste de lecture VOD dans S3 qui inclut des marqueurs publicitaires SCTE-35 aux positions où les annonces ont été déclenchées pendant la diffusion en direct. Consultez Référence de liste de lecture SSAI pour plus de détails.

Expérience des spectateurs

Par défaut, MediaTailor remplit les annonces et les diffuse à tous les spectateurs lorsque vous insérez une pause publicitaire. Si vous utilisez des jetons d’autorisation de lecture pour vos flux, vous pouvez exclure les spectateurs de la réception des annonces en ajoutant la revendication "aws:ads-opt-out": true à votre jeton JWT d’autorisation de lecture.

Lorsque des spectateurs commencent à lire le flux au milieu d’une pause publicitaire, IVS arrondit la durée de la pause publicitaire au quartile supérieur le plus proche. P. ex., un spectateur qui rejoint une pause publicitaire de 60 secondes alors qu’il reste 35 secondes aura une pause publicitaire de 45 secondes.

Lorsque vous mettez à jour votre configuration de lecture MediaTailor ou ajoutez de nouvelles annonces, les spectateurs risquent de ne pas voir les annonces la première fois que vous demandez une pause publicitaire, car MediaTailor doit d’abord les transcoder. Après quelques minutes, les appels suivants à InsertAdBreak permettront aux spectateurs de voir les annonces. Les journaux de transcodage MediaTailor enregistrent ces transcodages.

Paramètres de suivi des spectateurs

Lorsque vous configurez un serveur de décision publicitaire (ADS) dans votre PlaybackConfiguration Elemental MediaTailor, vous pouvez transmettre des paramètres à ADS à l’aide de modèles (voir Transmission de paramètres MediaTailor à ADS). Avec IVS SSAI, vous pouvez transmettre des paramètres pour chaque spectateur à l’aide du jeton d’autorisation de lecture de cet utilisateur, en ajoutant une revendication au format suivant :

"aws:ads-player-params": { 
   "key1": "value1", 
   "key2": "value2" 
}

Ces paramètres sont transmis à Elemental MediaTailor pour être renseignés comme variables de modèle [player_params.key1] et [player_params.key2]. Les clés que vous insérez dans cette liste sont toujours placées dans l’espace de noms des paramètres de modèle player_params.

La taille totale des données utiles pour l’ensemble des clés et valeurs combinées est limitée à 1 000 octets.

Mode de rapport

Lorsqu’un spectateur regarde une annonce, le client ou le serveur peut envoyer des balises indiquant la progression de la lecture de chaque création publicitaire. Par défaut, MediaTailor gère l’envoi de balises côté serveur. Vous pouvez contrôler le mode de rapport en ajoutant la revendication suivante au jeton d’autorisation de lecture :

"aws:ads-reporting-mode": "CLIENT" | "SERVER"

La valeur par défaut est  SERVER. Lorsqu’il est défini sur SERVER, MediaTailor envoie des balises côté serveur. Lorsqu’il est défini sur CLIENT, l’envoi de balises côté serveur est désactivé et les données de suivi sont fournies dans le champ metadata.trackingData de l’événement adBreakStarted du SDK du lecteur IVS. Le SDK du lecteur IVS n’appelle pas les URL de balise.

Problèmes connus

Référence de liste de lecture SSAI

Liste de lecture de variantes en direct avec SSAI

Lorsqu’une annonce est assemblée dans le flux, IVS insère les balises documentées ci-dessous avant les segments publicitaires.

1. Déclaration d’annonce assemblée

#EXT-X-DATERANGE:ID="stitched-ad-1765566299-20000000000",CLASS="live-video-net-stitched-ad",START-DATE="2025-12-12T19:04:59.079Z",DURATION=20.000,X-NET-LIVE-VIDEO-AD-AD-BREAK-ID="test"

2. Changement de source du flux

#EXT-X-DATERANGE:ID="source-1765566299",CLASS="live-video-net-stream-source",START-DATE="2025-12-12T19:04:59.079Z",END-ON-NEXT=YES,X-NET-LIVE-VIDEO-STREAM-SOURCE="0f262e65-a709-4ef1-8741-e82d936c"

3. Marqueur de discontinuité

#EXT-X-DISCONTINUITY

Balise HLS standard signalant que les paramètres d’encodage peuvent changer entre la diffusion en direct et le contenu publicitaire.

Segments publicitaires

#EXT-X-PROGRAM-DATE-TIME:2025-12-12T19:04:59.079Z 
#EXTINF:2.000,0f262e65-a709-4ef1-8741-e82d936c 
https://4ce388b1cf28.j.cloudfront.hls.live-video.net/v1/segment/CvsCse8Qbs5DU_aRmrVLd72_nK9lo9xS1KjD115LsIXcsD27JfLfkSuamLUivqOTrfHUeGf6Zmx_c9rhq0btTOu7E4F1DaU8knNoebLq6FlKp6q8ysaQdEA10gKCNP92oAQ_0DGLInY462O9HUxgtk5KHj23ZjPhVCxIh3DjWqwaevDci1_q7dYL55rgSKd11SfpsGSS9Yup4g5dfzyGhfz6Y2Skaj34JtoVyd8Nxlppc4jDlZl-6j7YM1i2qdUcM3VNWrZrxCisBXgOPtI3vFdeNcNjPzVdOGjMz5cXcQIp8YOCwnkdkomhn_3xxmB1Zngl3QPao6-oPsjH3qVcMOCuKfKZSmRJGFLvkrO1PefV5ya3eUvihXCMvDE-81EmGp5q9ErEgFpz06rMDbYFWb3z9H8X0t8KzvGDOaqKTYHZ0lgEV-fULeDQ76pDy_OVPwhO2vJMxBpfdQ_IeB1QUK2wJmXJ96Mvv0C2dcb0F7zE3lr_iBGemUjwmb7JmBoM3HdJbpV0TGp8C6vhIAEqCXVzLXdlc3QtMjD3DQ.ts?dna=CmanuVzG9F6kGS2X7ThbGZyZPHWgX2TiBlBMYsvGWLcWaLWyntTaWRp5D9qjZsrGKkzdwoLNY4pri6ZgpxnzqLqWvhcP6zoGu8vifP5NxPgiNKMmYdUmQrqTAf7jbauvE3c6B9ebptAaDEkrbrnG1qF8Cv3kbiABKgl1cy13ZXN0LTIw9w0

Liste de lecture de variantes VOD avec SSAI

Lorsqu’une diffusion en direct est enregistrée, IVS génère et écrit une liste de lecture VOD dans S3 qui inclut des marqueurs publicitaires SCTE-35 aux positions où les annonces ont été déclenchées pendant la diffusion en direct. Pour diffuser des annonces pendant la lecture VOD, vous diffusez cette liste de lecture IVS via MediaTailor, qui est chargé d’assembler les segments publicitaires dans la liste de lecture. MediaTailor remplace les segments VOD d’origine par des segments publicitaires pendant la pause publicitaire.

1. Marqueur de début de pause publicitaire (SCTE35-OUT)

#EXT-X-DATERANGE:ID="12345678",START-DATE="2025-12-06T00:45:45.723Z",PLANNED-DURATION=20.0,SCTE35-OUT=0xFC302000000000000000FFF00F05F8E7AEFC7FFFFE001B7740000000000000340CFD88

2. Segments publicitaires (assemblés par MediaTailor)

#EXTINF:2.0, ../../../../segment/b2857627df9428679e888ee8daa979d0b7559801/gk-test-ivs-vod/bd0c7d90-a47c-4a91-b5ec-7d0f9897049b/0/3

3. Marqueur de fin de pause publicitaire (SCTE35-IN)

#EXT-X-DATERANGE:ID="12345678",START-DATE="2025-12-06T00:45:45.723Z",END-DATE="2025-12-06T00:46:07.889Z",DURATION=20.0,SCTE35-IN=0xFC302000000000000000FFF00F05F8E7AEFC7F7FFE001B7740000000000000C23E5851