Configuration de la session

Une session correspond à une connexion authentifiée entre votre application cliente et l'API Vonage. Votre backend émet un JWT, et le Vonage Client SDK utilise ce JWT dans createSession().

Modèle de session

L'API Vonage gère le cycle de vie des sessions.
Le Client SDK ne génère pas de JWT et ne gère pas l'émission de jetons.
Votre backend reste la source de référence en matière de politique d'identité et d'accès.

Flux d'authentification

Émission de jetons JWT côté serveur

L'exemple ci-dessous illustre la structure requise pour un JWT. Votre implémentation concrète variera en fonction du langage et du framework utilisés pour votre backend.

Les JWT doivent être générés sur votre serveur. La mise en œuvre précise dépend de l'application.

const privateKeyPem =
  '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----';

const payload: GuideJwtPayload = {
  application_id: applicationId,
  sub: userName,
  acl: {
    paths: {
      '/*/users/**': {},
      '/*/conversations/**': {},
      '/*/sessions/**': {},
      '/*/devices/**': {},
      '/*/image/**': {},
      '/*/media/**': {},
      '/*/applications/**': {}
    }
  },
  exp: Math.floor(Date.now() / 1000) + 60 * 60
};

const jwt = signJwt(payload, privateKeyPem);
console.log(jwt);

Créer une session

client.setConfig({ region: ConfigRegion.EU });

try {
  const sessionId = await client.createSession(jwt);
  console.log(`Session created: ${sessionId}`);
} catch (error) {
  console.error('Failed to create session', error);
}

 val client = VoiceClient(ctx)

 val config = VGClientConfig(VGConfigRegion.EU)
 client.setConfig(config)

 client.createSession(jwt) { error, sessionId ->
     if (error != null) {
         println("Failed to create session: $error")
         return@createSession
     }

     println("Session created: $sessionId")
 }

 VoiceClient client = VoiceClient.createClient(ctx);

 VGClientConfig config = new VGClientConfig(ClientConfigRegion.EU);
 client.setConfig(config);

 client.createSession(jwt, null, (error, sessionId) -> {
     if (error != null) {
         System.out.println("Failed to create session: " + error);
         return null;
     }

     System.out.println("Session created: " + sessionId);
     return null;
 });

 let config = VGClientConfig(region: .EU)
 client.setConfig(config)

 client.createSession(jwt) { error, sessionId in
     guard error == nil, let sessionId = sessionId else {
         print("Failed to create session: \(error?.localizedDescription ?? "unknown")")
         return
     }

     print("Session created: \(sessionId)")
 }

 VGClientConfig *config = [[VGClientConfig alloc] initWithRegion:VGConfigRegionEU];
 [client setConfig:config];

 [client createSession:jwt callback:^(NSError * _Nullable error, NSString * _Nullable sessionId) {
     if (error != nil || sessionId == nil) {
         NSLog(@"Failed to create session: %@", error);
         return;
     }

     NSLog(@"Session created: %@", sessionId);
 }];

Durée de vie de la session

Une session reste active tant que le JWT utilisé dans createSession() est valide. La durée de vie de la session est définie par le JWT exp requête — c'est votre backend qui détermine la durée de cette session (minimum 30 secondes, maximum 24 heures ; la valeur par défaut est de 15 minutes si elle n'est pas explicitement définie). Le SDK n'impose aucune durée de vie (TTL) de session de son côté.

Pour prolonger une session avant l'expiration de son JWT, appelez refreshSession(jwt) avec un JWT récent. De nombreux clients émettent des JWT à durée de vie courte (15 minutes) et les actualisent toutes les 10 minutes environ depuis leur backend.

Rétablissement de la connexion après une coupure temporaire

Si la connexion WebSocket est interrompue pour quelque raison que ce soit (perte de connexion, application mise en veille, onglet fermé), le serveur marque la session comme déconnectée mais la maintient active pendant environ 15 minutes afin que le client puisse se reconnecter. Pendant ce laps de temps :

Appeler refreshSession(jwt) si vous disposez toujours de l'état du SDK (le SDK suit l'identifiant de session en interne).
Ou appelez-nous createSession(jwt, existingSessionId) si vous avez perdu l'état du SDK (par exemple, lors du redémarrage de l'application), mais que vous avez conservé vous-même l'identifiant de session.

Dans les deux cas, le serveur backend rejoue tous les événements survenus pendant que vous étiez déconnecté (invitations à des appels entrants, etc.), ce qui permet au client de répondre à un appel reçu pendant la période de reconnexion.

Au bout d'environ 15 minutes sans reconnexion, la session est supprimée et vous devez appeler createSession(jwt) avec un JWT valide pour en créer un nouveau.

Voir Sessions du Vonage Client SDK Pour plus d'informations sur le cycle de vie des sessions.

Durée de vie de la session (15 minutes) et date d'expiration du JWT (exp (réclamation) sont indépendantes. Un JWT peut être valide pendant plus de 15 minutes, mais la session expire tout de même au bout de 15 minutes si elle n'est pas actualisée. Veillez à toujours actualiser ou recréer la session avant l'expiration du TTL.

Traitement des erreurs

createSession peut échouer pour plusieurs raisons. Veillez à toujours gérer la fonction de rappel en cas d'erreur :

try {
  const sessionId = await client.createSession(token);
  console.log("Session created:", sessionId);
} catch (error) {
  // error is a VonageError with type and message
  console.error("Session creation failed:", error.type, error.message);
}

client.createSession(token) { error, sessionId ->
    if (error != null) {
        when {
            error.message?.contains("token") == true ->
                // Invalid or expired JWT — request a new one from your backend
                println("Token error: $error")
            error.message?.contains("already active") == true ->
                // Session already exists — call deleteSession first if you need a fresh session
                println("Session already active")
            else ->
                println("Session creation failed: $error")
        }
    } else {
        println("Session created: $sessionId")
    }
}

client.createSession(token) { error, sessionId in
    if let error = error {
        print("Session creation failed: \(error.localizedDescription)")
        return
    }
    print("Session created: \(sessionId ?? "")")
}

Pour obtenir la liste complète des types d'erreurs possibles, consultez Erreurs.