# IVS 播放器 SDK：Video.js 整合
本文件說明 Amazon Interactive Video Service (IVS) Video.js 播放器中可用的最重要功能。
**最新版 Video.js 播放器整合：**1.50.0 ([版本備註](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/release-notes.html#mar19-26-player-web-ll))
## 開始使用
透過 Video.js [技術](https://videojs.com/guides/tech/)，實現 Amazon IVS 對 Video.js 的支援。我們透過指令碼標記以及透過 npm 模組提供支援。Amazon IVS 支援 Video.js 版本 7.6.6 和更新的版本 7.\$1 和 8\$1。
請注意，執行個體化播放器時，不支援 Video.js [來源選項](https://videojs.com/guides/options/#sources)。相反地，正常執行個體化播放器，並呼叫 Video.js `src()` 函數。如果啟用了自動播放，串流將會開始播放；否則，請使用 `play()` 開始播放。
### 示範
下列即時示範展示如何在內容交付網路中使用 Video.js 整合與指令碼標記：[Amazon IVS 播放器 Video.js 整合](https://codepen.io/amazon-ivs/pen/NWqewZo/bdc01e977102051eae5fb85482f88276)。
### 使用指令碼標記進行設定
若要使用 `script` 標記設定 Amazon IVS 技術：
1. 包含下列標記 (適用於最新版本的播放器整合)。
```
```
1. 使用 `registerIVSTech` 函數註冊技術：
```
registerIVSTech(videojs);
```
其中，`videojs` 是 Video.js 提供的物件。
1. 在建立播放器的執行個體時，新增 `AmazonIVS` 作為 `techOrder` 選項中的第一個技術。
執行個體化播放器時，不支援 Video.js [來源選項](https://videojs.com/guides/options/#sources)。相反地，應設定來源，正常執行個體化播放器，然後呼叫其中的 Video.js `src()` 函數。如果啟用了自動播放，串流將會開始播放；否則，請使用 `play()` 開始播放。
### 範例程式碼
在此範例中，`PLAYBACK_URL` 是您想要載入的來源串流。此範例使用最新版本的 Amazon IVS 播放器。
```
```
### 使用 NPM 進行設定
要透過 npm 使用 Amazon IVS 播放器：
1. 安裝 [video.js](https://www.npmjs.com/package/video.js/v/7.6.6) NPM 套件或確保您的專案擁有 Video.js 程式庫的其它存取權。
1. 安裝 `amazon-ivs-player` npm 套件：
```
npm install amazon-ivs-player
```
1. 當您準備好註冊 Amazon IVS 技術時，請匯入 `registerIVSTech` 函數：
```
import { registerIVSTech } from 'amazon-ivs-player';
```
1. 使用 `registerIVSTech` 函數註冊技術：
```
registerIVSTech(videojs, options);
```
其中：
+ `videojs` 是 Video.js 提供的物件。
+ `options` 是適用於 Amazon IVS 技術層的選項。支援的選項包括：
+ `wasmWorker`：託管 `amazon-ivs-wasmworker.min.js` 檔案的 URL。
+ `wasmBinary`：託管 `amazon-ivs-wasmworker.min.wasm` 檔案的 URL。
工作者檔案位於 `amazon-ivs-player/dist/` 下的 `node_modules/` 資料夾中。您需要託管他們，才能使用 IVS 播放器。
1. 在建立播放器的執行個體時，新增 `AmazonIVS` 作為 `techOrder` 選項中的第一個技術。
```
const player = videojs('videojs-player', {
techOrder: ["AmazonIVS"]
});
```
### TypeScript
如果您使用的是 TypeScript，我們的 npm 套件包括您可能想要匯入和使用的以下類型。
+ `VideoJSEvents`，它描述了從 傳回的結構。`getIVSEvents()`
+ `VideoJSIVSTech`，它描述了使用 `AmazonIVS` 技術的播放器執行個體的界面。這可以與 [@types/video.js](https://www.npmjs.com/package/@types/video.js) npm 套件公開的 `VideoJsPlayer` 類型[相交](https://www.typescriptlang.org/docs/handbook/advanced-types.html#intersection-types)。
+ `TechOptions`，它描述界面，定義您可以傳送至 的組態選項。`registerIVSTech()`
如需這些類型的詳細資訊，請參閱 [Amazon IVS 播放器 SDK：Web 參考](https://aws.github.io/amazon-ivs-player-docs/1.50.0/web/)。
## 活動
若要接聽標準 Video.js 事件，請使用 Video.js 播放器的 [on](https://docs.videojs.com/docs/api/player.html#Methodson) 函數。
若要接聽 Amazon IVS 特定事件，請在 Amazon IVS Web 播放器上新增和移除事件接聽程式：
```
player.getIVSPlayer().addEventListener(event, callback);
player.getIVSPlayer().removeEventListener(event, callback);
```
其中，`callback` 是您定義的回呼，`event` 是以下其中一個：`PlayerEventType` 或 `PlayerState`。如需事件的詳細資訊，請參閱 [Amazon IVS 播放器開發套件：Web 參考](https://aws.github.io/amazon-ivs-player-docs/1.50.0/web/)。
## 錯誤
對於一般的 Video.js 錯誤，請接聽播放器上的一般 `error` 事件：
```
player.on("error", callback);
```
對於 Amazon IVS 特定錯誤，請在 Amazon IVS 播放器上接聽其本身的錯誤：
```
let playerEvent = player.getIVSEvents().PlayerEventType;
player.getIVSPlayer().addEventListener(playerEvent.ERROR, callback);
```
此回呼將收到具有以下欄位的物件：
| 欄位 | 描述 |
| --- | --- |
| `type` | 錯誤類型。對應 `ErrorType` 事件。如需詳細資訊，請參閱 [Amazon IVS 播放器開發套件：Web 參考](https://aws.github.io/amazon-ivs-player-docs/1.50.0/web/)。 |
| `code` | 錯誤代碼。 |
| `source` | 錯誤來源。 |
| `message` | 人類可讀的錯誤訊息。 |
## 外掛程式
我們提供了一個外掛程式，它为可用品質建立一個 UI 切換。要使用此外掛程式，如果您正在透過下面的 `script` 標記使用我們的技術，則必須透過包含 `amazon-ivs-quality-plugin.min.js` 檔案來載入它 (適用於 IVS 播放器的最新版本)：
```
```
如果您使用 npm，請從 `amazon-ivs-player` 模組匯入 `registerIVSQualityPlugin`：
```
import { registerIVSQualityPlugin } from 'amazon-ivs-player';
```
然後，建立 Video.js 播放器的執行個體之後，就需要下列呼叫才能註冊並啟用它：
```
registerIVSQualityPlugin(videojs); // where videojs is the video.js variable
player.enableIVSQualityPlugin(); // where player is the instance of the videojs player
```
這將建立一個 UI 選單按鈕，允許您選擇串流品質。
### 外掛程式和 TypeScript
如果您使用的是 TypeScript，我們的 npm 套件包括您利用我們的外掛程式想要匯入和使用的 `VideoJSQualityPlugin` 類型。外掛程式本質上是 mixins，所以這種類型的界面作為[交集類型](https://www.typescriptlang.org/docs/handbook/advanced-types.html#intersection-types)與 `VideoJSIVSTech` TypeScript 界面搭配使用。
## 內容安全政策
Amazon IVS Video.js API 設定為可在使用內容安全政策 (CSP) 的頁面上運作。請參閱 [IVS 播放器 SDK：Web 指南](web-content-security-policy.md) 中的「使用內容安全政策」章節。
## 函數
### 播放
Amazon IVS Video.js API 支援 Video.js 架構內部使用所需的界面。用戶端應用程式不太可能需要直接使用這些方法，因為 Video.js 會執行必要的整合，並提供標準界面。但是，如果需要，存取內部 Video.js 和 Amazon IVS 播放器方法的一種方式是使用 Video.js 播放器物件，為該技術獲得所需的物件控點。
若要存取 API，請擷取 Video.js 播放器的執行個體，就像平常一樣：
```
let player = videojs("videoTagId"); //replace videoTagId with your