# 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>

首次使用实时流式传输之前，请完成以下任务。有关说明，请参阅 [Getting Started with IVS Low-Latency Streaming](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/getting-started.html)。
+ 创建 AWS 账户
+ 设置根用户和管理用户

## 其他参考资料
<a name="getting-started-introduction-extref"></a>
+ [IVS Web Broadcast SDK Reference](https://aws.github.io/amazon-ivs-web-broadcast/docs/sdk-reference)
+ [IVS Android Broadcast SDK Reference](https://aws.github.io/amazon-ivs-broadcast-docs/latest/android/)
+ [IVS iOS Broadcast SDK Reference ](https://aws.github.io/amazon-ivs-broadcast-docs/latest/ios/)
+ [IVS Real-Time Streaming API Reference](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>

接下来，您必须创建 Amazon Identity and Access Management（IAM）policy，以授予用户一组基本权限（例如，创建 Amazon IVS 舞台和创建参与者令牌），并将该策略分配给用户。您可以在创建[新用户](#iam-permissions-new-user)时分配权限，也可以向[现有用户](#iam-permissions-existing-user)添加权限。这两项程序如下。

有关更多信息（例如，了解 IAM 用户和策略、如何将策略附加到用户以及如何限制用户可以使用 Amazon IVS 执行的操作），请参见：
+ [IAM 用户指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#Using_CreateUser_console)中的*创建 IAM 用户*
+ [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. 登录 Amazon 管理控制台，并通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。

1. 在导航窗格中，选择**策略**，然后选择**创建策略**。这时将会打开**指定权限**窗口。

1. 在**指定权限**窗口中，选择 **JSON** 选项卡，然后复制下列 IVS 策略并粘贴到**策略编辑器**文本区域。[该策略不包括所有 Amazon IVS 操作。您可以根据需要添加/删除（允许/拒绝）操作访问权限。有关 IVS 操作的详细信息，请参阅 [IVS Real-Time Streaming API Reference](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. 继续在**指定权限**窗口中，选择**下一步**（滚动到窗口底部即可看到此按钮）。这时将打开**检查并创建**窗口。

1. 在**检查并创建**窗口中，输入**策略名称**，此外还可以选择添加**描述**。记下策略名称，因为您在创建用户时需要使用该名称（如下文所述）。选择 **Create policy**（创建策略）（位于窗口底部）。

1. 您将返回到 IAM 控制台窗口，您应该会在该窗口中看到一条横幅，确认您的新策略已创建。

## 创建新用户并添加权限
<a name="iam-permissions-new-user"></a>

### IAM 用户访问密钥
<a name="iam-permissions-new-user-access-keys"></a>

IAM 访问密钥包含一个访问密钥 ID 和一个秘密访问密钥。它们用于对您向 Amazon 发出的编程请求进行签名。如果没有访问密钥，您可以从 Amazon 管理控制台创建。作为最佳实践，请勿创建根用户访问密钥。

*仅当创建访问密钥时，您才能查看或下载秘密访问密钥。以后您无法恢复它们。*但是，您随时可以创建新的访问密钥；您必须拥有执行所需 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. 在导航窗格中，选择**用户**，然后选择**创建用户**。这时将会打开**指定用户详细信息**窗口。

1. 在**指定用户详细信息**窗口中：

   1. 在**用户详细信息**下，键入要创建的新**用户名**。

   1. 选中**授予用户访问 Amazon 管理控制台的权限**。

   1. 在**控制台密码**下，选择**自动生成的密码**。

   1. 选中**用户下次登录时必须修改密码**旁的复选框。

   1. 选择**下一步**。这时将会打开**设置权限**窗口。

1. 在**设置权限**下，选择**直接附加策略**。这时将会打开**权限策略**窗口。

1. 在搜索框中，输入 IVS 策略名称（AWS 托管式策略或您之前创建的自定义策略）。找到该策略后，选中复选框以选择该策略。

1. 选择**下一步**（位于窗口底部）。这时将打开**检查并创建**窗口。

1. 在**检查并创建**窗口中，确认所有用户详细信息均正确无误，然后选择**创建用户**（位于窗口底部）。

1. 这时将会打开**找回密码**窗口，其中包含您的**控制台登录详细信息**。*妥善保存好此信息，以备将来参考*。完成后，选择**返回用户列表**。

## 向现有用户添加权限
<a name="iam-permissions-existing-user"></a>

按照以下步骤进行操作：

1. 登录 Amazon 管理控制台，并通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。

1. 在导航窗格中，选择**用户**，然后选择要更新的现有用户名。（单击选择用户名；不要选中选择框。）

1. 在**摘要**页面的**权限**选项卡中，选择**添加权限**。这时将会打开**添加权限**窗口。

1. 选择 **Attach existing policies directly**（直接附加现有策略）。这时将会打开**权限策略**窗口。

1. 在搜索框中，输入 IVS 策略名称（AWS 托管式策略或您之前创建的自定义策略）。找到该策略后，选中复选框以选择该策略。

1. 选择**下一步**（位于窗口底部）。这时将会打开**检查**窗口。

1. 在**检查**窗口中，选择**添加权限**（位于窗口底部）。

1. 在 **Summary**（摘要）页面上，确认已添加 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 存储桶。

录制到您的 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)。

   （您还可通过 [Amazon 管理控制台](https://console.aws.amazon.com/)访问 Amazon IVS 控制台。）

1. 请在左侧导航窗格中选择**舞台**，然后选择**创建舞台**。此时将显示**创建舞台**窗口。  
![\[使用“创建舞台”窗口，创建新舞台并为该舞台创建参与者令牌。\]](http://docs.aws.amazon.com/zh_cn/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_cn/ivs/latest/RealTimeUserGuide/images/Create_Stage_Console_enable_IPR.png)

1. 选择要录制的媒体类型。

1. 选择**创建存储配置**。此时会打开一个新窗口，其中选项用于创建 Amazon S3 桶并将其附加到新的录制配置。  
![\[使用“创建存储配置”窗口创建舞台的新存储配置。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Create_Storage_Configuration_IPR.png)

1. 填写以下字段：

   1. （可选）输入**存储配置名称**。

   1. 输入**存储桶名称**。

1. 选择**创建存储配置**，以创建具有唯一 ARN 的新存储配置资源。创建录制配置通常在数秒钟内完成，但最多可能需要 20 秒钟。存储配置创建完成后，您将返回到**创建舞台**窗口。在那里，**录制单个参与者**区域显示您的新**存储配置**和您创建的 S3 存储桶（**存储**）。  
![\[使用 IVS 控制台创建舞台：创建新的存储配置。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Create_Stage_Console_Storage_Configuration.png)

1. 您可以选择启用其他非默认选项，例如录制参与者副本、合并单个参与者录制以及缩略图录制。  
![\[使用 IVS 控制台创建舞台：启用缩略图录制和 IPR 拼接等高级选项。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Create_Stage_Console_IPR_Stitching.png)

## 创建 IVS 舞台的 CLI 说明
<a name="getting-started-create-stage-cli"></a>

要安装 Amazon CLI，请参阅 [Install or update to the latest version of the <shared id="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 进行签名，并将公有密钥导入到 Amazon 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>
```

如果区域位于您的本地亚马逊云科技配置文件中，您可以忽略 `--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. 选择要使用的暂存区。选择 **View details (查看详细信息)**。

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。它必须与从 [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 时间戳。（有关 Unix 时间戳的信息，请参阅 `exp` 的说明。） 该项必须是整型值。
  + `jti`（JWT 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_cn/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。有关详细信息，请参阅 [Amazon 命令行界面用户指南](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)。注意：使用 AWS CLI 生成令牌适合用于测试目的，但对于生产用途而言，我们建议您使用 AWS SDK 在服务器端生成令牌（请参阅以下说明）。

1. 使用舞台 ARN 运行 `create-participant-token` 命令。包括以下任何或所有功能：`"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 程序包。有关详细信息，请参阅 [Getting started with the AWS SDK for JavaScript](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 广播 SDK 作为 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 Broadcast SDK Guide》**中的 [Install the Library](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_cn/ivs/latest/RealTimeUserGuide/images/iOS_Configure.png)


# 步骤 5：发布和订阅视频
<a name="getting-started-pub-sub"></a>

您可以通过以下方式发布/订阅（实时）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)。

   （您还可通过 [Amazon 管理控制台](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_cn/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
};
```

## 创建 joinStage 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]);
```

## 创建 joinStage 3：定义舞台策略并创建舞台
<a name="getting-started-pub-sub-web-joinstage3"></a>

这个舞台策略是决策逻辑的核心，SDK 将使用此策略来决定要发布什么内容和订阅哪些参与者。有关此函数用途的更多信息，请参阅 [Strategy](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);
```

## 创建 JoinStage 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;
}
```

## 创建 joinStage 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_cn/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_cn/ivs/latest/RealTimeUserGuide/images/Publish_Android_2.png)


此项目的布局很简单：它包含用于渲染参与者视频流的视图和用于显示参与者有关信息的标签列表：

![\[为 Android 应用程序 RecyclerView 创建项目视图 – 标签。\]](http://docs.aws.amazon.com/zh_cn/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 适配器
<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>

首先使用自动创建的 `ViewController.swift` 文件来导入 `AmazonIVSBroadcast`，然后添加一些要链接的 `@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_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_1.png)


对于 AutoLayout 配置，需要自定义三个视图。第一个视图是**集合视图参与者** (`UICollectionView`)。将**开头**、**结尾**和**底部**绑定到**安全区域**。同时将**顶部**绑定到**控件容器**。

![\[自定义 iOS 集合视图参与者视图。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_2.png)


第二个视图是**控件容器**。将**开头**、**结尾**和**顶部**绑定到**安全区域**：

![\[自定义 iOS 控件容器视图。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_3.png)


第三个也是最后一个视图是**垂直堆栈视图**。将**顶部**、**开头**、**结尾**和**底部**绑定到**超级视图**。对于样式，将间距设置为 8 而不是 0。

![\[自定义 iOS 垂直堆栈视图。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_4.png)


**UIStackViews** 将处理剩余视图的布局。对于所有三个 **UIStackViews**，使用**填充**作为**对齐**和**分布**。

![\[使用 UIStackViews 自定义剩余的 iOS 视图。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_5.png)


最后，将这些观点链接到 `ViewController`。从上面绘制以下视图：
+ 将**文本字段加入**绑定到 `textFieldToken`。
+ 将**按钮加入**绑定到 `buttonJoin`。
+ 将**标签状态**绑定到 `labelState`。
+ 将**切换发布**绑定到 `switchPublish`。
+ 将**集合视图参与者**绑定到 `collectionViewParticipants`。

也可以利用这段时间将**集合视图参与者**项的 `dataSource` 设置为所属 `ViewController`：

![\[设置 iOS 应用程序的集合视图参与者的 dataSource。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_6.png)


现在创建 `UICollectionViewCell` 子类以在其中渲染参与者。首先创建一个新的 **Cocoa Touch 类**文件：

![\[创建 UICollectionViewCell 来渲染 iOS 的实时参与者。\]](http://docs.aws.amazon.com/zh_cn/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_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_8.png)


对于 AutoLayout，再次修改三个视图。第一个视图是**视图预览容器**。将**结尾**、**开头**、**顶部**和**底部**设置为**参与者集合视图单元格**。

![\[自定义 iOS 视图预览容器视图。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_9.png)


第二个视图是**视图**。将**开头**和**顶部**设置为**参与者集合视图单元格**并将值更改为 4。

![\[自定义 iOS 视图的视图。\]](http://docs.aws.amazon.com/zh_cn/ivs/latest/RealTimeUserGuide/images/Publish_iOS_10.png)


第三个视图是**堆栈视图**。将**结尾**、**开头**、**顶部**和**底部**设置为**超级视图**并将值更改为 4。

![\[自定义 iOS 堆栈视图的视图。\]](http://docs.aws.amazon.com/zh_cn/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 和 `updated` 的 `changeType` 调用 `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` 进行跟踪，其将在用户界面自行更新时自动更新。

```
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_cn/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),
        ])
    }
}
```