# 開始使用 IVS Web 播放器 SDK
<a name="web-getting-started"></a>

本文件將帶您了解開始使用 Amazon IVS Web 播放器 SDK 的相關步驟。

我們透過 `script` 標記以及透過 npm 模組提供支援。

## 示範
<a name="web-demo"></a>

下列即時示範展示如何在內容交付網路中使用 Web 播放器與 `script` 標籤：[Amazon IVS Player 範例](https://codepen.io/amazon-ivs/pen/QWbzORP/c3b13a2df34b60ada7756f3a2af8d2f0)。此示範包括設定事件接聽程式。

另外，如需選取其他 Web 播放器示範，請參閱 [https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample)。

## 使用指令碼標記進行設定
<a name="web-setup-script-tag"></a>

若要使用 `script` 標記設定 Amazon IVS 播放器：

1. 包含下列標記 (適用於最新版本的播放器)。

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

1. 加載 `amazon-ivs-player.min.js` 之後，它會將一個 `IVSPlayer` 變數新增至全域內容。這是您要用來建立播放器執行個體的程式庫。首先，檢查 `isPlayerSupported` 以確定瀏覽器是否支援 IVS 播放器：

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

   然後，若要建立播放器執行個體，請呼叫 `IVSPlayer` 物件上的 `create` 函數。

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

   Amazon IVS Web 播放器 SDK 會利用 Web 工作者來最佳化視訊播放。

1. 使用播放器執行個體上的 `load` 和 `play` 函數，載入並播放串流。

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

   其中，`PLAYBACK_URL` 是在請求串流金鑰時從 Amazon IVS API 傳回的 URL。

## 範例程式碼
<a name="web-sample-code"></a>

在此範例中，將 `PLAYBACK_URL` 改成您要載入的來源串流 URL。此範例使用最新版本的 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>
```

在 `<video>` 標籤中，在 iOS Safari 上進行內嵌播放時需要 `playsinline`。請參閱 [https://webkit.org/blog/6784/new-video-policies-for-ios/](https://webkit.org/blog/6784/new-video-policies-for-ios/)。

## 使用 NPM 進行設定
<a name="web-setup-npm"></a>

如需指導 (包括 Webpack 組態檔案範例)，請參閱下列儲存庫：[https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample)。

**備註：**從您自己的網域託管播放器靜態資產時，您必須將 WebAssembly 二進位檔 (`amazon-ivs-wasmworker.min.wasm`) 的「Content-Type」回應標頭設定為「application/wasm」。此外，您必須將資產 gzip 化，以減少透過連線下載的位元組，並改善播放器開始播放的時間。

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

如果您使用的是 TypeScript，npm 套件包含您可能想要匯入和使用的類型。如需這些類型的詳細資訊，請參閱 [Amazon IVS 播放器 SDK：Web 參考](https://aws.github.io/amazon-ivs-player-docs/1.50.0/web/)。

## 設定服務工作者
<a name="web-service-worker"></a>

為了進一步降低透過僅支援原生播放的瀏覽器 (主要是 iOS Safari) 播放時的延遲，可以設定和配置服務工作者。如需詳細資訊，請參閱[在第三方播放器中降低延遲](player.md#player-reducing-latency)。

若要設定 Amazon IVS 播放器來使用服務工作者：

1. 建立檔案以從 CDN 減輕 IVS 服務工作者的負載。這是必需的，因為服務工作者必須在與提取它們的頁面相同的網域上託管。

   建立名為 `amazon-ivs-service-worker-loader.js` 或類似的檔案，並新增以下一行：

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

1. 建立播放器執行個體時，請傳入參照 `amazon-ivs-service-worker-loader.js` 檔案的下列 `serviceWorker` 組態：

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

1. 在影片元素上，將 `crossOrigin` 屬性設定為 `anonymous`。這是允許服務工作者對清單檔案進行變更的必要動作。

**注意**：要在本機測試服務工作者，該頁面需要透過 *localhost* 或 *https* 提供服務。

如需現場展示，請參閱下列儲存庫中的服務工作者範例：

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

## 純音訊播放
<a name="web-audio-only-playback"></a>

純音訊品質必須透過 `setQuality()` 方法手動選取。請注意，此播放器不支援第二個引數 `adaptive` 的 `true` 值，因此該引數依預設為 `false`。

若要在播放開始之前將品質設定為純音訊，請在 `READY` 事件內呼叫 `setQuality()`：

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

在 `READY` 內設定品質適用於自動播放和非自動播放模式。

## 最佳化背景播放
<a name="web-optimize-background-playback"></a>

從 SDK 版本 1.45.0 開始，用戶端可以設定為在背景索引標籤中播放時最佳化資料用量。啟用此功能時，播放器會在指定的持續時間之後選取最高的可用 SD 影片品質，最高為 480p。播放器一律會選取影片；不會選取 audio\$1only。這同時適用於手動模式和自動模式。當標籤出現在前景中時，玩家會自動切換回先前的設定。

若要啟用此功能：

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