Anunciando o SDK Java da Vonage v8.0.0

Introdução

Muita coisa mudou no SDK do Java desde a última publicação de anúncio — mais de 17 mil linhas de código , na verdade! Embora grande parte disso seja refatoração interna e melhorias de usabilidade, há algumas mudanças importantes que devem ser levadas em conta, já que se trata de uma versão principal. Sem mais delongas, vamos mergulhar no assunto!

Video API

Vamos começar com a grande novidade: a Video API da Vonage já foi lançada oficialmente. A transição da OpenTok para a Vonage já vem sendo preparada há algum tempo, daí as inúmeras versões beta do SDK. Agora que a API está estável, ela está disponível no com.vonage.client.video pacote do SDK do Java Server.

Novo ID do artefato

Se há algo que vale a pena reter deste artigo, é o fato de que o SDK já foi migrado para um novo artifactId no Maven Central. Isso já fazia parte do plano de desenvolvimento desde 2022, como fica evidente pelas várias versões beta lançadas no novo repositório. O groupId ainda é o mesmo (com.vonage), mas o artifactId agora é server-sdk em vez de client. Essa migração foi sinalizada nos metadados, portanto, algumas ferramentas e sites podem direcioná-lo para o novo artefato. Você pode ver esse aviso em mvnrepository.com , por exemplo.

O que motivou essa mudança? O principal motivo é evitar confusão com outras ferramentas publicadas sob o com.vonage grupo. Como também oferecemos SDKs do lado do cliente para desenvolvimento em Android, a client nome pode causar alguma confusão, já que se trata, na verdade, do SDK do lado do servidor.

Atualizar suas dependências ainda deve ser um processo simples: substitua com.vonage:client:7.11.1 (ou qualquer que seja a versão que você esteja usando no momento) por com.vonage:server-sdk:8.0.0. As instruções para o seu sistema de compilação específico podem ser encontradas no lado direito da página do Maven Central.

Alterações que exigem atualização

Como a número da versão semântica sugere, há algumas alterações incompatíveis com versões anteriores na API pública do SDK nesta versão, mas não deixe que isso o impeça de atualizar, já que é improvável que a maioria delas o afete e, caso isso aconteça, deve ser bastante fácil de corrigir. O SDK ainda oferece suporte ao Java 8, e todos os nomes de pacotes e classes continuam os mesmos. No entanto, a maioria dos membros obsoletos no SDK foi removida conforme planejado. Por exemplo, o WAPPush tipo de mensagem SMS, que não é mais suportado pela API. Aqui está uma lista das remoções e suas substituições.

Rede social removida

Como em qualquer projeto com certa trajetória, inevitavelmente haverá código que não é mais utilizado nem mantido. No SDK do Java, havia alguns pacotes que não são mais mantidos devido à sua antiguidade e ao fato de não serem mais utilizados. O cliente SNS é um desses exemplos (a API está obsoleta há muito tempo), que também dependia de alguns utilitários XML. O legacyutils, sns e logging foram todos removidos. Isso inclui também a configuração de URI do SNS em HttpConfig , já que ela não é mais utilizada.

Dependências desnecessárias

Um dos problemas mais comuns ao usar qualquer biblioteca são os conflitos de dependências. Escrevi um artigo sobre como resolver isso, mas, de modo geral, é aconselhável que os mantenedores de bibliotecas minimizem o número de dependências sempre que possível.

Um exemplo disso no SDK foi a javax.servlet dependência. Como ela agora foi transferida para o namespace do Jakarta, isso torna mais difícil o uso do SDK do Java com versões mais recentes do Jakarta Servlet. Além disso, o uso dessa dependência era bastante desnecessário, e as classes que a utilizavam não são mais mantidas. Portanto, todos os métodos e classes que faziam referência a ela — especificamente, HttpServletRequest — foram removidos. Isso inclui o com.vonage.client.voice.servlet pacote e com.vonage.client.sms.callback.AbstractMOServlet. Se você estava usando a RequestSigning classe para verificar assinaturas de mensagens recebidas da SMS API, agora você pode usar o verifySignature — consulte o repositório de trechos de código para ver um exemplo.

A outra dependência que foi removida é jackson-dataformat-hal. Ela fornecia uma extensão à biblioteca Jackson para deserializar respostas HAL, mas era utilizada apenas pela API de Account — especificamente pela ListSecretsResponse classe. Para manter a consistência com o restante do SDK, isso foi refatorado, de modo que essa dependência não é mais necessária.

Verify API

Entre as remoções da Verify API está a BaseResult classe — que continha apenas códigos de status, mas não era utilizada no restante do SDK — e LineType, que já havia sido considerada obsoleta. Isso também inclui métodos que usavam LineType, é claro. O ipAddress campo também foi removido tanto AdvancedInsightRequest (no Numbers Insight) e CheckRequest. Recomenda-se o uso do verify2 pacote é recomendado para uso em vez de verify , já que a API do Verify v2 receberá mais suporte. Por falar nisso, inúmeras configurações regionais foram adicionadas ao Verify v2 — tantas que acompanhar essas mudanças se tornou um fardo de manutenção. Por esse motivo, a enumeração personalizada com.vonage.client.verify2.Locale foi removida. Em vez disso, você deve usar a java.util.Locale. Você pode usar o VerificationRequest.Builder#locale(String) por conveniência, fornecendo as tags de idioma e região de duas letras (por exemplo, en-gb).

Voice API

Foram feitas algumas melhorias de qualidade de vida na implementação da Voice API, que incluem a remoção de métodos anteriormente obsoletos — por exemplo, os setters da com.vonage.client.voice.Call classe, em favor do uso do construtor que foi adicionado na versão 7.3.0. As duas mudanças mais significativas estão em VoiceClient.

Em primeiro lugar, o modifyCall método foi removido juntamente com ModifyCallResponse. A implementação agora simplifica as ações de modificação de chamadas com chamadas diretas a métodos. Por exemplo, para encerrar (desligar) uma chamada, use o terminateCall(String) método, passando apenas o ID da chamada. Existem métodos semelhantes para as outras ações (earmuff / unearmuff, mute / unmute).

A outra alteração diz respeito ao downloadRecording método. Ele retornava um Recording objeto, com o qual havia apenas duas opções: obter o conteúdo como um InputStream ou chamar o save(Path) método para armazená-lo em um arquivo. A implementação interna disso não era muito boa, então foi simplificada com a adição de dois novos métodos em VoiceClient: void saveRecording(String recordingUrl, Path destination) e byte[] downloadRecordingRaw(String recordingUrl). O primeiro, como o próprio nome sugere, salvará a gravação da URL fornecida (recordingUrl) no arquivo desejado (destination). O segundo fornece o conteúdo binário da gravação (baixado da recordingUrl) como uma matriz de bytes, para que você possa decidir o que fazer com ela caso não queira salvá-la em um arquivo. Portanto, o método anterior Recording downloadRecording(String recordingUrl) foi removido, juntamente com a com.vonage.voice.client.Recording classe.

Por fim, a PayAction NCCO, juntamente com a PaymentPrompt classe foram removidos, uma vez que não são mais suportados pela API.

Outras atualizações

Além de remover código legado para lidar com a dívida técnica, há também alguns novos recursos descritos a seguir. Caso você esteja curioso, o trabalho interno de refatoração para desacoplar as implementações da API do cliente HTTP subjacente, iniciado na versão 7.7.0, já foi concluído, o que abre caminho para atualizações futuras do cliente — por exemplo, para permitir o suporte a solicitações assíncronas. Os testes também foram migrados para o JUnit 5.

Tempos limite configuráveis para solicitações

A versão 7.8.0 adicionou a possibilidade de definir um tempo limite personalizado para todas as solicitações enviadas pelo SDK. Embora nossas APIs REST geralmente respondam rapidamente (medido em milissegundos, e não em segundos), alguns endpoints podem demorar mais, dependendo da quantidade de processamento necessária e das condições da rede. Para aplicativos em que o tempo é um fator crítico, pode ser útil definir um prazo rígido para as respostas, de modo que você não fique esperando mais do que o necessário sem precisar criar threads separadas. Antes da v7.8.0, o tempo limite padrão dependia do sistema, pois era o valor padrão do cliente HTTP Apache subjacente (normalmente, 60 segundos). Agora, isso pode ser configurado com precisão de milissegundos usando o HttpConfig.Builder#timeoutMillis(int) método. Além disso, o valor padrão agora é de 60 segundos, independentemente das configurações do sistema.

Autenticação silenciosa

Foram adicionados alguns campos adicionais para o fluxo de trabalho de autenticação silenciosa na Verify API v2. A saber, o sandbox e redirect_url parâmetros em SilentAuthWorkflow, check_url em VerificationResponse. Nossa documentação traz mais informações sobre o fluxo de trabalho síncrono de autenticação silenciosa e sobre a área de testes da Autenticação Silenciosa , caso você tenha curiosidade.

AccountClient Melhorias

A AccountClient classe no SDK do Java possui endpoints tanto para a API de Preços quanto para a API de Accounts. No entanto, faltava o ponto de extremidade de preços de saída para todos os países , que foi adicionado a partir da versão 7.9.0. Esse endpoint — que pode ser chamado com o AccountClient#listPriceAllCountries(ServiceType) método — recupera informações de preços dos serviços para todos os países disponíveis.

Além disso, foram adicionadas sobrecargas de métodos de conveniência para o gerenciamento de segredos. Agora, se você quiser gerenciar segredos da sua conta principal (em vez de Subaccounts), não precisa fornecer a chave de API ao método — ela será derivada automaticamente do método de autenticação usado para construir o VonageClient.

Verificação do JWT

Ao receber webhooks da Vonage, recomenda-se que você verifique a autenticidade da carga útil validando a assinatura do token. Anteriormente, esse era um processo manual, mas a partir da versão 7.11.0, você pode usar o verifySignature(String jwt, String secret) método auxiliar em VoiceClient e MessagesClient. Isso simplesmente delega ao novo Jwt.verifySignature método no com.vonage:jwt artefato, que foi atualizado para oferecer suporte a esse recurso. Agora, você não precisa mais implementar a lógica para extrair e validar a assinatura de uma carga de dados recebida usando bibliotecas de terceiros — basta fornecer o JWT e o segredo compartilhado. O método retornará “true” se o token tiver sido assinado pelo segredo fornecido.

Encerrando

E essas são todas as alterações que você precisa saber sobre a versão 8.0.0 do Java SDK. Lembre-se de ficar atento aos lançamentos sob as com.vonage:server-sdk coordenadas para futuras atualizações! Se você encontrar algum problema ou tiver sugestões de melhorias, fique à vontade para abrir um ticket no GitHub, entre em contato conosco no Twitter ou dar uma passada no nosso Slack da Comunidade. Espero que você tenha uma ótima experiência ao usar as APIs da Vonage com a versão mais recente do SDK para Java!