# Guida introduttiva all'SDK IVS Player per il web
<a name="web-getting-started"></a>

Questo documento illustra i passaggi necessari per iniziare a utilizzare l'SDK Amazon IVS Player sul web.

Forniamo supporto attraverso un tag `script` così come attraverso un modulo npm. 

## Demo
<a name="web-demo"></a>

La seguente demo live mostra come utilizzare il lettore Web con un tag `script` dalla nostra rete di distribuzione di contenuti (CDN): [esempio di lettore Amazon IVS](https://codepen.io/amazon-ivs/pen/QWbzORP/c3b13a2df34b60ada7756f3a2af8d2f0). La demo include la configurazione di listener di eventi.

Vedi anche [https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample) per una selezione di demo aggiuntive del lettore per il web.

## Configurazione con tag di script
<a name="web-setup-script-tag"></a>

Per configurare il lettore Amazon IVS utilizzando il tag `script`:

1. Includere il seguente tag (per l'ultima versione del lettore).

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

1. Una volta caricato `amazon-ivs-player.min.js`, questo aggiungerà una variabile `IVSPlayer` al contesto globale. Questa è la libreria che sarà utilizzata per creare un'istanza del lettore. Innanzitutto, controllare `isPlayerSupported` per determinare se il browser supporta il lettore IVS:

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

   Quindi, per creare un'istanza del lettore, richiamare la funzione `create` sull'oggetto `IVSPlayer`.

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

   L'SDK Amazon IVS Player per il web utilizza worker web per ottimizzare la riproduzione video.

1. Caricare e riprodurre un flusso utilizzando le funzioni `load` e `play` sull'istanza del lettore:

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

   dove `PLAYBACK_URL` è l'URL restituito dall'API di Amazon IVS quando viene richiesta una chiave di flusso.

## Codice di esempio
<a name="web-sample-code"></a>

In questo esempio, sostituire `PLAYBACK_URL` con l'URL del flusso di origine che si desidera caricare. Nell'esempio viene utilizzata la versione più recente del lettore 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>
```

Nel tag `<video>`, `playsinline` è necessario per la riproduzione in linea su iOS Safari. Consultare [https://webkit.org/blog/6784/new-video-policies-for-ios/](https://webkit.org/blog/6784/new-video-policies-for-ios/).

## Configurazione con NPM
<a name="web-setup-npm"></a>

Per informazioni, incluso un esempio di file di configurazione Webpack, consultare il seguente repository: [https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample).

**Nota:** quando si esegue l'hosting delle risorse statiche del lettore dal proprio dominio, è necessario impostare l'intestazione di risposta "Content-Type" per il valore binario WebAssembly (`amazon-ivs-wasmworker.min.wasm`) su "application/wasm". È necessario, inoltre, comprimere in formato gzip le proprie risorse per ridurre i byte scaricati via cavo e migliorare il tempo di avvio della riproduzione del lettore.

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

Se si usa TypeScript, il pacchetto npm include tipi che potrebbero essere importati e utilizzati. Per informazioni su questi tipi, consultare [SDK Amazon IVS Player: Documentazione di riferimento per il Web](https://aws.github.io/amazon-ivs-player-docs/1.50.0/web/).

## Configurazione di un worker di servizi
<a name="web-service-worker"></a>

Per ridurre ulteriormente la latenza quando si riproduce tramite browser che supportano solo la riproduzione nativa (principalmente iOS Safari), è possibile impostare e configurare un worker di servizi. Per un contesto più approfondito, consulta [Riduzione della latenza nei lettori di terze parti](player.md#player-reducing-latency).

Per configurare il lettore Amazon IVS in modo che utilizzi un worker di servizi:

1. Crea un file per caricare il worker di servizi IVS dalla CDN. Ciò è necessario in quanto i worker di servizi devono essere ospitati sullo stesso dominio della pagina che li richiama.

   Crea un file denominato `amazon-ivs-service-worker-loader.js` o simile e aggiungi la seguente riga:

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

1. Quando crei un'istanza del lettore, inserisci la seguente configurazione `serviceWorker` che fa riferimento al file `amazon-ivs-service-worker-loader.js`:

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

1. Nell'elemento video, imposta l'attributo `crossOrigin` su `anonymous`. Ciò è necessario per consentire al worker di servizi di apportare modifiche al manifesto.

**Nota**: per testare il worker di servizi a livello locale, la pagina deve essere fornita da *localhost* o *https*.

Per una demo dal vivo, guarda l'esempio del worker di servizi nel seguente repository:

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

## Riproduzione solo audio
<a name="web-audio-only-playback"></a>

La qualità solo audio deve essere selezionata manualmente con il metodo `setQuality()`. Nota che il lettore non supporta un valore `true` per il secondo argomento, `adaptive`; pertanto, per impostazione predefinita, questo argomento è `false`.

Per impostare la qualità solo audio prima dell'inizio della riproduzione, chiama `setQuality()` all'interno dell'evento `READY`:

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

L'impostazione della qualità all'interno di `READY` funziona sia per la modalità di riproduzione automatica sia per quella non automatica.

## Ottimizzazione della riproduzione in background
<a name="web-optimize-background-playback"></a>

A partire dalla versione SDK 1.45.0, il client può essere configurato per ottimizzare l'utilizzo dei dati durante la riproduzione in una scheda in background. Quando questa funzione è abilitata, dopo la durata specificata il lettore seleziona la qualità video SD più alta, con un massimo di 480p. Il lettore seleziona sempre il video; audio\$1only non è selezionato. Ciò è valido sia per la modalità manuale sia per la modalità auto. Quando la scheda è in primo piano, il lettore torna automaticamente all'impostazione precedente.

Per abilitare questa caratteristica:

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