自定义参与者排序 - Amazon IVS
自定义排序的工作原理创建具有排序属性的令牌使用案例示例向后兼容

自定义参与者排序

借助自定义参与者排序功能，您可以根据参与者令牌中的自定义属性值控制参与者在网格和 PiP 布局中的定位，包括特写参与者的定位和 PiP 窗口中的参与者选择。这提供了确定性定位功能，可实现基于角色的布局。

自定义排序的工作原理

在布局配置中指定 participantOrderAttribute 后，系统将根据以下规则对参与者进行排序：

  • 令牌中包含指定排序属性的参与者排在最前，按其属性值的数值大小进行排序。

  • 缺少排序属性的参与者将重新按到达时间排序，并排在已排序的参与者之后。

  • 如有多个参与者的排序值相同，则按其进入舞台的时间再次排序。

  • 排序按数值大小（不是字典顺序）进行，因此“10”排在“9”之后，而不是在“1”之后。

  • 支持负值。负值应排于正值之前。

  • 非整数值（例如“abc”、“1.5”）将视为无效，这些参与者会重新按到达时间排序。

重要提示：参与者排序（无论是基于到达时间还是自定义）将在合成开始后生效。对于在合成开始之前进入舞台的参与者，无法保证参与者的正确排序。

创建具有排序属性的令牌

要使用自定义参与者排序功能，请在创建参与者令牌时将排序属性包含在其中：

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=1

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=2

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=3

您可以将自定义参与者排序属性与用于为精选槽位和 PiP 窗口选择参与者的属性相结合：

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=2,isFeatured=true

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=3,isFeatured=true

aws ivs-realtime create-participant-token --stage-arn "arn:aws:ivs:us-east-1:123456789012:stage/u9OiE29bT7Xp" --attributes order=4,isPip=true

使用案例示例

示例使用案例包括：

  • 一致的定位：参与者使用相同的令牌重新连接时会保持原来的位置。

  • 基于角色的定位：例如，您可以指定教师的顺序为 1，学生的顺序为 2。

  • 基于优先级的布局：顺序值较低的 VIP 参与者将首先出现。

  • 动态布局：您可以将自定义排序与 featuredParticipantAttribute 和 pipParticipantAttribute 组合使用，以满足复杂场景的需要。

  • 跨舞台互动：在 VS 模式竞赛等场景中使用参与者复制功能时，来自不同舞台的主播将进行互动，您可以通过覆盖排序属性来控制目标舞台合成中的定位。

注意：对于参与者复制使用案例，您可以在开始复制时根据需要覆盖参与者属性（包括排序属性），以在目标舞台中实现所需的布局。

向后兼容

自定义参与者排序是一项可选功能，并且完全向后兼容。没有 participantOrderAttribute 属性的现有合成会继续正常运行，按到达时间排序。将 participantOrderAttribute 设置为空字符串时，系统将完全忽略自定义排序并回退到默认行为。