IVS 广播 SDK：令牌交换 | 实时直播功能

通过令牌交换，您可以升级或降级参与者令牌功能以及更新广播 SDK 中的令牌属性，而无需参与者重新连接。这对于联合主持等场景非常实用，即参与者可以首先使用仅限订阅的功能，以后再需要发布功能的场景。

移动和网络广播 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 的远程参与者已发布的更新。尚未发布的远程参与者如果最终发布，则将通过现有的 onParticipantJoined/participantDidJoin renderer 函数公开更新后的userId 和 attributes。

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 时，这些更改的可见性取决于其当前的发布状态：

下表澄清了支持矩阵：