# SDK de transmissão do IVS: troca de tokens \| streaming em tempo real
<a name="broadcast-mobile-token-exchange"></a>

A troca de tokens permite fazer o upgrade ou o downgrade dos recursos de token do participante e a atualização dos atributos de token no SDK de transmissão, sem que os participantes precisem se reconectar. Isso é útil em cenários como co-hospedagem, em que os participantes podem começar com recursos somente para assinantes e, posteriormente, precisarem de recursos de publicação.

A troca de tokens é compatível com os SDKs de transmissão móvel e web. Quando um participante troca um token, a composição do servidor detecta em tempo real os atributos atualizados e ajusta automaticamente o leiaute; por exemplo, reatribuindo o espaço em destaque, reordenando os participantes ou movendo um participante para a sobreposição picture-in-picture, sem necessidade de reconexão. 

A troca de tokens funciona apenas com os tokens criados no servidor usando um [par de chaves](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/getting-started-distribute-tokens.html#getting-started-distribute-tokens-self-signed). Ela não funciona com tokens criados por meio da API [CreateParticipantToken](https://docs.aws.amazon.com/ivs/latest/RealTimeAPIReference/API_CreateParticipantToken.html).

## Troca de tokens
<a name="broadcast-mobile-token-exchange-exchanging-tokens"></a>

A troca de tokens é simples: chame a API `exchangeToken` no objeto `Stage`/`IVSStage` e forneça o novo token. Se os `capabilities` do novo token forem diferentes dos do token anterior, os recursos do novo token serão avaliados imediatamente. Por exemplo, se o token anterior não tiver o recurso `publish` e o novo token tiver, as funções de estratégia de estágio para publicação serão invocadas, permitindo que a aplicação de host decida se deseja publicar imediatamente com o novo recurso ou esperar. O mesmo vale para os recursos removidos: se o token anterior tinha a capacidade `publish` e o novo token não, o participante imediatamente cancela a publicação sem invocar as funções de estratégia de palco para publicação.

Ao trocar um token, o token anterior e o novo devem ter os mesmos valores para os seguintes campos de carga útil: 
+ `topic`
+ `resource`
+ `jti`
+ `whip_url`
+ `events_url`

Esses campos são imutáveis. A troca de um token que modifica um campo imutável faz com que o SDK rejeite imediatamente a troca.

Os campos restantes podem ser alterados, incluindo:
+ `attributes`
+ `capabilities`
+ `user`
+ `_id`
+ `iat`
+ `exp`

### iOS
<a name="broadcast-mobile-token-exchange-exchanging-tokens-ios"></a>



```
let stage = try IVSStage(token: originalToken, strategy: self)
stage.join()
stage.exchangeToken(newToken)
```

### Android
<a name="broadcast-mobile-token-exchange-exchanging-tokens-android"></a>



```
val stage = Stage(context, originalToken, strategy)
stage.join()
stage.exchangeToken(newToken)
```

### Web
<a name="broadcast-web-token-exchange-exchanging-tokens"></a>



```
const stage = new Stage(originalToken, strategy);
await stage.join();
await stage.exchangeToken(newToken);
```

## Receber atualizações
<a name="broadcast-mobile-token-exchange-receiving-updates"></a>

Uma função em `StageRenderer`/`IVSStageRenderer` recebe atualizações sobre participantes remotos já publicados que trocam seus tokens para atualizar seu `userId` ou `attributes`. Participantes remotos que ainda não estão publicando terão seus `userId` e `attributes` atualizados expostos por meio das funções de renderizador `onParticipantJoined`/`participantDidJoin`existentes se eventualmente publicarem.

### iOS
<a name="broadcast-mobile-token-exchange-receiving-updates-ios"></a>



```
class MyStageRenderer: NSObject, IVSStageRenderer {
    func stage(_ stage: IVSStage, participantMetadataDidUpdate participant: IVSParticipantInfo) {
        // participant will be a new IVSParticipantInfo instance with updated properties.
    }
}
```

### Android
<a name="broadcast-mobile-token-exchange-receiving-updates-android"></a>



```
private val stageRenderer = object : StageRenderer {
    override fun onParticipantMetadataUpdated(stage: Stage, participantInfo: ParticipantInfo) {
        // participantInfo will be a new ParticipantInfo instance with updated properties.
    }
}
```

### Web
<a name="broadcast-web-token-exchange-receiving-updates"></a>



```
stage.on(StageEvents.STAGE_PARTICIPANT_METADATA_CHANGED, (participantInfo: StageParticipantInfo) => { 
    // participantInfo properties will be updated with the changed properties 
    }
);
```

## Visibilidade das atualizações
<a name="broadcast-mobile-token-exchange-visibility"></a>

Quando um participante troca um token para atualizar seu `userId` ou `attributes`, a visibilidade dessas alterações depende do estado atual de publicação: 
+ **Se o participante *não* estiver publicando:** a atualização será processada silenciosamente. Se eles acabarem sendo publicados, todos os SDKs receberão a atualização `userId` e `attributes` como parte do evento de publicação inicial.
+ **Se o participante já *estiver* publicando:** a atualização será transmitida imediatamente aos participantes que usam os SDKs móveis v1.37.0\+, o SDK web e a composição do servidor. Os participantes que usam os SDKs móveis mais antigos não verão a alteração até a publicação ser removida e refeita.

Esta tabela esclarece a matriz de suporte:


| Estado do participante | Observador: SDK móvel 1.37.0\+, SDK Web, composição do servidor  | Observador: SDKs móveis mais antigos | 
| --- | --- | --- | 
| Não está publicando (depois começa) | ✅ Visível (na publicação por meio do evento participante que ingressou) | ✅ Visível (na publicação por meio do evento participante que ingressou) | 
| Já está publicando (nunca republica) | ✅ Visível (imediatamente por meio do evento atualizado de metadados do participante) | ❌ Não visível | 
| Já está publicando (cancela e republica) | ✅ Visível (imediatamente por meio do evento atualizado de metadados do participante) | ⚠️ Com o tempo, visível (após republicação por meio do evento em que o participante ingressou) |