IVS 廣播 SDK：符記交換 | 即時串流

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

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

限制：權杖交換僅適用於使用鍵值對在伺服器上建立的權杖。它不適用於透過 CreateParticipantToken API 建立的符記。

交換符記

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

交換符記時，先前和新的符記必須具有下列承載欄位的相同值：

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

其餘欄位可以變更，包括：

iOS

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

Android

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

Web

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

接收更新

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

iOS

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

Android

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

Web

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

更新可見性

當參與者交換符記以更新其 userId 或 attributes 時，這些變更的可見性取決於其目前的發布狀態：

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