Guia de migração do Twilio (Web)

Este guia explica como migrar sua implementação atual do Twilio Video para o SDK do Vonage Video. Ele se concentra no Vonage Video API e mapeia os Concepts do Twilio para seus equivalentes na Vonage, para que você possa migrar seu aplicativo com o mínimo de dificuldade.

Visão geral

As Video APIs do Twilio e do Vonage têm conceitos muito semelhantes. Este guia introdutório tem como objetivo ajudá-lo a migrar seu aplicativo de vídeo. A principal diferença é que, no Twilio, é necessário criar uma sala SID considerando que, no Vonage, você cria um sessionId. Em seguida, você cria tokens de autenticação que são usados no lado do cliente para se conectar a salas no Twilio ou a sessões no Vonage. Os diagramas a seguir detalham as principais diferenças:

Vonage Twilio migraiton illustration 1

Vonage Twilio migraiton illustration 1

Obter credenciais do Video SDK

Criar um Video Developer Account para acessar o Painel do Cliente da API da Vonage. Após se cadastrar, você precisará criar um aplicativo da Vonage com o recurso de vídeo ativado. Depois de fazer login no Painel do Cliente:

  1. Vá para “Criar e gerenciar” e, em seguida, “Applications'.
  2. Clique em '+ Criar um novo aplicativo.'
  3. Digite um nome para o aplicativo.
  4. Se necessário, altere a chave da API para o Account na qual este aplicativo será registrado. Para a maioria dos clientes, é possível manter a configuração pré-selecionada.
  5. Na seção “Autenticação”, clique em “Gerar chave pública e privada”. Será iniciado o download da chave privada, que será usada para autenticar seu Account ao acessar nossas APIs. Por exemplo, você usará essa chave com o SDKs de servidor para gerenciar suas sessões de vídeo.
  6. Role a página para baixo e ative a opção “Vídeo”. Não é necessário inserir nenhum URL ou configuração neste momento, mas, se você quiser habilitar diferentes callbacks para eventos, pode inserir aqui os URLs do seu aplicativo.
  7. Role a página para baixo e clique em “Gerar novo pedido”.
  8. Na parte superior da página “Applications”, estará o ID do aplicativo que você acabou de criar. Clique no ícone “Copiar” para salvá-lo para uso posterior.

Instalar

Instale o Vonage Client SDK para JS:

npm install @vonage/client-sdk-video

Ou use a tag de script do CDN:

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

Autenticação

O SDK de vídeo da Vonage utiliza tokens para autenticar usuários. Ao gerar um token, é possível definir a função do usuário (assinante, editor ou moderador). Opcionalmente, também é possível atribuir uma sequência de metadados ao token (ou seja, para identificar o cliente conectado). Consulte nosso Artigo “Visão geral da criação de tokens” para conhecer todas as opções disponíveis na geração de tokens. Os tokens devem ser gerados no lado do servidor e enviados ao lado do cliente sob demanda.

Criar uma sessão de vídeo

A "Sessão" é como um "sala". Todos os clientes que utilizarem o mesmo ID de sessão poderão se comunicar entre si.

Assim como os tokens, as sessões são criadas no lado do servidor. Consulte nosso Artigo: Visão geral da criação de sessões para obter mais detalhes, incluindo as diversas opções de configuração disponíveis.

Para criar uma sessão e gerar um token, recomendamos usar um dos nossos SDKs de servidor.

Este trecho de código em Node.js mostra como você pode criar uma API simples para gerar tokens e IDs de sessão no seu 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);
  }

});

O applicationID, sessionId, e token do lado do servidor será utilizado no lado do cliente para autenticar a sessão do cliente.

Conectar-se a uma sessão de vídeo

Para conectar um endpoint de cliente a uma sessão do Vonage Video, você precisa de um ID de aplicativo, um ID de sessão e um 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);
  }
});

Publicação de vídeo

Os SDKs de vídeo da Vonage ajustam a qualidade do vídeo automaticamente, com base nas condições da rede e nos recursos do dispositivo. Dito isso, é possível configurar determinadas propriedades, como resolução, taxa de quadros e alternativa de áudio. Para obter mais informações, consulte a lista completa de todas as opções configuráveis pelo editor.

Observação: um único objeto “publisher” pode lidar tanto com áudio quanto com vídeo. Você pode controlar seletivamente o áudio ou o vídeo utilizando os métodos fornecidos por este objeto.

Ligue a câmera

Assim que sua sessão estiver conectada, você poderá criar uma trilha de vídeo para exibir a pré-visualização local — na Vonage, chamamos isso de “pré-visualização do 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>

Neste momento, você deve ver a pré-visualização local, mas ela ainda não foi publicada na sessão. Para publicar o vídeo na sessão, adicione a seguinte linha de código:

session.publish(publisher, handleError);

Desligue a câmera

O SDK da Vonage oferece métodos simples para controlar a câmera.

Twilio

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

Vonage

Isso apenas interromperá a transmissão do vídeo para a sessão. Você ainda poderá ver a pré-visualização 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();

Exibir o vídeo de um usuário remoto

Semelhante ao Twilio participantConnected e trackSubscribed Além dos ouvintes de eventos, a Vonage também aciona os eventos `connectionCreated` e `streamCreated` quando um participante remoto se conecta à sessão e começa 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>

Áudio

O Twilio Video funciona com faixas, o que significa que você precisa percorrer cada faixa de áudio para iniciar a reprodução e adicionar o elemento de áudio ao DOM. O Vonage pode gerenciar tanto o áudio quanto o vídeo usando um único objeto Publisher. Quando você inicia a publicação com as opções padrão, publicamos tanto o áudio quanto o vídeo. No entanto, se você preferir uma sessão apenas de áudio, é possível configurar o Publisher para não publicar vídeo. Para mais informações, consulte nosso lista de opções de editoras.

Silenciar o microfone

Ao usar o Twilio, é preciso percorrer cada faixa de áudio para silenciar o microfone. O Vonage simplifica esse processo, oferecendo um único método que pode ser chamado.

Twilio

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

Vonage

publisher.publishAudio(false);

Ativar o microfone

Ao usar o Twilio Video, é necessário percorrer cada trilha de áudio para ativar o microfone. O Vonage simplifica esse processo, oferecendo um único método que pode ser chamado.

Twilio

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

Vonage

publisher.publishAudio(true);

Bate-papo por texto

É possível trocar dados (ou seja, mensagens de chat de texto ou mensagens JSON personalizadas) entre participantes individuais de uma sessão, bem como entre todos os participantes de uma sessão. Isso é feito por meio do nosso Client SDK, conforme mostrado a seguir:

//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);

Defina ouvintes de eventos para receber um sinal neste ponto de extremidade.

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

Ouvintes de eventos

A Vonage e a Twilio oferecem ouvintes de eventos para ajudar você a manter o estado de todos os participantes conectados.

Alterações na conexão dos participantes

Esses eventos são acionados quando um ponto final entra na sessão:

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
});

Além disso, a Vonage envia notificações para informar os participantes sobre desconexões temporárias da rede e oferece suporte a reconexão automática se a conexão com o cliente for perdida.

Sessões de saída e encerramento

Substituir o Twilio disconnect função com a Vonage disconnect função.

Twilio

twilio.disconnect();

Vonage

session.disconnect();

Mais informações: