# Ordenação personalizada de participantes
<a name="ssc-getting-started-custom-participant-ordering"></a>

A ordenação personalizada de participantes permite que você controle o posicionamento dos participantes nos layouts de grade e PiP com base nos valores de atributos personalizados nos tokens de participantes, incluindo o posicionamento dos participantes em destaque e a seleção de participantes para a janela PiP. Isso fornece um posicionamento determinístico do participante e permite layouts baseados em funções.

## Como funciona a ordenação personalizada
<a name="ssc-getting-started-custom-participant-ordering-how-custom-ordering-works"></a>

Quando `participantOrderAttribute` é especificado em sua configuração de layout, os participantes são ordenados de acordo com as seguintes regras:
+ Os participantes com o atributo de ordenação especificado em seus tokens são posicionados primeiro, classificados numericamente pelos valores dos atributos.
+ Os participantes sem o atributo de ordenação retornam à ordenação por tempo de chegada e são posicionados após os participantes ordenados.
+ Quando vários participantes têm valores de ordenação idênticos, eles são sub-classificados de acordo com o horário de chegada ao estágio.
+ A ordenação usa classificação numérica (não lexicográfica), então “10” vem depois de “9” (não depois de “1”).
+ Os valores negativos também são compatíveis. Eles são posicionados antes dos valores positivos.
+ Valores não numéricos (por exemplo, “abc”, “1.5”) são tratados como inválidos e esses participantes retornam à ordenação por tempo de chegada.

**Importante:** a ordenação de participantes (seja com base no horário de chegada ou personalizada) entra em vigor após o início da composição. A ordem correta dos participantes não é garantida para os participantes que entrarem no estágio antes do início da composição.

## Criando tokens com atributos de ordenação
<a name="ssc-getting-started-custom-participant-ordering-creating-tokens-with-ordering-attributes"></a>

Para usar a ordenação personalizada de participantes, inclua o atributo de ordenação em seus tokens de participante ao criá-los:

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

Você pode combinar o atributo custom-participant-order com os atributos para selecionar participantes para o slot em destaque e a janela 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
```

## Exemplo de casos de uso
<a name="ssc-getting-started-custom-participant-ordering-example-use-cases"></a>

Exemplo de casos de uso incluem:
+ Posicionamento consistente: os participantes mantêm suas posições ao se reconectarem com o mesmo token.
+ Posicionamento baseado em funções: por exemplo, você pode especificar professores com order=1 e alunos com order=2.
+ Layouts baseados em prioridades: os participantes VIP com valores de ordem mais baixos apareceriam primeiro.
+ Layouts dinâmicos: você pode combinar ordens personalizadas com `featuredParticipantAttribute` e `pipParticipantAttribute` para cenários complexos.
+ Interações entre estágios: ao usar a replicação de participantes para cenários como competições do Modo VS, em que streamers de diferentes estágios interagem, você pode substituir os atributos de ordenação para controlar o posicionamento na composição do estágio de destino.

**Observação:** para casos de uso de replicação de participantes, você pode substituir os atributos do participante (incluindo o atributo de ordem) conforme necessário ao iniciar uma replicação para obter o layout desejado no estágio de destino.

## Compatibilidade retroativa
<a name="ssc-getting-started-custom-participant-ordering-backward-compatibility"></a>

A ordenação personalizada de participantes é um recurso opcional e é totalmente compatível com versões anteriores. As composições existentes `participantOrderAttribute` continuam funcionando inalteradas, usando a ordem no horário de chegada. Quando `participantOrderAttribute` é definido como uma string vazia, o sistema ignora totalmente a ordenação personalizada e volta ao comportamento padrão.