Guía de migración a Twilio (Web)

Esta guía te indica cómo migrar tu implementación existente de Twilio Video al SDK de Vonage Video. Se centra en el SDK de Vonage Video API y asigna conceptos de Twilio a sus equivalentes de Vonage para que puedas trasladar tu aplicación con la mínima fricción.

Visión general

Las Video API de Twilio y Vonage tienen conceptos muy similares. Esta guía de inicio pretende ayudarte a migrar tu aplicación de vídeo. La principal diferencia es que en Twilio necesitas crear una sala SID mientras que en Vonage se crea un sessionId. Luego creas tokens de autenticación que se utilizan del lado del cliente para conectarse a salas en Twilio o sesiones en Vonage. Los siguientes diagramas detallan las principales diferencias:

Obtener credenciales de Video SDK

Crear un Video Developer Account para acceder al SDK del panel de control del cliente de la API de Vonage. Una vez que te registres, deberás crear una aplicación de Vonage con la función de video habilitada. Una vez que hayas iniciado sesión en el Panel del cliente:

Vaya a "Construir y gestionar" y después a 'Applications'.
Haga clic en '+ Crear una nueva aplicación.'
Introduzca un nombre para la aplicación.
Si es necesario, cambie la API Key a la Account a la que se registrará esta aplicación. Para la mayoría de los clientes, puede dejar esto en la configuración preseleccionada.
En "Autenticación", haz clic en "Generar clave pública y privada". Se iniciará una descarga de la clave privada, que se utilizará para autenticar su Account cuando acceda a nuestras API. Por ejemplo, la utilizará con la API SDK de servidor para gestionar tus sesiones de vídeo.
Desplácese hacia abajo y active "Vídeo". No es necesario introducir ninguna URL o configuración en este punto, pero si desea habilitar diferentes devoluciones de llamada para eventos, puede introducir las URL de su aplicación aquí.
Desplácese hacia abajo y haga clic en "Generar nueva solicitud".
En la parte superior de la página de Aplicaciones aparecerá el ID de la Aplicación que acaba de crear. Haga clic en el icono Copiar para guardarlo más tarde.

Instale

Instala el Vonage Video Client SDK para JS:

npm install @vonage/client-sdk-video

O utilice la etiqueta de script CDN:

<script src="https://www.unpkg.com/@vonage/client-sdk-video@2.26.4/dist/js/opentok.min.js"><script>

Autenticación

El SDK de Vonage Video utiliza tokens para autenticar a los usuarios. Al generar un token, puedes establecer el rol del usuario (suscriptor, editor o moderador). Opcionalmente, también puedes asignar una cadena de metadatos al token (es decir, para identificar al cliente conectado). Consulte nuestro Artículo de descripción general de la creación de tokens para conocer todas las opciones que puede utilizar al generar tokens. Los tokens deben generarse en el lado del servidor y enviarse al lado del cliente bajo demanda.

Crear una sesión de vídeo

A "Sesión" es como un "habitación". Todos los clientes que utilicen el mismo identificador de sesión podrán comunicarse entre sí.

Al igual que los tokens, las sesiones se crean en el servidor. Consulte nuestro Artículo sobre la creación de sesiones para más detalles, incluidas las distintas opciones de configuración disponibles.

Para crear una sesión y generar un token, recomendamos utilizar uno de nuestros módulos SDK para servidores.

Este fragmento de código en NodeJS muestra cómo puedes crear una API sencilla para generar tokens e identificadores de sesión en tu backend.

const { Auth } = require('@vonage/auth');
const { Video } = require('@vonage/server-sdk');

const credentials = new Auth({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: process.env.PRIVATE_KEY_PATH,
});

/**
 * Mapping of room names to session IDs
 * ie:
 *   sessions = {
 *     'room1': '12312312-3811-4726-b508-e41a0f96c68f',
 *     'my-room': '7c0680fc-6274-4de5-a66f-d0648e8d3ac2'
 *   }
 */
let sessions = {};

app.get('/sessionInfo', async (request, response) => {
  try {
    const { identity, roomName } = request.query;

    // Token options, this is optional
    let tokenOptions = {
      role: 'publisher', // subscriber, publisher or moderator
      data: `username=${identity}`, // metadata describing the connection
      expireTime: new Date().getTime() / 1000 + 5 * 60 , // Token expired after five minutes
    };

    // Check if we already have a session ID for this room
    if (sessions[roomName]) {
      const token = videoClient.generateClientToken(sessions[roomName], tokenOptions);

      return response.json({
        applicationId: process.env.VONAGE_APPLICATION_ID,
        sessionId: sessions[roomName],
        token
      });
    } else {
      // Create a new session since we do not have one cached by that name
      const session = await videoClient.createSession({ mediaMode: 'routed' });
      sessions[roomName] = session.sessionId;

      // Generate a token.
      const token = videoClient.generateClientToken(session.sessionId, tokenOptions);

      response.json({
        applicationId: process.env.VONAGE_APPLICATION_ID,
        sessionId: session.sessionId,
        token
      });
    }
  } catch (e) {
    console.log('Error creating session or token' + e);
  }

});

En applicationID, sessionIdy ficha del lado del servidor se utilizará en el lado del cliente para autenticar la sesión del cliente.

Conectarse a una sesión de vídeo

Para conectar un punto final de cliente a una sesión de Vonage Video necesitas un ID de aplicación, un ID de sesión y un token.

Twilio

import * as TwilioVideo from 'twilio-video';

var twilioVideo = TwilioVideo;
var twilioRoom;

twilioVideo
  .connect(TOKEN, {
    name: 'yourName',
    audio: false,
    video: false,
    dominantSpeaker: true,
  })
  .then(room => {
    twilioRoom = room;
  });

Vonage

const session = OT.initSession(applicationId, sessionId);

session.connect(token, error => {
  if (error) {
    handleError(error);
  }
});

Publicación de vídeos

Los SDK de video de Vonage manejan la calidad de video automáticamente, según las condiciones de la red y las capacidades del dispositivo. Dicho esto, puedes configurar ciertas propiedades, como la resolución, la frecuencia de cuadros y el audio fallback. Para obtener más información, consulta la lista exhaustiva de todas las opciones configurables por el editor.

Nota: Un único objeto editor puede gestionar tanto audio como vídeo. Es posible que controlar selectivamente el audio o el vídeo utilizando métodos proporcionados por este objeto.

Encender la cámara

Una vez que tu sesión esté conectada, puedes crear una pista de video para mostrar la vista previa local: en Vonage, la llamamos vista previa del editor.

Twilio

<div class="twilio-local"></div>

<script>
  twilioVideo.createLocalVideoTrack({
     height: { ideal: 720, min: 480, max: 1080 },
     width:  { ideal: 1280, min: 640, max: 1920 },
     aspectRatio: 16/9,
  }).then((localVideoTrack) => {
     twilioRoom.localParticipant.publishTrack(localVideoTrack)
     const localMediaContainer = document.getElementById('twilio-local')
     localMediaContainer!.appendChild(localVideoTrack.attach())
  });
</script>

Vonage

<div id="vonage-local"></div>
<script>
  const publisherOptions = {
      insertMode: 'append',
      width: '100%',
      height: '100%'
    };

    const publisher = OT.initPublisher(‘vonage-local’, publisherOptions, handleError);
</script>

En este punto, debería ver la vista previa local, pero aún no está publicada en la sesión. Para publicar el vídeo en la sesión, añada la siguiente línea de código:

session.publish(publisher, handleError);

Apagar la cámara

El SDK de Vonage ofrece métodos simples para controlar la cámara.

Twilio

twilioRoom.localParticipant.videoTracks.forEach(publication => {
  publication.unpublish();
  publication.track.stop();
  var selfTwilioVideo = document.getElementById('twilio-self-view-div');
  selfTwilioVideo?.querySelector('video')?.remove();
});

Vonage

Esto sólo detendrá la publicación de Video en la sesión. Usted todavía puede ver su vista previa local

publisher.publishVideo(false);

// This will only stop publishing all media (audio and video) to the session. You can still see your local preview
session.unpublish(publisher);

// To completely destroy the publisher and remove the local preview
publisher.destroy();

Renderizar un vídeo de usuario remoto

Similar a Twilio participantConnected y trackSubscribed Vonage también activa los eventos connectionCreated y streamCreated cuando un participante remoto se conecta a la sesión y comienza a enviar video.

Twilio

<div class="twilio-remote-user"></div>

<style>
  #twilio-user-view-div video {
    width: 100%;
    height: auto;
    aspect-ratio: 16/9;
  }
</style>

<script>
  twilioRoom.on('participantConnected', participant => {
    participant.on('trackSubscribed', track => {
      // a user turned on their video, render it_
      document.getElementById('twilio-remote-user').appendChild(track.attach());
    });

    participant.on('trackUnsubscribed', track => {
      // a user turned off their video, stop rendering it_
      var selfTwilioVideo = document.getElementById('twilio-remote-user');

      selfTwilioVideo.querySelector('video').remove();
    });
  });
</script>

Vonage

<div id="vonage-remote-user"></div>

<script>
  session.on('streamCreated', event => {
    const subscriberOptions = {
      insertMode: 'append',
      width: '100%',
      height: '100%',
    };

    session.subscribe(event.stream, 'vonage-remote-user', subscriberOptions, handleError);
  });
</script>

Audio

Twilio Video se basa en pistas, lo que significa que debes recorrer cada pista de audio para iniciar el audio y agregar el elemento de audio al DOM. Vonage puede administrar tanto el audio como el video utilizando un único objeto Publisher. Cuando comienzas a publicar con las opciones predeterminadas, publicamos tanto audio como video. Sin embargo, si prefieres tener una sesión sólo de audio, puedes configurar el editor para que no publique video. Para más información, consulte nuestra lista de opciones del editor.

Silenciar el micrófono

Cuando usas Twilio, debes pasar por cada pista de audio para silenciar el micrófono. Vonage simplifica esto al proporcionar un único método invocable.

Twilio

twilioRoom.localParticipant.audioTracks.forEach(publication => {
  publication.track.disable();
});

Vonage

publisher.publishAudio(false);

Desactivar micrófono

Al usar Twilio Video, debes pasar por cada pista de audio para anular el silencio del micrófono. Vonage simplifica esto al proporcionar un único método invocable.

Twilio

twilioRoom.localParticipant.audioTracks.forEach(publication => {
  publication.track.enable();
});

Vonage

publisher.publishAudio(true);

Chat de texto

Puede intercambiar datos (es decir, mensajes de chat de texto o mensajes JSON personalizados) entre participantes individuales de una sesión, así como entre todos los participantes de una sesión. Esto se logra utilizando nuestro Client SDK, como se muestra a continuación:

//send data to specific end-point
session.signal({ to: connection1, data: 'hello' }, errorHandler);

//send data to all connected end-points
session.signal({ data: 'hello' }, errorHandler);

Establecer escuchadores de eventos para recibir una señal en este punto final.

session.on('signal', function (event) {
  console.log('Signal sent from connection ' + event.from.id);
  // Process the event.data property, if there is any data.
});

Receptores de eventos

Vonage y Twilio tienen escuchadores de eventos para ayudarte a mantener el estado de todos los participantes conectados.

Cambios en la conexión de los participantes

Estos eventos se disparan cuando un punto final se une a la sesión:

Twilio

twilioRoom.on('participantConnected', participant => {
  // user joined
});

twilioVideo.on('participantDisconnected', participant => {
  // user left
});

Vonage

session.on('connectionCreated', payload => {
  // end-point joined
});

session.on('connectionDestroyed', payload => {
  // end-point left
});

Además, Vonage envía eventos para notificar a los participantes las desconexiones temporales de la red y admite reconexión automática si se pierde la conexión con el cliente.

Abandonar y finalizar sesiones

Sustituir el Twilio disconnect con la función Vonage disconnect función.

Twilio

twilio.disconnect();

Vonage

session.disconnect();

Más información:

API REST de Vonage para moderación de sesiones, grabación, difusión, interconexión SIP, subtítulos en directo, etc.
Ejemplos de Vonage JS Client SDK
Ejemplo de solicitud con sala de espera y funciones avanzadas.
Implementar una aplicación de vídeo con React Hooks
Buenas prácticas para la construcción de aplicaciones de vídeo.

Navegación

Guía de migración a Twilio (Web)

Visión general

Obtener credenciales de Video SDK

Instale

Autenticación

Crear una sesión de vídeo

Conectarse a una sesión de vídeo

Twilio

Vonage

Publicación de vídeos

Encender la cámara

Twilio

Vonage

Apagar la cámara

Twilio

Vonage

Renderizar un vídeo de usuario remoto

Twilio

Vonage

Audio

Silenciar el micrófono

Twilio

Vonage

Desactivar micrófono

Twilio

Vonage

Chat de texto

Receptores de eventos

Cambios en la conexión de los participantes

Twilio

Vonage

Abandonar y finalizar sesiones

Twilio

Vonage

Más información: