本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 串流即時媒體 (SDKs)
<a name="webrtc-sdks"></a>

在 Amazon Kinesis Video Streams WebRTC 中，對等是設定為透過訊號頻道進行即時雙向串流的裝置。Amazon Kinesis Video Streams with WebRTC SDKs easy-to-use的軟體程式庫，您可以下載並安裝在您想要設定為指定訊號頻道之對等的裝置和應用程式用戶端上。

Amazon Kinesis Video Streams with WebRTC 包含下列SDKs：
+ [Amazon Kinesis Video Streams with WebRTC SDK in C for embedded device](kvswebrtc-sdk-c.md)
+ [適用於 Web 應用程式的 JavaScript 中的 Amazon Kinesis Video Streams with WebRTC SDK WebRTC](kvswebrtc-sdk-js.md)
+ [適用於 Android 的 Amazon Kinesis Video Streams WebRTC 開發套件](kvswebrtc-sdk-android.md)
+ [適用於 iOS 的 Amazon Kinesis Video Streams WebRTC 開發套件](kvswebrtc-sdk-ios.md)

每個 SDK 都包含對應的範例和逐步指示，可協助您建置和執行這些應用程式。您可以使用這些範例進行低延遲、即時、雙向的音訊和視訊串流，以及在 Web/Android/iOS 應用程式或嵌入式裝置的任何組合之間進行資料交換。換句話說，您可以將嵌入式攝影機裝置的即時音訊和視訊串流至 Android 或 Web 應用程式，或在兩個 Android 應用程式之間串流。

# Amazon Kinesis Video Streams with WebRTC SDK in C for embedded device
<a name="kvswebrtc-sdk-c"></a>

以下step-by-step說明說明如何下載、建置和執行適用於嵌入式裝置的 C 中的 Kinesis Video Streams with WebRTC SDK 及其對應的範例。

支援下列轉碼器：
+ **音訊： **
  + G.711 A-Law
  + G.711 U-Law
  + Opus
+ **影片：**
  + H.264
  + H.265
  + VP8

## 下載軟體開發套件
<a name="gs-download-sdk"></a>

若要下載適用於嵌入式裝置的 C 中的 Kinesis Video Streams with WebRTC SDK，請執行下列命令：

```
$ git clone https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c.git
```

## 建置 SDK
<a name="gs-build-sdk"></a>

**重要**  
在 macOS 上完成這些步驟之前，視您擁有的 macOS 版本而定，您必須執行 `xcode-select --install`以使用命令列工具和標頭下載套件。然後開啟 `/Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg` 並遵循安裝程式來安裝命令列工具和標頭。您只需要在叫用 之前執行一次。 `cmake`如果您已安裝命令列工具和標頭，則不需要再次執行此命令。

請完成下列步驟：

****

1. 安裝 CMake：
   + 在 macOS 上，執行 `brew install cmake pkg-config srtp` 
   + 在 Ubuntu 上，執行 `sudo apt-get install pkg-config cmake libcap2 libcap-dev`

1. 取得您要用於此示範之 AWS 帳戶 的存取金鑰和私密金鑰。

1. 執行以下命令，在您下載的 WebRTC C 開發套件中建立 `build` 目錄，然後從中執行 `cmake`：

   ```
   $ mkdir -p amazon-kinesis-video-streams-webrtc-sdk-c/build; cd amazon-kinesis-video-streams-webrtc-sdk-c/build; cmake ..
   ```

1. 現在您已位於您剛使用上述步驟建立的`build`目錄中，請執行 `make` 來建置 WebRTC C 開發套件及其提供的範例。
**注意**  
 如果系統尚未`gstreamer`安裝 ，則`kvsWebrtcClientMasterGstSample`不會建置 。若要確保其已建置 （在 macOS 上），您必須執行： `brew install gstreamer gst-plugins-base gst-plugins-good`

## 執行 SDK 範例
<a name="gs-run-c-sample"></a>

完成上述程序之後，最後在 `build` 目錄中會出現下列範例應用程式：
+ `kvsWebrtcClientMaster` - 此應用程式透過訊號頻道傳送範例 H264/Opus 影格 (路徑：/samples/h264SampleFrames 和 /samples/opusSampleFrames)。也會接受傳入的音訊 (如果在瀏覽器中啟用)。在瀏覽器中檢查時，將會在終端機列印收到的音訊封包的中繼資料。
+ `kvsWebrtcClientViewer` - 此應用程式接受並印列範例 H264/Opus 影格。
+ `kvsWebrtcClientMasterGstSample` - 此應用程式從 GStreamer 管道傳送範例 H264/Opus 影格。

若要執行任何這些範例，請完成下列步驟：

1. 使用 AWS 帳戶 登入資料設定您的環境：

   ```
   export AWS_ACCESS_KEY_ID=YourAccessKey
   export AWS_SECRET_ACCESS_KEY=YourSecretKey
   export AWS_DEFAULT_REGION=YourAWSRegion
   ```

   如果您使用的是暫時 AWS 登入資料，也請匯出工作階段字符：

   ```
   export AWS_SESSION_TOKEN=YourSessionToken
   ```

   如果您有自訂 CA 憑證路徑要設定，您可以使用下列方式設定：

   ```
   export AWS_KVS_CACERT_PATH=../certs/cert.pem
   ```
**注意**  
根據預設，SSL CA 憑證設定為 ../certs/cert.pem，指向 [GitHub](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c/blob/master/certs/cert.pem) 中此儲存庫中的 檔案。

1. 將您要給訊號頻道的名稱傳給其中一個範例應用程式，以執行應用程式。應用程式會使用您提供的名稱建立訊號頻道。例如，若要建立名為 `myChannel` 的訊號頻道，並開始透過此頻道傳送範例 H264/Opus 影格，請執行下列命令：

   ```
   ./kvsWebrtcClientMaster myChannel
   ```

   當命令列應用程式列印 `Connection established` 時，您可以繼續進行下一個步驟。

1. 現在，訊號頻道已建立，且連線的主節點正在將媒體串流至訊號頻道，您可以檢視此串流。例如，您可以在 Web 應用程式中檢視此即時串流。若要這樣做，請使用 中的步驟開啟 WebRTC SDK 測試頁面，[使用範例應用程式](kvswebrtc-sdk-js.md#build-sdk-js)並使用您為上述主伺服器指定的相同 AWS 登入資料和相同訊號通道來設定下列值：
   + 存取金鑰 ID
   + 私密存取金鑰
   + 訊號頻道名稱
   + 用戶端 ID (選擇性)

   選擇 **Start viewer (啟動檢視器)**，開始範例 H264/Opus 影格的即時視訊串流。

## 影片教學課程
<a name="sdk-c-video"></a>

此影片示範如何連接相機並開始使用 Amazon Kinesis Video Streams for WebRTC。




# 適用於 Web 應用程式的 JavaScript 中的 Amazon Kinesis Video Streams with WebRTC SDK WebRTC
<a name="kvswebrtc-sdk-js"></a>

您可以在適用於 Web 應用程式的 JavaScript 中找到 Kinesis Video Streams with WebRTC SDK，以及其在 [GitHub](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-js) 中的對應範例。 JavaScript 

**Topics**
+ [安裝軟體開發套件](#install-sdk-js)
+ [WebRTC JavaScript SDK 文件](#docs-sdk-js)
+ [使用範例應用程式](#build-sdk-js)
+ [編輯範例應用程式](#run-sdk-js)

## 安裝軟體開發套件
<a name="install-sdk-js"></a>

在 JavaScript 中使用 WebRTC 開發套件安裝 Kinesis Video Streams 是否及如何安裝取決於程式碼是否在`Node.js`模組或瀏覽器指令碼中執行。

------
#### [ NodeJS module ]

在適用於 Node.js 的 JavaScript 中使用 WebRTC 開發套件安裝 Kinesis Video Streams 的首選方法是使用 [Node.js 套件管理員 npm。](https://www.npmjs.com/)

套件託管於 https：//[https://www.npmjs.com/package/amazon-kinesis-video-streams-webrtc](https://www.npmjs.com/package/amazon-kinesis-video-streams-webrtc?activeTab=readme)。

若要在`Node.js`專案中安裝此開發套件，請使用終端機導覽至與您專案的 相同的目錄`package.json`：

輸入下列內容：

```
npm install amazon-kinesis-video-streams-webrtc
```

您可以匯入 SDK 類別，例如典型的 Node.js 模組：

```
// JavaScript
const SignalingClient = require('amazon-kinesis-video-streams-webrtc').SignalingClient;
// TypeScript
import { SignalingClient } from 'amazon-kinesis-video-streams-webrtc';
```

------
#### [ Browser ]

您無需另行安裝，也能在瀏覽器指令碼中使用軟體開發套件。您可以使用 HTML 頁面中的 AWS 指令碼，直接從 載入託管 SDK 套件。

若要在瀏覽器中使用 SDK，請將下列指令碼元素新增至 HTML 頁面：

```
<script src="https://unpkg.com/amazon-kinesis-video-streams-webrtc/dist/kvs-webrtc.min.js"></script>
```

當您將軟體開發套件載入至頁面後，便可從全域變數 `KVSWebRTC` (或 `window.KVSWebRTC`) 取得該軟體開發套件。

例如 `window.KVSWebRTC.SignalingClient`。

------

## WebRTC JavaScript SDK 文件
<a name="docs-sdk-js"></a>

SDK 方法的文件位於 GitHub 讀我[檔案](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-js?tab=readme-ov-file#documentation)下。

在[用量](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-js?tab=readme-ov-file#usage)區段中，還有其他資訊可整合此 SDK 與適用於 JavaScript 的 AWS SDK，以建置 Web 型檢視器應用程式。

如需完整應用程式的範例，包括主要和檢視器角色，請參閱 `examples`目錄。

## 使用範例應用程式
<a name="build-sdk-js"></a>

Kinesis Video Streams with WebRTC 也會託管範例應用程式，您可以使用該應用程式建立新的訊號頻道，或連接到現有的頻道，並將其用作主頻道或檢視器。

Kinesis Video Streams with WebRTC 範例應用程式位於 [GitHub](https://awslabs.github.io/amazon-kinesis-video-streams-webrtc-sdk-js/examples/index.html)。

範例應用程式的程式碼位於 `examples`目錄中。

**Topics**
+ [從範例應用程式將peer-to-peer串流至 AWS 管理主控台](#sdk-js-stream-console)
+ [從範例應用程式將peer-to-peer串流至範例應用程式](#sdk-js-stream-test)
+ [使用 WebRTC 擷取從範例頁面串流peer-to-peer範例頁面](#sdk-js-stream-ingestion)

### 從範例應用程式將peer-to-peer串流至 AWS 管理主控台
<a name="sdk-js-stream-console"></a>



1. 開啟 [Kinesis Video Streams with WebRTC 範例應用程式](https://awslabs.github.io/amazon-kinesis-video-streams-webrtc-sdk-js/examples/index.html)，並完成下列操作：
   + AWS 區域。 例如，`us-west-2`。
   + IAM 使用者或角色的 AWS 存取金鑰和私密金鑰。如果您使用長期 AWS 登入資料，請將工作階段字符保留空白。
   + 您要連線的訊號頻道的名稱。

     如果您想要連接到新的訊號頻道，請選擇**建立頻道**，以使用方塊中提供的值來建立訊號頻道。
**注意**  
目前帳戶和區域的訊號頻道名稱必須是唯一的。您可以使用字母、數字、底線 (\$1) 和連字號 (-)，但不能使用空格。
   + 是否要傳送音訊、視訊或兩者。
   + WebRTC 擷取和儲存。展開節點，然後選擇下列其中一項：
     + 選取**自動判斷擷取模式**。
     + 確定未選取**自動判斷擷取模式**，並將手動覆寫設定為 **OFF**。
**注意**  
**自動判斷擷取模式**可讓應用程式呼叫 [DescribeMediaStorageConfiguration](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_DescribeMediaStorageConfiguration.html) API，以決定要在哪個模式中執行 (Peer-to-peer或 WebRTC 擷取）。此額外的 API 呼叫會將少量新增至啟動時間。  
如果您事先知道此訊號頻道執行的模式，請使用手動覆寫略過此 API 呼叫。
   + 產生 ICE 候選項目。保持`STUN`/`TURN`選取並保持`Trickle ICE`啟用狀態。

1. 選擇 **Start Master** 以連接至訊號頻道。

   如有需要，允許存取您的攝影機和/或麥克風。

1. 在 中開啟 [Kinesis Video Streams 主控台](https://console.aws.amazon.com//kinesisvideo/home/) AWS 管理主控台。

   確定已選取正確的區域。

1. 在左側導覽中，選取**[訊號頻道](https://console.aws.amazon.com//kinesisvideo/home#/signalingChannels/)**。

   選取上述訊號頻道的名稱。如有需要，請使用搜尋列。

1. 展開**媒體播放檢視器**區段。

1. 選擇影片播放器上的**播放**按鈕。這會以 的形式加入 WebRTC 工作階段`viewer`。

   在示範頁面上傳送的媒體應該會顯示在 中 AWS 管理主控台。

### 從範例應用程式將peer-to-peer串流至範例應用程式
<a name="sdk-js-stream-test"></a>

1. 開啟 [Kinesis Video Streams with WebRTC 範例應用程式](https://awslabs.github.io/amazon-kinesis-video-streams-webrtc-sdk-js/examples/index.html)，並完成下列資訊：
   + AWS 區域。 例如，`us-west-2`。
   + IAM 使用者或角色的 AWS 存取金鑰和私密金鑰。如果您使用長期 AWS 登入資料，請將工作階段字符保留空白。
   + 您要連線的訊號頻道的名稱。

     如果您想要連接到新的訊號頻道，請選擇**建立頻道**，以使用方塊中提供的值來建立訊號頻道。
**注意**  
目前帳戶和區域的訊號頻道名稱必須是唯一的。您可以使用字母、數字、底線 (\$1) 和連字號 (-)，但不能使用空格。
   + 是否要傳送音訊、視訊或兩者。
   + WebRTC 擷取和儲存。展開節點，然後選擇下列其中一項：
     + 選取**自動判斷擷取模式**。
     + 確定未選取**自動判斷擷取模式**，並將手動覆寫設定為 **OFF**。
**注意**  
**自動判斷擷取模式**可讓應用程式呼叫 [DescribeMediaStorageConfiguration](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_DescribeMediaStorageConfiguration.html) API，以決定要在哪個模式中執行 (Peer-to-peer或 WebRTC 擷取）。此額外的 API 呼叫會將少量新增至啟動時間。  
如果您事先知道此訊號頻道執行的模式，請使用手動覆寫略過此 API 呼叫。
   + 產生 ICE 候選項目。保持`STUN`/`TURN`選取並保持`Trickle ICE`啟用狀態。

1. 選擇 **Start Master** 以做為`master`角色連線至訊號頻道。

   如有需要，允許存取您的攝影機和/或麥克風。

1. 開啟另一個瀏覽器索引標籤，並開啟 [Kinesis Video Streams with WebRTC 範例應用程式](https://awslabs.github.io/amazon-kinesis-video-streams-webrtc-sdk-js/examples/index.html)。應載入先前執行的所有資訊。

1. 向下捲動並選擇**啟動檢視器**，以做為`viewer`角色連線至訊號頻道。

   您應該會看到在 `master`和 之間交換的媒體`viewer`。

### 使用 WebRTC 擷取從範例頁面串流peer-to-peer範例頁面
<a name="sdk-js-stream-ingestion"></a>

1. 遵循 [從瀏覽器擷取媒體](ingest-media.md#ingest-browser) 來連接主要參與者，並確認其已連線至儲存工作階段。

1. 遵循 [將檢視器新增至擷取工作階段](ingest-media.md#ingest-add-viewers) 新增瀏覽者參與者。

   檢視器參與者將連線至儲存工作階段並從中接收媒體。他們可以將選用的音訊傳回儲存工作階段。

   儲存工作階段會處理混合從主要和檢視器參與者收到的媒體，並將其傳送至適當的目的地。

1. 您可以透過 [Kinesis Video Streams 播放](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/how-playback.html)來檢視和使用擷取的媒體。

## 編輯範例應用程式
<a name="run-sdk-js"></a>

若要編輯 SDK 和範例應用程式以進行開發，請遵循下列指示。

**必要條件**

NodeJS 16\$1 版

**注意**  
我們建議您從 [https://nodejs.org/en/download](https://nodejs.org/en/download)：// 下載最新的長期支援 (LTS) 版本。

**編輯範例應用程式**

1. 在 JavaScript 中下載 Kinesis Video Streams with WebRTC SDK。

   在終端機中輸入下列項目：

   ```
   git clone https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-js.git
   ```

1. 使用 package.json 檔案導覽至 目錄。檔案位於儲存庫的根目錄中。

   在終端機中輸入下列項目：

   ```
   cd amazon-kinesis-video-streams-webrtc-sdk-js
   ```

1. 安裝依存項目。

   在終端機中輸入下列 [npm CLI](https://docs.npmjs.com/cli/v10/commands) 命令：

   ```
   npm install
   ```

1. 啟動 Web 伺服器以開始提供網頁。

   在終端機中輸入下列 [npm CLI](https://docs.npmjs.com/cli/v10/commands) 命令：

   ```
   npm run develop
   ```

1. 在您的瀏覽器中，請造訪 [http：//localhost：3001/](http://localhost:3001/)。

   您可以編輯 `examples`目錄中的檔案來編輯網頁。

# 適用於 Android 的 Amazon Kinesis Video Streams WebRTC 開發套件
<a name="kvswebrtc-sdk-android"></a>

下列逐步指示說明如何下載、建置和執行適用於 Android 的 Kinesis Video Streams with WebRTC 開發套件及其對應的範例。

**注意**  
Amazon Kinesis Video Streams 不支援 Android 上的 IPv6 地址。請參閱有關[在 Android 裝置上停用 IPv6 ](https://www.cactusvpn.com/tutorials/how-to-disable-ipv6-on-android/)的詳細資訊。

## 下載軟體開發套件
<a name="download-sdk-android"></a>

若要在 Android 中下載 WebRTC 開發套件，請執行下列命令：

```
$ git clone https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-android.git
```

## 建置 SDK
<a name="build-sdk-android"></a>

若要在 Android 中建置 WebRTC 開發套件，請完成以下步驟：

1. `amazon-kinesis-video-streams-webrtc-sdk-android/build.gradle` 使用 **Open as Project** 開啟，將 Android WebRTC SDK 匯入 Android Studio 整合開發環境 (IDE)。

1. 如果是第一次開啟專案，專案會自動同步。如果不是，請啟動同步。當您看到組建錯誤時，請選擇 **Install missing SDK package(s) (安裝缺少的 SDK 套件)**，然後選擇 **Accept (接受)** 並完成安裝，以安裝任何必要的 SDK 套件。

1. 進行 Amazon Cognito (使用者集區和身分集區) 設定。如需詳細步驟，請參閱[為 SDK 設定 Amazon Cognito](#build-sdk-android-cognito)。這將產生建置 Android WebRTC 開發套件所需的身分驗證和授權設定。

1. 在您的 Android IDE 中，開啟 `awsconfiguration.json` (從 `src/main/res/raw/`)。檔案看起來如下：

   ```
   {
     "Version": "1.0",
     "CredentialsProvider": {
       "CognitoIdentity": {
         "Default": {
           "PoolId": "REPLACE_ME",
           "Region": "REPLACE_ME"
         }
       }
     },
     "IdentityManager": {
       "Default": {}
     },
     "CognitoUserPool": {
       "Default": {
         "AppClientSecret": "REPLACE_ME",
         "AppClientId": "REPLACE_ME",
         "PoolId": "REPLACE_ME",
         "Region": "REPLACE_ME"
       }
     }
   }
   ```

   以執行 [為 SDK 設定 Amazon Cognito](#build-sdk-android-cognito)中的步驟所產生的值，更新 `awsconfiguration.json`。

1. 確保您的 Android 裝置已連線至執行 Android IDE 的電腦。在 Android IDE 中，選取連接的裝置，然後建置並執行 WebRTC Android 開發套件。

   此步驟會在您的 Android 裝置上安裝名為 `AWSKinesisVideoWebRTCDemoApp` 的應用程式。您可以使用此應用程式，驗證行動、Web 和 IoT 裝置用戶端之間的即時 WebRTC 音訊/視訊串流。

## 執行範例應用程式
<a name="run-sdk-android"></a>

****

請完成下列步驟：

1. 在您的 Android 裝置上，開啟 **AWSKinesisVideoWebRTCDemoApp**，並使用新的 (先建立) 或現有的 Amazon Cognito 帳戶登入。

1. 在 **AWSKinesisVideoWebRTCDemoApp** 中，瀏覽至 **Channel Configuration (頻道組態)** 頁面，然後建立新的訊號頻道，或選擇現有的訊號頻道。
**注意**  
目前，使用此開發套件中的範例應用程式時，您在 **AWSKinesisVideoWebRTCDemoApp** 中只能執行一個訊號頻道。

1. 選擇性：如果您要以檢視器身分連線到此頻道，請選擇唯一的 **Client Id (用戶端 ID)**。只有在多個檢視器連線至頻道時，才需要用戶端 ID。這有助於頻道的主節點識別各自的檢視器。

1. 選擇 AWS 區域 ，以及您要傳送音訊或視訊資料，還是兩者。

1. 若要驗證點對點串流，請執行下列任何一項：
**注意**  
請務必在此示範中使用的所有用戶端上，指定相同的訊號頻道名稱、 AWS 區域、檢視器 ID 和 AWS 帳戶 ID。
   + 兩個 Android 裝置之間的點對點串流：主節點和檢視器
     + 在兩個 Android 裝置上，使用上述程序下載、建置和執行 Android WebRTC 開發套件。
     + 在一個 Android 裝置上，以主節點模式開啟 **AWSKinesisVideoWebRTCDemoApp**，選擇 **START MASTER (啟動主節點)**，啟動新的工作階段 (訊號頻道)。
**注意**  
目前，任何給定的訊號頻道只能有一個主節點。
     + 在您的第二個 Android 裝置上，以檢視器模式開啟 **AWSKinesisVideoWebRTCDemoApp**，以連線至上述步驟中啟動的訊號頻道 (工作階段)，選擇 **START VIEWER (啟動檢視器)**。

       確認檢視器可以看到主節點的音訊/視訊資料。
   + 嵌入式開發套件主節點和 Android 裝置檢視器之間的點對點串流
     + 在攝影機裝置上，以主節點模式下載、建置和執行 [Amazon Kinesis Video Streams with WebRTC SDK in C for embedded device](kvswebrtc-sdk-c.md)。
     + 在 Android 裝置上，使用上述程序下載、建置和執行 Android WebRTC 開發套件。在此 Android 裝置上，以檢視器模式開啟 **AWSKinesisVideoWebRTCDemoApp**，並確認檢視器可以看到嵌入式 SDK 主節點的音訊/視訊資料。
   + Android 裝置 (主節點) 和 Web 瀏覽器 (檢視器) 之間的點對點串流
     + 在 Android 裝置上，使用上述程序下載、建置和執行 Android WebRTC 開發套件。在此 Android 裝置上，以主節點模式開啟 **AWSKinesisVideoWebRTCDemoApp**，選擇 **START MASTER (啟動主節點)**，啟動新的工作階段 (訊號頻道)。
     + 以檢視器身分下載、建置和執行 [適用於 Web 應用程式的 JavaScript 中的 Amazon Kinesis Video Streams with WebRTC SDK WebRTC](kvswebrtc-sdk-js.md)，並確認檢視器可以看到 Android 主節點的音訊/視訊。

## 為 SDK 設定 Amazon Cognito
<a name="build-sdk-android-cognito"></a>

### 先決條件
<a name="androidsdk-prerequisites"></a>
+ 建議使用 [Android Studio](https://developer.android.com/studio/index.html) 檢查、編輯和執行應用程式的程式碼。建議使用最新的穩定版本。
+ 在範本程式碼中，您會提供 Amazon Cognito 登入資料。

請依照這些程序來設定 Amazon Cognito 使用者集區和身分集區。

### 設定使用者集區
<a name="setup-user-pool"></a>

**設定使用者集區**

1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)並確認區域正確無誤。

1. 在左側導覽中，選擇**使用者集區**。

1. 在**使用者集**區區段中，選擇**建立使用者集區**。

1. 完成下列各節：

   1. **步驟 1：設定登入體驗** - 在 **Cognito 使用者集區登入選項**區段中，選取適當的選項。

      選取**下一步**。

   1. **步驟 2：設定安全需求** - 選取適當的選項。

      選取**下一步**。

   1. **步驟 3：設定註冊體驗** - 選取適當的選項。

      選取**下一步**。

   1. **步驟 4：設定訊息傳遞** - 選取適當的選項。

      在 **IAM 角色選取**欄位中，選取現有角色或建立新角色。

      選取**下一步**。

   1. **步驟 5：整合您的應用程式** - 選取適當的選項。

      在**初始應用程式用戶端**欄位中，選擇**機密用戶端**。

      選取**下一步**。

   1. **步驟 6：檢閱並建立** - 檢閱先前區段的選擇，然後選擇**建立使用者集區**。

1. 在**使用者集**區頁面上，選取您剛建立的集區。

   複製**使用者集區 ID**，並記下此 ID 以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CognitoUserPool.Default.PoolId`。

1. 選取**應用程式整合**索引標籤，然後移至頁面底部。

1. 在**應用程式用戶端清單**區段中，選擇您剛建立**的應用程式用戶端名稱**。

   複製**用戶端 ID** 並記下此 ID 以供稍後使用。在 `awsconfiguration.json` 檔案中，這是 `CognitoUserPool.Default.AppClientId`。

1. 顯示**用戶端秘密**，並記下此秘密以供稍後使用。在 `awsconfiguration.json` 檔案中，這是 `CognitoUserPool.Default.AppClientSecret`。

### 設定身分集區
<a name="setup-identity-pool"></a>

**設定身分集區**

1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)並確認區域正確無誤。

1. 在左側導覽中，選擇**身分集區**。

1. 選擇 **建立身分池**。

1. 設定身分集區。

   1. **步驟 1：設定身分集區信任** - 完成下列區段：
      + **使用者存取** - 選取**已驗證的存取**
      + **已驗證的身分來源** - 選取 **Amazon Cognito 使用者集區**

      選取**下一步**。

   1. **步驟 2：設定許可** - 在**已驗證角色**區段中，完成下列欄位：
      + **IAM 角色** - 選取**建立新的 IAM 角色**
      + **IAM 角色名稱** - 輸入名稱並將其記下以供後續步驟使用。

      選取**下一步**。

   1. **步驟 3：連接身分提供者** - 在**使用者集區詳細資訊**區段中，完成下列欄位：
      + **使用者集區 ID** - 選取您先前建立的使用者集區。
      + **應用程式用戶端 ID** - 選取您先前建立的應用程式用戶端 ID。

      選取**下一步**。

   1. **步驟 4：設定屬性** - 在**身分集區名稱欄位中輸入名稱**。

      選取**下一步**。

   1. **步驟 5：檢閱並建立** - 檢閱每個區段中的選擇，然後選取**建立身分集區**。

1. 在**身分集**區頁面上，選取新的身分集區。

   複製**身分集區 ID** 並記下此 ID 以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CredentialsProvider.CognitoIdentity.Default.PoolId`。

1. 更新 IAM 角色的許可。

   1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。

   1. 在左側導覽中，選擇**角色**。

   1. 尋找並選取您在上面建立的角色。
**注意**  
如有需要，請使用搜尋列。

   1. 選取連接的許可政策。

      選擇 **Edit** (編輯)。

   1. 選取 **JSON** 索引標籤，並以下列內容取代政策：

      ```
      {
          "Version": "2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "cognito-identity:*",
                      "kinesisvideo:*"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }
      ```

      選取**下一步**。

   1. 如果尚未選取，請選取**此新版本設定為預設值**旁的方塊。

      選取**儲存變更**。

# 適用於 iOS 的 Amazon Kinesis Video Streams WebRTC 開發套件
<a name="kvswebrtc-sdk-ios"></a>

下列逐步指示說明如何在 iOS 中下載、建置和執行 Kinesis Video Streams WebRTC 開發套件及其對應的範例。

## 下載軟體開發套件
<a name="download-sdk-js"></a>

若要在 iOS 中下載 WebRTC 開發套件，請執行下列命令：

```
$ git clone https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-ios.git
```

## 建置 SDK
<a name="build-sdk-ios"></a>

請完成下列步驟：

1. 在 iOS 電腦上，開啟 `KinesisVideoWebRTCDemoApp.xcworkspace` (路徑：amazon-kinesis-video-streams-webrtc-sdk-ios/Swift/AWSKinesisVideoWebRTCDemoApp.xcworkspace)，將 iOS WebRTC 開發套件匯入 XCode 整合開發環境 (IDE)。

1. 如果是第一次開啟專案，專案會自動建置。如果不是，請啟動建置。

   您可能會看到下列錯誤：

   ```
   error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' or update your CocoaPods installation.
   ```

   如果您看到此錯誤，請執行下列動作：

   1. 從目前的工作目錄切換至 `amazon-kinesis-video-streams-webrtc-sdk-ios/Swift`，並在命令列中執行以下命令：

      ```
      pod cache clean --all
      pod install
      ```

   1. 從目前的工作目錄切換至 `amazon-kinesis-video-streams-webrtc-sdk-ios`，並在命令列中執行以下命令：

      ```
      $ git checkout Swift/Pods/AWSCore/AWSCore/Service/AWSService.m
      ```

   1. `Build`。

1. 進行 Amazon Cognito (使用者集區和身分集區) 設定。如需詳細步驟，請參閱[為 SDK 設定 Amazon Cognito](#build-sdk-ios-cognito)。這將產生建置 iOS WebRTC 開發套件所需的身分驗證和授權設定。

1. 在 IDE 中，開啟 `awsconfiguration.json` 檔案 (從 `/Swift/KVSiOSApp`)。檔案看起來如下：

   ```
   {
       "Version": "1.0",
       "CredentialsProvider": {
           "CognitoIdentity": {
               "Default": {
                   "PoolId": "REPLACEME",
                   "Region": "REPLACEME"
               }
           }
       },
       "IdentityManager": {
           "Default": {}
       },
       "CognitoUserPool": {
           "Default": {
               "AppClientSecret": "REPLACEME",
               "AppClientId": "REPLACEME",
               "PoolId": "REPLACEME",
               "Region": "REPLACEME"
           }
       }
   }
   ```

   以執行 [為 SDK 設定 Amazon Cognito](kvswebrtc-sdk-android.md#build-sdk-android-cognito)中的步驟所產生的值，更新 `awsconfiguration.json`。

1. 在 IDE 中，開啟 `Constants.swift` 檔案 (從 `/Swift/KVSiOSApp`)。檔案看起來如下：

   ```
   import Foundation
   import AWSCognitoIdentityProvider
   
   let CognitoIdentityUserPoolRegion = AWSRegionType.USWest2
   let CognitoIdentityUserPoolId = "REPLACEME"
   let CognitoIdentityUserPoolAppClientId = "REPLACEME"
   let CognitoIdentityUserPoolAppClientSecret = "REPLACEME"
   
   let AWSCognitoUserPoolsSignInProviderKey = "UserPool"
   let CognitoIdentityPoolID = "REPLACEME"
   
   let AWSKinesisVideoEndpoint = "https://kinesisvideo.us-west-2.amazonaws.com"
   let AWSKinesisVideoKey = "kinesisvideo"
   
   let VideoProtocols =  ["WSS", "HTTPS"]
   
   let ConnectAsMaster = "connect-as-master"
   let ConnectAsViewer = "connect-as-viewer"
   
   let MasterRole = "MASTER"
   let ViewerRole = "VIEWER"
   
   let ClientID = "ConsumerViewer"
   ```

   以執行 [為 SDK 設定 Amazon Cognito](kvswebrtc-sdk-android.md#build-sdk-android-cognito)中的步驟所產生的值，更新 `Constants.swift`。

1. 確保您的 iOS 裝置已連線至執行 XCode 的 Mac 電腦。在 XCode 中，選取連接的裝置，然後建置並執行 WebRTC iOS 開發套件。

   此步驟會在您的 iOS 裝置上安裝名為 `AWSKinesisVideoWebRTCDemoApp` 的應用程式。您可以使用此應用程式，驗證行動、Web 和 IoT 裝置用戶端之間的即時 WebRTC 音訊/視訊串流。

## 執行範例應用程式
<a name="run-sdk-ios"></a>

****

請完成下列步驟：

1. 在您的 iOS 裝置上，開啟 **AWSKinesisVideoWebRTCDemoApp**，並使用新的 (先建立) 或現有的 Amazon Cognito 帳戶登入。

1. 在 **AWSKinesisVideoWebRTCDemoApp** 中，瀏覽至 **Channel Configuration (頻道組態)** 頁面，然後建立新的訊號頻道，或選擇現有的訊號頻道。
**注意**  
目前，使用此開發套件中的範例應用程式時，您在 **AWSKinesisVideoWebRTCDemoApp** 中只能執行一個訊號頻道。

1. (選擇性) 如果您要以檢視器身分連線到此頻道，請選擇唯一的 **Client Id (用戶端 ID)**。只有在多個檢視器連線至頻道時，才需要用戶端 ID。這有助於頻道的主節點識別各自的檢視器。

1. 選擇 AWS 區域 ，以及您要傳送音訊或視訊資料，還是兩者。

1. 若要驗證點對點串流，請執行下列任何一項：
**注意**  
請務必在此示範中使用的所有用戶端上，指定相同的訊號頻道名稱、 AWS 區域、檢視器 ID 和 AWS 帳戶 ID。
   + 兩個 iOS 裝置之間的點對點串流：主節點和檢視器
     + 在兩個 iOS 裝置上，使用上述程序下載、建置和執行 iOS WebRTC 開發套件。
     + 在一個 iOS 裝置上，以主節點模式開啟 **AWSKinesisVideoWebRTCDemoApp**，選擇 **START MASTER (啟動主節點)**，啟動新的工作階段 (訊號頻道)。
**注意**  
目前，任何給定的訊號頻道只能有一個主節點。
     + 在您的第二個 iOS 裝置上，以檢視器模式開啟 **AWSKinesisVideoWebRTCDemoApp**，以連線至上述步驟中啟動的訊號頻道 (工作階段)，選擇 **START VIEWER (啟動檢視器)**。

       確認檢視器可以看到主節點的音訊/視訊資料。
   + 嵌入式開發套件主節點和 iOS 裝置檢視器之間的點對點串流
     + 在攝影機裝置上，以主節點模式下載、建置和執行 [Amazon Kinesis Video Streams with WebRTC SDK in C for embedded device](kvswebrtc-sdk-c.md)。
     + 在 iOS 裝置上，使用上述程序下載、建置和執行 iOS WebRTC 開發套件。在此 iOS 裝置上，以檢視器模式開啟 **AWSKinesisVideoWebRTCDemoApp**，並確認 iOS 檢視器可以看到嵌入式 SDK 主節點的音訊/視訊資料。
   + iOS 裝置 (主節點) 和 Web 瀏覽器 (檢視器) 之間的點對點串流
     + 在 iOS 裝置上，使用上述程序下載、建置和執行 iOS WebRTC 開發套件。在此 iOS 裝置上，以主節點模式開啟 **AWSKinesisVideoWebRTCDemoApp**，選擇 **START MASTER (啟動主節點)**，啟動新的工作階段 (訊號頻道)。
     + 以檢視器身分下載、建置和執行 [適用於 Web 應用程式的 JavaScript 中的 Amazon Kinesis Video Streams with WebRTC SDK WebRTC](kvswebrtc-sdk-js.md)，並確認 JavaScript 檢視器可以看到 Android 主節點的音訊/視訊。

## 為 SDK 設定 Amazon Cognito
<a name="build-sdk-ios-cognito"></a>

### 先決條件
<a name="iossdk-prerequisites"></a>
+ 我們建議您使用 XCode 來檢查、編輯和執行應用程式碼。我們建議使用最新版本。
+ 在範本程式碼中，您會提供 Amazon Cognito 登入資料。

請依照這些程序來設定 Amazon Cognito 使用者集區和身分集區。

### 設定使用者集區
<a name="setup-user-pool"></a>

**設定使用者集區**

1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)並確認區域正確無誤。

1. 在左側導覽中，選擇**使用者集區**。

1. 在**使用者集**區區段中，選擇**建立使用者集區**。

1. 完成下列各節：

   1. **步驟 1：設定登入體驗** - 在 **Cognito 使用者集區登入選項**區段中，選取適當的選項。

      選取**下一步**。

   1. **步驟 2：設定安全需求** - 選取適當的選項。

      選取**下一步**。

   1. **步驟 3：設定註冊體驗** - 選取適當的選項。

      選取**下一步**。

   1. **步驟 4：設定訊息傳遞** - 選取適當的選項。

      在 **IAM 角色選取**欄位中，選取現有角色或建立新角色。

      選取**下一步**。

   1. **步驟 5：整合您的應用程式** - 選取適當的選項。

      在**初始應用程式用戶端**欄位中，選擇**機密用戶端**。

      選取**下一步**。

   1. **步驟 6：檢閱並建立** - 檢閱先前區段的選擇，然後選擇**建立使用者集區**。

1. 在**使用者集**區頁面上，選取您剛建立的集區。

   複製**使用者集區 ID**，並記下此 ID 以供稍後使用。在 `awsconfiguration.json` 檔案中，這是 `CognitoUserPool.Default.PoolId`。

1. 選取**應用程式整合**索引標籤，然後移至頁面底部。

1. 在**應用程式用戶端清單**區段中，選擇您剛建立**的應用程式用戶端名稱**。

   複製**用戶端 ID** 並記下此 ID 以供稍後使用。在 `awsconfiguration.json` 檔案中，這是 `CognitoUserPool.Default.AppClientId`。

1. 顯示**用戶端秘密**，並記下此秘密以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CognitoUserPool.Default.AppClientSecret`。

### 設定身分集區
<a name="setup-identity-pool"></a>

**設定身分集區**

1. 登入 [Amazon Cognito 主控台](https://console.aws.amazon.com/cognito/home)並確認區域正確無誤。

1. 在左側導覽中，選擇**身分集區**。

1. 選擇 **建立身分池**。

1. 設定身分集區。

   1. **步驟 1：設定身分集區信任** - 完成下列區段：
      + **使用者存取** - 選取**已驗證的存取**
      + **已驗證的身分來源** - 選取 **Amazon Cognito 使用者集區**

      選取**下一步**。

   1. **步驟 2：設定許可** - 在**已驗證角色**區段中，完成下列欄位：
      + **IAM 角色** - 選取**建立新的 IAM 角色**
      + **IAM 角色名稱** - 輸入名稱並將其記下以供後續步驟使用。

      選取**下一步**。

   1. **步驟 3：連接身分提供者** - 在**使用者集區詳細資訊**區段中，完成下列欄位：
      + **使用者集區 ID** - 選取您先前建立的使用者集區。
      + **應用程式用戶端 ID** - 選取您先前建立的應用程式用戶端 ID。

      選取**下一步**。

   1. **步驟 4：設定屬性** - 在**身分集區名稱欄位中輸入名稱**。

      選取**下一步**。

   1. **步驟 5：檢閱並建立** - 檢閱每個區段中的選擇，然後選取**建立身分集區**。

1. 在**身分集**區頁面上，選取新的身分集區。

   複製**身分集區 ID**，並記下此 ID 以供稍後使用。在 `awsconfiguration.json`檔案中，這是 `CredentialsProvider.CognitoIdentity.Default.PoolId`。

1. 更新 IAM 角色的許可。

   1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。

   1. 在左側導覽中，選擇**角色**。

   1. 尋找並選取您在上面建立的角色。
**注意**  
如有需要，請使用搜尋列。

   1. 選取連接的許可政策。

      選擇 **Edit** (編輯)。

   1. 選取 **JSON** 索引標籤，並以下列內容取代政策：

      ```
      {
          "Version": "2012-10-17",		 	 	 
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "cognito-identity:*",
                      "kinesisvideo:*"
                  ],
                  "Resource": [
                      "*"
                  ]
              }
          ]
      }
      ```

      選取**下一步**。

   1. 如果尚未選取，請選取**此新版本設定為預設值**旁的方塊。

      選取**儲存變更**。

# C SDK 的用戶端指標
<a name="kvswebrtc-reference"></a>

使用 Amazon Kinesis Video Streams with WebRTC 建置的應用程式由各種移動組件組成，包括聯網、訊號、候選者交換、對等連線和資料交換。C 中的 Kinesis Video Streams with WebRTC 支援各種用戶端指標，可讓您監控和追蹤應用程式中這些元件的效能和用量。支援的指標分為兩個主要類別：專門為 Kinesis Video Streams 的訊號和聯網實作定義的自訂指標，以及衍生自 [W3C](https://www.w3.org/TR/webrtc-stats/) 標準的媒體和資料相關通訊協定特定指標。請注意，目前 C 中的 Kinesis Video Streams with WebRTC 僅支援一部分的 W3C 標準指標。 WebRTC 

**Topics**
+ [訊號指標](#kvswebrtc-reference-signaling)
+ [C SDK 支援的 W3C 標準指標](#kvswebrtc-reference-w3cstandard)

## 訊號指標
<a name="kvswebrtc-reference-signaling"></a>

訊號指標可用來了解訊號用戶端在應用程式執行時的行為。您可以使用 `STATUS signalingClientGetMetrics (SIGNALING_CLIENT_HANDLE, PSignalingClientMetrics)` API 來取得這些訊號指標。以下是使用模式範例：

```
SIGNALING_CLIENT_HANDLE signalingClientHandle;
SignalingClientMetrics signalingClientMetrics;
STATUS retStatus = signalingClientGetMetrics(signalingClientHandle, &signalingClientMetrics);
printf("Signaling client connection duration: %" PRIu64 " ms",
       (signalingClientMetrics.signalingClientStats.connectionDuration / HUNDREDS_OF_NANOS_IN_A_MILLISECOND));
```

您可以在 [Stats.h](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c/blob/master/src/include/com/amazonaws/kinesis/video/webrtcclient/Stats.h) `signalingClientStats`中找到 的定義。

目前支援下列訊號指標：


****  

| 指標 | Description | 
| --- | --- | 
| cpApiCallLatency | 計算控制平面 API 呼叫的延遲。使用指數移動平均 (EMA) 完成計算。相關聯的呼叫包括： describeChannel、createChannel、getChannelEndpoint 和 deleteChannel。 | 
| dpApiCallLatency | 計算資料平面 API 呼叫的延遲。使用指數移動平均 (EMA) 完成計算。相關聯的呼叫包括：getIceConfig。 | 
| signalingClientUptime | 這表示用戶端物件存在的時間。每次叫用此指標時，都會發出最新的執行時間值。 | 
| connectionDuration | 如果建立連線，這會發出連線存活的持續時間。否則，會發出 0 的值。這與發出用戶端正常運作時間不同，因為連線會不斷出現，但 signalingClientUptime 表示用戶端物件本身。 | 
| numberOfMessagesSent | 此值會在對等傳送優惠、回答或 ICE 候選項目時更新。 | 
| numberOfMessagesReceived | 與 numberOfMessagesSent 不同，此指標會針對任何類型的訊號訊息進行更新。訊號訊息的類型可在 中使用SIGNALING\$1MESSAGE\$1TYPE。 | 
| iceRefreshCount | 這會在叫用 getIceConfig 時遞增。調用此 的速率是以 TTL 為基礎，做為所收到 ICE 組態的一部分。每次收到一組新的 ICE 組態時，都會將計時器設定為下次重新整理，因為組態中的登入資料有效性減去一些寬限期。 | 
| numberOfErrors | 計數器用於追蹤訊號用戶端內產生的錯誤數目。取得 ICE 組態、取得訊號狀態、追蹤訊號指標、傳送訊號訊息，以及將訊號用戶端連線至 Web 通訊端以追蹤傳送/接收訊息時所產生的錯誤。 | 
| numberOfRuntimeErrors | 指標包含訊號用戶端核心執行時所發生的錯誤。這裡會追蹤重新連線失敗、訊息接收失敗和 ICE 組態重新整理錯誤等案例。 | 
| numberOfReconnects | 指標會在每次重新連線時遞增。這是了解 設定中網路連線穩定性的實用指標。 | 

## C SDK 支援的 W3C 標準指標
<a name="kvswebrtc-reference-w3cstandard"></a>

使用 [W3C](https://www.w3.org/TR/webrtc-stats/)WebRTC 標準指標的子集。這些分為下列類別：
+ 網路：
  + [Ice Candidate](https://www.w3.org/TR/webrtc-stats/#icecandidate-dict*)：這些指標提供有關所選本機和遠端候選項目的資訊，以便在對等之間進行資料交換。這包括候選伺服器的伺服器來源、IP 地址、為通訊選取的候選類型，以及候選優先順序。這些指標可作為快照報告。
  + [Ice 伺服器](https://www.w3.org/TR/webrtc-stats/#ice-server-dict*)：這些指標用於收集支援的不同 ICE 伺服器的操作資訊。這在嘗試了解主要用於通訊和連線檢查的伺服器時非常有用。在某些情況下，如果收集候選項目失敗，檢查這些指標也很有用。
  + [Ice Candidate Pair](https://www.w3.org/TR/webrtc-stats/#candidatepair-dict*)：這些指標用於了解在對等和時間相關測量之間交換的位元組/封包數量。
+ 媒體和資料：
  + [遠端傳入 RTP](https://www.w3.org/TR/webrtc-stats/#remoteinboundrtpstats-dict*)：這些指標代表寄件者傳送之資料串流的端點觀點。
  + [傳出 RTP](https://www.w3.org/TR/webrtc-stats/#dom-rtcoutboundrtpstreamstats)：這些指標提供傳出 RTP 串流的相關資訊。在分析冗長的串流或串流停止時，它們也非常有用。
  + [傳入 RTP](https://www.w3.org/TR/webrtc-stats/#dom-rtcinboundrtpstreamstats)：這些指標提供傳入媒體的相關資訊。
  + [資料管道指標](https://www.w3.org/TR/webrtc-stats/#dcstats-dict*)：這些指標可協助您分析透過資料管道傳送和接收的訊息和位元組數。您可以使用頻道 ID 提取指標。

您可以使用 `STATUS rtcPeerConnectionGetMetrics (PRtcPeerConnection, PRtcRtpTransceiver, PRtcStats)` API 來收集與 ICE、RTP 和資料通道相關的指標。以下是使用範例：

```
RtcStats rtcStats;
rtcStats.requestedTypeOfStats = RTC_STATS_TYPE_LOCAL_CANDIDATE;
STATUS retStatus = rtcPeerConnectionGetMetrics (pRtcPeerConnection, NULL, &rtcStats);
printf(“Local Candidate address: %s\n”, rtcStats.rtcStatsObject.localIceCandidateStats.address);
```

以下是另一個顯示使用模式以取得收發器相關統計資料的範例：

```
RtcStats rtcStats;
PRtcRtpTransceiver pVideoRtcRtpTransceiver;
rtcStats.requestedTypeOfStats = RTC_STATS_TYPE_OUTBOUND_RTP;
STATUS retStatus = rtcPeerConnectionGetMetrics (pRtcPeerConnection, pVideoRtcRtpTransceiver, &rtcStats);
printf(“Number of packets discarded on send: %s\n”, rtcStats.rtcStatsObject.outboundRtpStreamStats.packetsDiscardedOnSend);
```

在上述範例中，如果 rtcPeerConnectionGetMetrics() 的第二個引數是 NULL，則會傳回清單中第一個收發器的資料。

rtcStatsObject 的定義可在 [Stats.h](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c/blob/master/src/include/com/amazonaws/kinesis/video/webrtcclient/Stats.h) 中找到。RtcStats 的定義可在 [Include.h](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c/blob/master/src/include/com/amazonaws/kinesis/video/webrtcclient/Include.h) 中找到。

您可以在 WebRTC C SDK 儲存庫的範例目錄中，以及 [Kinesis Video Streams 示範儲存庫](https://github.com/aws-samples/amazon-kinesis-video-streams-demos/tree/master/canary/webrtc-c/src)中找到 APIs [的範例](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c/tree/master/samples)用量和不同的指標。

使用 [W3C](https://www.w3.org/TR/webrtc-stats/)C 標準指標。 WebRTC 

**Topics**
+ [聯網](#kvswebrtc-reference-ice)
+ [媒體](#kvswebrtc-reference-media)
+ [資料管道](#kvswebrtc-reference-datachannel)

### 聯網
<a name="kvswebrtc-reference-ice"></a>

ICE 伺服器指標：


****  

| 指標 | Description | 
| --- | --- | 
| URL | 要追蹤之 STUN/TURN 伺服器的 URL | 
| 連接埠 | 用戶端使用的連接埠號碼 | 
| 通訊協定 | 從 ICE 伺服器 URI 擷取的傳輸通訊協定。如果值為 UDP，ICE 會透過 UDP 嘗試 TURN，否則 ICE 會透過 TCP/TLS 嘗試 TURN。如果 URI 不包含傳輸，ICE 會透過 UDP 和 TCP/TLS 嘗試 TURN。如果是 STUN 伺服器，此欄位為空白。 | 
| 傳送的請求總數  | 值會針對每個 srflx 候選請求更新，同時從輪換候選項目傳送繫結請求。 | 
| 收到的回應總數 | 每次收到 STUN 繫結回應時，都會更新此值。 | 
| 往返時間總計 | 每次收到請求的同等回應時，此值都會更新。系統會使用檢查總和做為金鑰，在雜湊映射中追蹤請求封包。 | 

ICE 候選統計資料：僅包含所選候選項目 （本機和遠端） 的相關資訊。


****  

| 指標 | Description | 
| --- | --- | 
| address | 這表示本機和遠端候選項目的 IP 地址。 | 
| port | 候選的連接埠號碼 | 
| protocol | 用來取得候選項目的通訊協定。有效值為 UDP/TCP。 | 
| candidateType | 選取的候選類型 - 主機、srflx 或轉送。 | 
| priority | 所選本機和遠端候選項目的優先順序。 | 
| url | 所選本機候選項目的來源。這會顯示所選候選項目是否從 STUN 伺服器或 TURN 伺服器接收。 | 
| relayProtocol | 如果使用 TURN 伺服器來取得選取的本機候選項目，此欄位會指出使用哪個通訊協定來取得它。有效值為 TCP/UDP。 | 

ICE 候選配對統計資料：僅包含所選候選配對的相關資訊。


****  

| 指標 | Description | 
| --- | --- | 
| localCandidateId | 配對中所選本機候選項目的 ID。 | 
| remoteCandidateId | 配對中所選遠端候選項目的 ID。 | 
| state | 正在檢查的候選配對狀態。 | 
| 已指定 | 設定為 TRUE，因為正在為選取的候選配對提取統計資料。 | 
| packetsSent | 傳送的封包數量。這是在 . 呼叫中計算的writeFrame。此資訊也可以從傳出的 RTP 統計資料中擷取，但由於 Ice 候選配對包含 lastPacketSent 時間戳記，因此計算兩個時間點之間傳送的封包數量可能很有用。 | 
| packetsReceived | 每次呼叫 incomingDataHandler 時都會更新。 | 
| bytesSent | 這是在 writeFrame() 呼叫的 iceAgentSendPacket()中計算的。這在計算位元速率時非常有用。目前，這也包含 標頭和填補，因為 ICE 層對 RTP 封包格式來說是絕對的。 | 
| bytesReceived | 每次呼叫 incomingDataHandler 時都會更新。目前，這也包含 標頭和填補，因為 ICE 層對 RTP 封包格式來說是絕對的。 | 
| lastPacketSentTimestamp | 每次傳送封包時都會更新。這可以與 packetsSent 和應用程式中記錄的開始時間搭配使用，以達到目前的封包傳輸速率。 | 
| lastPacketReceivedTimestamp | 這會在 中接收資料時更新incomingDataHandler()。這可與 packetsReceived 搭配使用，以推斷目前的封包接收速率。開始時間必須記錄在回transceiverOnFrame()呼中的應用程式層。 | 
| firstRequestTimestamp | 在 中成功傳送第一個 STUN 繫結請求時記錄iceAgentSendStunPacket()。這可以與 lastRequestTimestamp 和 requestsSent 搭配使用，以尋找 STUN 繫結請求之間的平均時間。 | 
| lastRequestTimestamp | 每次成功在 中傳送 STUN 繫結請求時都會記錄iceAgentSendStunPacket()。 | 
| lastResponseTimestamp | 每次收到 STUN 繫結回應時都會記錄。 | 
| totalRoundTripTime | 在收到請求的繫結回應時更新。請求和回應會根據檢查總和映射到雜湊表中。 | 
| currentRoundTripTime | 在收到候選配對請求的繫結回應時，最新的往返時間會更新。 | 
| requestsReceived | 在每個收到的 STUN 繫結請求上更新的計數器。 | 
| requestsSent | 在 中傳送的每個 STUN 繫結請求上更新的計數器iceAgentSendStunPacket()。 | 
| responsesSent | 在傳送的每個 STUN 繫結回應上更新的計數器，以回應 中的繫結請求handleStunPacket()。 | 
| responsesReceived | 在 中收到的每個 STUN 繫結回應上更新的計數器handleStunPacket()。 | 
| packetsDiscardedOnSend |  當封包傳送失敗時更新。換句話說，這會在iceUtilsSendData()失敗時更新。這有助於判斷在特定持續時間內捨棄的封包百分比。 | 
| bytesDiscardedOnSend | 當封包傳送失敗時更新。換句話說，這會在iceUtilsSendData()失敗時更新。這在判斷在特定持續時間內捨棄的封包百分比時非常有用。請注意，計數器也包含封包的標頭。 | 

### 媒體
<a name="kvswebrtc-reference-media"></a>

傳出 RTP 統計資料


****  

| 指標 | Description | 
| --- | --- | 
| voiceActivityFlag | 這目前是 Include.h 中RtcEncoderStats定義的一部分。如果最後一個音訊封包包含語音，則旗標設定為 TRUE。目前未在範例中設定 旗標。 | 
| packetsSent | 這表示針對所選 SSRC 送出的 RTP 封包總數。這是 [https://www.w3.org/TR/webrtc-stats/\$1sentrtpstats-dict\$1](https://www.w3.org/TR/webrtc-stats/#sentrtpstats-dict*) 的一部分，包含在傳出統計資料中。每次呼叫 writeFrame() 時都會遞增。 | 
| bytesSent | 已傳送的位元組總數，不包括 RTP 標頭和填補。這會在每次 writeFrame 呼叫時更新。 | 
| encoderImplementation | 這是由應用程式層更新為 RtcEncoderStats 物件的一部分。 | 
| packetsDiscardedOnSend | 如果 ICE 代理程式因任何原因無法傳送加密的 RTP 封包，此欄位會更新iceAgentSendPacket。 | 
| bytesDiscardedOnSend | 如果 ICE 代理程式因任何原因無法傳送加密的 RTP 封包，此欄位也會更新iceAgentSendPacket。 | 
| framesSent | 只有在媒體串流堆疊類型為 MEDIA\$1STREAM\$1TRACK\$1KIND\$1VIDEO 時，才會遞增。 | 
| hugeFramesSent | 此計數器會針對影格的平均大小 2.5 倍的影格進行更新。透過計算 fps （根據上次已知的影格計數時間和以時間間隔編碼的影格數量） 並使用應用程式設定的 RtcEncoderStats 中的 targetBitrate 來取得影格的大小。 | 
| framesEncoded | 只有在成功編碼影格後，才會針對影片軌跡更新此計數器。它會在每次 writeFrame 呼叫時更新。 | 
| keyFramesEncoded | 只有在金鑰影格成功編碼後，才會針對視訊軌更新此計數器。它會在每次 writeFrame 呼叫時更新。 | 
| framesDiscardedOnSend | 當影格傳送因iceAgentSendPacket呼叫失敗而失敗時，會更新此項目。框架由一組封包組成，目前，如果傳送時因錯誤而捨棄任何封包，framesDiscardedOnSend 會失敗。 | 
| frameWidth | 這理想地代表最後一個編碼影格的影格寬度。目前，應用程式將此值設定為 RtcEncoderStats\$1 \$1 的一部分，而且意義不大。 | 
| frameHeight | 這理想地代表最後一個編碼影格的影格高度。目前，應用程式將此值設定為 RtcEncoderStats 的一部分，意義不大。 | 
| frameBitDepth |  這表示最後一個編碼影格的每個像素寬度的位元深度。目前，這是由應用程式設定為 RtcEncoderStats 的一部分，並翻譯為傳出統計資料。 | 
| nackCount | 每次在 RTP 封包上收到 NACK 並再次嘗試傳送封包時，都會更新此值。堆疊支援在接收 NACK 時重新傳輸封包。 | 
| firCount | 收到 FIR 封包 (onRtcpPacket->onRtcpFIRPacket) 時會更新此值。它會指出串流落後且必須略過影格才能趕上進度的頻率。FIR 封包目前未解碼以擷取欄位，因此即使已設定計數，也不會採取任何動作。 | 
| pliCount | 收到 PLI 封包 (onRtcpPacket->onRtcpPLIPacket) 時會更新此值。這表示一或多個影格已遺失部分編碼的影片資料量。 | 
| sliCount | 收到 SLI 封包 (onRtcpPacket->onRtcpSLIPacket) 時會更新此值。它指出封包遺失影響單一影格的頻率。 | 
| qualityLimitationResolutionChanges | 目前，堆疊支援此指標，但不會監控每個編碼影格的影格寬度和高度。 | 
| lastPacketSentTimestamp | 傳送最後一個封包的時間戳記。它會在每次 writeFrame 呼叫時更新。 | 
| headerBytesSent | 為此 SSRC 傳送的 RTP 標頭和填補位元組總數，不包括實際 RTP 承載。 | 
| bytesDiscardedOnSend | 當因 iceAgentSendPacket 呼叫失敗而導致框架傳送失敗時，就會更新此項目。框架由一組封包組成，而封包則由位元組組成，目前，如果傳送時因錯誤而捨棄任何封包，則 bytesDiscardedOnSend 會失敗。 | 
| retransmittedPacketsSent | 接收 PLI/SLI/NACK 時重新傳輸的封包數量。目前，堆疊只會計算 NACK 的重新傳送封包，因為不支援 PLI 和 SLI 型重新傳輸。 | 
| retransmittedBytesSent | 接收 PLI/SLI/NACK 時重新傳輸的位元組數。目前，堆疊只會計算 NACK 的重新傳送位元組，因為不支援 PLI 和 SLI 型重新傳輸。 | 
| targetBitrate | 這是在應用程式層級中設定。 | 
| totalEncodedBytesTarget | 每次對影格進行編碼時，目標影格大小都會增加，以位元組為單位。這是使用框架結構中的大小參數進行更新。 | 
| framesPerSecond | 這是根據上次已知編碼影格所記錄的時間，以及在一秒內傳送的影格數來計算。 | 
| totalEncodeTime | 這在應用程式中設定為任意值，並在內部轉譯為傳出統計資料。 | 
| totalPacketSendDelay | 目前將此設為 0，因為 iceAgentSendPacket 會立即傳送封包。 | 

遠端傳入 RTP 統計資料：


****  

| 指標 | Description | 
| --- | --- | 
| roundTripTime | 接收 RTCP 封包類型 201 （接收者報告） 時，會從 RTCP 接收者報告中擷取此值。報告包含上次傳送者報告和自上次傳送者報告後延遲等詳細資訊，以計算往返時間。寄件者報告大約每 200 毫秒產生一次，其中包含傳送的封包數和從傳出統計資料擷取的位元組數等資訊。 | 
| totalRoundTripTime | 計算出的往返時間總和 | 
| fractionLost | 代表自傳送上一個寄件者/接收者 reporfractionLost 以來，SSRC 遺失的 RTP 封包部分。 | 
| reportsReceived | 每次收到接收者報告類型封包時更新。 | 
| roundTripTimeMeasurements | 指出針對包含有效往返時間的 SSRC 收到的報告總數。不過，目前此值會遞增，因此其意義與 reportsReceived 相同。 | 

傳入 RTP 統計資料：


****  

| 指標 | Description | 
| --- | --- | 
| packetsReceived | 收到特定 SSRC 的封包時，計數器會更新。 | 
| 抖動 | 此指標表示特定 SSRC 以秒為單位測量的封包抖動。 | 
| jitterBufferDelay | 此指標表示抖動緩衝區中每個封包所花費的時間總和。 | 
| jitterBufferEmittedCount | 從抖動緩衝區流出的音訊範例或影片影格總數。 | 
| packetsDiscarded | 當抖動緩衝區已滿且封包無法推送至其中時，計數器會更新。這可用於計算在固定持續時間內捨棄的封包百分比。 | 
| framesDropped | 此值會在叫用 onFrameDroppedFunc() 時更新。 | 
| lastPacketReceivedTimestamp | 代表此 SSRC 收到最後一個封包的時間戳記。 | 
| headerBytesReceived | 計數器會在接收 RTP 封包時更新。 | 
| bytesReceived | 收到的位元組數。這不包含標頭位元組。此指標可用來計算傳入位元速率。 | 
| packetsFailedDecryption | 當 SRTP 封包的解密失敗時，這會遞增。 | 

### 資料管道
<a name="kvswebrtc-reference-datachannel"></a>

資料管道指標：


****  

| 指標 | Description | 
| --- | --- | 
| label | Label 是要檢查的資料通道名稱。 | 
| protocol | 由於我們的堆疊使用 SCTP，因此通訊協定會設定為常數 SCTP。 | 
| dataChannelIdentifier | 用於唯一識別資料通道的偶數或奇數識別符。如果 SDK 是提供者，即使 SDK 是接聽者，此值也會更新為奇數值。 | 
| state | 查詢統計資料時資料通道的狀態。目前支援的兩個狀態為 RTC\$1DATA\$1CHANNEL\$1STATE\$1CONNECTING （建立頻道時） 和 RTC\$1DATA\$1CHANNEL\$1STATE\$1OPEN （在 onOpen() 事件中設定）。 | 
| messagesSent | 當 SDK 透過資料通道傳送訊息時，計數器會更新。 | 
| bytesSent | 計數器會以送出的訊息中的位元組進行更新。這可用來了解有多少位元組不會因為失敗而傳送，也就是了解傳送的位元組百分比。 | 
| messagesReceived | 指標會在回onMessage()呼中遞增。 | 
| bytesReceived | 指標會在回onMessage()呼中產生。 |