# Démarrage avec le kit SDK du lecteur Web d’IVS
<a name="web-getting-started"></a>

Ce document vous présente les étapes à suivre pour commencer à utiliser le kit SDK du lecteur Web d’Amazon IVS.

Nous fournissons un support via une balise `script`, ainsi que via un module npm. 

## Démonstrations
<a name="web-demo"></a>

La démo en direct suivante montre comment utiliser le lecteur Web avec une balise `script` de notre réseau de diffusion de contenu : [exemple pour le lecteur Amazon IVS](https://codepen.io/amazon-ivs/pen/QWbzORP/c3b13a2df34b60ada7756f3a2af8d2f0). La démonstration comprend la configuration d’écouteurs d’événements.

Consultez également [https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample) pour obtenir une sélection d’autres démonstrations de lecteurs Web.

## Configuration avec la balise de script
<a name="web-setup-script-tag"></a>

Pour configurer le lecteur Amazon IVS à l’aide de la balise `script` :

1. Incluez la balise suivante (pour la dernière version du lecteur).

   ```
   <script src="https://player.live-video.net/1.50.0/amazon-ivs-player.min.js"></script>
   ```

1. Une fois `amazon-ivs-player.min.js` chargé, il ajoute une variable `IVSPlayer` au contexte global. Il s’agit de la bibliothèque que vous allez utiliser pour créer une instance du lecteur. Tout d’abord, vérifiez `isPlayerSupported` pour déterminer si le navigateur prend en charge le lecteur IVS :

   ```
   if (IVSPlayer.isPlayerSupported) { ... }
   ```

   Ensuite, pour créer une instance du lecteur, appelez la fonction `create` sur l’objet `IVSPlayer`.

   ```
   const player = IVSPlayer.create();
   ```

   Le kit SDK du lecteur Web Amazon IVS utilise des travailleurs web pour optimiser la lecture vidéo.

1. Chargez et lisez un flux à l’aide des fonctions `load` et `play` sur l’instance du lecteur :

   ```
   player.load("PLAYBACK_URL");
   player.play();
   ```

   où `PLAYBACK_URL` est l’URL renvoyée par l’API Amazon IVS lorsqu’une clé de flux est demandée.

## Exemple de code
<a name="web-sample-code"></a>

Dans cet exemple, remplacez `PLAYBACK_URL` avec le flux source d’URL que vous souhaitez charger. L’exemple utilise la dernière version du lecteur Amazon IVS.

```
<script src="https://player.live-video.net/1.50.0/amazon-ivs-player.min.js"></script>
<video id="video-player" playsinline></video>
<script>
  if (IVSPlayer.isPlayerSupported) {
    const player = IVSPlayer.create();
    player.attachHTMLVideoElement(document.getElementById('video-player'));
    player.load("PLAYBACK_URL");
    player.play();
  }
</script>
```

Dans la balise `<video>`, `playsinline` est nécessaire pour la lecture en ligne sur iOS Safari. Voir [https://webkit.org/blog/6784/new-video-policies-for-ios/](https://webkit.org/blog/6784/new-video-policies-for-ios/).

## Configuration avec NPM
<a name="web-setup-npm"></a>

Pour obtenir des conseils, y compris un exemple de fichier de configuration Webpack, consultez le référentiel suivant : [https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample).

**Remarque :** lorsque vous hébergez des ressources de lecteur statiques à partir de votre propre domaine, vous devez définir l’en-tête de réponse « Content-Type » pour le binaire WebAssembly (`amazon-ivs-wasmworker.min.wasm`) sur « application/wasm ». Vous devez également compresser vos ressources à l’aide de gzip pour réduire la quantité d’octets téléchargés sur le réseau et permettre au lecteur de démarrer la lecture plus rapidement.

## TypeScript
<a name="web-typescript"></a>

Si vous utilisez TypeScript, le package npm inclut les types que vous voulez importer et utiliser. Pour plus d’informations sur ces types, consultez la rubrique [Kit SDK du lecteur Amazon IVS : références pour le Web](https://aws.github.io/amazon-ivs-player-docs/1.50.0/web/).

## Configurer un service worker
<a name="web-service-worker"></a>

Pour réduire davantage la latence lors de la lecture via des navigateurs qui ne prennent en charge que la lecture native (principalement iOS Safari), vous pouvez configurer un service worker. Pour obtenir plus de contexte, consultez [Réduire la latence des lecteurs tiers](player.md#player-reducing-latency).

Configurer le lecteur Amazon IVS de manière à ce qu’il utilise un service worker :

1. Créez un fichier pour charger le service worker IVS hors du CDN. Cela est nécessaire car les service workers doivent être hébergés sur le même domaine que la page qui les extrait.

   Créez un fichier nommé `amazon-ivs-service-worker-loader.js` ou de façon similaire et ajoutez la ligne suivante :

   ```
   importScripts('https://player.live-video.net/1.50.0/amazon-ivs-service-worker.min.js');
   ```

1. Lorsque vous créez une instance de lecteur, transmettez la configuration `serviceWorker` suivante faisant référence au fichier `amazon-ivs-service-worker-loader.js` :

   ```
   const player = IVSPlayerPackage.create({
      serviceWorker: {
         url: 'amazon-ivs-service-worker-loader.js'
      }
   });
   ```

1. Sur l’élément vidéo, définissez l’attribut `crossOrigin` sur `anonymous`. Cela est nécessaire pour permettre au service worker d’apporter des modifications au manifeste.

**Remarque** : pour tester le service worker localement, la page doit être diffusée avec *localhost* ou *https*.

Pour voir une démonstration en direct, consultez l’exemple du service worker dans le référentiel suivant :

[https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample)

## Lecture en mode audio uniquement
<a name="web-audio-only-playback"></a>

La qualité en mode audio uniquement doit être sélectionnée manuellement à l’aide de la méthode `setQuality()`. Notez que le lecteur ne prend pas en charge une valeur `true` pour le deuxième argument, `adaptive`, donc par défaut, cet argument est `false`.

Pour définir la qualité en mode audio uniquement avant le début de la lecture, appelez `setQuality()` dans l’événement `READY` :

```
player.addEventListener(PlayerState.READY, () => {
   const qualities = player.getQualities();
   const audioOnly = qualities.find(q => q.name === 'audio_only');
   if (audioOnly) {
      player.setQuality(audioOnly);
   }
});
```

La définition de la qualité dans `READY` fonctionne à la fois pour les modes de lecture automatique et non automatique.

## Optimisation de la lecture en arrière-plan
<a name="web-optimize-background-playback"></a>

À partir de la version 1.45.0 du kit SDK, le client peut être configuré pour optimiser l’utilisation des données pendant la lecture en arrière-plan. Lorsque cette fonctionnalité est activée, le lecteur sélectionne, après la durée spécifiée, la qualité vidéo SD la plus élevée disponible, avec un maximum de 480p. Le lecteur sélectionne toujours vidéo ; audio\$1only n’est pas sélectionné. Cela s’applique aux modes manuel et automatique. Lorsque l’onglet repasse au premier plan, le lecteur revient automatiquement à son paramètre précédent.

Pour activer cette fonctionnalité :

```
const player = IVSPlayer.create({
   optimizeBackgroundPlayback: {
      enabled: true,
      switchDelayMs: 60 * 1000,   // Optional, defaults to 60s
   }
});
```