Migração de sessões: instalação e configuração

Este guia fornece instruções detalhadas de configuração e exemplos de código para habilitar a migração de sessões em todas as plataformas compatíveis. Para obter uma visão geral da rotação de servidores e seu impacto nas sessões, consulte Rotação de servidores e migração de sessões.

Visão geral

Os servidores de mídia da Video API da Vonage são alternados periodicamente como parte da manutenção normal da nuvem, do dimensionamento automático e das atualizações da infraestrutura. As sessões em execução há mais de 8 horas têm maior probabilidade de serem afetadas.

A migração de sessão está disponível a partir de Versão 2.30.0 do SDK e chegou a Disponibilidade Geral (GA) no SDK 2.31.0 (agosto de 2025).

Como funciona

1. O back-end da Vonage detecta que um servidor de mídia que hospeda uma sessão está programado para rotação.
2. A sessionNotification o evento é enviado para o endpoint de callback do seu servidor — em 4 horas e novamente em 1 hora antes da rotação.
3. Se a migração de sessões estiver ativada, a plataforma migra automaticamente todas as conexões elegíveis para um novo servidor de mídia.
4. Os clientes se reconectam de forma transparente, com tempo de inatividade mínimo. A reconexão geralmente é concluída em poucos segundos.

O que é migrado automaticamente e o que requer ação manual

Quando ocorre uma migração de sessão, nem todos os serviços são tratados automaticamente. Use a tabela abaixo para entender o que seu aplicativo precisa tratar.

Ativação da migração automática de sessões

Client SDK (Web / Nativo)

Habilite a migração de sessão passando sessionMigration: true ao inicializar uma sessão:

Web (JavaScript)

const session = OT.initSession(apiKey, sessionId, {
  sessionMigration: true
});

iOS (Swift)

let settings = OTSessionSettings()
settings.sessionMigration = true
let session = OTSession(apiKey: apiKey, sessionId: sessionId, delegate: self, settings: settings)

Android (Kotlin)

val settings = Session.SessionProperties.Builder()
    .sessionMigration(true)
    .build()
val session = Session(context, apiKey, sessionId, settings)

React Native

// Pass sessionMigration in the OTSession options prop
<OTSession
  apiKey={apiKey}
  sessionId={sessionId}
  token={token}
  options={{ sessionMigration: true }}
>

SIP (API de discagem)

Para habilitar a migração de sessão para conexões SIP, inclua sessionMigration: true no corpo da sua solicitação à API Dial:

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "sessionMigration": true
  }
}

Conector de áudio (API Connect)

Para habilitar a migração de sessão para conexões WebSocket do Audio Connector, inclua sessionMigration: true no corpo da sua solicitação à API do Connect:

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "websocket": {
    "uri": "wss://your-websocket-server.example.com",
    "sessionMigration": true
  }
}

Conector de vídeo (SDK do Python)

Para habilitar a migração de sessão para o Video Connector, defina enable_migration=True nas configurações da sua sessão:

from vonage_video_connector import VonageVideoClient
from vonage_video_connector.models import SessionSettings

session_settings = SessionSettings(enable_migration=True)
client = VonageVideoClient()
client.connect(
    application_id="<application-id>",
    session_id="<session-id>",
    token="<token>",
    session_settings=session_settings
)

Como acionar manualmente a migração de sessão

Além da migração automática durante a rotação de servidores, é possível acionar manualmente uma migração de sessão por meio da API REST. Isso é útil para:

• Migrar proativamente uma sessão antes de uma rotação programada (por exemplo, na marca de 7,5 horas)
• Testando e simulando o comportamento da rotação de servidores em seu aplicativo
• Permitir que os clientes decidam quando a migração ocorrerá (por exemplo, durante um intervalo em uma reunião longa)

Migrar a API de sessão

Método: POST

URI:

/v2/project/<projectId>/session/<sessionId>/migrate

Títulos:

Exemplo de solicitação:

Códigos de resposta

Tratamento de eventos de sessionNotification

A plataforma da Vonage envia sessionNotification eventos de retorno de chamada para o seu servidor antes de uma rotação programada. Você pode usá-los para notificar os usuários de forma proativa ou acionar uma migração manual em um momento oportuno.

Exemplo de carga útil de callback:

{
  "sessionId": "<session-id>",
  "projectId": "<project-id>",
  "event": "sessionNotification",
  "reason": "serverRotation",
  "remainingTime": 3600
}

Para receber esses eventos, configure uma URL de retorno de chamada para monitoramento de sessão em seu Painel da API da Vonage.

Notas

• A migração de sessão se aplica apenas a rotação do servidor de mídia. Não abrange a rotação de servidores SIP ou TURN, que são gerenciadas separadamente pela plataforma.
• sessionMigration o valor padrão é false e deve ser explicitamente ativado em todas as conexões de cliente que devam ser reconectadas automaticamente. As conexões sem esse sinalizador serão encerradas durante a migração.
• A versão mínima do SDK necessária é 2,30,0. Certifique-se de que todos os clientes estejam utilizando o SDK 2.30.0 ou uma versão posterior.
• Para conexões SIP e Audio Connector, o canal de chamada externo (SIP ou WebSocket) permanece conectado durante a migração. As conexões de mídia são restabelecidas no novo servidor. Pode ocorrer um breve silêncio no terminal durante a troca.
• Os serviços Arquivamento, Transmissão, Experience Composer e Legendas ao Vivo devem ser reiniciados manualmente após a migração. No caso do Experience Composer, reinicie-o no mesmo ID de sessão — a sessão migrada mantém o mesmo ID de sessão no novo servidor.
• Após a migração, o novo servidor oferece um janela de tolerância de 10 minutos para permitir que os clientes se reconectem e os serviços sejam retomados. Durante esse período, qualquer tentativa de reconexão ou solicitação de API (como iniciar um arquivamento) é automaticamente direcionada para o novo servidor.
• A API Migrate Session impede que ocorram várias migrações simultâneas. Se uma migração já estiver em andamento, a API retorna um 409 erro com o código 15214. Se for chamado muito cedo após a criação da sessão ou após uma migração anterior, ele retorna 409 com código 15215.
• Para sessões que se aproximem das 8 horas, considere acionar proativamente a migração ao atingir a marca de 7,5 horas, utilizando a API Migrate Session, a fim de evitar interrupções durante os horários de pico.
• Monitor sessionNotification eventos — use os alertas com antecedência de 4 horas e 1 hora para informar os usuários de forma proativa ou agendar uma migração manual em um momento de baixo tráfego.