Compartir:
){kind=small}
Sina es promotora de desarrollo Java en Vonage. Procede del mundo académico y, en general, siente curiosidad por todo lo relacionado con los coches, los ordenadores, la programación, la tecnología y la naturaleza humana. En su tiempo libre, se le puede encontrar paseando o jugando a videojuegos de competición.
Anunciamos Vonage Java SDK v9.0.0
Tiempo de lectura: 13 minutos
Mucho ha cambiado en el SDK de Java desde el último anuncio - más de 39.000 líneas de código ¡de hecho! Esta importante versión ha tardado mucho en llegar, con un montón de mejoras y, sí, los inevitables cambios de última hora como resultado de las eliminaciones y refactorizaciones. Estoy muy contento de compartir finalmente estas actualizaciones con ustedes, ya que la calidad del SDK se ha nivelado aún más, con 100% de cobertura de pruebas y lo mismo puede decirse de nuestro SDK de Kotlin¡!
Naturalmente, mantenerse al día con la última versión del SDK es la mejor manera de asegurarse de que toda la funcionalidad de las API compatibles está disponible, junto con las correcciones de errores y las actualizaciones de seguridad, por supuesto. En concreto, se han realizado varias actualizaciones en API de Messagescon propiedades opcionales adicionales en los mensajes entrantes y salientes, nuevos tipos de mensajes compatibles para MMS, mensajes de WhatsApp Reaction y Button, la posibilidad de marcar los mensajes de WhatsApp como leídos y, por supuesto, compatibilidad con la mensajería mensajería RCS. En la Video API, la implementación se ha actualizado para soportar Live Captions, Audio Connector, Experience Composer, el rol Publisher-only en tokens de sesión, encriptación de extremo a extremo, bitrate máximo y parámetros de cuantización para Archivos, y varias correcciones de errores e inconsistencias.
También se han revisado y simplificado los webhooks, que se han trasladado a los paquetes adecuados para sus respectivas API. Para Voice, puede utilizar AnswerWebhook y EventWebhook para deserializar webhooks en función del tipo (ya que las URL de respuesta y de evento suelen enviarse a puntos finales diferentes). Para SMS API, utilice MessageEvent para analizar webhooks de mensajes entrantes.
Desde la última versión importante se han añadido tres nuevas API compatibles:
La tan esperada implementación de la Conversation API se añadió inicialmente al SDK de Java en la versión 8.4.0, pero desde entonces se ha mejorado con soporte para casi todos los tipos de eventos. Esta API de bajo nivel sustenta el funcionamiento interno de la Voice APIque ofrece funciones más potentes para gestionar llamadas y chats omnicanal con múltiples participantes. Se trata, sin duda, de la API más grande y compleja del SDK, que ahora los usuarios avanzados pueden utilizar con una implementación completa y fuertemente tipada, en lugar de depender de la referencia referencia de la API REST.
El sitio API de intercambio de SIM es una de las API de red de Vonage. Te permite verificar si la tarjeta SIM asociada con un número ha sido intercambiada a un dispositivo diferente. De forma predeterminada, se verifica dentro de los últimos 10 días, pero puede configurarse para cualquier período dentro de los últimos 100 días, con una precisión de una hora. Tenga en cuenta que actualmente sólo está disponible para los Numbers alemanes y españoles (véase Disponibilidad de las API de red). Aún así, puede probarlo utilizando nuestro Zona de juegos con Operadores virtuales. Aunque la API es un proceso de 3 pasos debido a OAuth, el SDK simplifica esto en una sola llamada a un método que automatiza todo esto para usted.
No debe confundirse con Number Insight, la API de verificación de Numbers es otra API de red que permite a los desarrolladores comprobar si el dispositivo del usuario coincide con su número de móvil. Esto ya está integrado en el flujo de trabajo de autenticación silenciosa en Verify API - consulte los fragmentos de código para ver ejemplos de uso. La API de verificación de Numbers es algo más compleja, ya que requiere varias llamadas a la API. La primera etapa construye una URL que puede pasar al usuario para que la siga en su dispositivo conectado a la red. Esto dará lugar a una devolución de llamada con un código que se enviará a su servidor, que luego pasará a la API para verificar que el número y el dispositivo coinciden. Actualmente, se aplican las mismas restricciones que la API SIM Swap descrita anteriormente.
Las versiones principales ofrecen una gran oportunidad para abordar la deuda técnica que se acumula de forma natural a lo largo del ciclo de vida del SDK a medida que evoluciona. Esta versión no es una excepción, con un montón de obsoletos desde la última versión principal. Estas desaprobaciones, excepto VonageClient.Builder#setHttpClient - han sido eliminadas. El setHttpClient sigue existiendo para los clientes que necesitan opciones más personalizadas, pero muchas de ellas se pueden lograr mediante el método httpConfig como el proxy, los tiempos de espera de las peticiones y la configuración de URIs base; todas ellas están disponibles en HttpConfig.Builder.
Además de la eliminación de las API obsoletas (Meetings y Proactive Connect), esta versión también mejora el SDK y encapsula los métodos, clases y constructores internos para ofrecer una forma más coherente y racionalizada de interactuar con el SDK y minimizar la confusión. Tomando prestado el mantra de mantra de Python:
"Debería haber una -y preferiblemente sólo una- forma obvia de hacerlo".
En consecuencia, los cambios de última hora de esta versión consisten principalmente en solucionar incoherencias. La mayoría de las refactorizaciones y cambios no afectarán a la mayoría de los usuarios y los que lo hagan requerirán refactorizaciones mínimas. Los principales aspectos a tener en cuenta son la reubicación de los enums (que se explica más adelante), tipos de retorno más específicos en lugar de String cuando proceda, y algunos lugares en los que se ha cambiado el nombre de los métodos en favor de alternativas más coherentes o sencillas. Afortunadamente, todo esto debería ser relativamente sencillo de resolver, sobre todo con la ayuda de su IDE y con los completos Javadocs. el registro de cambios para obtener una visión general de los cambios no descritos en este artículo. Para la mayoría de las desaprobaciones que se han eliminado, la alternativa se habrá descrito en el Javadoc, por lo que puede ser más fácil centrarse en abordar usos obsoletos primero antes de actualizar a v9.0.0 para una transición más suave.
La depuración y la trazabilidad son importantes en cualquier aplicación, por lo que este aspecto se ha mejorado en la versión 8.16.0. Dada la miríada de marcos de trabajo de registro en el ecosistema Java y la ahora infame vulnerabilidad Log4j que se descubrió hace unos años, el SDK de Java se basa en la función integrada java.util.logging para minimizar las dependencias y los posibles problemas de compatibilidad. El registro se realiza principalmente realiza en AbstractMethod#execute(REQ) si el nivel de registro es FINE. La petición se registra antes de que se realice la llamada a la API, incluyendo el URI completo, el método de petición, los parámetros de consulta y el cuerpo de la petición. Si la llamada se realiza correctamente, también se registra el cuerpo de la respuesta, si está presente. Para obtener un registro aún más detallado, consulte DynamicEndpoint.parseResponse.
Desde la versión 7.7.0, una refactorización sustancial del SDK introdujo la función Jsonable para los objetos de solicitud y respuesta. Ahora, todos estos objetos extienden la interfaz JsonableBaseObject JsonableBaseObject. Ésta implementa el método equals, hashCode y toString en función de los campos del objeto, y puede serializar y deserializar cargas JSON en función del modelo de datos del objeto mediante los métodos toJson y fromJson . Este último se implementa como un método estático en el objeto Jsonable .
Uno de los principales cambios de esta versión es el tratamiento de los enums. La mayoría de los enums se han movido fuera de las clases internas al nivel superior donde tiene sentido hacerlo, y algunos se han reubicado en la clase com.vonage.client.common si se utilizan en varias API. Además, la deserialización se ha estandarizado de forma generalizada, basándose en el método Jsonable.fromString . Si la representación de la cadena no coincide con un valor conocido, devolverá null en lugar de lanzar una IllegalArgumentException. Esto permite poblar el resto del modelo de datos del objeto, ya que de otro modo se habría impedido. Para mantener la coherencia con este planteamiento, el método UNKNOWN en la mayoría de los enums, a menos que sea un valor literal válido que pueda devolverse desde la API (como ocurre en Number Insight, por ejemplo).
Además de los cambios de última hora, esta versión mejora los tipos utilizados en los objetos del modelo de datos. Varios tipos de retorno se han cambiado de cadenas a enums, o a un tipo más apropiado, como UUID, URI, Double, etc. Actualizar su aplicación para que funcione con estos cambios debería ser sencillo y autoexplicativo, pero se describen con más detalle en el registro de cambios.
Los cambios más transformadores se aprecian en la Voice API de voz. Ahora todos los métodos y clases están completamente documentados y se han solucionado muchas de las incoherencias. Se han eliminado todos los métodos setter y se han sustituido por constructores. Además de las nuevas funciones y la corrección de errores, se han introducido muchos cambios en la Voice API. Por ejemplo, ahora los constructores sólo aceptan una única URL para parámetros como eventUrl. Aunque al serializarlo como JSON debe envolverse en una matriz, el SDK lo oculta para evitar confusiones. Lo mismo ocurre con los puntos finales de Llamada y ConnectAction - sólo se puede utilizar un único endpoint, pero anteriormente el SDK daba la impresión de que se podían especificar múltiples endpoints de destino cuando en realidad es sólo porque el endpoint debe estar envuelto en un array JSON. Hablando de puntos finales, es posible que haya encontrado cierta confusión al utilizar NCCOs para conectar una llamada, ya que había dos clases: com.vonage.client.voice.Endpoint y com.vonage.client.voice.ncco.Endpoint. La primera se utiliza en Llamadamientras que el segundo se utiliza en ConnectAction NCCO. Ahora se han rebautizado como CallEndpoint y ConnectEndpoint respectivamente, para evitar conflictos y requerir nombres de clase totalmente cualificados, por lo que puedes importar ambos. Por último, se ha estandarizado filtro de llamadas (que ahora extiende HalFilterRequest), que utiliza Instant en lugar del obsoleto Fecha y CallInfoPageque ahora extiende HalPageResponse. Tenga en cuenta que la clase EmbeddedCalls se ha eliminado, por lo que puede acceder a la lista de llamadas más directamente con la función getCallInfos() de CallInfoPage. Por último, como ya se ha mencionado, se utiliza una tipificación más fuerte cuando procede (por ejemplo, tasa y precio en CallInfo son ahora Dobles en lugar de Cadenas), y los enums se han movido fuera de las clases internas.
En la versión 8.10.0, la API de Numbers se ha actualizado no sólo para añadir las propiedades que faltaban, sino también para mejorar la documentación. Se han eliminado los setters en favor de constructores para mantener la coherencia con otras API. La vinculación de Numbers a una aplicación funciona ahora como estaba previsto, ya que se ha añadido la propiedad que faltaba para ello. En NumbersClient#listNumbers devuelve ahora una Lista<NúmeroPropio> directamente en lugar de ListNumbersResponseahorrándole una llamada adicional al método, ya que este envoltorio adicional es innecesario.
Los usuarios de la API Number Insight estarán encantados de leer que la compatibilidad con la API información avanzada asíncrona se ha implementado correctamente, con los tipos de solicitud y respuesta correctos, a diferencia de la solución chapucera que establecía un indicador booleano en el Advanced insight síncrono de versiones anteriores. El callback devolución de llamada es obligatorio para los conocimientos avanzados asíncronos, ya que es aquí donde se entregará la respuesta completa, que luego puede analizarse como AdvancedInsightResponse mediante la función Jsonable.fromJson(String, Clase) .
Como nota al margen, puede que se pregunte qué ha pasado con Number Insight v2. Técnicamente, esta API estaba en fase Beta, por lo que ha sido eliminada en esta versión, tras haber sido añadida en la v8.2.0. La API ha pasado a llamarse Detección de fraudespero tenemos planes más ambiciosos para la detección y prevención del fraude, así como para Number Insight, así que mantente al tanto de las novedades.
Si alguna vez ha intentado crear mensajes multicanal o multimedia con la API Messages del SDK de Java, es posible que se haya encontrado con el problema de tener que gestionar cada combinación de canal y tipo de forma individual, aunque el código para cada caso sea idéntico. Por ejemplo, considere el código utilizado para demostrar todas las combinaciones de canales y tipos de mensajes en esta aplicación SpringBoot. ¿Qué tienen en común? Bueno, todos los mensajes de texto (es decir, cuando el tipo de mensaje MessageType es TEXTO) tienen una función text(Cadena) en el constructor. Del mismo modo, todos los mensajes multimedia (es decir, cuando el MessageType es ARCHIVO, IMAGEN, AUDIO, VIDEOo VCARD) tienen una url(Cadena) en sus constructores. Hay dos formas de refactorizarlos para que se establezcan en un solo lugar sin repetición. La forma más complicada es a través de la reflexión. Una mejor opción sería a través de una interfaz. Eso es exactamente lo que se ha implementado desde la versión 8.11.0. Ahora puedes lanzar los constructores de mensajes de texto a TextMessageRequest.Buildery MediaMessageRequest para los mensajes con un campo URL. Dado que algunos canales también admiten un título opcional, también existe la propiedad CaptionMediaMessageRequestque extiende MediaMessageRequest con esta propiedad. En consecuencia, la aplicación de una URL, pie de foto o texto ahora se puede realizar polimórficamente a través de múltiples canales.
El año pasado, mientras desarrollaba el SDK de Kotlin, me di cuenta de que el SDK de Java gestionaba las capacidades de la API de Aplicaciones dejaba mucho que desear, debido a su innecesaria verbosidad y al hecho de que no es correcta por construcción. La implementación del SDK de Kotlin corrigió esto asegurándose de que los tipos de webhook (p. ej. event_url, status_url, answer_url, etc.) sólo pueden aplicarse a las capacidades que las admiten. Los creadores de capacidades en el SDK de Java se han actualizado para que sean correctos por construcción, lo que significa que la función addWebhook y removeWebhook han sido sustituidos por métodos específicos para cada tipo. Por ejemplo, en com.vonage.client.application.capabilities.Voice.Builder ahora existen los métodos evento, answer y fallbackAnswer. Para la función Mensajes, existe estado y evento. Cada uno de estos métodos establecerá la propiedad apropiada en la carga JSON, haciendo que los constructores sean más declarativos, menos verbosos y correctos por construcción. Para eliminar un webhook, puede pasar simplemente null como entrada a estos métodos.
Dado que el SDK de Kotlin se basa en el SDK de Java, se ha actualizado para que sea compatible con los cambios de última hora introducidos en la versión 9.0.0, lo que incluye la eliminación de elementos obsoletos, funciones que ya no son compatibles, como la antigua API de preciosy el flujo de trabajo WhatsApp Codeless en Verify API. El SDK de Kotlin sigue Versionado semántico como era de esperar, de ahí la versión 2.0.0.
Una nota rápida sobre la documentación: aunque puede encontrar documentación de código en línea directamente desde su IDE o desde un renderizador Javadoc (funciona para ambos Java SDK y Kotlin SDK) y, por supuesto, puedes encontrar fragmentos de código en nuestro Portal del desarrollador para cada producto, es posible que desee una vista concisa de una sola página de ejemplos de código que demuestren cómo utilizar cada API con el SDK. Me complace anunciar que ya se ha automatizado la generación de un archivo de este tipo tanto para Java y Kotlinpara que puedas pulsar Ctrl-F hasta que te canses.
El SDK de Java (y, por extensión, de Kotlin) sigue siendo compatible con Java 8 como tiempo de ejecución mínimo necesario, incluso en esta versión principal. Es descabellado pensar que Java 8, que se lanzó hace 11 años en el momento de escribir estas líneas, siga siendo relevante y se utilice en 2025. Sin embargo, los frameworks más populares han migrado hacia Java 17 como mínimo, e incluso las principales herramientas de compilación en las que confiamos (Maven, Gradle) han dejado de soportar Java 8. Además, el Apache HTTP Client 4 en el que se basa el Java SDK ha dejado de desarrollarse activamente. Mientras tanto, el soporte para llamadas asíncronas/reactivas se ha solicitado desde hace tiempo. Para facilitarlo, y tal vez sólo por actualizaciones de seguridad, sería prudente pasar la línea de base a Java 11, que introdujo un cliente HTTP integrado integrado en el JDK. Al aprovechar esto en lugar de una dependencia externa, la huella del SDK se puede reducir aún más, mientras que empuja el mantenimiento y la carga de seguridad del cliente HTTP subyacente a la propia plataforma. Por lo tanto, le animo a migrar de Java 8 tanto como una buena práctica general como en preparación para la próxima versión principal.
Y estos son todos los cambios que debes conocer de la versión 9.0.0 del SDK de Java y de la versión 2.0.0 del SDK de Kotlin que la acompaña. Para obtener un resumen más completo de los cambios, consulte CHANGELOG.md para Java y Kotlin respectivamente. Si encuentra algún problema o tiene sugerencias de mejora, no dude en plantear un problema en GitHub o pásate por nuestra Slack de la comunidad. Espero que tengas una gran experiencia usando las API de Vonage con la última versión de los SDK de Java y Kotlin.
Compartir:
Sina es promotora de desarrollo Java en Vonage. Procede del mundo académico y, en general, siente curiosidad por todo lo relacionado con los coches, los ordenadores, la programación, la tecnología y la naturaleza humana. En su tiempo libre, se le puede encontrar paseando o jugando a videojuegos de competición.