自訂參與者排序 - 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

您可以將 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

範例使用案例

範例使用案例包括：

  • 一致的定位 – 當參與者使用相同權杖重新連線時，會維持其位置。

  • 基於角色的定位 – 例如，您可以指定 order=1 的教師和 order=2 的學生。

  • 基於優先級的版面配置 – 順序值較低的 VIP 參與者會優先顯示。

  • 動態版面配置 – 對於複雜的案例，您可以將自訂排序與 featuredParticipantAttribute 和 pipParticipantAttribute 結合使用。

  • 跨舞台互動 – 將參與者複寫用於不同舞台的實況主互動的 VS 模式競賽等案例時，您可以覆寫排序屬性，以控制目的地舞台合成中的位置。

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

回溯相容性

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