Migración de sesiones: Instalación y configuración

Esta guía proporciona instrucciones detalladas de configuración y ejemplos de código para habilitar la migración de sesiones en todas las plataformas compatibles. Para obtener una visión general de la rotación de servidores y su impacto en las sesiones, consulte Rotación de servidores y migración de sesiones.

Visión general

Los servidores de medios de la Video API de Vonage se rotan periódicamente como parte del mantenimiento normal de la nube, el autoescalado y las actualizaciones de infraestructura. Las sesiones que se ejecutan durante más de 8 horas son especialmente propensas a verse afectadas.

La migración de sesiones está disponible en SDK versión 2.30.0 y alcanzó Disponibilidad general (GA) en SDK 2.31.0 (agosto de 2025).

Cómo funciona

1. El backend de Vonage detecta que un servidor de medios que aloja una sesión está programado para rotar.
2. A sessionNotification se envía a su punto final de devolución de llamada del servidor - en 4 horas y de nuevo en 1 hora antes de la rotación.
3. Si la migración de sesión está activada, la plataforma migra automáticamente todas las conexiones elegibles a un nuevo servidor multimedia.
4. Los clientes se reconectan de forma transparente con un tiempo de inactividad mínimo. La reconexión suele completarse en unos segundos.

Qué se migra automáticamente y qué requiere una acción manual

Cuando se produce una migración de sesión, no todos los servicios se gestionan automáticamente. Utilice la tabla siguiente para saber qué debe gestionar su aplicación.

Activación de la migración automática de sesiones

Client SDK (Web / Nativo)

Activar la migración de sesión pasando sessionMigration: true al inicializar una sesión:

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 marcación)

Para habilitar la migración de sesión para conexiones SIP, incluya sessionMigration: true en el cuerpo de la solicitud de la Dial API:

{
  "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 audio (Connect API)

Para habilitar la migración de sesión para las conexiones WebSocket del conector de audio, incluya sessionMigration: true en el cuerpo de la solicitud de Connect API:

{
  "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 (Python SDK)

Para activar la migración de sesiones para el conector de vídeo, establezca enable_migration=True en la configuración de la sesión:

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
)

Activación manual de la migración de sesiones

Además de la migración automática durante la rotación del servidor, puede activar manualmente una migración de sesión utilizando la API REST. Esto es útil para:

• Migración proactiva de una sesión antes de una rotación programada (por ejemplo, a las 7,5 horas).
• Prueba y simulación del comportamiento de rotación del servidor en su aplicación
• Dar a los clientes el control sobre cuándo se produce la migración (por ejemplo, durante una pausa en una reunión larga).

Migrar API de sesión

Método:

URI:

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

Cabeceras:

Ejemplo de solicitud:

Códigos de respuesta

Manejo de eventos sessionNotification

La plataforma de Vonage envía sessionNotification a su servidor antes de una rotación programada. Puede utilizarlos para notificar proactivamente a los usuarios o para activar una migración manual en el momento oportuno.

Ejemplo de carga de devolución de llamada:

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

Para recibir estos eventos, configure una URL de devolución de llamada de supervisión de sesión en su Panel de API de Vonage.

Notas

• La migración de sesiones sólo se aplica a rotación del servidor multimedia. No cubre la rotación del servidor SIP o del servidor TURN, que la plataforma gestiona por separado.
• sessionMigration por defecto false y debe activarse explícitamente en cada conexión de cliente que deba reconectarse automáticamente. Las conexiones sin este indicador se cerrarán durante la migración.
• La versión mínima requerida del SDK es 2.30.0. Asegúrese de que todos los clientes tienen el SDK 2.30.0 o posterior.
• Para las conexiones SIP y Audio Connector, el tramo de llamada externo (SIP o WebSocket) permanece conectado durante la migración. Las conexiones multimedia se restablecen en el nuevo servidor. Es posible que se produzca un breve silencio en el terminal durante el cambio.
• Archiving, Broadcasting, Experience Composer y Live Captions deben reiniciarse manualmente después de la migración. En el caso de Experience Composer, reinicie el mismo ID de sesión - la sesión migrada conserva el mismo ID de sesión en el nuevo servidor.
• Tras la migración, el nuevo servidor proporciona un 10 minutos de gracia para permitir que los clientes se vuelvan a conectar y se reanuden los servicios. Durante esta ventana, cualquier intento de reconexión o solicitud de API (como iniciar un archivo) se dirige automáticamente al nuevo servidor.
• La API Migrar sesión impide que se produzcan varias migraciones simultáneas. Si ya hay una migración en curso, la API devuelve un mensaje 409 error con código 15214. Si se llama demasiado pronto después de la creación de la sesión o de una migración anterior, devuelve 409 con código 15215.
• Para las sesiones que se aproximan a las 8 horas, considere la posibilidad de activar proactivamente la migración en la marca de 7,5 horas mediante la API Migrar sesión para evitar interrupciones durante los picos de uso.
• Monitor sessionNotification eventos: utilice los avisos de 4 horas y 1 hora para informar proactivamente a los usuarios o programe una migración manual en un momento de poco tráfico.