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

Esta guía te explica paso a paso cómo migrar tu implementación actual de Twilio Video al SDK de Vonage Video. Se centra en 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 tiene como objetivo ayudarte a migrar tu aplicación de vídeo. La principal diferencia es que, en Twilio, es necesario 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:

Vonage Twilio migraiton illustration 1

Vonage Twilio migraiton illustration 1

Obtener las credenciales del SDK de vídeo

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:

  1. Ve a «Crear y gestionar» y, a continuación, a «Applications'.
  2. Haz clic en «+ Crear una nueva aplicación.'
  3. Introduzca un nombre para la aplicación.
  4. 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.
  5. 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.
  6. 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í.
  7. Desplázate hacia abajo y haz clic en «Generar nueva aplicación».
  8. En la parte superior de la página «Applications» aparecerá el ID de aplicación que acabas de crear. Haz clic en el icono «Copiar» para guardarlo para más adelante.

Instale

Instala el Vonage 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 vídeo de Vonage utiliza tokens para autenticar a los usuarios. Al generar un token, puedes establecer el rol del usuario (suscriptor, editor o moderador). Si lo deseas, también puedes asignar una cadena de metadatos al token (es decir, para identificar al cliente conectado). Consulte nuestro Artículo de introducción a «Crear token» 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 ID 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 obtener más información, 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);
  }

});

El applicationID, sessionIdy ficha desde el 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 vídeo de Vonage gestionan la calidad del vídeo de forma automática, en función de las condiciones de la red y las capacidades del dispositivo. No obstante, puedes configurar ciertas propiedades, como la resolución, la velocidad de fotogramas y la opción de audio alternativa. Para obtener más información, consulta la lista exhaustiva de todas las opciones configurables del 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 Además de los oyentes de eventos, Vonage también activa los eventos «connectionCreated» y «streamCreated» cuando un participante remoto se conecta a la sesión y empieza a enviar vídeo.

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 de editor.

Silenciar el micrófono

Al utilizar Twilio, hay que recorrer cada pista de audio para silenciar el micrófono. Vonage simplifica este proceso al ofrecer un único método invocable.

Twilio

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

Vonage

publisher.publishAudio(false);

Activar el micrófono

Al utilizar Twilio Video, debes recorrer cada pista de audio para activar el micrófono. Vonage simplifica este proceso al ofrecer un único método invocable.

Twilio

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

Vonage

publisher.publishAudio(true);

Chat de texto

Puedes intercambiar datos (por ejemplo, mensajes de chat de texto o mensajes JSON personalizados) entre participantes individuales de una sesión, así como con todos los participantes de una sesión. Esto se lleva a cabo mediante nuestro Client SDK, tal y 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 cuentan con detectores de eventos que te ayudan a mantener el estado de todos los participantes conectados.

Cambios en la conexión de los participantes

Estos eventos se activan 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 notificaciones para informar a los participantes de las desconexiones temporales de la red y admite reconexión automática si se pierde la conexión con el cliente.

Iniciar 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: