Kit SDK de diffusion IVS : échange de jetons | Diffusion en temps réel

L’échange de jetons vous permet de mettre à niveau ou de rétrograder les fonctionnalités des jetons des participants et de mettre à jour les attributs des jetons dans le SDK de diffusion, sans que les participants aient besoin de se reconnecter. Cela est utile pour des scénarios comme le co-hébergement, où les participants peuvent commencer par des fonctionnalités d’abonnement uniquement, puis avoir besoin de fonctionnalités de publication.

L’échange de jetons est pris en charge à la fois dans les SDK de diffusion mobiles et Web. Lorsqu’un participant échange un jeton, le montage côté serveur détecte les attributs mis à jour en temps réel et ajuste automatiquement la mise en page, par exemple en réattribuant le créneau sélectionné, en réorganisant les participants ou en déplaçant un participant dans la superposition image dans image, sans qu’il soit nécessaire de se reconnecter.

Limitation : l’échange de jetons ne fonctionne qu’avec les jetons créés sur votre serveur avec une paire de clés. Cela ne fonctionne pas avec les jetons créés via l’API CreateParticipantToken.

Échange de jetons

L’échange de jetons est simple : appelez l’API exchangeToken sur l’objet Stage/IVSStage et fournissez le nouveau jeton. Si les capabilities du nouveau jeton sont différentes de celles du jeton précédent, les capacités du nouveau jeton sont immédiatement évaluées. Par exemple, si le jeton précédent n’avait pas la capacité publish et que le nouveau la possède, les fonctions de stratégie de publication sont invoquées, ce qui permet à l’application hôte de décider si elle souhaite publier immédiatement avec la nouvelle fonctionnalité ou attendre. Il en va de même pour les fonctionnalités supprimées : si le jeton précédent possédait la capacité publish et le nouveau jeton non, le participant annule immédiatement la publication sans invoquer les fonctions de stratégie d’étape pour la publication.

Lors de l’échange d’un jeton, le jeton précédent et le nouveau jeton doivent avoir les mêmes valeurs pour les champs de données utiles suivants :

Ces champs sont immuables. L’échange d’un jeton qui modifie un champ immuable entraîne le rejet immédiat de l’échange par le SDK.

Les autres champs peuvent être modifiés, notamment :

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);

Réception des mises à jour

Une fonction dans StageRenderer/IVSStageRenderer reçoit des mises à jour concernant des participants distants déjà publiés qui échangent leurs jetons pour mettre à jour leur userId ou leurs attributes. Les participants distants qui ne publient pas encore verront leur userId et leurs attributes mis à jour exposés via les fonctions de rendu onParticipantJoined/participantDidJoin existantes s’ils finissent par être publiés.

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

Visibilité des mises à jour

Lorsqu’un participant échange un jeton pour mettre à jour son userId ou ses attributes, la visibilité de ces modifications dépend de son état de publication actuel :

Le tableau suivant précise la matrice de prise en charge :