# カスタム参加者の順序付け
<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 Mode 競技などのシナリオで参加者レプリケーションを使用する場合、順序付け属性を上書きして、宛先ステージコンポジションの配置を制御できます。

**注:** 参加者レプリケーションのユースケースでは、レプリケーションを開始するときに必要に応じて参加者属性 (順序属性を含む) を上書きして、レプリケート先ステージで目的のレイアウトを実現できます。

## 下位互換性
<a name="ssc-getting-started-custom-participant-ordering-backward-compatibility"></a>

カスタム参加者の順序はオプション機能であり、完全な下位互換性が維持されます。`participantOrderAttribute` のない既存のコンポジションは、到着時刻の順序付けを使用して変更されずに動作し続けます。`participantOrderAttribute` が空の文字列に設定されている場合、システムはカスタム順序を完全に無視し、デフォルトの動作にフォールバックします。