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

Esta guía ofrece 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, consulta Rotación de servidores y migración de sesiones.

Visión general

Los servidores multimedia de la Video API de Vonage se renuevan periódicamente como parte del mantenimiento habitual de la nube, el escalado automático y las actualizaciones de la infraestructura. Las sesiones que llevan más de 8 horas en ejecución son las que tienen más probabilidades de verse afectadas.

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

Cómo funciona

1. El sistema de fondo de Vonage detecta que un servidor multimedia que aloja una sesión está programado para una rotación.
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 sesiones está activada, la plataforma migra automáticamente todas las conexiones que cumplan los requisitos a un nuevo servidor multimedia.
4. Los clientes se vuelven a conectar 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. Utiliza la tabla siguiente para saber qué aspectos debe gestionar tu 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 iniciar 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 sesiones para las conexiones WebSocket de Audio Connector, incluye 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:

• Migrar de forma proactiva una sesión antes de una rotación programada (por ejemplo, al cumplirse las 7,5 horas)
• Prueba y simulación del comportamiento de rotación del servidor en su aplicación
• Permitir a los clientes decidir cuándo se lleva a cabo la migración (por ejemplo, durante una pausa en una reunión larga)

API de migración de sesiones

Método: [PUBLICACIÓN]

URI:

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

Encabezados:

Ejemplo de solicitud:

Códigos de respuesta

Manejo de eventos sessionNotification

La plataforma de Vonage envía sessionNotification eventos de devolución de llamada a tu servidor antes de una rotación programada. Puedes utilizarlos para notificar de forma proactiva a los usuarios o para activar una migración manual en el momento que te resulte más conveniente.

Ejemplo de carga útil de una llamada de retorno:

{
  "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 control de la API de Vonage.

Notas

• La migración de sesiones solo 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 del SDK necesaria es 2,30,0. Asegúrese de que todos los clientes tienen el SDK 2.30.0 o posterior.
• En el caso de las conexiones SIP y Audio Connector, el canal 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.
• Las funciones «Archiving», «Broadcasting», «Experience Composer» y «Live Captions» deben reiniciarse manualmente tras la migración. En el caso de «Experience Composer», reinícialo en el 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 ofrece 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 el 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.