# IVS Web 回放器 SDK 入门
<a name="web-getting-started"></a>

本文档将引导您完成 Amazon IVS Web 回放器 SDK 入门所涉及的步骤。

我们通过 `script` 标签以及通过 npm 模块提供支持。

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

以下现场演示展示了如何将 Web 播放器与来自我们的“内容分发网络：[Amazon IVS 播放器示例](https://codepen.io/amazon-ivs/pen/QWbzORP/c3b13a2df34b60ada7756f3a2af8d2f0)”中的 `script` 标签一起使用。该演示包括设置事件侦听器。

另请参阅 [https://github.com/aws-samples/amazon-ivs-player-web-sample](https://github.com/aws-samples/amazon-ivs-player-web-sample)，了解更多精选的 Web 回放器演示。

## 使用脚本标签进行设置
<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` 替换为您要加载的源流。此示例使用最新版本的 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`) 的“内容类型”响应标头设为 "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
   }
});
```