Guia de transição do Vonage Video para o Node

A transição de opentok para @vonage/video ou @vonage/server-sdk

Introdução

Objetivo

O SDK do OpenTok para Node está em modo de manutenção, pois fizemos a transição para um novo SDK de vídeo, no qual as credenciais da Vonage podem ser utilizadas em nosso SDK para Node em todas as APIs.

Âmbito

Para manter o @vonage/server-sdk Para tornar o pacote o menor possível, o SDK do Node foi dividido em módulos menores. Isso significa que você pode instalar apenas o @vonage/video no seu projeto, em vez de todo o SDK. Seja qual for a opção escolhida, apenas LTS versões do Node.js serão compatíveis (no momento da redação deste artigo, a versão mínima é a 18). O SDK também oferece suporte a módulos Node.js tanto no formato ESM quanto no CJS.

Para os fins deste documento, todos os exemplos serão apresentados utilizando o SDK completo como um módulo CJS. async/await também será usado, pois é mais conciso do que usar promises. Lembre-se de que async/await é apenas um recurso sintático em torno das promessas. Não há diferença em termos de funcionalidade. Este documento também utilizará o suporte mais recente do ECMAScript para const e let além de utilizar funções “fat-arrow”.

O NodeSDK foi escrito em Typescript, mas isso não é um requisito. O Typescript fornece arquivos de definição para que seu IDE exiba corretamente as instruções de uso.

Suposições

Para migrar do OpenTok para o Node SDK, você precisará saber como funcionam as promessas (ou async/await) funcionam. Os callbacks não são mais suportados.

Recursos

Código-fonte do SDK de vídeo da Vonage Documentação da Video API da Vonage Especificações da Video API da Vonage

Planejando sua migração

Avaliar o impacto

O SDK do OpenTok foi desenvolvido utilizando callbacks. Isso significa que a migração exigirá mudanças significativas em seu projeto. Dependendo de como você estruturou suas funções, isso pode se tornar um desafio. Tomemos, por exemplo, a criação de uma sessão

Para o SDK do node, é tão simples quanto:

try {
    const session = await vonage.video.createSession(
        {} // session options
    );
    console.log(session.sessionId);
} catch (err) {
    console.error(err);
}

Enquanto, no passado, isso exigia o uso de callbacks para realizar a mesma tarefa:

OT.createSession(
    {}, // session options
    function (err, session) {
        if (err) {
            console.error(err)
            return;
        }
        
        console.log(session.sessionId);
    }
);

Como você pode ver, trata-se de uma grande mudança de paradigma no design, que afeta o funcionamento do seu projeto. Se o seu projeto depende de outro pacote que não oferece suporte a promises, você pode usar Promise.resolve para forçar a resolução da promessa. No entanto, isso pode acarretar algum custo de desempenho, já que o aplicativo terá que aguardar que o SDK conclua a chamada à API antes de poder continuar.

Se você realmente não puder converter para async/await, você não poderá realizar a migração.

Linha do tempo

Leve em consideração o tempo necessário para concluir a transição. Isso vai depender da sua experiência com o projeto e do impacto dele, bem como dos testes. É fundamental contar com um bom conjunto de testes para que você possa verificar a equivalência entre os SDKs de vídeo do OpenTok e da Vonage. O tempo necessário para concluir a transição é aproximadamente proporcional ao número de locais em que o SDK do OpenTok é usado em seu código, bem como à variedade de recursos utilizados. Algumas chamadas de API serão mais simples de substituir do que outras.

Atualização do pacote

Para atualizar o pacote de vídeos, você pode fazer a instalação usando npm ou yarn assim:

Se você quiser instalar o módulo independente (os usuários do Typescript também precisarão importar @vonage/auth para criar o cliente de vídeo):

Alterações na autenticação

A autenticação, tanto no OpenTok quanto no Node SDK, é feita automaticamente para você, portanto, basta fornecer as credenciais da sua conta uma única vez, na inicialização. A diferença é que o OpenTok exige uma chave e um segredo de API, enquanto que, para a Video API no SDK do Node, você precisa fornecer um ID de aplicativo e sua chave privada. Embora tanto a Vonage quanto o OpenTok utilizem autenticação baseada em tokens, os tokens da Vonage são JWTs enquanto o OpenTok utiliza um formato personalizado. Embora seja possível fornecer uma chave de API e um segredo ao VonageClient Assim como no caso do OpenTok, isso é utilizado para outras APIs da Vonage, e não para vídeo. Portanto, você precisará criar um aplicativo ou usar um já existente.

Você pode criar um aplicativo a partir do Painel do Vonage. Certifique-se de que o recurso de vídeo esteja ativado no seu aplicativo. Clique em “Editar” em uma aplicação existente para visualizar seus recursos e credenciais. A partir daqui, clique em “Gerar chave pública e privada”. Isso só deve ser feito uma vez, pois cada vez que você fizer isso, as credenciais serão alteradas, o que invalidará o par de chaves existente. Ao clicar nessa opção, será iniciado o download da sua chave privada. Você deve armazenar esse arquivo em um local seguro para fins de teste. NUNCA COMPARTILHE NEM REVELE SUA CHAVE PRIVADA! A chave privada é, na verdade, a “senha” do seu aplicativo; portanto, deve ser tratada com cuidado.

Para obter mais orientações sobre como configurar um aplicativo, consulte o guia de introdução.

Depois de criar o aplicativo e baixar a chave privada, você deve passar essas informações para o cliente:

const { Vonage } = require('@vonage/server-sdk')

const vonage = new Vonage({
  appId: 'Your application id',
  privateKey: 'Your private key',
});

Estratégias de migração

Migrar de callbacks para promises não é tarefa fácil. É provável que todo o seu projeto utilize callbacks. Você também pode estar usando pacotes de terceiros que foram escritos com base em callbacks. O melhor é abordar cada chamada de API, uma de cada vez.

Observe que o uso do recurso integrado util.promisify utilitário, pode nem sempre funcionar. Existem algumas funções de retorno que retornam vários parâmetros, o que util.promisify não consegue lidar.

Métodos alterados

Recomendações para testes

Testes completos são essenciais para uma transição tranquila, tanto durante quanto após a migração. Isso inclui não apenas testes unitários, mas também testes de integração e de regressão. Também vale a pena testar manualmente o fluxo do seu aplicativo pelo menos uma vez antes e depois da migração para garantir que seus testes automatizados funcionem como você espera, ou para identificar quaisquer problemas que os testes possam não ter detectado. Você pode até considerar a criação de testes de equivalência. A ideia é criar um conjunto de testes que comprove que tanto a versão OpenTok quanto a versão Vonage Video da sua aplicação funcionam da mesma maneira. Esses testes podem então ser descartados assim que a transição estiver concluída e a versão OpenTok da sua aplicação for removida.

Canais de suporte

Para obter ajuda geral e participar de discussões sobre a migração para o Vonage Video, confira o Canal #Video API no nosso Slack da Comunidade, onde você pode obter respostas da equipe da Vonage e de outros usuários.

Você também pode entrar em contato conosco no X @VonageDev.

O principal ponto de contato para quaisquer questões relacionadas à própria Video API é support@api.vonage.com.

Suporte direto pelo Slack: Slack dos desenvolvedores da Vonage

Se você encontrar um bug no SDK, abra um ticket em abrir um ticket no GitHub com os passos para reproduzir o problema

Por fim, o módulo de vídeo possui documentação gerada automaticamente, hospedada no wiki seção do repositório do GitHub.