# 自訂參與者排序
<a name="ssc-getting-started-custom-participant-ordering"></a>

自訂參與者排序可讓您根據參與者權杖中的自訂屬性值，控制網格和 PiP 版面配置中的參與者位置，包括確定重點參與者的位置以及為 PiP 視窗選取參與者。這可提供確定性的參與者定位，並啟用基於角色的版面配置。

## 自訂排序的運作方式
<a name="ssc-getting-started-custom-participant-ordering-how-custom-ordering-works"></a>

在版面配置組態中指定 `participantOrderAttribute` 時，參與者會根據下列規則排序：
+ 權杖中具有指定排序屬性的參與者會優先定位，並依其屬性值按數字排序。
+ 未具備排序屬性的參與者會回復為到達時間排序，並排在已排序的參與者之後。
+ 當多個參與者的排序值相同時，會依其加入階段的到達時間進行次排序。
+ 排序採用數字排序（非詞典編纂順序排序），因此「10」會排在「9」之後（而非「1」之後）。
+ 支援負值。負值會排在正值之前。
+ 非數字值（例如「abc」、「1.5」）會被視為無效，這些參與者會回復為到達時間排序。

**重要：**參與者排序（無論基於到達時間或自訂規則）會在合成開始後生效。對於在合成開始前加入階段的參與者，不保證其排序正確。

## 建立具有排序屬性的權杖
<a name="ssc-getting-started-custom-participant-ordering-creating-tokens-with-ordering-attributes"></a>

若要使用自訂參與者排序，請在建立參與者權杖時於權杖中包含排序屬性：

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

您可以將 custom-participant-order 屬性與用於為重點位置和 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
```

## 範例使用案例
<a name="ssc-getting-started-custom-participant-ordering-example-use-cases"></a>

範例使用案例包括：
+ 一致的定位 – 當參與者使用相同權杖重新連線時，會維持其位置。
+ 基於角色的定位 – 例如，您可以指定 order=1 的教師和 order=2 的學生。
+ 基於優先級的版面配置 – 順序值較低的 VIP 參與者會優先顯示。
+ 動態版面配置 – 對於複雜的案例，您可以將自訂排序與 `featuredParticipantAttribute` 和 `pipParticipantAttribute` 結合使用。
+ 跨舞台互動 – 將參與者複寫用於不同舞台的實況主互動的 VS 模式競賽等案例時，您可以覆寫排序屬性，以控制目的地舞台合成中的位置。

**注意：**對於參與者複寫使用案例，您可以在開始複寫時視需要覆寫參與者屬性 (包括順序屬性)，以在目的地舞台中實現所需的配置。

## 回溯相容性
<a name="ssc-getting-started-custom-participant-ordering-backward-compatibility"></a>

自訂參與者排序是一項選用功能，可完全回溯相容。沒有 `participantOrderAttribute` 的現有合成會將維持不變，繼續使用到達時間排序。當 `participantOrderAttribute` 設為空字串時，系統會完全忽略自訂排序，回復為預設行為。