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

符記交換可讓您在行動廣播 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) 建立的符記。
+ 如果您使用符記交換來變更驅動 server-side-composition 配置的屬性 (例如 featuredParticipantAttribute 和 participantOrderAttribute)，則在參與者重新連線之前，作用中合成的配置將不會更新。

## 交換符記
<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)
```

## 接收更新
<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.
    }
}
```

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

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

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


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