# 開始使用 IVS 即時串流
<a name="getting-started"></a>

本文件將引導您完成將 Amazon IVS 即時串流功能整合到應用程式所涉及的步驟。

**Topics**
+ [IVS 即時串流簡介](getting-started-introduction.md)
+ [步驟 1：設定 IAM 許可](getting-started-iam-permissions.md)
+ [步驟 2：建立具有選用參與者錄製的階段](getting-started-create-stage.md)
+ [步驟 3：分發參與者權杖](getting-started-distribute-tokens.md)
+ [步驟 4：整合 IVS 廣播 SDK](getting-started-broadcast-sdk.md)
+ [步驟 5：發布和訂閱影片](getting-started-pub-sub.md)

# IVS 即時串流簡介
<a name="getting-started-introduction"></a>

本節列出使用即時串流的先決條件，並介紹關鍵術語。

## 必要條件
<a name="getting-started-introduction-prereq"></a>

第一次使用即時串流之前，請先完成以下任務。如需說明，請參閱[開始使用 IVS 低延遲串流](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/getting-started.html)。
+ 建立 AWS 帳戶
+ 設定根使用者和管理使用者。

## 其他參考
<a name="getting-started-introduction-extref"></a>
+ [IVS Web 廣播 SDK 參考](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference)
+ [IVS Android 廣播 SDK 參考](https://aws.github.io/amazon-ivs-broadcast-docs/latest/android/)
+ [IVS iOS 廣播 SDK 參考](https://aws.github.io/amazon-ivs-broadcast-docs/latest/ios/)
+ [IVS 即時串流 API 參考](https://docs.aws.amazon.com/ivs/latest/RealTimeAPIReference/Welcome.html)

## 即時串流術語
<a name="getting-started-introduction-terminology"></a>


| 術語 | 說明 | 
| --- | --- | 
| 階段 | 參與者可即時交換影片的虛擬空間。 | 
| 主機 | 將本機影片傳送至階段的參與者。 | 
| 觀眾 | 接收主持人影片的參與者。 | 
| 參與者 | 以主持人或觀眾的身分連線至階段的使用者。 | 
| 參與者權杖 | 驗證參與者加入階段時的權杖。 | 
| 廣播 SDK | 可讓參與者傳送和接收影片的用戶端程式庫。 | 

## 步驟概觀
<a name="getting-started-introduction-steps"></a>

1. [設定 IAM 許可](getting-started-iam-permissions.md) – 建立 AWS Identity and Access Management (IAM) 政策，為使用者提供一組基本許可，並將該政策指派給使用者。

1. [建立階段](getting-started-create-stage.md) – 建立一個虛擬空間，參與者可以在這裡即時交換影片。

1. [分發參與者權杖](getting-started-distribute-tokens.md) – 向參與者傳送記號，以便他們可以加入您的階段。

1. [整合 IVS 廣播 SDK](getting-started-broadcast-sdk.md) – 將廣播 SDK 新增至應用程式，以便讓參與者傳送和接收影片：[Web](getting-started-broadcast-sdk.md#getting-started-broadcast-sdk-web)、[Android](getting-started-broadcast-sdk.md#getting-started-broadcast-sdk-android) 和 [iOS](getting-started-broadcast-sdk.md#getting-started-broadcast-sdk-ios)。

1. [發布和訂閱影片](getting-started-pub-sub.md) – 將影片傳送至舞台，並從其他主機接收影片：[IVS 主控台](getting-started-pub-sub.md#getting-started-pub-sub-console)、[使用 IVS Web 廣播 SDK 發布和訂閱](getting-started-pub-sub-web.md)、[使用 IVS Android 廣播 SDK 發布和訂閱](getting-started-pub-sub-android.md) 和 [使用 IVS iOS 廣播 SDK 發布和訂閱](getting-started-pub-sub-ios.md)。

# 步驟 1：設定 IAM 許可
<a name="getting-started-iam-permissions"></a>

接下來，您必須建立 AWS Identity and Access Management (IAM) 政策，為使用者提供一組基本許可 (例如，用於建立 Amazon IVS 階段並建立參與者權杖的許可)，並將該政策指派給使用者。您可以在建立[新使用者](#iam-permissions-new-user)時指派許可，也可以為[現有的使用者](#iam-permissions-existing-user)新增許可。兩種程序如下所示。

如需詳細資訊 (例如，若要了解 IAM 使用者和政策、如何將政策附加到使用者、以及如何限制使用者可以使用 Amazon IVS 執行的動作)，請參閱：
+ 《IAM 使用者指南》**中的[建立 IAM 使用者](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#Using_CreateUser_console)
+ [Amazon IVS 安全性](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/security.html) 中有關 IAM 和「IVS 的受管政策」的資訊。
+ [Amazon IVS 安全性](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/security.html)中的 IAM 資訊

您可以對 Amazon IVS 使用現有的 AWS 受管政策，也可以建立新政策來自訂要授予一組使用者、群組或角色的許可。兩種方法皆在下面有所描述。

## 對 IVS 許可使用現有的政策
<a name="iam-permissions-existing-policy"></a>

在大多數情況下，您會想要對 Amazon IVS 使用 AWS 受管政策。*IVS 安全性*的 [IVS 的受管政策](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/security-iam-awsmanpol.html)章節對它們進行了完整描述。
+ 使用 `IVSReadOnlyAccess` AWS 受管政策可讓應用程式開發人員存取所有 IVS Get 和 List API 操作 (同時適用於低延遲和即時串流)。
+ 使用 `IVSFullAccess` AWS 受管政策可讓應用程式開發人員存取所有 IVS API 操作 (同時適用於低延遲和即時串流)。

## 選用：為 Amazon IVS 許可建立自訂政策
<a name="iam-permissions-new-policy"></a>

請遵循下列步驟：

1. 登入 AWS 管理主控台，然後前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在導覽窗格中，選擇**政策**，然後選擇**建立政策**。**Specify permissions** (指定許可) 視窗隨即開啟。

1. 在**指定許可**視窗中，選擇 **JSON** 標籤，將以下 IVS 政策複製並貼上至**政策編輯器**文字區域。(此政策不包括所有 Amazon IVS 動作。您可以視需要新增/刪除 (允許/拒絕) 操作存取許可。如需有關 IVS 操作的詳細資訊，請參閱《[IVS 即時串流 API 參考](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/Welcome.html)》。)

------
#### [ JSON ]

****  

   ```
   {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
         {
            "Effect": "Allow",
            "Action": [
               "ivs:CreateStage",
               "ivs:CreateParticipantToken",
               "ivs:GetStage",
               "ivs:GetStageSession",
               "ivs:ListStages",
               "ivs:ListStageSessions",
               "ivs:CreateEncoderConfiguration",
               "ivs:GetEncoderConfiguration",
               "ivs:ListEncoderConfigurations",
               "ivs:GetComposition",
               "ivs:ListCompositions",
               "ivs:StartComposition",
               "ivs:StopComposition"
             ],
             "Resource": "*"
         },
         {
            "Effect": "Allow",
            "Action": [
               "cloudwatch:DescribeAlarms",
               "cloudwatch:GetMetricData",
               "s3:DeleteBucketPolicy",
               "s3:GetBucketLocation",
               "s3:GetBucketPolicy",
               "s3:PutBucketPolicy",
               "servicequotas:ListAWSDefaultServiceQuotas",
               "servicequotas:ListRequestedServiceQuotaChangeHistoryByQuota",
               "servicequotas:ListServiceQuotas",
               "servicequotas:ListServices",
               "servicequotas:ListTagsForResource"
            ],
            "Resource": "*"
         }
      ]
   }
   ```

------

1. 仍在**指定許可**視窗中，選擇**下一步** (捲動至視窗底部即可看到此選項)。**Review and create** (審查並建立) 視窗隨即開啟。

1. 在**審查並建立**視窗中，輸入**政策名稱**，並選擇性地新增**描述**。請記下政策名稱，因為您在建立使用者時要用到此資料 (如下)。選擇 **Create policy** (建立政策) (位於視窗底部)。

1. 您會返回 IAM 主控台視窗，在其中看到一個橫幅，確認您的新政策已建立。

## 建立新使用者並新增許可
<a name="iam-permissions-new-user"></a>

### IAM 使用者存取金鑰
<a name="iam-permissions-new-user-access-keys"></a>

IAM 存取金鑰由存取金鑰 ID 和私密存取金鑰組成。這些金鑰用於簽署您對 AWS 提出的程式設計請求。如果您沒有存取金鑰，可以使用 AWS 管理主控台來建立。根據最佳實務，請勿建立根使用者存取金鑰。

*您只能在建立存取金鑰時，檢視或下載私密存取金鑰。稍後您便無法復原。*不過，您可以隨時建立新的存取金鑰；您必須具有執行必要 IAM 動作的許可。

請務必安全地儲存存取金鑰。切勿與第三方分享 (即使查詢似乎來自 Amazon)。如需詳細資訊，請參閱《IAM 使用者指南》**中的[管理 IAM 使用者的存取金鑰](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)。

### 程序
<a name="iam-permissions-new-user-procedure"></a>

請遵循下列步驟：

1. 在導覽窗格中，選擇 **Users** (使用者)，然後選擇 **Create user** (建立使用者)。**Specify user details** (指定使用者詳細資訊) 視窗隨即開啟。

1. 在**指定使用者詳細資訊**視窗：

   1. 在 **User details** (使用者詳細資訊)，輸入要建立的新 **User name** (使用者名稱)。

   1. 勾選**提供使用者對 AWS 管理主控台的存取權**。

   1. 在**主控台密碼**下選取**自動產生的密碼**。

   1. 選取**使用者必須在下次登入時建立新密碼**。

   1. 選擇**下一步**。**Set permissions** (設定許可) 視窗隨即開啟。

1. 在**設定許可**下，選取**直接連接政策**。**Permissions policies** (許可策略) 視窗隨即開啟。

1. 在搜尋方塊中，輸入 IVS 政策名稱 (AWS 受管政策或之前建立的自訂政策)。找到後，勾選方塊以選取政策。

1. 選擇 **Next** (下一步) (位於視窗底部)。**Review and create** (審查並建立) 視窗隨即開啟。

1. 在 **Review and create** (審查並建立) 視窗中，確認所有使用者詳細資訊都正確無誤，然後選擇 **Create user** (建立使用者) (位於視窗底部)。

1. **Retrieve password** (擷取密碼) 視窗隨即開啟，其中包含您的**主控台登入詳細資訊**。*安全地儲存此資訊以供日後參考*。當您完成時，請選擇 **Return to users list** (返回使用者清單)。

## 為現有的使用者新增許可
<a name="iam-permissions-existing-user"></a>

請遵循下列步驟：

1. 登入 AWS 管理主控台，然後前往 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 開啟 IAM 主控台。

1. 在導覽窗格中，選擇**使用者**，然後選擇要更新的現有使用者名稱。(按一下名稱來選擇名稱；請勿勾選選取方塊。)

1. 在 **Summary** (摘要) 頁面的 **Permissions** (許可) 索引標籤中，選擇 **Add permissions** (新增許可)。**Add permissions** (新增許可) 視窗隨即開啟。

1. 選取**直接連接現有政策**。**Permissions policies** (許可策略) 視窗隨即開啟。

1. 在搜尋方塊中，輸入 IVS 政策名稱 (AWS 受管政策或之前建立的自訂政策)。找到政策後，勾選方塊以選取政策。

1. 選擇 **Next** (下一步) (位於視窗底部)。**Review** (審查) 視窗隨即開啟。

1. 在**檢閱**視窗上，選取**新增許可** (位於視窗底部)。

1. 在**摘要**頁面上，確認已新增 IVS 政策。

# 步驟 2：建立具有選用參與者錄製的階段
<a name="getting-started-create-stage"></a>

階段是參與者可即時交換影片的虛擬空間。它是即時串流 API 的基本資源。您可以使用主控台或 CreateStage 操作來建立舞台。

建議您儘可能針對每個邏輯工作階段建立一個新階段，並在完成後將其刪除，而不是保留舊階段供重複使用。如果未清除過時的資源 (舊階段，未重複使用)，則可能會更快地達到階段數目上限。

您可以透過 Amazon IVS 主控台或 AWS CLI 建立階段，包含或不包含個別參與者錄製皆可。我們會在下方討論階段建立和錄製。

## 個別參與者錄製
<a name="getting-started-create-stage-ipr-overview"></a>

您可以選擇為階段啟用個別參與者錄製。如果已啟用個別參與者錄製到 S3 的功能，則系統會錄製所有個別參與者廣播至階段，並儲存至您擁有的 Amazon S3 儲存貯體。隨後，錄製內容可用於隨需播放。

*設定它是一個進階選項。*依預設，會在建立階段時停用錄製。

在設定階段進行錄製之前，您必須先建立*儲存空間組態*。這項資源指定了用於為階段儲存錄製串流的 Amazon S3 位置。您可以使用主控台或 CLI 建立和管理儲存空間組態；兩種程序如下所示。建立儲存空間組態之後，您可以在建立階段時 (如下所述) 或稍後透過更新現有階段，將其與階段建立關聯。(在 API 中，請參閱 [CreateStage](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_CreateStage.html) 和 [UpdateStage](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_UpdateStage.html))。您可以將多個階段與相同的儲存空間組態建立關聯。您可以刪除不再與任何階段關聯的儲存空間組態。

請謹記以下幾點限制：
+ 您必須擁有 S3 儲存貯體。也就是說，設定要錄製的階段之帳戶必須擁有可供儲存錄製內容的 S3 儲存貯體。
+ 階段、儲存空間組態和 S3 位置，皆必須位於相同的 AWS 區域。如果您在其他區域建立階段，並且想要錄製這些階段，則必須亦在這些區域設定儲存空間組態和 S3 儲存貯體。

必須使用您的 AWS 登入資料進行授權，才能錄製到 S3 儲存貯體。為了提供 IVS 必要的存取權限，建立錄製組態時會自動建立 AWS IAM [服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) (SLR)：SLR 僅限於在特定儲存貯體上提供 IVS 寫入許可。

請注意，串流位置與 AWS 之間或 AWS 內部的網路問題可能會導致在錄製串流時遺失某些資料。在這些情況下，Amazon IVS 會將即時串流優先於錄製。如需備援，請透過串流工具在本機進行錄製。

如需詳細資訊 (包括如何在錄製的檔案上設定後製處理或 VOD 播放)，請參閱[個別參與者錄製](rt-individual-participant-recording.md)。

### 如何停用錄製
<a name="getting-started-disable-recording"></a>

若要在現有階段上停用 Amazon S3 錄製：
+ 主控台 — 在相關階段的詳細資訊頁面上，在**錄製個別參與者**串流區段中，關閉**自動錄製到 S3** 下的**啟用自動錄製**，然後選擇**儲存變更**。這會移除儲存空間組態與頻道之間的關聯；系統將不再錄製該階段上的串流。
+ CLI — 執行 `update-stage` 命令並將錄製組態 ARN 作為空字串傳入：

  ```
  aws ivs-realtime update-stage --arn arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh --auto-participant-recording-configuration storageConfigurationArn=""
  ```

  這將傳回一個 `storageConfigurationArn` 為空字串的階段物件，表示錄製已停用。

## 建立 IVS 階段的主控台說明
<a name="getting-started-create-stage-console"></a>

1. 開啟 [Amazon IVS 主控台](https://console.aws.amazon.com/ivs)。

   (您也可以透過 [AWS 管理主控台](https://console.aws.amazon.com/)來存取 Amazon IVS 主控台。)

1. 在左側導覽窗格中，選取**階段**，然後選取**建立階段**。**建立階段**視窗出現。  
![\[使用「建立階段」視窗來為其建立新階段及參與者權杖。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Create_Stage_Console_IPR.png)

1. 或者，輸入**階段名稱**。

1. 如果您想要啟用個別參與者錄製，請完成下方[設定自動化個別參與者錄製到 Amazon S3 (選用)](#getting-started-create-stage-ipr) 中的步驟。

1. 選取**建立階段**以建立階段。此時會顯示新階段的階段詳細資訊頁面。

### 設定自動化個別參與者錄製到 Amazon S3 (選用)
<a name="getting-started-create-stage-ipr"></a>

請依照下列步驟，在建立階段時啟用個別參與者錄製：

1. 在**建立階段**頁面的**錄製個別參與者**下，打開**啟用自動錄製**。此時會顯示其他欄位，以選擇**錄製的媒體類型**、選擇現有的**儲存空間組態**或建立新的組態，以及選擇錄製縮圖時是否要有間隔。  
![\[使用錄製個別參與者對話方塊來設定階段的個別參與者錄製。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Create_Stage_Console_enable_IPR.png)

1. 選擇要錄製的媒體類型。

1. 選擇**建立儲存空間組態**。新的視窗將開啟，其中包含用於建立 Amazon S3 儲存貯體並將其附加到新錄製組態的選項。  
![\[使用「建立儲存空間組態」視窗，為階段建立新的儲存空間組態。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Create_Storage_Configuration_IPR.png)

1. 填寫以下欄位：

   1. 您可以選擇性地輸入**儲存空間組態名稱**。

   1. 輸入 **Bucket name (儲存貯體名稱)**。

1. 選擇**建立儲存空間組態**，建立具有專屬 ARN 的新儲存空間組態資源。通常，建立錄製組態需要幾秒鐘，但最多可能需要 20 秒鐘。建立儲存空間組態時，您會返回**建立階段**視窗。接著，**錄製個別參與者**區域會顯示您的新**儲存空間組態**和您建立的 S3 儲存貯體 (**儲存空間**)。  
![\[使用 IVS 主控台來建立階段：已建立新的儲存空間組態。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Create_Stage_Console_Storage_Configuration.png)

1. 您可以選擇啟用其他非預設選項，例如錄製參與者複本、合併個別參與者錄製，以及縮圖錄製。  
![\[使用 IVS 主控台建立階段：啟用進階選項，例如縮圖錄製和 IPR 拼接。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Create_Stage_Console_IPR_Stitching.png)

## 建立 IVS 階段的 CLI 指示
<a name="getting-started-create-stage-cli"></a>

若要安裝 AWS CLI，請參閱[安裝或更新至最新版 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。

現在，您可以使用 CLI 並依照下列兩個程序其中之一來建立和管理資源，取決於您是否要建立已啟用或未啟用個別參與者錄製的階段。

### 建立沒有個別參與者錄製的階段
<a name="getting-started-create-stage-cli-without-ipr"></a>

階段 API 位於 ivs-realtime 命名空間下方。例如，若要建立階段：

```
aws ivs-realtime create-stage --name "test-stage"
```

回應為：

```
{
   "stage": {
      "arn": "arn:aws:ivs:us-west-2:376666121854:stage/VSWjvX5XOkU3",
      "name": "test-stage"
   }
}
```

### 建立沒有個別參與者錄製的階段
<a name="getting-started-create-stage-cli-with-ipr"></a>

若要建立已啟用個別參與者錄製的階段：

```
aws ivs-realtime create-stage --name "test-stage-participant-recording" --auto-participant-recording-configuration storageConfigurationArn=arn:aws:ivs:us-west-2:123456789012:storage-configuration/LKZ6QR7r55c2,mediaTypes=AUDIO_VIDEO
```

除此之外，您亦可傳遞 `thumbnailConfiguration` 參數來手動設定縮圖儲存空間和錄製模式，以及縮圖間隔秒數：

```
aws ivs-realtime create-stage --name "test-stage-participant-recording" --auto-participant-recording-configuration storageConfigurationArn=arn:aws:ivs:us-west-2:123456789012:storage-configuration/LKZ6QR7r55c2,mediaTypes=AUDIO_VIDEO,thumbnailConfiguration="{targetIntervalSeconds=10,storage=[SEQUENTIAL,LATEST],recordingMode=INTERVAL}"
```

或者，傳遞 `recordingReconnectWindowSeconds` 參數以啟用合併分段的個別參與者錄製：

```
aws ivs-realtime create-stage --name "test-stage-participant-recording" --auto-participant-recording-configuration "storageConfigurationArn=arn:aws:ivs:us-west-2:123456789012:storage-configuration/LKZ6QR7r55c2,mediaTypes=AUDIO_VIDEO,thumbnailConfiguration="{targetIntervalSeconds=10,storage=[SEQUENTIAL,LATEST],recordingMode=INTERVAL}",recordingReconnectWindowSeconds=60"
```

回應為：

```
{
   "stage": {
      "arn": "arn:aws:ivs:us-west-2:123456789012:stage/VSWjvX5XOkU3",
      "autoParticipantRecordingConfiguration": {
         "hlsConfiguration": {
             "targetSegmentDurationSeconds": 6
         },
         "mediaTypes": [
            "AUDIO_VIDEO"
         ],
         "recordingReconnectWindowSeconds": 60,
         "recordParticipantReplicas": true,
         "storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/LKZ6QR7r55c2",
         "thumbnailConfiguration": {
            "recordingMode": "INTERVAL",
            "storage": [
               "SEQUENTIAL",
               "LATEST"
            ],
            "targetIntervalSeconds": 10
         }
      },
      "endpoints": {
         "events": "<events-endpoint>",
         "rtmp": "<rtmp-endpoint>",
         "rtmps": "<rtmps-endpoint>",
         "whip": "<whip-endpoint>"
      },
      "name": "test-stage-participant-recording"
   }
}
```

# 步驟 3：分發參與者權杖
<a name="getting-started-distribute-tokens"></a>

現在您有了一個舞台，需要建立權杖，並將其分發給參與者，使參與者能夠加入此舞台，並開始傳送和接收影片。有兩種權杖產生方法：
+ 使用金鑰對[建立](#getting-started-distribute-tokens-self-signed)權杖。
+ [使用 IVS 即時串流 API 建立權杖](#getting-started-distribute-tokens-api)。

這兩種方法皆在下面有所描述。

## 使用金鑰對建立權杖
<a name="getting-started-distribute-tokens-self-signed"></a>

您可以在伺服器應用程式建立權杖，然後將權杖分發給參與者，用以加入舞台。您需要產生 ECDSA 公有/私有金鑰對來簽署 JWT，並且將公有金鑰匯入至 IVS。然後，IVS 就可以在有人加入舞台時驗證權杖。

IVS 不會自動刪除到期的金鑰。如果私有金鑰遭到盜用，您必須刪除舊的公有金鑰。

### 建立新的金鑰對
<a name="getting-started-distribute-tokens-self-signed-create-key-pair"></a>

有多種方法可以建立金鑰對。以下提供兩個範例。

若要在主控台中建立新的金鑰對，請依照下列步驟執行：

1. [開啟 Amazon IVS 主控台](https://console.aws.amazon.com/ivs)。如果您尚未在舞台中，請選擇舞台區域。

1. 在左側導覽功能表中，選擇**即時串流 > 公有金鑰**。

1. 選擇**建立公有金鑰**。**建立公有金鑰**對話方塊隨即出現。

1. 依照提示進行操作並選擇 **Create** (建立)。

1. Amazon IVS 會產生新的金鑰對。公有金鑰會作為公有金鑰資源匯入，而私有金鑰可立即用於下載。如有需要，也可以稍後下載公有金鑰。

   Amazon IVS 會在用戶端產生金鑰，而不會儲存私有金鑰。***請務必儲存金鑰；稍後無法擷取金鑰。***

若要使用 OpenSSL 建立新 P384 EC 金鑰對 (您可能必須先安裝 [OpenSSL](https://www.openssl.org/source/))，請依照下列步驟執行。此過程可讓您存取私有金鑰和公有金鑰。只有當您想測試符記的驗證時，才需要公有金鑰。

```
openssl ecparam -name secp384r1 -genkey -noout -out priv.pem
openssl ec -in priv.pem -pubout -out public.pem
```

現在，按照下列指示匯入新的公有金鑰。

### 匯入公有金鑰
<a name="getting-started-distribute-tokens-import-public-key"></a>

在您取得金鑰對後，就可以將公有金鑰匯入 IVS。我們的系統不需要私有金鑰，但您可以用來簽署符記。

若要使用主控台匯入現有的公有金鑰：

1. [開啟 Amazon IVS 主控台](https://console.aws.amazon.com/ivs)。如果您尚未在舞台中，請選擇舞台區域。

1. 在左側導覽功能表中，選擇**即時串流 > 公有金鑰**。

1. 選擇**匯入**。**匯入公有金鑰**對話方塊隨即出現。

1. 依照提示進行操作並選擇 **Import** (匯入)。

1. Amazon IVS 會匯入公有金鑰並產生公有金鑰資源。

若要使用 CLI 匯入現有的公有金鑰：

```
aws ivs-realtime import-public-key --public-key-material "`cat public.pem`" --region <aws-region>
```

如果區域位於本機 AWS 組態檔案中，您可以省略 `--region <aws-region>`。

這是回應範例：

```
{
    "publicKey": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:public-key/f99cde61-c2b0-4df3-8941-ca7d38acca1a",
        "fingerprint": "98:0d:1a:a0:19:96:1e:ea:0a:0a:2c:9a:42:19:2b:e7",
        "publicKeyMaterial": "-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEVjYMV+P4ML6xemanCrtse/FDwsNnpYmS\nS6vRV9Wx37mjwi02hObKuCJqpj7x0lpz0bHm5v1JBvdZYAd/r2LR5aChK+/GM2Wj\nl8MG9NJIVFaw1u3bvjEjzTASSfS1BDX1\n-----END PUBLIC KEY-----\n",
        "tags": {}
    }
}
```

### API 請求
<a name="getting-started-distribute-tokens-create-api"></a>

```
POST /ImportPublicKey HTTP/1.1
{
  "publicKeyMaterial": "<pem file contents>"
}
```

### 產生和簽署權杖
<a name="getting-started-distribute-tokens-self-signed-generate-sign"></a>

如需有關使用 JWT 以及用於簽章符記的支援程式庫的詳細資訊，請造訪 [jwt.io](https://jwt.io/)。在 jwt.io 介面上，您必須輸入私有金鑰才能簽署符記。只有在您想驗證符記時才需要公有金鑰。

所有 JWT 都有三個欄位：標頭、承載和簽章。

JWT 標頭和承載的 JSON 結構描述如下所述。您也可以從 IVS 主控台複製範例 JSON。若要從 IVS 主控台取得標頭和承載 JSON：

1. [開啟 Amazon IVS 主控台](https://console.aws.amazon.com/ivs)。如果您尚未在舞台中，請選擇舞台區域。

1. 在左側導覽功能表中，選擇**即時串流 > 舞台**。

1. 選取您要使用的舞台。請選取**檢視詳細資訊**。

1. 在**參與者權杖**區段中，選取**建立權杖**旁的下拉式清單。

1. 選取**建置權杖標頭和承載**。

1. 填寫表單並複製彈出視窗底部顯示的 JWT 標頭和承載。

#### 權杖結構描述：標頭
<a name="getting-started-distribute-tokens-self-signed-generate-sign-header"></a>

標頭指定：
+ `alg` 是簽章演算法。這是 ES384，一種使用 SHA-384 雜湊演算法的 ECDSA 簽章演算法。
+ `typ` 是符記類型，JWT。
+ `kid` 是用來簽署權杖的公有金鑰 ARN。此 ARN 必須與從 [GetPublicKey](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_GetPublicKey.html) API 請求傳回的 ARN 相同。

```
{
  "alg": "ES384",
  "typ": "JWT"
  “kid”: “arn:aws:ivs:123456789012:us-east-1:public-key/abcdefg12345”
}
```

#### 權杖結構描述：承載
<a name="getting-started-distribute-tokens-self-signed-generate-sign-payload"></a>

此承載包含 IVS 特定資料。除了 `user_id` 之外的所有欄位都是必填欄位。
+ JWT 規格中的 `RegisteredClaims` 是保留宣告，必須提供此宣告，舞台權杖才會有效：
  + `exp` (過期時間) 是權杖過期時間的 Unix UTC 時間戳記。(Unix 時間戳記是一個數值，表示從 1970-01-01T00:00:00Z UTC 到指定 UTC 日期/時間的秒數 (忽略閏秒)。) 參與者加入舞台時，系統會驗證此權杖。IVS 提供預設 12 小時 (我們的建議值) TTL 的權杖；此時間最多可延長至發行時間 (iat) 後 14 天。此值必須為整數類型。
  + `iat` (發行時間) 是 JWT 發行時間的 Unix UTC 時間戳記。(請參閱 `exp` 有關 Unix 時間戳記的備註。) 此值必須為整數類型。
  + `jti` (JWT ID) 是參與者 ID，此 ID 會用於追蹤和指代獲得權杖的參與者。每個權杖都必須具有唯一的參與者 ID。此 ID 必須是區分大小寫的字串、長度上限為 64 個字元，且只包含英數字元、連字號 (-) 和底線 (\$1) 字元。不允許使用其他特殊字元。
+ `user_id` 是客戶指派名稱 (選用)，可協助識別權杖，可用來將參與者連結至客戶自有系統中的使用者。它應與 [CreateParticipantToken](https://docs.aws.amazon.com/ivs/latest/RealTimeAPIReference/API_CreateParticipantToken.html) API 請求中的 `userId` 欄位相符。它可以是任何 UTF-8 編碼文字，而且是最多 128 個字元的字串。*此欄位會向所有舞台參與者顯示，而此資訊不應用於個人身分識別、機密或敏感資訊。*
+ `resource` 是舞台的 ARN；例如 `arn:aws:ivs:us-east-1:123456789012:stage/oRmLNwuCeMlQ`。
+ `topic` 是舞台的 ID，可以從舞台 ARN 中擷取。例如，如果舞台 ARN 為 `arn:aws:ivs:us-east-1:123456789012:stage/oRmLNwuCeMlQ`，則舞台 ID 為 `oRmLNwuCeMlQ`。
+ `events_url` 必須是 CreateStage 或 GetStage 操作傳回的事件端點。建議您在建立舞台時快取此值，可對該值進行快取的時間最長為 14 天。範例值為 `wss://global.events.live-video.net`。
+ `whip_url` 必須是 CreateStage 或 GetStage 操作傳回的 WHIP 端點。建議您在建立舞台時快取此值，可對該值進行快取的時間最長為 14 天。範例值為 `https://453fdfd2ad24df.global-bm.whip.live-video.net`。
+ `capabilities` 會指定權杖的功能；有效值為 `allow_publish` 和 `allow_subscribe`。對於僅限訂閱的權杖，請僅將 `allow_subscribe` 設定為 `true`。
+ `attributes` 是選填欄位，您可以在其中指定應用程式提供的屬性，以編碼至權杖並連接至舞台。映射的鍵值可以包含 UTF-8 編碼文字。此欄位的長度上限總計為 1 KB。*此欄位會向所有舞台參與者顯示，而此資訊不應用於個人身分識別、機密或敏感資訊。*
+ `version` 必須為 `1.0`。

  ```
  {
    "exp": 1697322063,
    "iat": 1697149263,
    "jti": "Mx6clRRHODPy",
    "user_id": "<optional_customer_assigned_name>",
    "resource": "<stage_arn>",
    "topic": "<stage_id>",
    "events_url": "wss://global.events.live-video.net",
    "whip_url": "https://114ddfabadaf.global-bm.whip.live-video.net",
    "capabilities": {
      "allow_publish": true,
      "allow_subscribe": true
    },
    "attributes": {
      "optional_field_1": "abcd1234",
      "optional_field_2": "false"
    },
    "version": "1.0"
  }
  ```

#### 權杖結構描述：簽章
<a name="getting-started-distribute-tokens-self-signed-generate-sign-signature"></a>

若要建立簽章，請使用私有金鑰搭配標頭 (ES384) 中指定的演算法來簽署已編碼的標頭和承載。

```
ECDSASHA384(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  <private-key>
)
```

#### 指示
<a name="getting-started-distribute-tokens-self-signed-generate-sign-instructions"></a>

1. 使用 ES384 簽署演算法和與提供給 IVS 的公有金鑰相關聯的私有金鑰，來產生權杖的簽章。

1. 組合符記。

   ```
   base64UrlEncode(header) + "." +
   base64UrlEncode(payload) + "." +
   base64UrlEncode(signature)
   ```

## 使用 IVS 即時串流 API 建立權杖
<a name="getting-started-distribute-tokens-api"></a>

![\[分發參與者權杖：階段權杖工作流程\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Distribute_Participant_Tokens.png)


如上所示，用戶端應用程式會向您的伺服器端應用程式索取字符，伺服器端應用程式會使用 AWS SDK 或 Sigv4 簽署的請求呼叫 CreateParticipantToken。由於我們使用 AWS 憑證呼叫 API，因此應在安全的伺服器端應用程式中產生字符，而不是在用戶端應用程式中產生。

建立參與者權杖時，您可以選擇是否指定屬性和/或功能：
+ 您可以指定應用程式提供的屬性，以編碼至權杖並連接至舞台。映射的鍵值可以包含 UTF-8 編碼文字。此欄位的長度上限總計為 1 KB。*此欄位會向所有舞台參與者顯示，而此資訊不應用於個人身分識別、機密或敏感資訊。*
+ 您可以指定權杖可啟用的功能。預設值為 `PUBLISH` 和 `SUBSCRIBE`，這可讓參與者傳送和接收音訊和影片，但您可以簽發具有功能子集的權杖。例如，您可以簽發僅具有主持人適用 `SUBSCRIBE` 功能的權杖。在這種情況下，主持人可以看到正在傳送影片但不傳送自己影片的參與者。

如需詳細資訊，請參閱 [CreateParticipantToken](https://docs.aws.amazon.com//ivs/latest/RealTimeAPIReference/API_CreateParticipantToken.html)。

您可以透過主控台或 CLI 建立參與者權杖，以進行測試和開發，但很可能您想要在生產環境中使用 AWS SDK 建立權杖。

您必須知道如何從伺服器將權杖分發給每位客戶 (例如透過 API 請求)。我們未提供此功能。依據本指南，您只需遵循下列步驟複製權杖並將其貼至用戶端程式碼。

**重要**：將權杖視為不透明；即，不根據權杖內容來建置功能。權杖的格式將來可能會改變。

### 主控台說明
<a name="getting-started-distribute-tokens-console"></a>

1. 導覽至您在上一個步驟中建立的階段。

1. 選取**建立權杖**。**建立權杖**視窗隨即出現。

1. 輸入要與權杖建立關聯的使用者 ID。這可以是任何 UTF-8 編碼文字。

1. 選取**建立**。

1. 複製字符。*重要：請務必儲存權杖；IVS 不會存放該權杖，並且您稍後無法擷取*。

### CLI 說明
<a name="getting-started-distribute-tokens-cli"></a>

使用 AWS CLI 建立權杖，需要您先在機器上下載並設定 CLI。如需詳細資訊，請參閱《[AWS 命令列介面使用者指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)》。請注意，使用 AWS CLI 產生符記適合在測試時使用，但對於生產用途，建議您使用 AWS SDK 在伺服器端產生符記 (請參閱下述說明)。

1. 執行 `create-participant-token` 命令與階段 ARN。納入任何或所有這些功能：`"PUBLISH"`、`"SUBSCRIBE"`。

   ```
   aws ivs-realtime create-participant-token --stage-arn arn:aws:ivs:us-west-2:376666121854:stage/VSWjvX5XOkU3 --capabilities '["PUBLISH", "SUBSCRIBE"]'
   ```

1. 這會傳回參與者權杖：

   ```
   {
       "participantToken": {
           "capabilities": [
               "PUBLISH",
               "SUBSCRIBE"
           ],
           "expirationTime": "2023-06-03T07:04:31+00:00",
           "participantId": "tU06DT5jCJeb",
           "token": "eyJhbGciOiJLTVMiLCJ0eXAiOiJKV1QifQ.eyJleHAiOjE2NjE1NDE0MjAsImp0aSI6ImpGcFdtdmVFTm9sUyIsInJlc291cmNlIjoiYXJuOmF3czppdnM6dXMtd2VzdC0yOjM3NjY2NjEyMTg1NDpzdGFnZS9NbzhPUWJ0RGpSIiwiZXZlbnRzX3VybCI6IndzczovL3VzLXdlc3QtMi5ldmVudHMubGl2ZS12aWRlby5uZXQiLCJ3aGlwX3VybCI6Imh0dHBzOi8vNjZmNzY1YWM4Mzc3Lmdsb2JhbC53aGlwLmxpdmUtdmlkZW8ubmV0IiwiY2FwYWJpbGl0aWVzIjp7ImFsbG93X3B1Ymxpc2giOnRydWUsImFsbG93X3N1YnNjcmliZSI6dHJ1ZX19.MGQCMGm9affqE3B2MAb_DSpEm0XEv25hfNNhYn5Um4U37FTpmdc3QzQKTKGF90swHqVrDgIwcHHHIDY3c9eanHyQmcKskR1hobD0Q9QK_GQETMQS54S-TaKjllW9Qac6c5xBrdAk"
       }
   }
   ```

1. 儲存此權杖。您將需要此項才能加入階段，並傳送和接收影片。

### AWS SDK 說明
<a name="getting-started-distribute-tokens-sdk"></a>

您可以使用 AWS SDK 來建立權杖。以下是使用 JavaScript 的 AWS SDK 說明。

**重要：**此程式碼必須在伺服器端執行，再將其輸出傳遞給用戶端。

**先決條件：**若要使用下面的程式碼範例，您需要安裝 aws-sdk/client-ivs-realtime 套件。如需詳細資訊，請參閱[適用於 JavaScript 的 AWS SDK 入門](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html)。

```
import { IVSRealTimeClient, CreateParticipantTokenCommand } from "@aws-sdk/client-ivs-realtime";

const ivsRealtimeClient = new IVSRealTimeClient({ region: 'us-west-2' });
const stageArn = 'arn:aws:ivs:us-west-2:123456789012:stage/L210UYabcdef';
const createStageTokenRequest = new CreateParticipantTokenCommand({
  stageArn,
});
const response = await ivsRealtimeClient.send(createStageTokenRequest);
console.log('token', response.participantToken.token);
```

# 步驟 4：整合 IVS 廣播 SDK
<a name="getting-started-broadcast-sdk"></a>

IVS 提供適用於 Web、Android 和 iOS 的廣播 SDK，並且您可以將其整合至應用程式。廣播 SDK 用於傳送和接收影片。如果已[為舞台設定 RTMP 擷取](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/rt-stream-ingest.html)，則可以使用任何可以廣播到 RTMP 端點的編碼器 (例如 OBS 或 ffmpeg)。

在本節中，我們編寫了一個簡單的應用程式，讓兩個或更多參與者可以即時進行互動。下列步驟將引導您建立一個稱為 BasicRealTime 的應用程式。應用程式的完整程式碼位於 CodePen 和 GitHub：
+  Web：[https://codepen.io/amazon-ivs/pen/ZEqgrpo](https://codepen.io/amazon-ivs/pen/ZEqgrpo) 
+  Android 版：[https://github.com/aws-samples/amazon-ivs-real-time-streaming-android-samples](https://github.com/aws-samples/amazon-ivs-real-time-streaming-android-samples) 
+  iOS 版：[https://github.com/aws-samples/amazon-ivs-real-time-streaming-ios-samples](https://github.com/aws-samples/amazon-ivs-real-time-streaming-ios-samples) 

## Web
<a name="getting-started-broadcast-sdk-web"></a>

### 設定檔案
<a name="getting-started-broadcast-sdk-web-setup"></a>

首先，建立資料夾和初始 HTML 和 JS 檔案來設定檔案：

```
mkdir realtime-web-example
cd realtime-web-example
touch index.html
touch app.js
```

您可以使用指令碼標籤或 NPM 來安裝廣播 SDK。為了簡單起見，範例使用指令碼標籤，但如果您稍後選擇使用 NPM，修改起來會很容易。

### 使用指令碼標籤
<a name="getting-started-broadcast-sdk-web-script"></a>

Web 廣播開發套件以 JavaScript 程式庫的形式發佈，可以在 [https://web-broadcast.live-video.net/1.33.0/amazon-ivs-web-broadcast.js](https://web-broadcast.live-video.net/1.33.0/amazon-ivs-web-broadcast.js) 上擷取。

透過 `<script>` 標籤載入時，程式庫會在名為 `IVSBroadcastClient` 的視窗範圍中公開全域變數。

### 使用 NPM
<a name="getting-started-broadcast-sdk-web-npm"></a>

安裝 NPM 套件：

```
npm install amazon-ivs-web-broadcast
```

您現在可以存取 IVSBroadcastClient 物件：

```
const { Stage } = IVSBroadcastClient;
```

## Android
<a name="getting-started-broadcast-sdk-android"></a>

### 建立 Android 專案
<a name="getting-started-broadcast-sdk-android-project"></a>

1. 在 Android Studio 中，建立**新專案**。

1. 選擇**空白檢視活動**。

   注意：在舊版 Android Studio 中，以檢視為基礎的活動被稱為**空活動**。如果您的 Android Studio 視窗顯示**空活動**，並確實*不*顯示**空檢視**活動，則請選取**空活動**。否則，請勿選取**空活動**，因為我們將使用 View API (而不是 Jetpack Compose)。

1. 為您的專案**命名**，然後選取**完成**。

### 安裝廣播 SDK
<a name="getting-started-broadcast-sdk-android-install"></a>

若要將 Amazon IVS Android 廣播程式庫新增到您的 Android 開發環境中，請將該程式庫新增到模組的 `build.gradle` 檔案，如下所示 (適用於 Amazon IVS 廣播 SDK 的最新版本)。在較新的專案中，`mavenCentral` 儲存庫可能已包含在您的 `settings.gradle` 檔案中，如果是這種情況，則您可以省略 `repositories` 區塊。在我們的範例中，也需要在 `android` 區塊中啟用資料繫結。

```
android {
    dataBinding.enabled true
}

repositories {
    mavenCentral()
}
 
dependencies {
     implementation 'com.amazonaws:ivs-broadcast:1.40.0:stages@aar'
}
```

或者，若要手動安裝 SDK，請從此位置下載最新版本：

[https://search.maven.org/artifact/com.amazonaws/ivs-broadcast](https://search.maven.org/artifact/com.amazonaws/ivs-broadcast)

## iOS
<a name="getting-started-broadcast-sdk-ios"></a>

### 建立 iOS 專案
<a name="getting-started-broadcast-sdk-ios-project"></a>

1. 建立新的 Xcode 專案。

1. 若是**平台**，請選取 **iOS**。

1. 若是**應用程式**，請選取**应用程式**。

1. 輸入應用程式的**產品名稱**，然後選取**下一步**。

1. 選擇 (導覽至) 儲存專案的目錄，然後選取**建立**。

接著，您需要在 SDK 使用。如需指示，請參閱 *iOS 廣播 SDK 指南*中的[安裝程式庫](broadcast-ios-getting-started.md#broadcast-ios-install)。

### 設定許可
<a name="getting-started-broadcast-sdk-ios-config"></a>

您需要更新您的專案 `Info.plist`，以新增 `NSCameraUsageDescription` 和 `NSMicrophoneUsageDescription` 的兩個項目。針對這些值，請提供解釋應用程式為何要求攝影機和麥克風存取權的面向使用者的說明。

![\[設定 iOS 許可\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/iOS_Configure.png)


# 步驟 5：發布和訂閱影片
<a name="getting-started-pub-sub"></a>

您可以使用下列方式發布到 IVS/訂閱 (即時) IVS：
+ 支援 WebRTC 和 RTMPS 的原生 [IVS 廣播 SDK](https://docs.aws.amazon.com//ivs/latest/LowLatencyUserGuide/getting-started-set-up-streaming.html#broadcast-sdk)。建議採用此方式，尤其在生產情境下更是如此。請參閱下列有關 [Web](getting-started-pub-sub-web.md)、[Android](getting-started-pub-sub-android.md) 和 [iOS](getting-started-pub-sub-ios.md) 的詳細資訊。
+ Amazon IVS 主控台：適用於測試串流。請參閱以下 。
+ 其他串流軟體和硬體編碼器：您可以使用任何支援 RTMP、RTMPS 或 WHIP 通訊協定的串流編碼器。如需詳細資訊，請參閱[串流擷取](rt-stream-ingest.md)。

## IVS 主控台
<a name="getting-started-pub-sub-console"></a>

1. 開啟 [Amazon IVS 主控台](https://console.aws.amazon.com/ivs)。

   (您也可以透過 [AWS 管理主控台](https://console.aws.amazon.com/)來存取 Amazon IVS 主控台。)

1. 在導覽窗格中，選取**舞台**。(如果導覽窗格已收起，選取漢堡圖示即可展開。)

1. 選取您要訂閱或向其進行發布的舞台，以前往其詳細資訊頁面。

1. 若要訂閱：如果舞台有一或多名發布者，您可以按下**訂閱**索引標籤下的**訂閱**按鈕來進行訂閱。(索引標籤位於**一般組態**區段下方)。

1. 若要發布：

   1. 選取**發布**索引標籤。

   1. 系統會提示您授予 IVS 主控台存取攝影機和麥克風的權限；請**允許**這些權限。

   1. 在**發布**索引標籤的底部，使用下拉式方塊選取麥克風和攝影機的輸入裝置。

   1. 若要開始發布，請選取**開始發布**。

   1. 若要檢視已發布的內容，請返回**訂閱**索引標籤。

   1. 若要停止發布，請前往**發布**索引標籤，並將按下底部的**停止發布**按鈕。

**注意**：訂閱和發布會耗用資源，而且連線到舞台的時間會產生每小時費用。若要進一步了解，請參閱 IVS 定價頁面上的[即時串流](https://aws.amazon.com/ivs/pricing/#Real-Time_Streaming)。

# 使用 IVS Web 廣播 SDK 發布和訂閱
<a name="getting-started-pub-sub-web"></a>

本節將引導您完成使用 Web 應用程式發布和訂閱階段的相關步驟。

## 建立 HTML 樣板
<a name="getting-started-pub-sub-web-html"></a>

首先，建立 HTML 樣板並將程式庫匯入為指令碼標籤：

```
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />

  <!-- Import the SDK -->
  <script src="https://web-broadcast.live-video.net/1.33.0/amazon-ivs-web-broadcast.js"></script>
</head>

<body>

<!-- TODO - fill in with next sections -->
<script src="./app.js"></script>

</body>
</html>
```

## 接受權杖輸入並新增加入/離開按鈕
<a name="getting-started-pub-sub-web-join"></a>

在這裡用輸入控制填寫內文。這些做為輸入權杖，然後設定**加入**和**離開**按鈕。通常，應用程式會透過您的應用程式 API 請求權杖，但在本範例中，您將複製權杖並將其貼至權杖輸入。

```
<h1>IVS Real-Time Streaming</h1>
<hr />

<label for="token">Token</label>
<input type="text" id="token" name="token" />
<button class="button" id="join-button">Join</button>
<button class="button" id="leave-button" style="display: none;">Leave</button>
<hr />
```

## 新增媒體容器元素
<a name="getting-started-pub-sub-web-media"></a>

這些元素將為本機和遠端參與者保留媒體。新增了一個指令碼標籤，來載入 `app.js` 中定義的應用程式邏輯。

```
<!-- Local Participant -->
<div id="local-media"></div>

<!-- Remote Participants -->
<div id="remote-media"></div>

<!-- Load Script -->
<script src="./app.js"></script>
```

這樣就完成了 HTML 頁面，並且您應在瀏覽器中載入 `index.html` 時看到此頁面：

![\[在瀏覽器中檢視即時串流：HTML 設定完成。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/RT_Browser_View.png)


## 建立 app.js
<a name="getting-started-pub-sub-web-appjs"></a>

繼續來定義 `app.js` 檔案的內容。首先，透過 SDK 的全域匯入所有必要的屬性：

```
const {
  Stage,
  LocalStageStream,
  SubscribeType,
  StageEvents,
  ConnectionState,
  StreamType
} = IVSBroadcastClient;
```

## 建立應用程式變數
<a name="getting-started-pub-sub-web-vars"></a>

建立變數來保留**加入**和**離開**按鈕 HTML 元素的參考，以及存放應用程式的狀態：

```
let joinButton = document.getElementById("join-button");
let leaveButton = document.getElementById("leave-button");

// Stage management
let stage;
let joining = false;
let connected = false;
let localCamera;
let localMic;
let cameraStageStream;
let micStageStream;
```

## 建立 joinStage 1：定義函數並驗證輸入
<a name="getting-started-pub-sub-web-joinstage1"></a>

該 `joinStage` 函數採用輸入權杖，建立與階段的連線，並開始發布從 `getUserMedia` 中擷取的影片和音訊。

首先，定義函數並驗證狀態和權杖輸入。我們將在接下來的幾個部分完善此功能。

```
const joinStage = async () => {
  if (connected || joining) {
    return;
  }
  joining = true;

  const token = document.getElementById("token").value;

  if (!token) {
    window.alert("Please enter a participant token");
    joining = false;
    return;
  }

  // Fill in with the next sections
};
```

## 建立 JoinSage 2：取得要發布的媒體
<a name="getting-started-pub-sub-web-joinstage2"></a>

以下是將在階段上發布的媒體：

```
async function getCamera() {
  // Use Max Width and Height
  return navigator.mediaDevices.getUserMedia({
    video: true,
    audio: false
  });
}

async function getMic() {
  return navigator.mediaDevices.getUserMedia({
    video: false,
    audio: true
  });
}

// Retrieve the User Media currently set on the page
localCamera = await getCamera();
localMic = await getMic();

// Create StageStreams for Audio and Video
cameraStageStream = new LocalStageStream(localCamera.getVideoTracks()[0]);
micStageStream = new LocalStageStream(localMic.getAudioTracks()[0]);
```

## 建立 JoinSage 3：定義階段策略並建立階段
<a name="getting-started-pub-sub-web-joinstage3"></a>

此階段策略是 SDK 用於決定發布內容，以及要訂閱哪些參與者的決策邏輯核心。如需函數用途的詳細資訊，請參閱[策略](web-publish-subscribe.md#web-publish-subscribe-concepts-strategy)。

這項策略很簡單。加入階段後，發布剛剛擷取的串流，並訂閱每個遠端參與者的音訊和影片：

```
const strategy = {
  stageStreamsToPublish() {
    return [cameraStageStream, micStageStream];
  },
  shouldPublishParticipant() {
    return true;
  },
  shouldSubscribeToParticipant() {
    return SubscribeType.AUDIO_VIDEO;
  }
};

stage = new Stage(token, strategy);
```

## 建立 JoinSage 4：處理階段事件並轉譯媒體
<a name="getting-started-pub-sub-web-joinstage4"></a>

階段會發出許多事件。我們需要監聽 `STAGE_PARTICIPANT_STREAMS_ADDED` 和 `STAGE_PARTICIPANT_LEFT` 來回轉譯和移除頁面中的媒體。更詳盡的事件集列於[活動](web-publish-subscribe.md#web-publish-subscribe-concepts-events)中。

請注意，我們在這裡建立了四個協助程式函數，來協助管理必要的 DOM 元素：`setupParticipant`、`teardownParticipant`、`createVideoEl` 和 `createContainer`。

```
stage.on(StageEvents.STAGE_CONNECTION_STATE_CHANGED, (state) => {
  connected = state === ConnectionState.CONNECTED;

  if (connected) {
    joining = false;
    joinButton.style = "display: none";
    leaveButton.style = "display: inline-block";
  }
});

stage.on(
  StageEvents.STAGE_PARTICIPANT_STREAMS_ADDED,
  (participant, streams) => {
    console.log("Participant Media Added: ", participant, streams);

    let streamsToDisplay = streams;

    if (participant.isLocal) {
      // Ensure to exclude local audio streams, otherwise echo will occur
      streamsToDisplay = streams.filter(
        (stream) => stream.streamType === StreamType.VIDEO
      );
    }

    const videoEl = setupParticipant(participant);
    streamsToDisplay.forEach((stream) =>
      videoEl.srcObject.addTrack(stream.mediaStreamTrack)
    );
  }
);

stage.on(StageEvents.STAGE_PARTICIPANT_LEFT, (participant) => {
  console.log("Participant Left: ", participant);
  teardownParticipant(participant);
});


// Helper functions for managing DOM

function setupParticipant({ isLocal, id }) {
  const groupId = isLocal ? "local-media" : "remote-media";
  const groupContainer = document.getElementById(groupId);

  const participantContainerId = isLocal ? "local" : id;
  const participantContainer = createContainer(participantContainerId);
  const videoEl = createVideoEl(participantContainerId);

  participantContainer.appendChild(videoEl);
  groupContainer.appendChild(participantContainer);

  return videoEl;
}

function teardownParticipant({ isLocal, id }) {
  const groupId = isLocal ? "local-media" : "remote-media";
  const groupContainer = document.getElementById(groupId);
  const participantContainerId = isLocal ? "local" : id;

  const participantDiv = document.getElementById(
    participantContainerId + "-container"
  );
  if (!participantDiv) {
    return;
  }
  groupContainer.removeChild(participantDiv);
}

function createVideoEl(id) {
  const videoEl = document.createElement("video");
  videoEl.id = id;
  videoEl.autoplay = true;
  videoEl.playsInline = true;
  videoEl.srcObject = new MediaStream();
  return videoEl;
}

function createContainer(id) {
  const participantContainer = document.createElement("div");
  participantContainer.classList = "participant-container";
  participantContainer.id = id + "-container";

  return participantContainer;
}
```

## 建立 JoinSage 5：加入階段
<a name="getting-started-pub-sub-web-joinstage5"></a>

最終加入階段以完成 `joinStage` 函數！

```
try {
  await stage.join();
} catch (err) {
  joining = false;
  connected = false;
  console.error(err.message);
}
```

## 建立 leaveStage
<a name="getting-started-pub-sub-web-leavestage"></a>

定義 `leaveStage` 離開按鈕將調用的函數。

```
const leaveStage = async () => {
  stage.leave();

  joining = false;
  connected = false;
};
```

## 初始化輸入事件處理常式
<a name="getting-started-pub-sub-web-handlers"></a>

將新增一個最後的函數至 `app.js` 檔案。當載入頁面並建立事件處理常式以加入和離開階段時，會立即調用此函數。

```
const init = async () => {
  try {
    // Prevents issues on Safari/FF so devices are not blank
    await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
  } catch (e) {
    alert(
      "Problem retrieving media! Enable camera and microphone permissions."
    );
  }

  joinButton.addEventListener("click", () => {
    joinStage();
  });

  leaveButton.addEventListener("click", () => {
    leaveStage();
    joinButton.style = "display: inline-block";
    leaveButton.style = "display: none";
  });
};

init(); // call the function
```

## 執行應用程式並提供權杖
<a name="getting-started-pub-sub-run-app"></a>

此時，您可以在本地或與其他人分享網頁，[打開頁面](#getting-started-pub-sub-web-media)，然後輸入參與者權杖並加入階段。

## 後續步驟？
<a name="getting-started-pub-sub-next"></a>

有關 npm、React 等的更詳細範例，請參閱 [IVS 廣播 SDK：網絡指南（即時串流指南）](broadcast-web.md)。

# 使用 IVS Android 廣播 SDK 發布和訂閱
<a name="getting-started-pub-sub-android"></a>

本節將引導您完成使用 Android 應用程式發布和訂閱階段的相關步驟。

## 建立檢視
<a name="getting-started-pub-sub-android-views"></a>

首先使用自動建立的 `activity_main.xml` 檔案，來建立應用程式的簡單配置。配置包含一個可新增權杖的 `EditText`、一個加入 `Button`、一個可顯示階段狀態的 `TextView`，以及一個可切換發布的 `CheckBox`。

![\[為您的 Android 應用程式設定發布配置。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_Android_1.png)


以下是檢視背後的 XML：

```
<?xml version="1.0" encoding="utf-8"?>
<layout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools">

    <androidx.constraintlayout.widget.ConstraintLayout
        android:keepScreenOn="true"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context=".BasicActivity">

        <androidx.constraintlayout.widget.ConstraintLayout
            android:id="@+id/main_controls_container"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:background="@color/cardview_dark_background"
            android:padding="12dp"
            app:layout_constraintTop_toTopOf="parent">

            <EditText
                android:id="@+id/main_token"
                android:layout_width="0dp"
                android:layout_height="wrap_content"
                android:autofillHints="@null"
                android:backgroundTint="@color/white"
                android:hint="@string/token"
                android:imeOptions="actionDone"
                android:inputType="text"
                android:textColor="@color/white"
                app:layout_constraintEnd_toStartOf="@id/main_join"
                app:layout_constraintStart_toStartOf="parent"
                app:layout_constraintTop_toTopOf="parent" />

            <Button
                android:id="@+id/main_join"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:backgroundTint="@color/black"
                android:text="@string/join"
                android:textAllCaps="true"
                android:textColor="@color/white"
                android:textSize="16sp"
                app:layout_constraintBottom_toBottomOf="@+id/main_token"
                app:layout_constraintEnd_toEndOf="parent"
                app:layout_constraintStart_toEndOf="@id/main_token" />

            <TextView
                android:id="@+id/main_state"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:text="@string/state"
                android:textColor="@color/white"
                android:textSize="18sp"
                app:layout_constraintBottom_toBottomOf="parent"
                app:layout_constraintStart_toStartOf="parent"
                app:layout_constraintTop_toBottomOf="@id/main_token" />

            <TextView
                android:id="@+id/main_publish_text"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:text="@string/publish"
                android:textColor="@color/white"
                android:textSize="18sp"
                app:layout_constraintBottom_toBottomOf="parent"
                app:layout_constraintEnd_toStartOf="@id/main_publish_checkbox"
                app:layout_constraintTop_toBottomOf="@id/main_token" />

            <CheckBox
                android:id="@+id/main_publish_checkbox"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:buttonTint="@color/white"
                android:checked="true"
                app:layout_constraintBottom_toBottomOf="@id/main_publish_text"
                app:layout_constraintEnd_toEndOf="parent"
                app:layout_constraintTop_toTopOf="@id/main_publish_text" />

        </androidx.constraintlayout.widget.ConstraintLayout>

        <androidx.recyclerview.widget.RecyclerView
            android:id="@+id/main_recycler_view"
            android:layout_width="match_parent"
            android:layout_height="0dp"
            app:layout_constraintTop_toBottomOf="@+id/main_controls_container"
            app:layout_constraintBottom_toBottomOf="parent" />

    </androidx.constraintlayout.widget.ConstraintLayout>
<layout>
```

我們在這裡引用了幾個字串 ID，因此，現在將建立整個 `strings.xml` 檔案：

```
<resources>
    <string name="app_name">BasicRealTime</string>
    <string name="join">Join</string>
    <string name="leave">Leave</string>
    <string name="token">Participant Token</string>
    <string name="publish">Publish</string>
    <string name="state">State: %1$s</string>
</resources>
```

將 XML 中的這些檢視連結至 `MainActivity.kt`:

```
import android.widget.Button
import android.widget.CheckBox
import android.widget.EditText
import android.widget.TextView
import androidx.recyclerview.widget.RecyclerView

private lateinit var checkboxPublish: CheckBox
private lateinit var recyclerView: RecyclerView
private lateinit var buttonJoin: Button
private lateinit var textViewState: TextView
private lateinit var editTextToken: EditText

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    checkboxPublish = findViewById(R.id.main_publish_checkbox)
    recyclerView = findViewById(R.id.main_recycler_view)
    buttonJoin = findViewById(R.id.main_join)
    textViewState = findViewById(R.id.main_state)
    editTextToken = findViewById(R.id.main_token)
}
```

現在，將為 `RecyclerView` 建立項目檢視。若要執行此操作，在 `res/layout` 目錄上按一下滑鼠右鍵，然後選取**新增 > 配置資源檔案**。將此新檔案命名為 `item_stage_participant.xml`。

![\[為您的 Android 應用程式 RecyclerView 建立項目檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_Android_2.png)


此項目的配置很簡單：包含一個用於轉譯參與者影片串流的檢視，以及一個用於顯示參與者資訊的標籤清單：

![\[為您的 Android 應用程式 RecyclerView 建立項目檢視 – 標籤。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_Android_3.png)


下面是 XML：

```
<?xml version="1.0" encoding="utf-8"?>
<com.amazonaws.ivs.realtime.basicrealtime.ParticipantItem xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <FrameLayout
        android:id="@+id/participant_preview_container"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:background="@android:color/darker_gray" />

    <LinearLayout
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginStart="8dp"
        android:layout_marginTop="8dp"
        android:background="#50000000"
        android:orientation="vertical"
        android:paddingLeft="4dp"
        android:paddingTop="2dp"
        android:paddingRight="4dp"
        android:paddingBottom="2dp"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent">

        <TextView
            android:id="@+id/participant_participant_id"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:textColor="@android:color/white"
            android:textSize="16sp"
            tools:text="You (Disconnected)" />

        <TextView
            android:id="@+id/participant_publishing"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:textColor="@android:color/white"
            android:textSize="16sp"
            tools:text="NOT_PUBLISHED" />

        <TextView
            android:id="@+id/participant_subscribed"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:textColor="@android:color/white"
            android:textSize="16sp"
            tools:text="NOT_SUBSCRIBED" />

        <TextView
            android:id="@+id/participant_video_muted"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:textColor="@android:color/white"
            android:textSize="16sp"
            tools:text="Video Muted: false" />

        <TextView
            android:id="@+id/participant_audio_muted"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:textColor="@android:color/white"
            android:textSize="16sp"
            tools:text="Audio Muted: false" />

        <TextView
            android:id="@+id/participant_audio_level"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:textColor="@android:color/white"
            android:textSize="16sp"
            tools:text="Audio Level: -100 dB" />

    </LinearLayout>

</com.amazonaws.ivs.realtime.basicrealtime.ParticipantItem>
```

此 XML 檔案擴充了尚未建立的類別 `ParticipantItem`。由於 XML 包括完整的命名空間，因此請務必將此 XML 檔案更新至您的命名空間。建立此類別並設定檢視，否則現在將其保留為空白。

建立一個新的 Kotlin 類別 `ParticipantItem`:

```
package com.amazonaws.ivs.realtime.basicrealtime

import android.content.Context
import android.util.AttributeSet
import android.widget.FrameLayout
import android.widget.TextView
import kotlin.math.roundToInt

class ParticipantItem @JvmOverloads constructor(
    context: Context,
    attrs: AttributeSet? = null,
    defStyleAttr: Int = 0,
    defStyleRes: Int = 0,
) : FrameLayout(context, attrs, defStyleAttr, defStyleRes) {

    private lateinit var previewContainer: FrameLayout
    private lateinit var textViewParticipantId: TextView
    private lateinit var textViewPublish: TextView
    private lateinit var textViewSubscribe: TextView
    private lateinit var textViewVideoMuted: TextView
    private lateinit var textViewAudioMuted: TextView
    private lateinit var textViewAudioLevel: TextView

    override fun onFinishInflate() {
        super.onFinishInflate()
        previewContainer = findViewById(R.id.participant_preview_container)
        textViewParticipantId = findViewById(R.id.participant_participant_id)
        textViewPublish = findViewById(R.id.participant_publishing)
        textViewSubscribe = findViewById(R.id.participant_subscribed)
        textViewVideoMuted = findViewById(R.id.participant_video_muted)
        textViewAudioMuted = findViewById(R.id.participant_audio_muted)
        textViewAudioLevel = findViewById(R.id.participant_audio_level)
    }
}
```

## 許可
<a name="getting-started-pub-sub-android-perms"></a>

若要使用攝影機和麥克風，您需要向使用者請求許可。我們對此遵循標準許可流程：

```
override fun onStart() {
    super.onStart()
    requestPermission()
}

private val requestPermissionLauncher =
    registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { permissions ->
        if (permissions[Manifest.permission.CAMERA] == true && permissions[Manifest.permission.RECORD_AUDIO] == true) {
            viewModel.permissionGranted() // we will add this later
        }
    }

private val permissions = listOf(
    Manifest.permission.CAMERA,
    Manifest.permission.RECORD_AUDIO,
)

private fun requestPermission() {
    when {
        this.hasPermissions(permissions) -> viewModel.permissionGranted() // we will add this later
        else -> requestPermissionLauncher.launch(permissions.toTypedArray())
    }
}

private fun Context.hasPermissions(permissions: List<String>): Boolean {
    return permissions.all {
        ContextCompat.checkSelfPermission(this, it) == PackageManager.PERMISSION_GRANTED
    }
}
```

## 應用程式狀態
<a name="getting-started-pub-sub-android-app-state"></a>

我們的應用程式會在 `MainViewModel.kt` 中本機追蹤參與者，並且使用 Kotlin 的 [StateFlow](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-state-flow/) 將狀態傳回至 `MainActivity`。

建立一個新的 Kotlin 類別 `MainViewModel`:

```
package com.amazonaws.ivs.realtime.basicrealtime

import android.app.Application
import androidx.lifecycle.AndroidViewModel

class MainViewModel(application: Application) : AndroidViewModel(application), Stage.Strategy, StageRenderer {

}
```

將在 `MainActivity.kt` 中管理檢視模型：

```
import androidx.activity.viewModels

private val viewModel: MainViewModel by viewModels()
```

若要使用 `AndroidViewModel` 和這些 Kotlin `ViewModel` 延伸，您需要將以下內容新增至模組的 `build.gradle` 檔案:

```
implementation 'androidx.core:core-ktx:1.10.1'
implementation "androidx.activity:activity-ktx:1.7.2"
implementation 'androidx.appcompat:appcompat:1.6.1'
implementation 'com.google.android.material:material:1.10.0'
implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"

def lifecycle_version = "2.6.1"
implementation "androidx.lifecycle:lifecycle-livedata-ktx:$lifecycle_version"
implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:$lifecycle_version"
implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
```

### RecyclerView Adapter
<a name="getting-started-pub-sub-android-app-state-recycler"></a>

我們將建立一個簡單的 `RecyclerView.Adapter` 子類別，以追蹤參與者並更新階段事件的 `RecyclerView`。首先，需要一個代表參與者的類別。建立一個新的 Kotlin 類別 `StageParticipant`:

```
package com.amazonaws.ivs.realtime.basicrealtime

import com.amazonaws.ivs.broadcast.Stage
import com.amazonaws.ivs.broadcast.StageStream

class StageParticipant(val isLocal: Boolean, var participantId: String?) {
    var publishState = Stage.PublishState.NOT_PUBLISHED
    var subscribeState = Stage.SubscribeState.NOT_SUBSCRIBED
    var streams = mutableListOf<StageStream>()

    val stableID: String
        get() {
            return if (isLocal) {
                "LocalUser"
            } else {
                requireNotNull(participantId)
            }
        }
}
```

我們將使用接下來會建立的 `ParticipantAdapter` 類別中的此類別。首先定義類別，並建立用於追蹤參與者的變數：

```
package com.amazonaws.ivs.realtime.basicrealtime

import android.view.LayoutInflater
import android.view.ViewGroup
import androidx.recyclerview.widget.RecyclerView

class ParticipantAdapter : RecyclerView.Adapter<ParticipantAdapter.ViewHolder>() {

    private val participants = mutableListOf<StageParticipant>()
```

此外還必須定義 `RecyclerView.ViewHolder`，再實作其餘的覆寫：

```
class ViewHolder(val participantItem: ParticipantItem) : RecyclerView.ViewHolder(participantItem)
```

使用此類別，可實作標準 `RecyclerView.Adapter` 覆寫：

```
override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): ViewHolder {
    val item = LayoutInflater.from(parent.context)
        .inflate(R.layout.item_stage_participant, parent, false) as ParticipantItem
    return ViewHolder(item)
}

override fun getItemCount(): Int {
    return participants.size
}

override fun getItemId(position: Int): Long =
    participants[position]
        .stableID
        .hashCode()
        .toLong()

override fun onBindViewHolder(holder: ViewHolder, position: Int) {
    return holder.participantItem.bind(participants[position])
}

override fun onBindViewHolder(holder: ViewHolder, position: Int, payloads: MutableList<Any>) {
    val updates = payloads.filterIsInstance<StageParticipant>()
    if (updates.isNotEmpty()) {
        updates.forEach { holder.participantItem.bind(it) // implemented later }
    } else {
        super.onBindViewHolder(holder, position, payloads)
    }
}
```

最後，我們新增一些新的方法，當對參與者做出變更時，將會從 `MainViewModel` 中呼叫這些方法。這些方法是轉接器上的標準 CRUD 作業。

```
fun participantJoined(participant: StageParticipant) {
    participants.add(participant)
    notifyItemInserted(participants.size - 1)
}

fun participantLeft(participantId: String) {
    val index = participants.indexOfFirst { it.participantId == participantId }
    if (index != -1) {
        participants.removeAt(index)
        notifyItemRemoved(index)
    }
}

fun participantUpdated(participantId: String?, update: (participant: StageParticipant) -> Unit) {
    val index = participants.indexOfFirst { it.participantId == participantId }
    if (index != -1) {
        update(participants[index])
        notifyItemChanged(index, participants[index])
    }
}
```

回到 `MainViewModel`，我們需要建立並保留此轉接器的參考：

```
internal val participantAdapter = ParticipantAdapter()
```

## 階段狀態
<a name="getting-started-pub-sub-android-views-stage-state"></a>

還需要追蹤 `MainViewModel` 內的一些階段狀態。現在，我們來定義這些屬性：

```
private val _connectionState = MutableStateFlow(Stage.ConnectionState.DISCONNECTED)
val connectionState = _connectionState.asStateFlow()

private var publishEnabled: Boolean = false
    set(value) {
        field = value
        // Because the strategy returns the value of `checkboxPublish.isChecked`, just call `refreshStrategy`.
        stage?.refreshStrategy()
    }

private var deviceDiscovery: DeviceDiscovery? = null
private var stage: Stage? = null
private var streams = mutableListOf<LocalStageStream>()
```

若要在加入階段之前查看您自己的預覽，我們會立即建立本機參與者：

```
init {
    deviceDiscovery = DeviceDiscovery(application)

    // Create a local participant immediately to render our camera preview and microphone stats
    val localParticipant = StageParticipant(true, null)
    participantAdapter.participantJoined(localParticipant)
}
```

我們希望確保在清除 `ViewModel` 時也清除這些資源。我們會馬上覆寫 `onCleared()`，因此不要忘了清除這些資源。

```
override fun onCleared() {
    stage?.release()
    deviceDiscovery?.release()
    deviceDiscovery = null
    super.onCleared()
}
```

現在，一旦授予許可，我們會填充本機 `streams`，實作之前呼叫的 `permissionsGranted` 方法：

```
internal fun permissionGranted() {
    val deviceDiscovery = deviceDiscovery ?: return
    streams.clear()
    val devices = deviceDiscovery.listLocalDevices()
    // Camera
    devices
        .filter { it.descriptor.type == Device.Descriptor.DeviceType.CAMERA }
        .maxByOrNull { it.descriptor.position == Device.Descriptor.Position.FRONT }
        ?.let { streams.add(ImageLocalStageStream(it)) }
    // Microphone
    devices
        .filter { it.descriptor.type == Device.Descriptor.DeviceType.MICROPHONE }
        .maxByOrNull { it.descriptor.isDefault }
        ?.let { streams.add(AudioLocalStageStream(it)) }

    stage?.refreshStrategy()

    // Update our local participant with these new streams
    participantAdapter.participantUpdated(null) {
        it.streams.clear()
        it.streams.addAll(streams)
    }
}
```

## 實作階段 SDK
<a name="getting-started-pub-sub-android-stage-sdk"></a>

以下是三個以即時功能為基礎的核心[概念](android-publish-subscribe.md#android-publish-subscribe-concepts)：階段、策略和轉譯器。設計目標是盡可能減少打造工作產品所需的用戶端邏輯數量。

### Stage.Strategy
<a name="getting-started-pub-sub-android-stage-sdk-strategy"></a>

`Stage.Strategy` 實作很簡單：

```
override fun stageStreamsToPublishForParticipant(
    stage: Stage,
    participantInfo: ParticipantInfo
): MutableList<LocalStageStream> {
    // Return the camera and microphone to be published.
    // This is only called if `shouldPublishFromParticipant` returns true.
    return streams
}

override fun shouldPublishFromParticipant(stage: Stage, participantInfo: ParticipantInfo): Boolean {
    return publishEnabled
}

override fun shouldSubscribeToParticipant(stage: Stage, participantInfo: ParticipantInfo): Stage.SubscribeType {
    // Subscribe to both audio and video for all publishing participants.
    return Stage.SubscribeType.AUDIO_VIDEO
}
```

總而言之，根據內部的 `publishEnabled` 狀態來發布，如果要發布，我們會發布之前收集的串流。最後，針對此範例，始終會訂閱其他參與者，同時接收其音訊和影片。

### StageRenderer
<a name="getting-started-pub-sub-android-stage-sdk-renderer"></a>

`StageRenderer` 實作也非常簡單，但要考慮包含相當多程式碼的函數數量。當 SDK 通知我們有關參與者的變更時，此轉譯器中的一般方法是更新 `ParticipantAdapter`。在某些情況下，對於本機參與者的處理方式有所不同，因為我們已決定自行管理他們，以便在他們加入之前查看其攝影機預覽。

```
override fun onError(exception: BroadcastException) {
    Toast.makeText(getApplication(), "onError ${exception.localizedMessage}", Toast.LENGTH_LONG).show()
    Log.e("BasicRealTime", "onError $exception")
}

override fun onConnectionStateChanged(
    stage: Stage,
    connectionState: Stage.ConnectionState,
    exception: BroadcastException?
) {
    _connectionState.value = connectionState
}

override fun onParticipantJoined(stage: Stage, participantInfo: ParticipantInfo) {
    if (participantInfo.isLocal) {
        // If this is the local participant joining the stage, update the participant with a null ID because we
        // manually added that participant when setting up our preview
        participantAdapter.participantUpdated(null) {
            it.participantId = participantInfo.participantId
        }
    } else {
        // If they are not local, add them normally
        participantAdapter.participantJoined(
            StageParticipant(
                participantInfo.isLocal,
                participantInfo.participantId
            )
        )
    }
}

override fun onParticipantLeft(stage: Stage, participantInfo: ParticipantInfo) {
    if (participantInfo.isLocal) {
        // If this is the local participant leaving the stage, update the ID but keep it around because
        // we want to keep the camera preview active
        participantAdapter.participantUpdated(participantInfo.participantId) {
            it.participantId = null
        }
    } else {
        // If they are not local, have them leave normally
        participantAdapter.participantLeft(participantInfo.participantId)
    }
}

override fun onParticipantPublishStateChanged(
    stage: Stage,
    participantInfo: ParticipantInfo,
    publishState: Stage.PublishState
) {
    // Update the publishing state of this participant
    participantAdapter.participantUpdated(participantInfo.participantId) {
        it.publishState = publishState
    }
}

override fun onParticipantSubscribeStateChanged(
    stage: Stage,
    participantInfo: ParticipantInfo,
    subscribeState: Stage.SubscribeState
) {
    // Update the subscribe state of this participant
    participantAdapter.participantUpdated(participantInfo.participantId) {
        it.subscribeState = subscribeState
    }
}

override fun onStreamsAdded(stage: Stage, participantInfo: ParticipantInfo, streams: MutableList<StageStream>) {
    // We don't want to take any action for the local participant because we track those streams locally
    if (participantInfo.isLocal) {
        return
    }
    // For remote participants, add these new streams to that participant's streams array.
    participantAdapter.participantUpdated(participantInfo.participantId) {
        it.streams.addAll(streams)
    }
}

override fun onStreamsRemoved(stage: Stage, participantInfo: ParticipantInfo, streams: MutableList<StageStream>) {
    // We don't want to take any action for the local participant because we track those streams locally
    if (participantInfo.isLocal) {
        return
    }
    // For remote participants, remove these streams from that participant's streams array.
    participantAdapter.participantUpdated(participantInfo.participantId) {
        it.streams.removeAll(streams)
    }
}

override fun onStreamsMutedChanged(
    stage: Stage,
    participantInfo: ParticipantInfo,
    streams: MutableList<StageStream>
) {
    // We don't want to take any action for the local participant because we track those streams locally
    if (participantInfo.isLocal) {
        return
    }
    // For remote participants, notify the adapter that the participant has been updated. There is no need to modify
    // the `streams` property on the `StageParticipant` because it is the same `StageStream` instance. Just
    // query the `isMuted` property again.
    participantAdapter.participantUpdated(participantInfo.participantId) {}
}
```

## 實作自訂 RecyclerView LayoutManager
<a name="getting-started-pub-sub-android-layout"></a>

配置不同數量的參與者可能很複雜。您希望他們佔用整個父檢視的框架，但不想單獨處理每個參與者配置。為了簡化這一點，我們將逐步實作 `RecyclerView.LayoutManager`。

建立另一個新類別 `StageLayoutManager`，這應當會延伸 `GridLayoutManager`。設計此類別的目的是，根據以流程為基礎的資料列/資料欄配置中的參與者人數，來計算每個參與者的配置。每個資料列的高度與其他資料列相同，但每個資料列的寬度可能有所差異。請參閱 `layouts` 變數上方的程式碼註解，描述了如何自訂此行為。

```
package com.amazonaws.ivs.realtime.basicrealtime

import android.content.Context
import androidx.recyclerview.widget.GridLayoutManager
import androidx.recyclerview.widget.RecyclerView

class StageLayoutManager(context: Context?) : GridLayoutManager(context, 6) {

    companion object {
        /**
         * This 2D array contains the description of how the grid of participants should be rendered
         * The index of the 1st dimension is the number of participants needed to active that configuration
         * Meaning if there is 1 participant, index 0 will be used. If there are 5 participants, index 4 will be used.
         *
         * The 2nd dimension is a description of the layout. The length of the array is the number of rows that
         * will exist, and then each number within that array is the number of columns in each row.
         *
         * See the code comments next to each index for concrete examples.
         *
         * This can be customized to fit any layout configuration needed.
         */
        val layouts: List<List<Int>> = listOf(
            // 1 participant
            listOf(1), // 1 row, full width
            // 2 participants
            listOf(1, 1), // 2 rows, all columns are full width
            // 3 participants
            listOf(1, 2), // 2 rows, first row's column is full width then 2nd row's columns are 1/2 width
            // 4 participants
            listOf(2, 2), // 2 rows, all columns are 1/2 width
            // 5 participants
            listOf(1, 2, 2), // 3 rows, first row's column is full width, 2nd and 3rd row's columns are 1/2 width
            // 6 participants
            listOf(2, 2, 2), // 3 rows, all column are 1/2 width
            // 7 participants
            listOf(2, 2, 3), // 3 rows, 1st and 2nd row's columns are 1/2 width, 3rd row's columns are 1/3rd width
            // 8 participants
            listOf(2, 3, 3),
            // 9 participants
            listOf(3, 3, 3),
            // 10 participants
            listOf(2, 3, 2, 3),
            // 11 participants
            listOf(2, 3, 3, 3),
            // 12 participants
            listOf(3, 3, 3, 3),
        )
    }

    init {
        spanSizeLookup = object : SpanSizeLookup() {
            override fun getSpanSize(position: Int): Int {
                if (itemCount <= 0) {
                    return 1
                }
                // Calculate the row we're in
                val config = layouts[itemCount - 1]
                var row = 0
                var curPosition = position
                while (curPosition - config[row] >= 0) {
                    curPosition -= config[row]
                    row++
                }
                // spanCount == max spans, config[row] = number of columns we want
                // So spanCount / config[row] would be something like 6 / 3 if we want 3 columns.
                // So this will take up 2 spans, with a max of 6 is 1/3rd of the view.
                return spanCount / config[row]
            }
        }
    }

    override fun onLayoutChildren(recycler: RecyclerView.Recycler?, state: RecyclerView.State?) {
        if (itemCount <= 0 || state?.isPreLayout == true) return

        val parentHeight = height
        val itemHeight = parentHeight / layouts[itemCount - 1].size // height divided by number of rows.

        // Set the height of each view based on how many rows exist for the current participant count.
        for (i in 0 until childCount) {
            val child = getChildAt(i) ?: continue
            val layoutParams = child.layoutParams as RecyclerView.LayoutParams
            if (layoutParams.height != itemHeight) {
                layoutParams.height = itemHeight
                child.layoutParams = layoutParams
            }
        }
        // After we set the height for all our views, call super.
        // This works because our RecyclerView can not scroll and all views are always visible with stable IDs.
        super.onLayoutChildren(recycler, state)
    }

    override fun canScrollVertically(): Boolean = false
    override fun canScrollHorizontally(): Boolean = false
}
```

回到 `MainActivity.kt`，我們需要為 `RecyclerView` 設定轉接器和配置管理器：

```
// In onCreate after setting recyclerView.
recyclerView.layoutManager = StageLayoutManager(this)
recyclerView.adapter = viewModel.participantAdapter
```

## 掛接 UI 動作
<a name="getting-started-pub-sub-android-actions"></a>

即將結束；我們只需掛接幾個 UI 動作。

首先，讓 `MainActivity` 觀測 `MainViewModel` 中的 `StateFlow` 變更：

```
// At the end of your onCreate method
lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.CREATED) {
        viewModel.connectionState.collect { state ->
            buttonJoin.setText(if (state == ConnectionState.DISCONNECTED) R.string.join else R.string.leave)
            textViewState.text = getString(R.string.state, state.name)
        }
    }
}
```

接著，將接聽程式新增至加入按鈕和發布核取方塊：

```
buttonJoin.setOnClickListener {
    viewModel.joinStage(editTextToken.text.toString())
}
checkboxPublish.setOnCheckedChangeListener { _, isChecked ->
    viewModel.setPublishEnabled(isChecked)
}
```

上述兩個呼叫功能均位於 `MainViewModel`，現在將在此實作：

```
internal fun joinStage(token: String) {
    if (_connectionState.value != Stage.ConnectionState.DISCONNECTED) {
        // If we're already connected to a stage, leave it.
        stage?.leave()
    } else {
        if (token.isEmpty()) {
            Toast.makeText(getApplication(), "Empty Token", Toast.LENGTH_SHORT).show()
            return
        }
        try {
            // Destroy the old stage first before creating a new one.
            stage?.release()
            val stage = Stage(getApplication(), token, this)
            stage.addRenderer(this)
            stage.join()
            this.stage = stage
        } catch (e: BroadcastException) {
            Toast.makeText(getApplication(), "Failed to join stage ${e.localizedMessage}", Toast.LENGTH_LONG).show()
            e.printStackTrace()
        }
    }
}

internal fun setPublishEnabled(enabled: Boolean) {
    publishEnabled = enabled
}
```

## 轉譯參與者
<a name="getting-started-pub-sub-android-participants"></a>

最後，我們需要將從 SDK 接收的資料，轉譯到之前建立的參與者項目上。我們已經完成了 `RecyclerView` 邏輯，因此只需實作 `ParticipantItem` 中的 `bind` API。

從新增空函數開始，然後逐步實作：

```
fun bind(participant: StageParticipant) {

}
```

首先，將處理簡易狀態、參與者 ID、發布狀態和訂閱狀態。對於這些，只需直接更新 `TextViews`：

```
val participantId = if (participant.isLocal) {
    "You (${participant.participantId ?: "Disconnected"})"
} else {
    participant.participantId
}
textViewParticipantId.text = participantId
textViewPublish.text = participant.publishState.name
textViewSubscribe.text = participant.subscribeState.name
```

接著，將更新音訊和影片靜音狀態。為取得靜音狀態，需要從串流陣列中找到 `ImageDevice` 和 `AudioDevice`。為優化效能，我們會記住上次連接的裝置 ID。

```
// This belongs outside the `bind` API.
private var imageDeviceUrn: String? = null
private var audioDeviceUrn: String? = null

// This belongs inside the `bind` API.
val newImageStream = participant
    .streams
    .firstOrNull { it.device is ImageDevice }
textViewVideoMuted.text = if (newImageStream != null) {
    if (newImageStream.muted) "Video muted" else "Video not muted"
} else {
    "No video stream"
}

val newAudioStream = participant
    .streams
    .firstOrNull { it.device is AudioDevice }
textViewAudioMuted.text = if (newAudioStream != null) {
    if (newAudioStream.muted) "Audio muted" else "Audio not muted"
} else {
    "No audio stream"
}
```

最後，要轉譯 `imageDevice` 的預覽：

```
if (newImageStream?.device?.descriptor?.urn != imageDeviceUrn) {
    // If the device has changed, remove all subviews from the preview container
    previewContainer.removeAllViews()
    (newImageStream?.device as? ImageDevice)?.let {
        val preview = it.getPreviewView(BroadcastConfiguration.AspectMode.FIT)
        previewContainer.addView(preview)
        preview.layoutParams = FrameLayout.LayoutParams(
            FrameLayout.LayoutParams.MATCH_PARENT,
            FrameLayout.LayoutParams.MATCH_PARENT
        )
    }
}
imageDeviceUrn = newImageStream?.device?.descriptor?.urn
```

然後顯示 `audioDevice` 中的音訊統計資料：

```
if (newAudioStream?.device?.descriptor?.urn != audioDeviceUrn) {
    (newAudioStream?.device as? AudioDevice)?.let {
        it.setStatsCallback { _, rms ->
            textViewAudioLevel.text = "Audio Level: ${rms.roundToInt()} dB"
        }
    }
}
audioDeviceUrn = newAudioStream?.device?.descriptor?.urn
```

# 使用 IVS iOS 廣播 SDK 發布和訂閱
<a name="getting-started-pub-sub-ios"></a>

本節將引導您完成使用 iOS 應用程式發布和訂閱階段的相關步驟。

## 建立檢視
<a name="getting-started-pub-sub-ios-views"></a>

首先，使用自動建立用於匯入 `AmazonIVSBroadcast` 的 `ViewController.swift` 檔案，然後新增一些要連結的 `@IBOutlets`：

```
import AmazonIVSBroadcast

class ViewController: UIViewController {

    @IBOutlet private var textFieldToken: UITextField!
    @IBOutlet private var buttonJoin: UIButton!
    @IBOutlet private var labelState: UILabel!
    @IBOutlet private var switchPublish: UISwitch!
    @IBOutlet private var collectionViewParticipants: UICollectionView!
```

現在，建立這些檢視，並在 `Main.storyboard` 中將其連結。以下是將使用的檢視結構：

![\[使用 Main.storyboard 來建立 iOS 檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_1.png)


若是 AutoLayout 組態，需要自訂三個檢視。第一個檢視是**集合檢視參與者** (`UICollectionView`)。將**前導**、**尾隨**和**底部**繫結至**安全區域**。同時將**頂部**繫結至**控制容器**。

![\[自訂 iOS 集合檢視參與者的檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_2.png)


第二個檢視是**控制容器**。將**前導**、**尾隨**和**頂部**繫結至**安全區域**。

![\[自訂 iOS 控制容器檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_3.png)


第三個和最後一個檢視是**垂直堆疊檢視**。將**頂部**、**前導**、**尾隨**和**底部**繫結至**父檢視**。針對樣式，將間距設定為 8，而不是 0。

![\[自訂 iOS 垂直堆疊檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_4.png)


**UIStackViews** 會處理其餘檢視的配置。針對所有三個 **UIStackViews**，在**對齊**和**分佈**時使用**填滿**。

![\[使用 UIStackViews 自訂其餘的 iOS 檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_5.png)


最後，將這些檢視連結至 `ViewController`。從上方映射下列檢視：
+ **文字欄位加入**繫結至 `textFieldToken`。
+ **按鈕加入**繫結至 `buttonJoin`。
+ **標籤狀態**繫結至 `labelState`。
+ **切換發布**繫結至 `switchPublish`。
+ **集合檢視參與者**繫結至 `collectionViewParticipants`。

同時還會將**集合檢視參與者**項目的 `dataSource` 設定為擁有的 `ViewController`:

![\[若是 iOS 應用程式，還會設定集合檢視參與者的資料來源。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_6.png)


現在，建立要在其中轉譯參與者的 `UICollectionViewCell` 子類別。首先，建立一個新的 **Cocoa Touch 類別**檔案：

![\[建立 UICollectionViewCell，以轉譯 iOS 即時參與者。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_7.png)


將其命名為 `ParticipantUICollectionViewCell`，然後使其成為 Swift 中 `UICollectionViewCell` 的子類別。再次從 Swift 檔案開始，建立要連結的 `@IBOutlets`：

```
import AmazonIVSBroadcast

class ParticipantCollectionViewCell: UICollectionViewCell {

    @IBOutlet private var viewPreviewContainer: UIView!
    @IBOutlet private var labelParticipantId: UILabel!
    @IBOutlet private var labelSubscribeState: UILabel!
    @IBOutlet private var labelPublishState: UILabel!
    @IBOutlet private var labelVideoMuted: UILabel!
    @IBOutlet private var labelAudioMuted: UILabel!
    @IBOutlet private var labelAudioVolume: UILabel!
```

在關聯的 XIB 檔案中，建立此檢視階層：

![\[在關聯的 XIB 檔案中，建立 iOS 檢視階層。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_8.png)


針對 AutoLayout，將再次修改三個檢視。第一個檢視是**檢視預覽容器**。將**尾隨**、**前導**、**頂部**和**底部**設定為**參與者集合檢視儲存格**。

![\[自訂 iOS 檢視預覽容器檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_9.png)


第二個檢視是**檢視**。將**前導**和**頂部**設定為**參與者集合檢視儲存格**，並將該值變更為 4。

![\[自訂 iOS 檢視的檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_10.png)


第三個檢視是**堆疊檢視**。將 **Trailing**、**Leading**、**Top** 和 **Bottom** 設定為 **Superview**，並將值變更為 4。

![\[自訂 iOS 堆疊檢視的檢視。\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_11.png)


## 許可和閒置計時器
<a name="getting-started-pub-sub-ios-perms"></a>

回到 `ViewController`，將停用系統閒置計時器，以免在使用應用程式時，裝置進入睡眠狀態：

```
override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)
    // Prevent the screen from turning off during a call.
    UIApplication.shared.isIdleTimerDisabled = true
}

override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    UIApplication.shared.isIdleTimerDisabled = false
}
```

接著，請求系統的攝影機和麥克風許可：

```
private func checkPermissions() {
    checkOrGetPermission(for: .video) { [weak self] granted in
        guard granted else {
            print("Video permission denied")
            return
        }
        self?.checkOrGetPermission(for: .audio) { [weak self] granted in
            guard granted else {
                print("Audio permission denied")
                return
            }
            self?.setupLocalUser() // we will cover this later
        }
    }
}

private func checkOrGetPermission(for mediaType: AVMediaType, _ result: @escaping (Bool) -> Void) {
    func mainThreadResult(_ success: Bool) {
        DispatchQueue.main.async {
            result(success)
        }
    }
    switch AVCaptureDevice.authorizationStatus(for: mediaType) {
    case .authorized: mainThreadResult(true)
    case .notDetermined:
        AVCaptureDevice.requestAccess(for: mediaType) { granted in
            mainThreadResult(granted)
        }
    case .denied, .restricted: mainThreadResult(false)
    @unknown default: mainThreadResult(false)
    }
}
```

## 應用程式狀態
<a name="getting-started-pub-sub-ios-app-state"></a>

需要設定 `collectionViewParticipants` 以及之前建立的配置檔案：

```
override func viewDidLoad() {
    super.viewDidLoad()
    // We render everything to exactly the frame, so don't allow scrolling.
    collectionViewParticipants.isScrollEnabled = false
    collectionViewParticipants.register(UINib(nibName: "ParticipantCollectionViewCell", bundle: .main), forCellWithReuseIdentifier: "ParticipantCollectionViewCell")
}
```

為了代表每個參與者，我們建立了一個稱為 `StageParticipant` 的簡單結構。這可包含在 `ViewController.swift` 檔案中，或建立新的檔案。

```
import Foundation
import AmazonIVSBroadcast

struct StageParticipant {
    let isLocal: Bool
    var participantId: String?
    var publishState: IVSParticipantPublishState = .notPublished
    var subscribeState: IVSParticipantSubscribeState = .notSubscribed
    var streams: [IVSStageStream] = []

    init(isLocal: Bool, participantId: String?) {
        self.isLocal = isLocal
        self.participantId = participantId
    }
}
```

為了追蹤這些參與者，我們將其陣列做為私有屬性保留在 `ViewController` 中:

```
private var participants = [StageParticipant]()
```

此屬性將用於支援之前從分鏡腳本連結的 `UICollectionViewDataSource`：

```
extension ViewController: UICollectionViewDataSource {

    func collectionView(_ collectionView: UICollectionView, numberOfItemsInSection section: Int) -> Int {
        return participants.count
    }

    func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        if let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "ParticipantCollectionViewCell", for: indexPath) as? ParticipantCollectionViewCell {
            cell.set(participant: participants[indexPath.row])
            return cell
        } else {
            fatalError("Couldn't load custom cell type 'ParticipantCollectionViewCell'")
        }
    }

}
```

若要在加入階段之前查看您自己的預覽，我們會立即建立本機參與者：

```
override func viewDidLoad() {
    /* existing UICollectionView code */
    participants.append(StageParticipant(isLocal: true, participantId: nil))
}
```

這會導致在應用程式執行後，代表本機參與者立即轉譯參與者儲存格。

使用者希望能夠在加入階段之前看到自己，因此，接下來我們實作 `setupLocalUser()` 方法，可從稍早的許可處理程式碼中呼叫。將攝影機和麥克風參考做為 `IVSLocalStageStream` 物件來存放。

```
private var streams = [IVSLocalStageStream]()
private let deviceDiscovery = IVSDeviceDiscovery()

private func setupLocalUser() {
    // Gather our camera and microphone once permissions have been granted
    let devices = deviceDiscovery.listLocalDevices()
    streams.removeAll()
    if let camera = devices.compactMap({ $0 as? IVSCamera }).first {
        streams.append(IVSLocalStageStream(device: camera))
        // Use a front camera if available.
        if let frontSource = camera.listAvailableInputSources().first(where: { $0.position == .front }) {
            camera.setPreferredInputSource(frontSource)
        }
    }
    if let mic = devices.compactMap({ $0 as? IVSMicrophone }).first {
        streams.append(IVSLocalStageStream(device: mic))
    }
    participants[0].streams = streams
    participantsChanged(index: 0, changeType: .updated)
}
```

在這裡透過 SDK 找到了裝置的攝影機和麥克風，並將其存放在本機 `streams` 物件中，然後將第一個參與者 (我們之前建立的本機參與者) 的 `streams` 陣列指派到 `streams`。最後，呼叫 `index` 為 0，以及 `changeType` 為 `updated` 的 `participantsChanged`。該函數是透過良好的動畫更新 `UICollectionView` 的輔助程式函數。這是呈現的外觀：

```
private func participantsChanged(index: Int, changeType: ChangeType) {
    switch changeType {
    case .joined:
        collectionViewParticipants?.insertItems(at: [IndexPath(item: index, section: 0)])
    case .updated:
        // Instead of doing reloadItems, just grab the cell and update it ourselves. It saves a create/destroy of a cell
        // and more importantly fixes some UI flicker. We disable scrolling so the index path per cell
        // never changes.
        if let cell = collectionViewParticipants?.cellForItem(at: IndexPath(item: index, section: 0)) as? ParticipantCollectionViewCell {
            cell.set(participant: participants[index])
        }
    case .left:
        collectionViewParticipants?.deleteItems(at: [IndexPath(item: index, section: 0)])
    }
}
```

別擔心 `cell.set`；稍後會處理，這就是我們將根據參與者轉譯儲存格內容的地方。

`ChangeType` 是一個簡單的列舉：

```
enum ChangeType {
    case joined, updated, left
}
```

最後，想要追蹤階段是否已建立連線。使用一個簡單的 `bool` 來追蹤，在其自行更新時，會自動更新 UI。

```
private var connectingOrConnected = false {
    didSet {
        buttonJoin.setTitle(connectingOrConnected ? "Leave" : "Join", for: .normal)
        buttonJoin.tintColor = connectingOrConnected ? .systemRed : .systemBlue
    }
}
```

## 實作階段 SDK
<a name="getting-started-pub-sub-ios-stage-sdk"></a>

以下是三個以即時功能為基礎的核心[概念](ios-publish-subscribe.md#ios-publish-subscribe-concepts)：階段、策略和轉譯器。設計目標是盡可能減少打造工作產品所需的用戶端邏輯數量。

### IVSStageStrategy
<a name="getting-started-pub-sub-ios-stage-sdk-strategy"></a>

`IVSStageStrategy` 實作很簡單：

```
extension ViewController: IVSStageStrategy {
    func stage(_ stage: IVSStage, streamsToPublishForParticipant participant: IVSParticipantInfo) -> [IVSLocalStageStream] {
        // Return the camera and microphone to be published.
        // This is only called if `shouldPublishParticipant` returns true.
        return streams
    }

    func stage(_ stage: IVSStage, shouldPublishParticipant participant: IVSParticipantInfo) -> Bool {
        // Our publish status is based directly on the UISwitch view
        return switchPublish.isOn
    }

    func stage(_ stage: IVSStage, shouldSubscribeToParticipant participant: IVSParticipantInfo) -> IVSStageSubscribeType {
        // Subscribe to both audio and video for all publishing participants.
        return .audioVideo
    }
}
```

總而言之，只有在發布切換按鈕處於「開啟」位置時才會發布，如果要發布，我們會發布之前收集的串流。最後，針對此範例，始終會訂閱其他參與者，同時接收其音訊和影片。

### IVSStageRenderer
<a name="getting-started-pub-sub-ios-stage-sdk-renderer"></a>

`IVSStageRenderer` 實作也非常簡單，但要考慮包含相當多程式碼的函數數量。當 SDK 通知我們有關參與者的變更時，此轉譯器中的一般方法是更新我們的 `participants` 陣列。在某些情況下，對於本機參與者的處理方式有所不同，因為我們已決定自行管理他們，以便在他們加入之前查看其攝影機預覽。

```
extension ViewController: IVSStageRenderer {

    func stage(_ stage: IVSStage, didChange connectionState: IVSStageConnectionState, withError error: Error?) {
        labelState.text = connectionState.text
        connectingOrConnected = connectionState != .disconnected
    }

    func stage(_ stage: IVSStage, participantDidJoin participant: IVSParticipantInfo) {
        if participant.isLocal {
            // If this is the local participant joining the Stage, update the first participant in our array because we
            // manually added that participant when setting up our preview
            participants[0].participantId = participant.participantId
            participantsChanged(index: 0, changeType: .updated)
        } else {
            // If they are not local, add them to the array as a newly joined participant.
            participants.append(StageParticipant(isLocal: false, participantId: participant.participantId))
            participantsChanged(index: (participants.count - 1), changeType: .joined)
        }
    }

    func stage(_ stage: IVSStage, participantDidLeave participant: IVSParticipantInfo) {
        if participant.isLocal {
            // If this is the local participant leaving the Stage, update the first participant in our array because
            // we want to keep the camera preview active
            participants[0].participantId = nil
            participantsChanged(index: 0, changeType: .updated)
        } else {
            // If they are not local, find their index and remove them from the array.
            if let index = participants.firstIndex(where: { $0.participantId == participant.participantId }) {
                participants.remove(at: index)
                participantsChanged(index: index, changeType: .left)
            }
        }
    }

    func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didChange publishState: IVSParticipantPublishState) {
        // Update the publishing state of this participant
        mutatingParticipant(participant.participantId) { data in
            data.publishState = publishState
        }
    }

    func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didChange subscribeState: IVSParticipantSubscribeState) {
        // Update the subscribe state of this participant
        mutatingParticipant(participant.participantId) { data in
            data.subscribeState = subscribeState
        }
    }

    func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didChangeMutedStreams streams: [IVSStageStream]) {
        // We don't want to take any action for the local participant because we track those streams locally
        if participant.isLocal { return }
        // For remote participants, notify the UICollectionView that they have updated. There is no need to modify
        // the `streams` property on the `StageParticipant` because it is the same `IVSStageStream` instance. Just
        // query the `isMuted` property again.
        if let index = participants.firstIndex(where: { $0.participantId == participant.participantId }) {
            participantsChanged(index: index, changeType: .updated)
        }
    }

    func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didAdd streams: [IVSStageStream]) {
        // We don't want to take any action for the local participant because we track those streams locally
        if participant.isLocal { return }
        // For remote participants, add these new streams to that participant's streams array.
        mutatingParticipant(participant.participantId) { data in
            data.streams.append(contentsOf: streams)
        }
    }

    func stage(_ stage: IVSStage, participant: IVSParticipantInfo, didRemove streams: [IVSStageStream]) {
        // We don't want to take any action for the local participant because we track those streams locally
        if participant.isLocal { return }
        // For remote participants, remove these streams from that participant's streams array.
        mutatingParticipant(participant.participantId) { data in
            let oldUrns = streams.map { $0.device.descriptor().urn }
            data.streams.removeAll(where: { stream in
                return oldUrns.contains(stream.device.descriptor().urn)
            })
        }
    }

    // A helper function to find a participant by its ID, mutate that participant, and then update the UICollectionView accordingly.
    private func mutatingParticipant(_ participantId: String?, modifier: (inout StageParticipant) -> Void) {
        guard let index = participants.firstIndex(where: { $0.participantId == participantId }) else {
            fatalError("Something is out of sync, investigate if this was a sample app or SDK issue.")
        }

        var participant = participants[index]
        modifier(&participant)
        participants[index] = participant
        participantsChanged(index: index, changeType: .updated)
    }
}
```

此程式碼使用延伸，將連線狀態轉換為易讀的文字：

```
extension IVSStageConnectionState {
    var text: String {
        switch self {
        case .disconnected: return "Disconnected"
        case .connecting: return "Connecting"
        case .connected: return "Connected"
        @unknown default: fatalError()
        }
    }
}
```

## 實作自訂 UICollectionViewLayout
<a name="getting-started-pub-sub-ios-layout"></a>

配置不同數量的參與者可能很複雜。您希望他們佔用整個父檢視的框架，但不想單獨處理每個參與者配置。為了簡化這一點，我們將逐步實作 `UICollectionViewLayout`。

建立另一個新檔案 `ParticipantCollectionViewLayout.swift`，這應當會延伸 `UICollectionViewLayout`。此類別會使用另一個稱為 `StageLayoutCalculator` 類別，我們很快會介紹。該類別會接收針對每個參與者計算的影格值，然後產生必要的 `UICollectionViewLayoutAttributes` 物件。

```
import Foundation
import UIKit

/**
 Code modified from https://developer.apple.com/documentation/uikit/views_and_controls/collection_views/layouts/customizing_collection_view_layouts?language=objc
 */
class ParticipantCollectionViewLayout: UICollectionViewLayout {

    private let layoutCalculator = StageLayoutCalculator()

    private var contentBounds = CGRect.zero
    private var cachedAttributes = [UICollectionViewLayoutAttributes]()

    override func prepare() {
        super.prepare()

        guard let collectionView = collectionView else { return }

        cachedAttributes.removeAll()
        contentBounds = CGRect(origin: .zero, size: collectionView.bounds.size)

        layoutCalculator.calculateFrames(participantCount: collectionView.numberOfItems(inSection: 0),
                                         width: collectionView.bounds.size.width,
                                         height: collectionView.bounds.size.height,
                                         padding: 4)
        .enumerated()
        .forEach { (index, frame) in
            let attributes = UICollectionViewLayoutAttributes(forCellWith: IndexPath(item: index, section: 0))
            attributes.frame = frame
            cachedAttributes.append(attributes)
            contentBounds = contentBounds.union(frame)
        }
    }

    override var collectionViewContentSize: CGSize {
        return contentBounds.size
    }

    override func shouldInvalidateLayout(forBoundsChange newBounds: CGRect) -> Bool {
        guard let collectionView = collectionView else { return false }
        return !newBounds.size.equalTo(collectionView.bounds.size)
    }

    override func layoutAttributesForItem(at indexPath: IndexPath) -> UICollectionViewLayoutAttributes? {
        return cachedAttributes[indexPath.item]
    }

    override func layoutAttributesForElements(in rect: CGRect) -> [UICollectionViewLayoutAttributes]? {
        var attributesArray = [UICollectionViewLayoutAttributes]()

        // Find any cell that sits within the query rect.
        guard let lastIndex = cachedAttributes.indices.last, let firstMatchIndex = binSearch(rect, start: 0, end: lastIndex) else {
            return attributesArray
        }

        // Starting from the match, loop up and down through the array until all the attributes
        // have been added within the query rect.
        for attributes in cachedAttributes[..<firstMatchIndex].reversed() {
            guard attributes.frame.maxY >= rect.minY else { break }
            attributesArray.append(attributes)
        }

        for attributes in cachedAttributes[firstMatchIndex...] {
            guard attributes.frame.minY <= rect.maxY else { break }
            attributesArray.append(attributes)
        }

        return attributesArray
    }

    // Perform a binary search on the cached attributes array.
    func binSearch(_ rect: CGRect, start: Int, end: Int) -> Int? {
        if end < start { return nil }

        let mid = (start + end) / 2
        let attr = cachedAttributes[mid]

        if attr.frame.intersects(rect) {
            return mid
        } else {
            if attr.frame.maxY < rect.minY {
                return binSearch(rect, start: (mid + 1), end: end)
            } else {
                return binSearch(rect, start: start, end: (mid - 1))
            }
        }
    }
}
```

更重要的是 `StageLayoutCalculator.swift` 類別。設計此類別的目的是，根據以流程為基礎的資料列/資料欄配置中的參與者人數，來計算每個參與者的影格。每個資料列的高度與其他資料列相同，但每個資料列的寬度可能有所差異。請參閱 `layouts` 變數上方的程式碼註解，描述了如何自訂此行為。

```
import Foundation
import UIKit

class StageLayoutCalculator {

    /// This 2D array contains the description of how the grid of participants should be rendered
    /// The index of the 1st dimension is the number of participants needed to active that configuration
    /// Meaning if there is 1 participant, index 0 will be used. If there are 5 participants, index 4 will be used.
    ///
    /// The 2nd dimension is a description of the layout. The length of the array is the number of rows that
    /// will exist, and then each number within that array is the number of columns in each row.
    ///
    /// See the code comments next to each index for concrete examples.
    ///
    /// This can be customized to fit any layout configuration needed.
    private let layouts: [[Int]] = [
        // 1 participant
        [ 1 ], // 1 row, full width
        // 2 participants
        [ 1, 1 ], // 2 rows, all columns are full width
        // 3 participants
        [ 1, 2 ], // 2 rows, first row's column is full width then 2nd row's columns are 1/2 width
        // 4 participants
        [ 2, 2 ], // 2 rows, all columns are 1/2 width
        // 5 participants
        [ 1, 2, 2 ], // 3 rows, first row's column is full width, 2nd and 3rd row's columns are 1/2 width
        // 6 participants
        [ 2, 2, 2 ], // 3 rows, all column are 1/2 width
        // 7 participants
        [ 2, 2, 3 ], // 3 rows, 1st and 2nd row's columns are 1/2 width, 3rd row's columns are 1/3rd width
        // 8 participants
        [ 2, 3, 3 ],
        // 9 participants
        [ 3, 3, 3 ],
        // 10 participants
        [ 2, 3, 2, 3 ],
        // 11 participants
        [ 2, 3, 3, 3 ],
        // 12 participants
        [ 3, 3, 3, 3 ],
    ]

    // Given a frame (this could be for a UICollectionView, or a Broadcast Mixer's canvas), calculate the frames for each
    // participant, with optional padding.
    func calculateFrames(participantCount: Int, width: CGFloat, height: CGFloat, padding: CGFloat) -> [CGRect] {
        if participantCount > layouts.count {
            fatalError("Only \(layouts.count) participants are supported at this time")
        }
        if participantCount == 0 {
            return []
        }
        var currentIndex = 0
        var lastFrame: CGRect = .zero

        // If the height is less than the width, the rows and columns will be flipped.
        // Meaning for 6 participants, there will be 2 rows of 3 columns each.
        let isVertical = height > width

        let halfPadding = padding / 2.0

        let layout = layouts[participantCount - 1] // 1 participant is in index 0, so `-1`.
        let rowHeight = (isVertical ? height : width) / CGFloat(layout.count)

        var frames = [CGRect]()
        for row in 0 ..< layout.count {
            // layout[row] is the number of columns in a layout
            let itemWidth = (isVertical ? width : height) / CGFloat(layout[row])
            let segmentFrame = CGRect(x: (isVertical ? 0 : lastFrame.maxX) + halfPadding,
                                      y: (isVertical ? lastFrame.maxY : 0) + halfPadding,
                                      width: (isVertical ? itemWidth : rowHeight) - padding,
                                      height: (isVertical ? rowHeight : itemWidth) - padding)

            for column in 0 ..< layout[row] {
                var frame = segmentFrame
                if isVertical {
                    frame.origin.x = (itemWidth * CGFloat(column)) + halfPadding
                } else {
                    frame.origin.y = (itemWidth * CGFloat(column)) + halfPadding
                }
                frames.append(frame)
                currentIndex += 1
            }

            lastFrame = segmentFrame
            lastFrame.origin.x += halfPadding
            lastFrame.origin.y += halfPadding
        }
        return frames
    }

}
```

回到 `Main.storyboard`，請務必將 `UICollectionView` 的配置類別設定為我們剛才建立的類別：

![\[Xcode interface showing storyboard with UICollectionView and its layout settings.\]](http://docs.aws.amazon.com/zh_tw/ivs/latest/RealTimeUserGuide/images/Publish_iOS_12.png)


## 掛接 UI 動作
<a name="getting-started-pub-sub-ios-actions"></a>

我們即將結束，只需建立幾個 `IBActions`。

首先，將處理加入按鈕。其反應因 `connectingOrConnected` 的值而異。一旦建立連線後，便會離開階段。如果中斷連線，則會從權杖 `UITextField` 讀取文字，並建立具有該文字的新的 `IVSStage`。然後，新增 `ViewController` 做為 `strategy`、`errorDelegate` 和用於 `IVSStage` 的轉譯器，最後，我們以非同步方式加入階段。

```
@IBAction private func joinTapped(_ sender: UIButton) {
    if connectingOrConnected {
        // If we're already connected to a Stage, leave it.
        stage?.leave()
    } else {
        guard let token = textFieldToken.text else {
            print("No token")
            return
        }
        // Hide the keyboard after tapping Join
        textFieldToken.resignFirstResponder()
        do {
            // Destroy the old Stage first before creating a new one.
            self.stage = nil
            let stage = try IVSStage(token: token, strategy: self)
            stage.errorDelegate = self
            stage.addRenderer(self)
            try stage.join()
            self.stage = stage
        } catch {
            print("Failed to join stage - \(error)")
        }
    }
}
```

需要掛接的另一個 UI 動作是發布切換按鈕：

```
@IBAction private func publishToggled(_ sender: UISwitch) {
    // Because the strategy returns the value of `switchPublish.isOn`, just call `refreshStrategy`.
    stage?.refreshStrategy()
}
```

## 轉譯參與者
<a name="getting-started-pub-sub-ios-participants"></a>

最後，我們需要將從 SDK 接收的資料，轉譯到之前建立的參與者儲存格上。我們已經完成了 `UICollectionView` 邏輯，因此只需實作 `ParticipantCollectionViewCell.swift` 中的 `set` API。

從新增 `empty` 函數開始，然後逐步實作：

```
func set(participant: StageParticipant) {
   
}
```

首先，處理簡易狀態、參與者 ID、發布狀態和訂閱狀態。對於這些，只需直接更新 `UILabels`：

```
labelParticipantId.text = participant.isLocal ? "You (\(participant.participantId ?? "Disconnected"))" : participant.participantId
labelPublishState.text = participant.publishState.text
labelSubscribeState.text = participant.subscribeState.text
```

發布和訂閱列舉的文字屬性源自本機延伸：

```
extension IVSParticipantPublishState {
    var text: String {
        switch self {
        case .notPublished: return "Not Published"
        case .attemptingPublish: return "Attempting to Publish"
        case .published: return "Published"
        @unknown default: fatalError()
        }
    }
}

extension IVSParticipantSubscribeState {
    var text: String {
        switch self {
        case .notSubscribed: return "Not Subscribed"
        case .attemptingSubscribe: return "Attempting to Subscribe"
        case .subscribed: return "Subscribed"
        @unknown default: fatalError()
        }
    }
}
```

接著，更新音訊和影片靜音狀態。為取得靜音狀態，需要從 `streams` 陣列中找到 `IVSImageDevice` 和 `IVSAudioDevice`。為優化效能，會記住上次連接的裝置。

```
// This belongs outside `set(participant:)`
private var registeredStreams: Set<IVSStageStream> = []
private var imageDevice: IVSImageDevice? {
    return registeredStreams.lazy.compactMap { $0.device as? IVSImageDevice }.first
}
private var audioDevice: IVSAudioDevice? {
    return registeredStreams.lazy.compactMap { $0.device as? IVSAudioDevice }.first
}

// This belongs inside `set(participant:)`
let existingAudioStream = registeredStreams.first { $0.device is IVSAudioDevice }
let existingImageStream = registeredStreams.first { $0.device is IVSImageDevice }

registeredStreams = Set(participant.streams)

let newAudioStream = participant.streams.first { $0.device is IVSAudioDevice }
let newImageStream = participant.streams.first { $0.device is IVSImageDevice }

// `isMuted != false` covers the stream not existing, as well as being muted.
labelVideoMuted.text = "Video Muted: \(newImageStream?.isMuted != false)"
labelAudioMuted.text = "Audio Muted: \(newAudioStream?.isMuted != false)"
```

最後，要轉譯 `imageDevice` 的預覽，並顯示 `audioDevice` 的音訊統計資料:

```
if existingImageStream !== newImageStream {
    // The image stream has changed
    updatePreview() // We’ll cover this next
}

if existingAudioStream !== newAudioStream {
    (existingAudioStream?.device as? IVSAudioDevice)?.setStatsCallback(nil)
    audioDevice?.setStatsCallback( { [weak self] stats in
        self?.labelAudioVolume.text = String(format: "Audio Level: %.0f dB", stats.rms)
    })
    // When the audio stream changes, it will take some time to receive new stats. Reset the value temporarily.
    self.labelAudioVolume.text = "Audio Level: -100 dB"
}
```

我們需要建立的最後一個函數是 `updatePreview()`，這會將參與者的預覽新增至檢視：

```
private func updatePreview() {
    // Remove any old previews from the preview container
    viewPreviewContainer.subviews.forEach { $0.removeFromSuperview() }
    if let imageDevice = self.imageDevice {
        if let preview = try? imageDevice.previewView(with: .fit) {
            viewPreviewContainer.addSubviewMatchFrame(preview)
        }
    }
}
```

上面使用了 `UIView` 上的輔助程式函數，使嵌入子檢視變得更容易：

```
extension UIView {
    func addSubviewMatchFrame(_ view: UIView) {
        view.translatesAutoresizingMaskIntoConstraints = false
        self.addSubview(view)
        NSLayoutConstraint.activate([
            view.topAnchor.constraint(equalTo: self.topAnchor, constant: 0),
            view.bottomAnchor.constraint(equalTo: self.bottomAnchor, constant: 0),
            view.leadingAnchor.constraint(equalTo: self.leadingAnchor, constant: 0),
            view.trailingAnchor.constraint(equalTo: self.trailingAnchor, constant: 0),
        ])
    }
}
```