# Insertion d’annonces côté serveur (SSAI)
<a name="server-side-ad-insertion"></a>

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](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/costs.html).

## Mise en route avec SSAI
<a name="ssai-getting-started-with-ssai"></a>

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
<a name="ssai-getting-started-with-ssai-step-1"></a>

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 :
+ **ARN du canal** : vous en aurez besoin pour mettre à jour le canal ultérieurement.
+ **Préfixe d’URL de lecture** : extrayez le préfixe d’URL de l’URL de lecture (tout ce qui précède /api/). P. ex., si votre URL de lecture est :
  + https://c17b3fb37fc9.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.ABcdef12ghIJ.m3u8

  le préfixe est :
  + https://c17b3fb37fc9.us-west-2.playback.live-video.net/
+ **Format du conteneur** : doit être défini sur Flux de transport (TS) MPEG

### Étape 2 : créer une configuration de lecture MediaTailor
<a name="ssai-getting-started-with-ssai-step-2"></a>

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](https://docs.aws.amazon.com/mediatailor/latest/ug/configurations-create.html) 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 :


| Paramètre | Location | Value | 
| --- | --- | --- | 
| URL du serveur de décision publicitaire | Paramètres obligatoires | URL du serveur de décision publicitaire | 
| Source de contenu | Paramètres obligatoires | Préfixe d’URL de votre URL de lecture IVS ; p. ex., https://c17b3fb37fc9.us-west-2.playback.live-video.net/ | 
| Mode d’insertion | Détails de personnalisation | PLAYER\_SELECT | 

**Important**  
Spécifiez la source de contenu en utilisant uniquement le préfixe de l’URL de lecture de votre canal (se terminant par `live-video.net/`), et non l’URL complète. Si le format est incorrect, la création d’une configuration publicitaire à l’étape suivante échoue avec une erreur de validation.

### Étape 3 : créer une configuration publicitaire IVS
<a name="ssai-getting-started-with-ssai-step-3"></a>

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
<a name="ssai-getting-started-with-ssai-step-4"></a>

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
<a name="ssai-getting-started-with-ssai-step-5"></a>

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
<a name="ssai-getting-started-with-ssai-step-6"></a>

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.

**Important**  
Vous ne pouvez pas insérer d’autres pauses publicitaires tant qu’une pause publicitaire existante est toujours en cours. Les appels suivants à InsertAdBreak renverront une erreur 409 `ConflictException` jusqu’à la fin de la pause publicitaire en cours.

#### Intégration d'EventBridge
<a name="ssai-getting-started-with-ssai-step-6-eventbridge-integration"></a>

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


| Champ | Description | 
| --- | --- | 
| event\_name | Nom de l’événement émis. | 
| channel\_name | Nom du canal déclenché par la demande d’API InsertAdBreak. | 
| stream\_id | ID de diffusion en direct vers le canal déclenché par la demande d’API InsertAdBreak. | 
| ad\_break\_id | ID unique associé à la pause publicitaire, qui correspond à l’ID de pause publicitaire dans la réponse de la demande InsertAdBreak initiale. | 
| duration\_seconds | Valeur en secondes incluse dans la demande InsertAdBreak et spécifiée par le client. | 
| target\_start\_time | Horodatage estimé de la diffusion en direct lorsque la pause publicitaire est insérée dans la liste de lecture.  | 

### Étape 7 : événements du SDK du lecteur
<a name="ssai-getting-started-with-ssai-step-7"></a>

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 :


| Événement | Charge utile | Déclencheur | 
| --- | --- | --- | 
| Début de la pause publicitaire | AdBreak | Premier segment de la pause publicitaire | 
| Début de la création publicitaire | AdCreative | Premier segment de chaque création | 
| Mise à jour du temps publicitaire | AdTimeUpdate | Chaque seconde pendant la lecture de l’annonce | 
| Fin de la création publicitaire | AdCreative | Dernier segment de chaque création | 
| Fin de la pause publicitaire | AdBreak | Premier segment de contenu après la pause | 

Pour connaître les noms des événements et données utiles propres à chaque plateforme, consultez la documentation du SDK du lecteur :
+ Web : consultez l’énumération PlayerEventType à l’adresse [https://aws.github.io/amazon-ivs-player-docs/latest/web/](https://aws.github.io/amazon-ivs-player-docs/latest/web/)
+ Android : consultez la classe Player.Listener à l’adresse [https://aws.github.io/amazon-ivs-player-docs/latest/android/](https://aws.github.io/amazon-ivs-player-docs/latest/android/)
+ iOS : consultez le protocole IVSPlayerDelegate à l’adresse [https://aws.github.io/amazon-ivs-player-docs/latest/ios/](https://aws.github.io/amazon-ivs-player-docs/latest/ios/)

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é
<a name="ssai-getting-started-with-ssai-ad-markers"></a>

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](#ssai-playlist-reference) pour plus de détails.

### Expérience des spectateurs
<a name="ssai-getting-started-with-ssai-viewer-experience"></a>

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
<a name="ssai-getting-started-with-ssai-viewer-tracking-parameters"></a>

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](https://docs.aws.amazon.com/mediatailor/latest/ug/passing-paramters-to-the-ads.html)). 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
<a name="ssai-getting-started-with-ssai-reporting-mode"></a>

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
<a name="ssai-getting-started-with-ssai-known-issues"></a>
+ Les annonces IVS ne fonctionnent pas si le `containerFormat` du canal IVS est défini sur `FRAGMENTED_MP4`. Les appels à UpdateChannel et CreateChannel renverront une erreur de validation si le format de conteneur FMP4 est utilisé avec une configuration publicitaire.
+ Pendant la lecture des annonces, le basculement entre le mode de débit adaptatif et la sélection manuelle de la qualité peut entraîner des problèmes de blocage et de mise en mémoire tampon pour le lecteur.
+ Pour les flux de plus de 12 heures ayant rencontré une pénurie, la date/heure de programme peut dériver, ce qui empêche la diffusion d’annonces aux spectateurs. La solution consiste à redémarrer le flux côté diffuseur.

## Référence de liste de lecture SSAI
<a name="ssai-playlist-reference"></a>

### Liste de lecture de variantes en direct avec SSAI
<a name="ssai-playlist-reference-live"></a>

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"
```


| Attribut | Description | 
| --- | --- | 
| ID | Format : .: `stitched-ad-{timestamp}-{duration}`<br />`{timestamp}` : horodatage Unix du début de l’annonce<br />`{duration}:` Durée de l’annonce sous forme d’entier en nanosecondes<br />Type : tableau de chaînes | 
| CLASS | Toujours live-video-net-stitched-ad pour les annonces SSAI. | 
| START-DATE | Date/heure de programme ISO 8601 au début de l’annonce. | 
| DURATION | Durée de l’annonce en secondes. | 
| X-NET-LIVE-VIDEO-AD-AD-BREAK-ID | ID de pause publicitaire renvoyé par IVS lorsque l’opération InsertAdBreak a été appelée. | 

**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"
```


| Attribut | Description | 
| --- | --- | 
| CLASS | Toujours live-video-net-stream-source. | 
| START-DATE / END-ON-NEXT | Métadonnées temporelles de cette plage source. | 
| X-NET-LIVE-VIDEO-STREAM-SOURCE | Indique au lecteur que la source vidéo change. La valeur est « live » pour le contenu principal, ou un ID unique pour le contenu publicitaire. | 

**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
<a name="ssai-playlist-reference-live-ad-segments"></a>

```
#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
```


| Attribut | Description | 
| --- | --- | 
| EXT-X-PROGRAM-DATE-TIME | Horodatage de ce segment. | 
| EXTINF | Format : .: `{duration},{tag}`<br />`{duration}` : durée du segment en secondes.<br />`{tag}` : identifiant de la source. Pour le contenu en direct, il s’agit toujours de `live`. Pour le contenu publicitaire, il s’agit d’un UUID fourni par MediaTailor qui identifie de façon unique le transcodage de la ressource d’annonce. | 
| URL du segment | Point de terminaison hébergé par IVS contenant des informations chiffrées sur le segment et son emplacement dans les caches IVS. | 

### Liste de lecture de variantes VOD avec SSAI
<a name="ssai-playlist-reference-vod"></a>

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
```


| Attribut | Description | 
| --- | --- | 
| ID | Identifiant unique de cette pause publicitaire. Utilisé pour corréler les marqueurs de début et de fin. | 
| START-DATE | Date/heure de programme ISO 8601 au début de la pause publicitaire. | 
| PLANNED-DURATION | Durée prévue de la pause publicitaire en secondes. | 
| SCTE35-OUT | Marqueur SCTE-35 signalant le début de la pause publicitaire. | 

**2. Segments publicitaires (assemblés par MediaTailor)**

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


| Attribut | Description | 
| --- | --- | 
| EXTINF | Durée du segment publicitaire en secondes. | 
| Segment URL | Chemin relatif vers le segment publicitaire hébergé par MediaTailor. | 

**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
```


| Attribut | Description | 
| --- | --- | 
| ID | Même ID que le marqueur de début. Associe les deux éléments. | 
| START-DATE | Heure de début initiale de la pause publicitaire (identique à celle du marqueur de début). | 
| END-DATE | Horodatage ISO 8601 à la fin de la pause publicitaire. | 
| DURATION | Durée réelle de la pause publicitaire en secondes. | 
| SCTE35-IN | Marqueur SCTE-35 signalant la fin de la pause publicitaire. |