Configuração da sessão

Uma sessão é uma conexão autenticada entre seu aplicativo cliente e a API da Vonage. Seu backend emite um JWT, e o Client SDK utiliza esse JWT em createSession().

Modelo de sessão

A API da Vonage controla o ciclo de vida da sessão.
O Client SDK não gera JWTs nem gerencia a emissão de tokens.
Seu backend continua sendo a fonte de referência para as políticas de identidade e acesso.

Fluxo de autenticação

Geração de JWT no backend

O exemplo a seguir ilustra a estrutura necessária do JWT. Sua implementação concreta irá variar de acordo com a linguagem e o framework do seu backend.

Os JWT devem ser gerados no seu servidor. A implementação exata depende do aplicativo.

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

Criar uma sessão

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

Duração da sessão

Uma sessão permanece ativa enquanto o JWT usado em createSession() é válida. A duração da sessão é definida pelo JWT exp sessão — seu backend determina a duração dessa sessão (mínimo de 30 segundos, máximo de 24 horas; o padrão é de 15 minutos, caso não seja definido explicitamente). O SDK não impõe nenhum tempo de vida (TTL) próprio para a sessão.

Para prorrogar uma sessão antes que o JWT expire, chame refreshSession(jwt) com um JWT novo. Muitos clientes geram JWTs de curta duração (15 minutos) e os atualizam a cada ~10 minutos a partir de seu backend.

Reconexão após uma desconexão temporária

Se a conexão do WebSocket for interrompida por qualquer motivo (perda de conexão, aplicativo suspenso, aba fechada), o backend marca a sessão como desconectada, mas a mantém ativa por aproximadamente 15 minutos para que o cliente possa se reconectar. Durante esse intervalo:

Ligar refreshSession(jwt) se você ainda estiver no estado do SDK (o SDK rastreia o ID da sessão internamente).
Ou ligue createSession(jwt, existingSessionId) se você perdeu o estado do SDK (por exemplo, ao reiniciar o aplicativo), mas armazenou manualmente o ID da sessão.

Em ambos os casos, o backend reproduz todos os eventos que ocorreram enquanto você estava desconectado (convites para chamadas recebidas, etc.), de modo que o cliente ainda possa atender uma chamada que tenha chegado durante o período de reconexão.

Após cerca de 15 minutos sem reconexão, a sessão é excluída e você deve ligar para createSession(jwt) com um JWT novo para iniciar um novo.

Veja Sessões do Vonage Client SDK para obter mais detalhes sobre o ciclo de vida da sessão.

TTL da sessão (15 minutos) e validade do JWT (exp (claim) são independentes. Um JWT pode ter validade superior a 15 minutos, mas a sessão ainda assim expira após 15 minutos, a menos que seja atualizada. Sempre atualize ou recrie a sessão antes que o TTL expire.

Tratamento de erros

createSession pode falhar por diversos motivos. Sempre lide com a função de retorno de chamada de erro:

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

Para obter uma lista completa dos tipos de erros possíveis, consulte Erros.