Guia de transição do Vonage Video para Java

A transição de `com.tokbox:opentok-server-sdk` para `com.vonage:server-sdk`.

Introdução

Objetivo

O objetivo deste documento é fornecer um ponto de partida para a transição do SDK do servidor Java da OpenTok para o SDK do servidor Java da Vonage.

Âmbito

Este documento pressupõe que você esteja usando, no mínimo, a versão 4.0.0 ou posterior do SDK do OpenTok para Java. A Video API foi adicionada ao Java Server SDK na versão 8.0.0. Você deve usar a versão mais recente do SDK Java da Vonage, que pode ser encontrada em GitHub ou Maven Central.

Suposições

Este guia destina-se a ser seguido por um engenheiro de software profissional. Presume-se que o leitor possua, no mínimo, um nível básico de conhecimento em Java, nas ferramentas comuns de desenvolvimento Java, em sistemas de compilação (Maven ou Gradle) e no Git (ou outro sistema de controle de versão). Você deve estar à vontade para ler e escrever código Java, gerenciar dependências de projeto, implantar e executar um projeto Java. Uma introdução à linguagem Java, à plataforma e às ferramentas associadas está bem além do escopo deste documento.

Recursos

Os links a seguir são úteis para leituras complementares a este documento e como referência para qualquer assunto não abordado neste documento:

Vonage

TokBox

Planejando sua migração

Antes de fazer a transição do OpenTok para o Vonage Video, é importante levar em conta a magnitude da tarefa para definir expectativas realistas.

Avaliar o impacto

A primeira pergunta a ser respondida é: qual a proporção do código do seu aplicativo que depende do SDK do OpenTok? Faça uma lista de todos os arquivos nos quais o SDK é usado diretamente. Ou seja, qualquer arquivo-fonte Java que contenha importações do com.opentok pacote. Você pode procurar nos arquivos do seu projeto pela instrução import com.opentok usando um IDE ou uma ferramenta de linha de comando para identificar os arquivos afetados.

Linha do tempo

Leve em consideração o tempo necessário para concluir a transição. Isso 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 o OpenTok e o Vonage Video. O tempo necessário para concluir a transição é aproximadamente proporcional ao número de locais em que o SDK do OpenTok é utilizado em seu código, bem como à variedade de recursos utilizados. Algumas chamadas de API serão mais simples de substituir do que outras.

Controle de versões

O ideal é criar um novo branch no seu sistema de controle de versão para a transição, de modo que você possa fazer alterações gradualmente e com frequência sem afetar o projeto existente. Você também pode usar os testes do projeto existente como referência para verificar a correção. O ideal é só mesclar o branch de transição ao branch principal depois de concluir a conversão.

Principais mudanças e considerações

Novos recursos e normas

A Video API da Vonage possui paridade de recursos com a OpenTok, e o SDK para Java é mantido ativamente para estar em conformidade com a especificação da API. Uma das diferenças entre os SDKs Java do OpenTok e da Vonage é que o SDK Java utiliza um modelo de dados com tipagem mais forte, em vez de simples strings. Ele também apresenta maior consistência com outras APIs do SDK e segue convenções que devem tornar o uso do SDK intuitivo. Outra diferença importante é que as classes de solicitação e resposta são unificadas. Por exemplo, você usaria a Archive classe tanto para criar quanto para recuperar um arquivo, enquanto no OpenTok você usaria ArchiveProperties para a solicitação e Archive para a resposta. Assim como o SDK do OpenTok, o SDK do Java utiliza o padrão Builder para construir objetos de solicitação.

Ao contrário do SDK do OpenTok, o SDK da Vonage não utiliza exceções verificadas. Portanto, você não precisa mais fazer um try {...} catch (InvalidArgumentException ex), permitindo que você simplifique seu código. Se você quiser interceptar exceções decorrentes de chamadas de API malsucedidas (ou seja, com código de status diferente de 2xx), você pode interceptar VideoResponseException em vez de OpenTokException.

Atualização de dependências

Primeiramente, você precisará atualizar as dependências do seu sistema de compilação para usar o SDK Java da Vonage em vez do OpenTok. As instruções sobre como fazer isso dependerão do seu sistema de compilação. As instruções sobre como incluir a versão mais recente do SDK Java da Vonage na sua compilação podem ser encontradas em Maven Central ou mvnrepository.com.

Para uma migração gradual, você pode incluir as dependências do OpenTok e do Vonage em seu projeto; no entanto, recomendamos enfaticamente que isso seja feito apenas para fins de teste, e não para implantações em produção, pois o SDK do OpenTok tende a utilizar versões mais antigas das dependências, o que pode causar problemas durante a execução.

Nome do pacote

Depois de adicionar o SDK Java da Vonage ao seu classpath usando sua ferramenta de compilação, você poderá começar a utilizá-lo em seu código.

Você pode substituir as importações do com.opentok e com.opentok.exception pacotes com com.vonage.client.video. Uma operação de “Localizar e Substituir” no seu IDE ou editor de código deve ajudar bastante a resolver a maioria dos erros de compilação.

Observe que não há outros subpacotes para exceções — a única exceção que você precisará interceptar para lidar com erros da API é com.vonage.client.video.VideoResponseException.

Alterações na autenticação

A autenticação nos SDKs de servidor Java do OpenTok e do Vonage é gerenciada automaticamente para você; portanto, basta fornecer as credenciais da sua conta uma única vez, durante a inicialização. A diferença é que o OpenTok exige uma chave e um segredo de API, enquanto que, para a Video API no SDK Java da Vonage, 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 OpenTok, isso é utilizado para outras APIs da Vonage, e não para vídeo. Portanto, você precisará criar uma Application ou usar uma 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 daí, clique em “Gerar chave pública e privada”. Isso só deve ser feito uma vez, pois, a cada vez que você fizer isso, as credenciais serão alteradas, o que invalidará o par de chaves existente. Ao clicar aqui, será iniciado o download da sua chave privada. Você deve armazenar esse arquivo em um local seguro para fins de teste. NUNCA COMPARTILHE OU DIVULGUE SUA CHAVE PRIVADA! A chave privada é, na verdade, a “senha” do seu aplicativo; portanto, deve ser tratada com cuidado. Recomenda-se que você crie uma variável de ambiente que aponte para o caminho do arquivo da sua chave privada, para que possa consultá-la ao configurar o VonageClient, nomeando a variável algo como VONAGE_PRIVATE_KEY_PATH. O mesmo deve ser feito com o ID do seu aplicativo (que pode ser encontrado no painel ou na URL ao editá-lo).

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

Uso

Veja O arquivo README do SDK do Java para obter instruções de configuração.

Em vez disso:

OpenTok videoClient = new OpenTok.Builder(apiKey, apiSecret).build();

Faça o seguinte:

import com.vonage.client.video.*;
import com.vonage.client.VonageClient;

// Inside a constructor or method body:
VonageClient vonage = VonageClient.builder()
 .applicationId(VONAGE_APPLICATION_ID)
 .privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
 .build();
VideoClient videoClient = vonage.getVideoClient();

Depois de instanciar o VonageClient, você pode usar o Video API usando o VideoClient, conforme obtido a partir do VonageClient (veja acima).

Os métodos da API em VideoClient estão documentados no Javadocs e são, em linhas gerais, análogos aos métodos encontrados no OpenTok classe.

Para obter instruções de uso mais detalhadas, consulte o Guia em vídeo do Java Server SDK.

Alterações no método

Há algumas pequenas alterações que você deve levar em conta ao migrar do OpenTok para o Vonage. Muitas delas são simples e seu IDE irá ajudá-lo com o preenchimento automático, mas, para maior clareza, considere o seguinte:

projectId agora é applicationId quando for o caso.
Utilização de tipagem mais forte sempre que aplicável (por exemplo, UUID e URI em vez de String).
playDTMF renomeado para sendDtmf para todos os terminais DTMF aplicáveis.
OpenTok#disableForceMute(String) substituído por VideoClient#muteSession(String, boolean, String...). Você precisa definir o active parâmetro booleano para false para obter o mesmo efeito.
O MuteAllProperties classe e parâmetro em OpenTok foi substituído pelo uso do excludedStreamIds diretamente no parâmetro do método de VideoClient#muteSession(String, boolean, Collection<String>) (ou VideoClient#muteSession(String, boolean, String...) for convenience). Esses métodos substituem OpenTok#forceMuteAll(String, MuteAllProperties).
ArchiveProperties e BroadcastProperties - conforme utilizados nos parâmetros de solicitação no OpenTok - foram substituídos por Archive e Broadcast respectivamente. Ambos utilizam o padrão builder para sua construção.
- Archive e Broadcast Na Vonage, as respostas também são apresentadas de maneira semelhante às do OpenTok.
- Assim, os objetos de solicitação e resposta que representam Archive e Broadcast foram unificados na implementação da Vonage.
OpenTok#setBroadcastLayout(String, BroadcastProperties) substituído por VideoClient#updateBroadcastLayout(String, StreamCompositionLayout).
OpenTok#setArchiveLayout(String, ArchiveProperties) substituído por VideoClient#updateArchiveLayout(String, StreamCompositionLayout).
OpenTok#dial(String, String, SipProperties) substituído por VideoClient#sipDial(SipDialRequest).
- Sip substituído por SipResponse.
O listArchives Os métodos com vários parâmetros no OpenTok foram substituídos por VideoClient#listArchives(ListStreamCompositionsRequest) para controlar as opções.
- A resposta é um simples List<Archive> em vez de ArchiveList. Usar Collection#size() em vez de ArchiveList#getTotalCount() para obter o número de elementos.
OpenTok#setStreamLayouts(String, StreamListProperties) substituído por VideoClient#setStreamLayout(String, List<SessionStream>) (ou VideoClient#setStreamLayout(String, SessionStream...) (por uma questão de praticidade).
OpenTok#signal(String, String, SignalProperties) e OpenTok#signal(String, SignalProperties) substituído por VideoClient#signal(String, String, SignalRequest) e VideoClient#signalAll(String, SignalRequest), respectivamente.
A estrutura dos tokens obtidos utilizou o generateToken métodos em OpenTok e VideoClient são diferentes. A Vonage usa JWTs, enquanto a OpenTok usa uma solução personalizada.
OpenTok#startCaptions(String, String, CaptionProperties) substituído por VideoClient#startCaptions(CaptionsRequest).
- CaptionProperties substituído porCaptionsRequest.
- Caption substituído por CaptionsResponse.
  - CaptionsRequest usa uma enumeração para o languageCode em vez de uma string simples.
  - O token e sessionId ainda são necessários e estão definidos no CaptionsRequest.Builder objeto.
OpenTok#connectAudioStream(String, String, AudioConnectorProperties) substituído por VideoClient#connectToWebsocket(ConnectRequest).
- AudioConnectorProperties substituído por ConnectRequest.
- AudioConnector substituído por ConnectResponse.
OpenTok#startRender(String, String, RenderProperties) substituído por VideoClient#startRender(RenderRequest).
- RenderProperties substituído por RenderRequest.
  - name parâmetro no interno Properties a classe está definida no nível superior RenderRequest.Builder.
- Render substituído por RenderResponse.
  - resolution agora é uma enumeração, em vez de uma string simples.
OpenTok#listRenders(Integer, Integer) substituído por VideoClient#listRenders(ListStreamCompositionsRequest).
- Isso funciona de maneira semelhante à versão atualizada listBroadcasts e listArchives métodos (ver acima).

Recomendações para testes

Testes minuciosos são essenciais para uma transição tranquila, tanto durante quanto após a migração. Isso inclui não apenas testes de unidade, 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 esperado 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 do seu aplicativo funcionam da mesma maneira. Esses testes podem ser descartados assim que a transição estiver concluída e a versão OpenTok do seu aplicativo for removida.

Solução de problemas e suporte

O SDK do Servidor Java da Vonage se empenha em fornecer mensagens de exceção úteis nos rastreamentos de pilha, caso você encontre erros de tempo de execução. Analise-as cuidadosamente para determinar a causa.

Canais de suporte

Para obter ajuda geral e participar de discussões sobre a migração para o Vonage Video, acesse 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. Se você encontrar um bug no SDK, por favor, abrir um ticket no GitHub com os passos para reproduzir o problema.