Partager:
){kind=small}
Sina est développeur Java chez Vonage. Il est issu d'une formation universitaire et est généralement curieux de tout ce qui touche aux voitures, aux ordinateurs, à la programmation, à la technologie et à la nature humaine. Pendant son temps libre, on peut le trouver en train de marcher ou de jouer à des jeux vidéo compétitifs.
Annonce du SDK Java de Vonage v9.0.0
Temps de lecture : 14 minutes
Beaucoup de choses ont changé dans le SDK Java depuis la dernière annonce post - plus de 39 000 lignes de code en fait ! Cette version majeure a été longue à venir, avec une tonne d'améliorations et, oui, les inévitables ruptures résultant des suppressions et des refactorisations. Je suis heureux de pouvoir enfin partager ces mises à jour avec vous, car la qualité du SDK s'est encore améliorée, avec 100% de couverture de test Il en va de même pour notre SDK Kotlin!
Naturellement, la meilleure façon de s'assurer que toutes les fonctionnalités des API prises en charge sont disponibles est de se tenir au courant de la dernière version du SDK, ainsi que des corrections de bogues et des mises à jour de sécurité, bien entendu. En particulier, plusieurs mises à jour ont été apportées à Messages APIavec des propriétés optionnelles supplémentaires pour les messages entrants et sortants, de nouveaux types de messages pris en charge pour les MMS, les messages WhatsApp Reaction et Button, la possibilité de marquer les messages WhatsApp comme lus et, bien sûr, la prise en charge de la messagerie messagerie RCS. Concernant l'API Video, l'implémentation a été mise à jour pour prendre en charge Live Captions, Audio Connector, Experience Composer, le rôle Publisher-only dans les jetons de session, le chiffrement de bout en bout, le débit maximal et les paramètres de quantification pour les Archives, ainsi que diverses corrections de bugs et d'incohérences.
Les Webhooks ont également été révisés et simplifiés, étant déplacés dans les paquets appropriés pour leurs API respectives. Pour Voice, vous pouvez utiliser AnswerWebhook et EventWebhook pour désérialiser les webhooks en fonction du type (puisque les URL de réponse et d'événement sont généralement envoyées à des points d'extrémité différents). Pour l'API SMS, utilisez MessageEvent pour analyser les webhooks de les webhooks des messages entrants.
Trois nouvelles API prises en charge ont été ajoutées depuis la dernière version majeure :
La mise en œuvre tant attendue de l Conversation API a été initialement ajoutée au SDK Java dans la version 8.4.0, mais a depuis été améliorée avec la prise en charge de presque tous les types d'événements. Cette API de bas niveau est à la base du fonctionnement interne de l Voice APIqui offre des capacités plus puissantes pour gérer les appels et les chats omni-canaux multiparticipants. Il s'agit sans aucun doute de l'API la plus importante et la plus complexe prise en charge dans le SDK, que les utilisateurs avancés / puissants peuvent désormais utiliser avec une implémentation complète et fortement typée plutôt que de s'appuyer sur la référence de l'API REST.
L'API SIM Swap API est l'une des API de réseau de Vonage. Elle vous permet de vérifier si la carte SIM associée à un numéro a été remplacée par un autre appareil. Par défaut, cette vérification porte sur les 10 derniers jours, mais elle peut être réglée sur n'importe quelle période des 100 derniers jours, à l'heure près. Notez que cette fonction n'est actuellement disponible que pour les numéros allemands et espagnols (voir disponibilité pour les API réseau). Vous pouvez néanmoins l'essayer en utilisant notre Terrain de jeu avec opérateurs virtuels. Bien que l'appel à l API soit un processus en trois étapes à cause d'OAuth, le SDK le simplifie en un seul appel de méthode qui automatise tout cela pour vous.
A ne pas confondre avec Number Insight, l Number Verification API est une autre API de réseau qui permet aux développeurs de vérifier si l'appareil de l'utilisateur correspond à son numéro de mobile. Cette fonction est déjà intégrée dans le flux de travail de l'authentification silencieuse de l'API Verify. flux de travail de l'authentification silencieuse dans Verify API - voir les extraits de code pour un exemple d'utilisation. L'API de vérification des numéros est légèrement plus complexe car elle nécessite plusieurs appels d'API. La première étape consiste à créer une URL que vous pouvez transmettre à l'utilisateur pour qu'il la suive sur son appareil connecté au réseau. Un rappel avec un code est alors envoyé à votre serveur, que vous transmettez ensuite à l'API pour vérifier la correspondance entre le numéro et l'appareil. Actuellement, les mêmes restrictions s'appliquent que pour l'API SIM Swap décrite ci-dessus.
Les versions majeures offrent une excellente occasion de remédier à la dette technique qui s'accumule naturellement au cours du cycle de vie du SDK et de son évolution. Cette version ne fait pas exception, avec une série de dépréciations depuis la dernière version majeure. Ces dépréciations - à l'exception de VonageClient.Builder#setHttpClient - ont toutes été supprimées. La fonction setHttpClient existe toujours pour les clients qui ont besoin d'options plus personnalisées, mais beaucoup d'entre elles peuvent être réalisées à l'aide de la méthode httpConfig comme le proxy, les délais d'attente des requêtes et la définition des URI de base ; toutes ces options sont disponibles dans le module HttpConfig.Builder.
Outre la suppression des API en voie d'extinction - Meetings et Proactive Connect - cette version met également de l'ordre dans le SDK et encapsule davantage les méthodes, classes et constructeurs internes afin d'offrir un moyen plus cohérent et rationalisé d'interagir avec le SDK et de minimiser les confusions. Pour reprendre le mantra de Python:
"Il devrait y avoir une - et de préférence une seule - façon évidente de procéder.
Par conséquent, les changements de rupture de cette version concernent principalement la correction des incohérences. La majorité des refactorisations et des changements n'affecteront pas la plupart des utilisateurs et ceux qui le feront nécessiteront des refactorisations minimales. Les principales choses à surveiller sont les enums relocalisés (développés plus loin), des types de retour plus spécifiques au lieu de String lorsque c'est applicable, et quelques endroits où les méthodes ont été renommées en faveur d'alternatives plus cohérentes ou plus simples. Avec un peu de chance, ces problèmes devraient être relativement simples à résoudre, en particulier avec l'aide de votre IDE et des Javadocs complets, cependant, il peut être utile de se référer à le journal des modifications pour avoir une vue d'ensemble des changements qui ne sont pas décrits dans cet article. Pour la plupart des dépréciations qui ont été supprimées, l'alternative aura été décrite dans la Javadoc, il peut donc être plus facile de se concentrer d'abord sur les usages dépréciés avant de passer à la version 9.0.0 pour une transition plus douce.
Le débogage et la traçabilité sont importants dans toute application, c'est pourquoi cet aspect a été amélioré dans la version 8.16.0. Compte tenu de la myriade de cadres de journalisation dans l'écosystème Java et de la désormais tristement célèbre vulnérabilité Log4j découverte il y a quelques années, le SDK Java s'appuie sur l'outil intégré java.util.logging ce qui minimise encore les dépendances et les problèmes de compatibilité potentiels. La journalisation est principalement effectuée dans AbstractMethod#execute(REQ) si le niveau de journalisation est défini sur FINE. La demande est enregistrée avant l'appel à l'API, y compris l'URI complet, la méthode de requête, les paramètres de la requête et le corps de la requête. Si l'appel a abouti, le corps de la réponse est également consigné, le cas échéant. Pour une journalisation encore plus fine, voir DynamicEndpoint.parseResponse.
Depuis la version 7.7.0, une refonte substantielle du SDK a introduit la fonctionnalité Jsonable pour les objets de requête et de réponse. Désormais, ces objets étendent tous l'interface JsonableBaseObject de la classe JsonableBaseObject. Celle-ci implémente la fonction égal, hashCode, et toString en fonction des champs de l'objet, et vous pouvez sérialiser et désérialiser des données utiles JSON en fonction du modèle de données de l'objet à l'aide de la méthode toJson et fromJson pour sérialiser et désérialiser les données utiles JSON en fonction du modèle de données de l'objet. Cette dernière est implémentée en tant que méthode statique sur l'objet Jsonable .
L'un des principaux changements de cette version concerne la gestion des enums. La plupart des enums ont été déplacés des classes internes vers le niveau supérieur lorsque cela s'avérait judicieux, et certains ont été déplacés vers la classe com.vonage.client.common si elles sont utilisées par plusieurs API. De plus, la désérialisation a été standardisée dans tous les cas, en s'appuyant sur la méthode Jsonable.fromString . Si la représentation de la chaîne ne correspond pas à une valeur connue, elle renverra null au lieu de lancer une exception IllegalArgumentException. Cela permet de remplir le reste du modèle de données de l'objet, ce qui aurait été impossible autrement. Pour des raisons de cohérence avec cette approche, l'élément UNKNOWN a été supprimée dans la plupart des enums, sauf s'il s'agit d'une valeur littérale valide qui peut être renvoyée par l'API (comme c'est le cas dans Number Insight, par exemple).
En plus des changements de rupture, cette version améliore les types utilisés dans les objets du modèle de données. Plusieurs types de retour ont été remplacés par des enums, ou un type plus approprié, tel que UUID, URI, Double, etc. La mise à jour de votre application pour travailler avec ces changements devrait être simple et explicite, mais ils sont décrits plus en détail dans le le journal des modifications.
Les changements les plus importants sont visibles dans l Voice API . Chaque méthode et chaque classe sont désormais entièrement documentées, et de nombreuses incohérences ont été corrigées. Toutes les méthodes de type "setter" ont été supprimées et remplacées par des "builders". Outre les nouvelles fonctionnalités et les corrections de bogues, de nombreux changements ont été apportés à l'API Voice. Par exemple, les constructeurs n'acceptent plus qu'une seule URL pour les paramètres tels que eventUrl. Même si ce paramètre doit être enveloppé dans un tableau lorsqu'il est sérialisé en JSON, le SDK le cache pour éviter toute confusion. Il en va de même pour les points de terminaison dans Call et ConnectAction - un seul point de terminaison peut être utilisé, mais auparavant le SDK donnait l'impression que plusieurs points de terminaison de destination pouvaient être spécifiés, alors qu'en fait c'est seulement parce que le point de terminaison doit être enveloppé dans un tableau JSON. En parlant de points de terminaison, vous avez peut-être rencontré une certaine confusion lors de l'utilisation des NCCO pour connecter un appel, car il y avait deux classes : com.vonage.client.voice.Endpoint et com.vonage.client.voice.ncco.Endpoint. La première est utilisée dans Calltandis que le second est utilisé dans l'action ConnectAction NCCO. Ils ont été renommés CallEndpoint et ConnectEndpoint afin d'éviter les conflits et d'exiger des noms de classe pleinement qualifiés, de sorte que vous pouvez les importer tous les deux. Enfin, il y a eu une certaine standardisation dans CallsFilter (qui étend désormais HalFilterRequest), qui utilise Instant au lieu de l'ancienne méthode Date (jeu de mots !), et CallInfoPagequi étend désormais la classe HalPageResponse. Il convient de noter que les classes EmbeddedCalls a été supprimée, ce qui vous permet d'accéder plus directement à la liste des appels avec la méthode getCallInfos() sur la page CallInfoPage. Enfin, comme indiqué précédemment, un typage plus fort est utilisé le cas échéant (par exemple, taux et prix dans CallInfo sont désormais des doubles au lieu de chaînes), et les enums ont été déplacés hors des classes internes.
Dans la version 8.10.0, l Numbers API Numbers a été mise à jour non seulement pour ajouter les propriétés manquantes, mais aussi pour améliorer la documentation. Les setters ont été supprimés au profit des builders, dans un souci de cohérence avec les autres API. Lier les Numbers à une application fonctionne désormais comme prévu, puisque la propriété manquante pour cela a été ajoutée. La propriété NumbersClient#listNumbers renvoie désormais une List<OwnedNumber> directement au lieu de ListNumbersResponsece qui permet d'économiser un appel de méthode supplémentaire puisque ce wrapping additionnel n'est pas nécessaire.
Les utilisateurs de Number Insight API seront heureux de lire que la prise en charge de la fonction aperçu avancé asynchrone asynchrone a été correctement implémentée, avec les types de demande et de réponse corrects, contrairement à la solution bidon qui définissait un drapeau booléen sur l'aperçu avancé synchrone dans les versions précédentes. Le callback est obligatoire pour les analyses avancées asynchrones, car c'est là que la réponse complète sera livrée, qui peut ensuite être analysée dans le fichier AdvancedInsightResponse à l'aide de la méthode Jsonable.fromJson(String, Class) pour l'analyse de la réponse.
Par ailleurs, vous vous demandez peut-être ce qu'il est advenu de Number Insight v2. Techniquement, cette API était en version bêta et a donc été supprimée dans cette version, après avoir été ajoutée dans la v8.2.0. L'API a été renommée Détection de la fraudeL'API a été renommée Fraud Detection, mais nous avons de plus grands projets pour la détection et la prévention des fraudes, ainsi que pour Number Insight, alors restez à l'écoute pour de nouvelles mises à jour.
Si vous avez déjà essayé de créer des messages multicanaux ou multimédias à l'aide de l'API Messages du SDK Java, vous avez peut-être rencontré le problème de la nécessité de gérer chaque combinaison de canal et de type individuellement, même si le code pour chaque cas est identique. Prenons par exemple le code utilisé pour démontrer toutes les combinaisons de canaux et de types de messages dans l'application SpringBoot suivante cette application SpringBoot. Quel est le point commun ? Eh bien, tous les messages textuels (c'est-à-dire lorsque le type de message MessageType est TEXT) ont une fonction text(String) sur le constructeur. De même, tous les messages multimédias (c'est-à-dire lorsque le type de message Type de message est FILE, IMAGE, AUDIO, VIDEOou VCARD) ont un url(Chaîne) sur leurs constructeurs. Il y a deux façons de remanier ces méthodes pour qu'elles soient définies à un seul endroit sans répétition. La solution de contournement est la réflexion. Une meilleure option serait d'utiliser une interface. C'est exactement ce qui a été mis en place depuis la version 8.11.0. Vous pouvez à présent faire passer les constructeurs de messages texte dans l'interface TextMessageRequest.Builderet MediaMessageRequest pour les messages comportant un champ URL. Étant donné que certains canaux prennent également en charge une légende optionnelle, il existe également CaptionMediaMessageRequestqui étend la propriété MediaMessageRequest avec cette propriété. Par conséquent, l'application d'une URL, d'une légende ou d'un texte peut désormais être effectuée de manière polymorphe sur plusieurs canaux.
En développant le SDK Kotlin l'année dernière, j'ai remarqué que la gestion des capacités par le SDK Java dans l Application API laissait beaucoup à désirer, en raison de sa verbosité inutile et du fait qu'elle n'est pas correcte par construction. L'implémentation du SDK Kotlin a corrigé ce problème en s'assurant que les types de webhooks (par ex. event_url, status_url, answer_url, etc.) ne peuvent être appliquées qu'aux capacités qui les prennent en charge. Les créateurs de capacités dans le SDK Java ont été mis à jour pour être corrects par construction, ce qui signifie que la fonction addWebhook et removeWebhook ont été remplacées par des méthodes spécifiques au type. Par exemple, dans la classe com.vonage.client.application.capabilities.Voice.Builder il y a maintenant des méthodes event, answer, et réponse de secours. Pour la fonction Messages, il y a statut et événement. Chacune de ces méthodes définira la propriété appropriée dans la charge utile JSON, ce qui rend les constructeurs plus déclaratifs, moins verbeux et corrects par construction. Pour supprimer un webhook, vous pouvez simplement passer null en entrée de ces méthodes.
Le SDK Kotlin étant construit au-dessus du SDK Java, il a été mis à jour pour être compatible avec les changements radicaux introduits dans la version 9.0.0, ce qui inclut la suppression des dépréciations, des fonctionnalités qui ne sont plus prises en charge, telles que l' l'ancienne API de tarificationet le workflow WhatsApp Codeless dans l'API Verify. Le SDK Kotlin suit versionnement sémantique comme on peut s'y attendre, d'où la version 2.0.0.
Une petite remarque sur la documentation : bien que vous puissiez trouver la documentation du code en ligne directement depuis votre IDE ou depuis un moteur de rendu Javadoc (qui fonctionne pour les deux Java SDK et Kotlin SDK), et vous pouvez, bien sûr, trouver des extraits de code dans notre portail des développeurs pour chaque produit, vous souhaiterez peut-être disposer d'une vue concise, sur une seule page, d'échantillons de code démontrant comment utiliser chaque API avec le SDK. J'ai le plaisir d'annoncer que la génération d'un tel fichier a été automatisée pour les API Java et KotlinVous pouvez donc faire du Ctrl-F à volonté !
Le SDK Java (et, par extension, Kotlin) continue de prendre en charge Java 8 en tant que système d'exécution minimum requis, même dans cette version majeure. Il est incroyable de penser que Java 8, qui a été publié il y a 11 ans au moment de la rédaction du présent document, est toujours pertinent et utilisé en 2025. Cependant, les frameworks les plus populaires ont migré vers Java 17 au minimum, et même les principaux outils de construction sur lesquels nous nous appuyons (Maven, Gradle) ont déprécié le support de Java 8. En outre, le Client HTTP Apache 4 sur lequel le SDK Java est basé a cessé son développement actif. Entre-temps, la prise en charge des appels asynchrones/réactifs est demandée depuis longtemps. Pour faciliter cette prise en charge, et peut-être uniquement pour les mises à jour de sécurité, il serait prudent de passer à Java 11, qui a introduit un client HTTP intégré dans le JDK. En tirant parti de ce client au lieu d'une dépendance externe, l'empreinte du Client SDK peut être encore réduite tout en repoussant la charge de maintenance et de sécurité du client HTTP sous-jacent à la plate-forme elle-même. Je vous encourage donc à abandonner Java 8, à la fois comme bonne pratique générale et en préparation de la prochaine version majeure.
Voilà tous les changements que vous devriez connaître dans la version 9.0.0 du SDK Java et la version 2.0.0 du SDK Kotlin qui l'accompagne. Pour un résumé plus complet des changements, voir CHANGELOG.md pour le SDK Java et Kotlin respectivement. Si vous rencontrez des problèmes ou si vous avez des suggestions d'amélioration, n'hésitez pas à soulever un problème sur GitHub ou de passer par notre Communauté Slack. J'espère que l'utilisation des API de Vonage avec la dernière version des SDK Java et Kotlin vous procurera une excellente expérience !
Partager:
Sina est développeur Java chez Vonage. Il est issu d'une formation universitaire et est généralement curieux de tout ce qui touche aux voitures, aux ordinateurs, à la programmation, à la technologie et à la nature humaine. Pendant son temps libre, on peut le trouver en train de marcher ou de jouer à des jeux vidéo compétitifs.