Vonage Video-Übergangsleitfaden für Java

Der Übergang von com.tokbox:opentok-server-sdk zu com.vonage:server-sdk.

Einführung

Zweck

Das Ziel dieses Dokuments ist es, einen Ausgangspunkt für den Übergang vom OpenTok Java Server SDK zum Vonage Java Server SDK zu bieten.

Umfang

In diesem Dokument wird davon ausgegangen, dass Sie mindestens die Version 4.0.0 oder höher des OpenTok Java SDK. Die Video API wurde dem Java Server SDK in Version 8.0.0 hinzugefügt. Sie sollten die neueste Version des Vonage Java SDK verwenden, die Sie unter GitHub oder Maven-Zentrale.

Annahmen

Dieser Leitfaden richtet sich an einen professionellen Softwareentwickler. Es werden zumindest grundlegende Kenntnisse im Umgang mit Java, gängigen Java-Entwicklerwerkzeugen, Build-Systemen (Maven oder Gradle) und Git (oder einem anderen Versionskontrollsystem) vorausgesetzt. Sie sollten mit dem Lesen und Schreiben von Java-Code, der Verwaltung von Projektabhängigkeiten, der Bereitstellung und Ausführung eines Java-Projekts vertraut sein. Eine Einführung in die Java-Sprache, -Plattform und die zugehörigen Werkzeuge würde den Rahmen dieses Dokuments sprengen.

Ressourcen

Die folgenden Links sind nützlich für weiterführende Lektüre zu diesem Dokument und als Referenz für alles, was nicht in diesem Dokument behandelt wird:

Vonage

TokBox

Planung Ihrer Migration

Bevor Sie von OpenTok auf Vonage Video umsteigen, sollten Sie den Umfang der Aufgabe bedenken, um realistische Erwartungen zu setzen.

Bewertung der Auswirkungen

Die erste Frage, die es zu beantworten gilt, lautet: Wie viel vom Code Ihrer Anwendung hängt vom OpenTok SDK ab? Erstellen Sie eine Liste aller Dateien, in denen das SDK direkt verwendet wird. Das heißt, jede Java-Quelldatei, die Importe aus dem com.opentok Paket. Sie können die Dateien in Ihrem Projekt nach der Anweisung import com.opentok eine IDE oder ein Befehlszeilentool verwenden, um die betroffenen Dateien zu identifizieren.

Zeitleiste

Berücksichtigen Sie die für die Umstellung erforderliche Zeit. Dies hängt von Ihrer Erfahrung mit dem Projekt und seinen Auswirkungen sowie von den Tests ab. Es ist wichtig, eine gute Test-Suite zu haben, um die Gleichwertigkeit von OpenTok und Vonage Video zu verifizieren. Der Zeitaufwand für die Umstellung ist in etwa proportional zur Anzahl der Stellen, an denen das OpenTok SDK in Ihrem Code verwendet wird, sowie zur Vielfalt der verwendeten Funktionen. Einige API-Aufrufe werden einfacher zu ersetzen sein als andere.

Versionierung

Idealerweise sollten Sie für den Übergang einen neuen Zweig in Ihrem Versionskontrollsystem anlegen, damit Sie schrittweise und häufig Änderungen vornehmen können, ohne das bestehende Projekt zu zerstören. Sie können auch die Tests des bestehenden Projekts als Orakel für die Korrektheit verwenden. Idealerweise sollten Sie den Übergangszweig erst dann mit dem Hauptzweig zusammenführen, wenn Sie die Umstellung abgeschlossen haben.

Wichtige Änderungen und Überlegungen

Neue Funktionen und Standards

Die Vonage Video API hat die gleichen Funktionen wie OpenTok, und das Java SDK wird aktiv gepflegt, um mit der API-Spezifikation übereinzustimmen. Einer der Unterschiede zwischen den Java-SDKs von OpenTok und Vonage besteht darin, dass das Java-SDK ein Datenmodell mit stärkerer Typisierung anstelle von einfachen Strings verwendet. Außerdem ist es konsistenter mit anderen APIs im SDK und folgt Konventionen, die die Verwendung des SDKs intuitiv machen sollten. Ein weiterer wichtiger Unterschied besteht darin, dass die Request- und Response-Klassen vereinheitlicht wurden. Zum Beispiel würden Sie die Archive Klasse sowohl für das Erstellen als auch für das Abrufen eines Archivs, während Sie in OpenTok die ArchiveProperties für die Anfrage und Archive für die Antwort. Wie das OpenTok-SDK verwendet auch das Java-SDK das Builder-Muster für die Konstruktion von Anfrageobjekten.

Anders als das OpenTok SDK verwendet das Vonage SDK keine geprüften Ausnahmen. Daher müssen Sie nicht mehr eine try {...} catch (InvalidArgumentException ex)so dass Sie Ihren Code entrümpeln können. Wenn Sie Ausnahmen für erfolglose API-Aufrufe (d. h. ohne Statuscode 2xx) abfangen möchten, können Sie VideoResponseException anstelle von OpenTokException.

Aktualisierung der Abhängigkeiten

Zunächst müssen Sie die Abhängigkeiten Ihres Build-Systems aktualisieren, um das Vonage Java SDK anstelle von OpenTok zu verwenden. Die Anweisungen dazu hängen von Ihrem Build-System ab. Eine Anleitung, wie Sie die neueste Version des Vonage Java SDK in Ihr Build einbinden können, finden Sie unter Maven-Zentrale oder mvnrepository.com.

Für eine schrittweise Migration können Sie sowohl OpenTok- als auch Vonage-Abhängigkeiten in Ihr Projekt einbinden. Wir empfehlen jedoch dringend, dies nur zu Testzwecken zu tun und nicht in der Produktion einzusetzen, da das OpenTok SDK in der Regel ältere Versionen von Abhängigkeiten verwendet, die zur Laufzeit Probleme verursachen können.

Name des Pakets

Sobald Sie das Vonage Java SDK mit Ihrem Build-Tool zu Ihrem Klassenpfad hinzugefügt haben, können Sie es in Ihrem Code verwenden.

Sie können die Importe aus dem com.opentok und com.opentok.exception Pakete mit com.vonage.client.video. Ein Suchen und Ersetzen mit Ihrer IDE oder Ihrem Code-Editor für Ihr Projekt sollte die meisten Kompilierungsfehler beheben können.

Beachten Sie, dass es keine weiteren Unterpakete für Ausnahmen gibt - die einzige Ausnahme, die Sie jemals abfangen müssen, um mit API-Fehlern umzugehen, ist com.vonage.client.video.VideoResponseException.

Änderungen bei der Authentifizierung

Die Authentifizierung wird sowohl bei OpenTok als auch bei Vonage Java Server SDKs für Sie durchgeführt, so dass Sie Ihre Account-Anmeldedaten nur einmal bei der Initialisierung angeben müssen. Der Unterschied besteht darin, dass OpenTok API-Schlüssel und -Geheimnis benötigt, während Sie für die Video API im Vonage Java SDK eine Anwendungs-ID und ihren privaten Schlüssel angeben müssen. Während sowohl Vonage als auch OpenTok eine Token-basierte Authentifizierung verwenden, sind die Token von Vonage JWTs während OpenTok ein eigenes Format verwendet. Sie können zwar einen API-Schlüssel und ein Geheimnis für die VonageClient Genau wie bei OpenTok wird dies für andere Vonage APIs verwendet, nicht für Video. Daher müssen Sie eine bestehende Anwendung erstellen oder verwenden.

Sie können eine Anwendung aus dem Menü Vonage Dashboard. Stellen Sie sicher, dass Ihre Anwendung die Videofunktion aktiviert hat. Klicken Sie bei einer bestehenden Anwendung auf "Bearbeiten", um deren Fähigkeiten und Anmeldeinformationen anzuzeigen. Klicken Sie hier auf "Öffentlichen und privaten Schlüssel generieren". Dies sollte nur einmal durchgeführt werden, da sich die Anmeldeinformationen jedes Mal ändern und somit das bestehende Schlüsselpaar zerstört wird. Wenn Sie auf diese Schaltfläche klicken, wird ein Download Ihres privaten Schlüssels ausgelöst. Sie sollten diese Datei zu Testzwecken an einem sicheren Ort ablegen. GEBEN SIE NIEMALS IHREN PRIVATEN SCHLÜSSEL WEITER ODER VERÖFFENTLICHEN SIE IHN! Der private Schlüssel ist quasi das "Passwort" für Ihre Anwendung und sollte daher sorgfältig behandelt werden. Es wird empfohlen, eine Umgebungsvariable zu erstellen, die auf den Pfad Ihrer privaten Schlüsseldatei verweist, so dass Sie beim Einrichten der Anwendung auf diese verweisen können. VonageClientund nennt die Variable etwa so VONAGE_PRIVATE_KEY_PATH. Dasselbe gilt für Ihre Anwendungs-ID (die Sie auf dem Dashboard oder in der URL finden, wenn Sie sie bearbeiten).

Weitere Hinweise zum Einrichten einer Anwendung finden Sie unter die Anleitung "Erste Schritte.

Verwendung

Siehe Das Java SDK README für Anweisungen zur Einrichtung.

Stattdessen:

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

Gehen Sie wie folgt vor:

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

Sobald Sie die Instanzierung der VonageClientkönnen Sie die Video API durch die Verwendung der VideoClientwie sie sich aus dem VonageClient (siehe oben).

Die API-Methoden auf VideoClient sind mit Javadocs dokumentiert und entsprechen in etwa den Methoden, die in der OpenTok Klasse.

Ausführlichere Anweisungen zur Verwendung finden Sie in der Java Sever SDK Videoanleitung.

Änderungen der Methode

Bei der Migration von OpenTok zu Vonage gibt es einige kleine Änderungen zu beachten. Viele davon sind unkompliziert und Ihre IDE wird Ihnen bei der automatischen Vervollständigung helfen, aber zur Verdeutlichung sollten Sie die folgenden Punkte beachten:

  • projectId ist jetzt applicationId falls zutreffend.
  • Gegebenenfalls wird eine stärkere Typisierung verwendet (z. B. UUID und URI anstelle von String).
  • playDTMF umbenannt in sendDtmf für alle anwendbaren DTMF-Endpunkte.
  • OpenTok#disableForceMute(String) ersetzt durch VideoClient#muteSession(String, boolean, String...). Sie müssen die active boolescher Parameter an false um denselben Effekt zu erzielen.
  • Die MuteAllProperties Klasse und Parameter in OpenTok wurde ersetzt durch die Verwendung des excludedStreamIds direkt in den Methodenparameter von VideoClient#muteSession(String, boolean, Collection<String>) (oder VideoClient#muteSession(String, boolean, String...) for convenience). Diese Methoden ersetzen OpenTok#forceMuteAll(String, MuteAllProperties).
  • ArchiveProperties und BroadcastProperties - wie sie in OpenTok in Anfrageparametern verwendet werden - wurden ersetzt durch Archive und Broadcast beziehungsweise. Beide verwenden das Bauherrenmuster für die Konstruktion.
    • Archive und Broadcast in Vonage stellen die Antworten in ähnlicher Weise dar wie ihre OpenTok-Pendants.
    • Somit stellen die Anfrage- und Antwortobjekte Archive und Broadcast wurden in der Vonage-Implementierung vereinheitlicht.
  • OpenTok#setBroadcastLayout(String, BroadcastProperties) ersetzt durch VideoClient#updateBroadcastLayout(String, StreamCompositionLayout).
  • OpenTok#setArchiveLayout(String, ArchiveProperties) ersetzt durch VideoClient#updateArchiveLayout(String, StreamCompositionLayout).
  • OpenTok#dial(String, String, SipProperties) ersetzt durch VideoClient#sipDial(SipDialRequest).
    • Sip ersetzt durch SipResponse.
  • Die listArchives Methoden mit verschiedenen Parametern in OpenTok wurden ersetzt durch VideoClient#listArchives(ListStreamCompositionsRequest) zur Steuerung der Optionen.
    • Die Antwort ist eine einfache List<Archive> anstelle von ArchiveList. Verwenden Sie Collection#size() anstelle von ArchiveList#getTotalCount() um die Anzahl der Elemente zu ermitteln.
  • OpenTok#setStreamLayouts(String, StreamListProperties) ersetzt durch VideoClient#setStreamLayout(String, List<SessionStream>) (oder VideoClient#setStreamLayout(String, SessionStream...) der Einfachheit halber).
  • OpenTok#signal(String, String, SignalProperties) und OpenTok#signal(String, SignalProperties) ersetzt durch VideoClient#signal(String, String, SignalRequest) und VideoClient#signalAll(String, SignalRequest).
  • Die Struktur der Token, die mit Hilfe der generateToken Methoden in OpenTok und VideoClient sind unterschiedlich. Vonage verwendet JWTs, während OpenTok eine eigene Lösung verwendet.
  • OpenTok#startCaptions(String, String, CaptionProperties) ersetzt durch VideoClient#startCaptions(CaptionsRequest).
    • CaptionProperties ersetzt durchCaptionsRequest.
    • Caption ersetzt durch CaptionsResponse.
      • CaptionsRequest verwendet ein Enum für die languageCode anstelle einer einfachen Zeichenkette.
      • Die token und sessionId sind weiterhin erforderlich und werden auf der CaptionsRequest.Builder Objekt.
  • OpenTok#connectAudioStream(String, String, AudioConnectorProperties) ersetzt durch VideoClient#connectToWebsocket(ConnectRequest).
    • AudioConnectorProperties ersetzt durch ConnectRequest.
    • AudioConnector ersetzt durch ConnectResponse.
  • OpenTok#startRender(String, String, RenderProperties) ersetzt durch VideoClient#startRender(RenderRequest).
    • RenderProperties ersetzt durch RenderRequest.
      • name Parameter in der inneren Properties Klasse auf der obersten Ebene festgelegt ist RenderRequest.Builder.
    • Render ersetzt durch RenderResponse.
      • resolution ist jetzt eine Aufzählung anstelle einer einfachen Zeichenkette.
  • OpenTok#listRenders(Integer, Integer) ersetzt durch VideoClient#listRenders(ListStreamCompositionsRequest).
    • Dies funktioniert ähnlich wie die aktualisierte listBroadcasts und listArchives Methoden (siehe oben).

Test-Empfehlungen

Gründliche Tests sind für einen reibungslosen Übergang sowohl während als auch nach der Migration unerlässlich. Dazu gehören nicht nur Unit-Tests, sondern auch Integrations- und Regressionstests. Es lohnt sich auch, Ihren Anwendungsablauf mindestens einmal vor und nach der Migration manuell zu testen, um sicherzustellen, dass Ihre automatisierten Tests das tun, was Sie glauben, dass sie es tun, oder um Probleme aufzuspüren, die die Tests möglicherweise nicht erkannt haben. Sie können sogar die Erstellung von Äquivalenztests in Betracht ziehen. Dabei geht es darum, eine Suite zu erstellen, die bestätigt, dass die OpenTok- und die Vonage Video-Version Ihrer Anwendung das Gleiche tun. Diese Tests können dann verworfen werden, sobald der Übergang abgeschlossen ist und die OpenTok-Version Ihrer Anwendung entfernt wurde.

Fehlersuche & Unterstützung

Das Vonage Java Server SDK ist bestrebt, hilfreiche Ausnahmemeldungen in den Stack Traces bereitzustellen, wenn Sie auf Laufzeitfehler stoßen. Untersuchen Sie diese sorgfältig, um die Ursache zu ermitteln.

Support-Kanäle

Allgemeine Hilfe und Diskussionen zum Umstieg auf Vonage Video finden Sie in der #video-api Kanal auf unserem Community Slackwo Sie Antworten von Vonage-Mitarbeitern und anderen Benutzern erhalten können. Sie können uns auch über X erreichen @VonageDev. Der Hauptansprechpartner für alle Probleme mit der Video API selbst ist support@api.vonage.com. Wenn Sie einen Fehler im SDK finden, bitten wir Sie ein Problem mit Schritten zur Reproduktion auf GitHub einreichen.