Einrichtung der Sitzung

Eine Sitzung ist eine authentifizierte Verbindung zwischen Ihrer Client-App und der Vonage-API. Ihr Backend stellt ein JWT aus, und das Vonage Client SDK verwendet dieses JWT in createSession().

Sitzungsmodell

  • Die Vonage-API steuert den Lebenszyklus der Sitzung.
  • Das Client SDK erstellt keine JWT-Token und verwaltet auch nicht die Token-Ausstellung.
  • Ihr Backend bleibt die maßgebliche Quelle für Identitäts- und Zugriffsrichtlinien.

Ablauf der Authentifizierung

JWT-Generierung im Backend

Das folgende Beispiel veranschaulicht die erforderliche JWT-Struktur. Ihre konkrete Umsetzung hängt von der Sprache und dem Framework Ihres Backends ab.

JWTs müssen auf Ihrem Server generiert werden. Die genaue Umsetzung ist anwendungsspezifisch.

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

Eine Sitzung erstellen

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

Dauer der Sitzung

Eine Sitzung bleibt so lange bestehen, wie das in createSession() ist gültig. Die Sitzungsdauer wird durch das JWT festgelegt. exp Anfrage – Ihr Backend legt fest, wie lange diese dauert (mindestens 30 Sekunden, höchstens 24 Stunden, standardmäßig 15 Minuten, sofern nicht ausdrücklich anders festgelegt). Das SDK schreibt keine eigene Sitzungs-TTL vor.

Um eine Sitzung zu verlängern, bevor das JWT abläuft, rufen Sie folgenden Befehl auf: refreshSession(jwt) mit einem neuen JWT. Viele Kunden stellen kurzlebige (15-minütige) JWTs aus und aktualisieren diese etwa alle 10 Minuten über ihr Backend.

Wiederherstellung der Verbindung nach einer vorübergehenden Unterbrechung

Wenn die WebSocket-Verbindung aus irgendeinem Grund unterbrochen wird (Netzwerkausfall, App angehalten, Tab geschlossen), markiert das Backend die Sitzung als unterbrochen, hält sie jedoch für etwa 15 Minuten damit sich der Client wieder verbinden kann. Während dieses Zeitfensters:

  • Rufen Sie an. refreshSession(jwt) sofern der SDK-Status noch vorhanden ist (das SDK verfolgt die Sitzungs-ID intern).
  • Oder rufen Sie an createSession(jwt, existingSessionId) falls Sie den SDK-Status verloren haben (z. B. durch einen Neustart der App), die Sitzungs-ID jedoch selbst gespeichert haben.

In beiden Fällen spielt das Backend alle Ereignisse nach, die während der Unterbrechung der Verbindung eingegangen sind (Einladungen zu eingehenden Anrufen usw.), sodass ein Kunde einen Anruf, der während des Zeitfensters für die Wiederherstellung der Verbindung eingegangen ist, dennoch annehmen kann.

Nach etwa 15 Minuten ohne erneute Verbindung wird die Sitzung gelöscht und Sie müssen den Befehl aufrufen createSession(jwt) mit einem neuen JWT, um einen neuen zu starten.

Siehe Vonage Client SDK-Sitzungen Weitere Informationen zum Lebenszyklus einer Sitzung.

Sitzungs-TTL (15 Minuten) und JWT-Ablaufzeit (exp (Claim) sind voneinander unabhängig. Ein JWT kann länger als 15 Minuten gültig sein, doch die Sitzung läuft dennoch nach 15 Minuten ab, sofern sie nicht aktualisiert wird. Aktualisieren oder erstellen Sie die Sitzung stets neu, bevor die TTL abläuft.

Umgang mit Fehlern

createSession kann aus verschiedenen Gründen fehlschlagen. Behandeln Sie den Fehler-Callback immer wie folgt:

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 ?? "")")
}

Eine vollständige Liste der möglichen Fehlerarten finden Sie unter Fehler.