Guide de transition vidéo de Vonage pour Java

Transition de com.tokbox:opentok-server-sdk à com.vonage:server-sdk.

Introduction

Objectif

L'objectif de ce document est de fournir un point de départ pour la transition du SDK OpenTok Java Server vers le SDK Vonage Java Server.

Champ d'application

Ce document suppose que vous utilisez au moins la version 4.0.0 ou une version ultérieure de l'application OpenTok Java SDK. L'API Video a été ajoutée au SDK Java Server dans la version 8.0.0. Vous devez utiliser la dernière version du SDK Java de Vonage, qui peut être trouvée sur GitHub ou Maven Central.

Hypothèses

Ce guide est destiné à être suivi par un ingénieur logiciel professionnel. Il suppose au moins un niveau de compétence de base avec Java, les outils de développement Java courants, les systèmes de construction (Maven ou Gradle) et Git (ou un autre système de contrôle de version). Vous devez être à l'aise avec la lecture et l'écriture de code Java, la gestion des dépendances d'un projet, le déploiement et l'exécution d'un projet Java. Une introduction au langage Java, à la plateforme et aux outils associés dépasse largement le cadre de ce document.

Ressources

Les liens suivants sont utiles pour compléter le présent document et pour se référer à tout ce qui n'est pas couvert dans le présent document :

Vonage

TokBox

Planifier votre migration

Avant de passer d'OpenTok à Vonage Video, vous devez prendre en compte l'ampleur de la tâche afin de fixer des attentes réalistes.

Évaluer l'impact

La première question à laquelle il faut répondre est la suivante : quelle est la part du code de votre application qui dépend du SDK OpenTok ? Dressez une liste de tous les fichiers dans lesquels le SDK est directement utilisé. En d'autres termes, tout fichier source Java qui contient des importations du SDK com.opentok paquet. Vous pouvez rechercher dans les fichiers de votre projet l'instruction import com.opentok en utilisant un IDE ou un outil de ligne de commande pour identifier les fichiers concernés.

Chronologie

Tenez compte du temps nécessaire pour mener à bien la transition. Cela dépendra de votre expérience du projet et de son impact, ainsi que des tests. Il est crucial de disposer d'une bonne suite de tests afin de pouvoir vérifier l'équivalence entre l'OpenTok et Vonage Video. Le temps nécessaire pour effectuer la transition est à peu près proportionnel au nombre d'endroits où le SDK OpenTok est utilisé dans votre code, ainsi qu'à la variété des fonctionnalités utilisées. Certains appels API seront plus simples à remplacer que d'autres.

Versionnement

L'idéal est de créer une nouvelle branche sur votre système de contrôle de version pour la transition, afin de pouvoir apporter des modifications progressivement et fréquemment sans casser le projet existant. Vous pouvez également utiliser les tests du projet existant en tant qu'oracle pour vérifier l'exactitude des données. Idéalement, vous ne devriez fusionner la branche de transition avec la branche principale qu'une fois la conversion terminée.

Principaux changements et considérations

Nouvelles caractéristiques et normes

L'API Video de Vonage présente les mêmes caractéristiques qu'OpenTok, et le SDK Java est activement mis à jour pour être conforme à la spécification de l'API. L'une des différences entre les SDK OpenTok et Vonage Java est que le SDK Java utilise un modèle de données avec un typage plus fort plutôt que des chaînes simples. Il est également plus cohérent avec les autres API du SDK et suit des conventions qui devraient rendre l'utilisation du SDK intuitive. Une autre différence essentielle est que les classes de demande et de réponse sont unifiées. Par exemple, vous utiliseriez la classe Archive pour créer et récupérer une archive, alors que dans OpenTok, vous utiliseriez la classe ArchiveProperties pour la demande et Archive pour la réponse. Comme pour le SDK OpenTok, le SDK Java utilise le modèle Builder pour construire les objets de requête.

Contrairement au SDK OpenTok, le SDK Vonage n'utilise pas d'exceptions vérifiées. Par conséquent, vous n'avez plus besoin d'effectuer une try {...} catch (InvalidArgumentException ex)ce qui vous permet d'alléger votre code. Si vous souhaitez capturer des exceptions pour les appels API qui n'ont pas abouti (c'est-à-dire qui n'ont pas le code d'état 2xx), vous pouvez capturer les exceptions suivantes VideoResponseException au lieu de OpenTokException.

Mise à jour sur la dépendance

Tout d'abord, vous devrez mettre à jour les dépendances de votre système de construction pour utiliser le SDK Java de Vonage au lieu d'OpenTok. Les instructions sur la façon de procéder dépendent de votre système de construction. Les instructions pour inclure la dernière version du SDK Java de Vonage dans votre système de construction sont disponibles sur le site suivant Maven Central ou mvnrepository.com.

Pour une migration progressive, vous pouvez inclure les dépendances OpenTok et Vonage dans votre projet, mais nous vous recommandons fortement de ne le faire que pour des tests plutôt que pour des déploiements en production, car le SDK OpenTok a tendance à utiliser des versions plus anciennes des dépendances, ce qui peut causer des problèmes au moment de l'exécution.

Nom du paquet

Une fois que vous avez ajouté le SDK Java de Vonage à votre chemin de classe à l'aide de votre outil de construction, vous pouvez commencer à l'utiliser dans votre code.

Vous pouvez remplacer les importations de la com.opentok et com.opentok.exception paquets avec com.vonage.client.video. Une recherche et un remplacement à l'aide de votre IDE ou de l'éditeur de code de votre projet devraient permettre de résoudre la plupart des erreurs de compilation.

Notez qu'il n'y a pas d'autres sous-paquets pour les exceptions - la seule exception que vous aurez besoin d'attraper pour traiter les erreurs de l'API est la suivante com.vonage.client.video.VideoResponseException.

Modifications de l'authentification

L'authentification dans les SDK OpenTok et Vonage Java Server est gérée pour vous, de sorte que vous ne devez fournir les informations d'identification de votre compte qu'une seule fois lors de l'initialisation. La différence réside dans le fait qu'OpenTok requiert la clé et le secret de l'API, tandis que pour l'API Video du SDK Java de Vonage, vous devez fournir un identifiant d'application et sa clé privée. Alors que Vonage et OpenTok utilisent tous deux une authentification basée sur un jeton, les jetons de Vonage sont les suivants JWTs tandis qu'OpenTok utilise un format personnalisé. Bien que vous puissiez fournir une clé API et un secret à la fonction VonageClient Tout comme pour OpenTok, ceci est utilisé pour d'autres API de Vonage, pas pour Video. Par conséquent, vous devrez créer ou utiliser une application existante.

Vous pouvez créer une application à partir de l'application Tableau de bord Vonage. Assurez-vous que la fonction vidéo est activée dans votre application. Cliquez sur "Modifier" pour une application existante afin d'afficher ses capacités et ses informations d'identification. Cliquez ensuite sur "Générer une clé publique et privée". Cette opération ne doit être effectuée qu'une seule fois, car à chaque fois que vous effectuez cette opération, les informations d'identification changent et la paire de clés existante est rompue. En cliquant sur ce bouton, vous déclencherez le téléchargement de votre clé privée. Vous devez placer ce fichier dans un endroit sûr pour le tester. NE JAMAIS PARTAGER OU EXPOSER SA CLÉ PRIVÉE ! La clé privée est en fait le "mot de passe" de votre application et doit donc être traitée avec soin. Il est recommandé de créer une variable d'environnement qui pointe vers le chemin de votre fichier de clé privée, afin que vous puissiez vous y référer lors de la configuration de l'application VonageClienten appelant la variable de la manière suivante VONAGE_PRIVATE_KEY_PATH. Il convient de faire de même pour l'identifiant de votre application (qui se trouve sur le tableau de bord ou dans l'URL lors de son édition).

Pour plus d'informations sur la création d'une application, voir le guide de démarrage.

Utilisation

Voir Le README du SDK Java pour les instructions d'installation.

Au lieu de cela :

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

Procédez comme suit :

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();

Une fois que vous avez instancié le VonageClientvous pouvez utiliser la fonction Video API en utilisant le VideoClienttel qu'il a été obtenu à partir de la base de données de l VonageClient (voir ci-dessus).

Les méthodes de l'API sur VideoClient sont documentées à l'aide de Javadocs, et sont à peu près analogues aux méthodes trouvées dans la section OpenTok classe.

Pour des instructions d'utilisation plus détaillées, voir le Guide vidéo du SDK Java Sever.

Changements de méthode

Il y a quelques petits changements dont il faut tenir compte lors de la migration vers Vonage à partir d'OpenTok. La plupart d'entre eux sont simples et votre IDE vous aidera avec l'auto-complétion, mais pour plus de clarté, considérez ce qui suit :

  • projectId est maintenant applicationId le cas échéant.
  • Des caractères plus forts sont utilisés le cas échéant (par ex. UUID et URI au lieu de String).
  • playDTMF renommé en sendDtmf pour tous les terminaux DTMF concernés.
  • OpenTok#disableForceMute(String) remplacé par VideoClient#muteSession(String, boolean, String...). Vous devez définir le active paramètre booléen à false pour obtenir le même effet.
  • Les MuteAllProperties et le paramètre dans la classe OpenTok a été remplacée par l'utilisation du excludedStreamIds directement dans le paramètre de la méthode de VideoClient#muteSession(String, boolean, Collection<String>) (ou VideoClient#muteSession(String, boolean, String...) for convenience). Ces méthodes remplacent les OpenTok#forceMuteAll(String, MuteAllProperties).
  • ArchiveProperties et BroadcastProperties - tels qu'ils sont utilisés dans les paramètres de requête dans OpenTok - ont été remplacés par Archive et Broadcast respectivement. Tous deux utilisent le modèle du bâtisseur pour la construction.
    • Archive et Broadcast de Vonage représentent également les réponses de la même manière que leurs homologues d'OpenTok.
    • Ainsi, les objets de demande et de réponse représentant Archive et Broadcast ont été unifiées dans la mise en œuvre de Vonage.
  • OpenTok#setBroadcastLayout(String, BroadcastProperties) remplacé par VideoClient#updateBroadcastLayout(String, StreamCompositionLayout).
  • OpenTok#setArchiveLayout(String, ArchiveProperties) remplacé par VideoClient#updateArchiveLayout(String, StreamCompositionLayout).
  • OpenTok#dial(String, String, SipProperties) remplacé par VideoClient#sipDial(SipDialRequest).
    • Sip remplacé par SipResponse.
  • Les listArchives avec différents paramètres dans OpenTok ont été remplacées par des méthodes VideoClient#listArchives(ListStreamCompositionsRequest) pour contrôler les options.
    • La réponse est un simple List<Archive> au lieu de ArchiveList. Utiliser Collection#size() au lieu de ArchiveList#getTotalCount() pour obtenir le nombre d'éléments.
  • OpenTok#setStreamLayouts(String, StreamListProperties) remplacé par VideoClient#setStreamLayout(String, List<SessionStream>) (ou VideoClient#setStreamLayout(String, SessionStream...) pour plus de commodité).
  • OpenTok#signal(String, String, SignalProperties) et OpenTok#signal(String, SignalProperties) remplacé par VideoClient#signal(String, String, SignalRequest) et VideoClient#signalAll(String, SignalRequest)respectivement.
  • La structure des jetons obtenus à l'aide de l'outil generateToken méthodes en OpenTok et VideoClient sont différents. Vonage utilise des JWT, tandis qu'OpenTok utilise une solution personnalisée.
  • OpenTok#startCaptions(String, String, CaptionProperties) remplacé par VideoClient#startCaptions(CaptionsRequest).
    • CaptionProperties remplacé parCaptionsRequest.
    • Caption remplacé par CaptionsResponse.
      • CaptionsRequest utilise une énumération pour l'option languageCode au lieu d'une simple chaîne de caractères.
      • Les token et sessionId sont toujours nécessaires et définies dans le CaptionsRequest.Builder objet.
  • OpenTok#connectAudioStream(String, String, AudioConnectorProperties) remplacé par VideoClient#connectToWebsocket(ConnectRequest).
    • AudioConnectorProperties remplacé par ConnectRequest.
    • AudioConnector remplacé par ConnectResponse.
  • OpenTok#startRender(String, String, RenderProperties) remplacé par VideoClient#startRender(RenderRequest).
    • RenderProperties remplacé par RenderRequest.
      • name dans le paramètre interne Properties est définie au niveau supérieur RenderRequest.Builder.
    • Render remplacé par RenderResponse.
      • resolution est désormais une énumération au lieu d'une simple chaîne de caractères.
  • OpenTok#listRenders(Integer, Integer) remplacé par VideoClient#listRenders(ListStreamCompositionsRequest).
    • Cela fonctionne de la même manière que la mise à jour de la listBroadcasts et listArchives (voir ci-dessus).

Recommandations pour les tests

Des tests approfondis sont essentiels pour assurer une transition en douceur, tant pendant qu'après la migration. Il s'agit non seulement de tests unitaires, mais aussi de tests d'intégration et de régression. Il est également utile de tester manuellement le flux de votre application au moins une fois avant et après la migration pour s'assurer que vos tests automatisés font ce que vous pensez qu'ils font, ou pour détecter tout problème que les tests n'auraient pas décelé. Vous pouvez même envisager de créer des tests d'équivalence. L'idée est de créer une suite qui affirme que les versions OpenTok et Vonage Video de votre application font la même chose. Ces tests peuvent ensuite être supprimés une fois que la transition est terminée et que la version OpenTok de votre application est supprimée.

Dépannage et assistance

Le SDK Java Server de Vonage s'efforce de fournir des messages d'exception utiles dans les traces de pile si vous rencontrez des erreurs d'exécution. Examinez-les attentivement pour en déterminer la cause.

Canaux de soutien

Pour obtenir de l'aide générale et discuter de la transition vers Vonage Video, consultez la section Canal #video-api sur notre communauté Slackoù vous pourrez obtenir des réponses du personnel de Vonage et d'autres utilisateurs. Vous pouvez également nous contacter sur X @VonageDev. La personne à contacter en cas de problème avec l'API Video elle-même est support@api.vonage.com. Si vous trouvez un bogue avec le SDK, veuillez déposer un problème avec les étapes à suivre pour le reproduire sur GitHub.