# IVS 廣播 SDK：符記交換 \| 即時串流
<a name="broadcast-mobile-token-exchange"></a>

權杖交換可讓您在廣播 SDK 中升級或降級參與者權杖功能並更新權杖屬性，而不需要參與者重新連線。此功能適用於共同託管等案例，因參與者可能僅以訂閱功能開始，之後則需要發布功能。

行動和 Web 廣播 SDK 皆支援權杖交換。當參與者進行權杖交換時，伺服器端合成會即時偵測到更新後的屬性，並自動調整版面配置，例如重新分配重點插槽、重新排序參與者，或將某位參與者移至子母畫面覆蓋層，過程中完全不需要重新連線。

限制：權杖交換僅適用於使用[鍵值對](https://docs.aws.amazon.com//ivs/latest/RealTimeUserGuide/getting-started-distribute-tokens.html#getting-started-distribute-tokens-self-signed)在伺服器上建立的權杖。它不適用於透過 [CreateParticipantToken API](https://docs.aws.amazon.com/ivs/latest/RealTimeAPIReference/API_CreateParticipantToken.html) 建立的符記。

## 交換符記
<a name="broadcast-mobile-token-exchange-exchanging-tokens"></a>

交換符記相當簡單：呼叫 `Stage` / `IVSStage` 物件上的 `exchangeToken` API，並提供新的符記。如果新符記 `capabilities` 的與先前符記所擁有的不同，則系統會立即評估新符記的功能。例如，如果先前的符記沒有 `publish` 功能，而新的符記有，則會調用用於發布的階段策略函數，讓主機應用程式決定是否要使用新功能立即發布，或選擇稍後再發布。移除的功能也是如此：如果先前的符記具有 `publish` 功能，但新的符記沒有，則參與者會立即取消發布，而不會調用階段策略函數進行發布。

交換符記時，先前和新的符記必須具有下列承載欄位的相同值：
+ `topic`
+ `resource`
+ `jti`
+ `whip_url`
+ `events_url`

這些欄位不可變。交換修改不可變欄位的符記會導致 SDK 立即拒絕交換。

其餘欄位可以變更，包括：
+ `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);
```

## 接收更新
<a name="broadcast-mobile-token-exchange-receiving-updates"></a>

`StageRenderer` / `IVSStageRenderer` 中的函數會收到有關已發布的遠端參與者的更新，這些參與者交換其符記以更新其 `userId` 或 `attributes`。尚未進行發布的遠端參與者，若日後開始發布，其更新後的 `userId` 與 `attributes` 將透過既有的 `onParticipantJoined` / `participantDidJoin` 轉譯器函數對外提供。

### 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 
    }
);
```

## 更新可見性
<a name="broadcast-mobile-token-exchange-visibility"></a>

當參與者交換符記以更新其 `userId` 或 `attributes` 時，這些變更的可見性取決於其目前的發布狀態：
+ **如果該參與者*尚未*進行發布：**則該更新將以無提示的方式處理。若日後開始發布，所有 SDK 都將收到已更新的 `userId` 和 `attributes`，作為初始發布事件的一部分。
+ **如果參與者*已*發布：**該更新將立即廣播至使用行動 SDKs v1.37.0\+、Web SDK 和伺服器端合成的參與者。在參與者取消發布和重新發布之前，使用舊版行動 SDK 的參與者不會看到變更。

此表說明支援情況的對應矩陣：


| 參與者狀態 | 觀察者：行動 SDK 1.37.0\+、Web SDK、伺服器端合成  | 觀察者：舊版行動 SDK | 
| --- | --- | --- | 
| 不發布 (然後啟動) | ✅ 可見 (透過參與者加入的事件發布時可見) | ✅ 可見 (透過參與者加入的事件發布時可見) | 
| 已發布 (從未重新發布) | ✅ 可見 (透過參與者中繼資料更新事件立即可見) | ❌ 不可見 | 
| 已發布 (取消發布並重新發布) | ✅ 可見 (透過參與者中繼資料更新事件立即可見) | ⚠️ 最終可見 (透過參與者加入的事件重新發布時可見) |