Vonage Video Transition Guide for Java

Transitioning from `com.tokbox:opentok-server-sdk` to `com.vonage:server-sdk`.

Introduction

Purpose

The goal of this document is to provide a starting point for transitioning from the OpenTok Java Server SDK to the Vonage Java Server SDK.

Scope

This document assumes that you are using at least version 4.0.0 or later of the OpenTok Java SDK. The Video API was added to the Java Server SDK in version 8.0.0. You should use the latest version of the Vonage Java SDK, which can be found on GitHub or Maven Central.

Assumptions

This guide is intended to be followed by a professional software engineer. At least a basic level of competency with Java, common Java developer tools, build systems (Maven or Gradle) and Git (or other version control system) is assumed. You should be comfortable with reading and writing Java code, managing project dependencies, deploying and executing a Java project. An introduction to the Java language, platform and associated tooling is well beyond the scope of this document.

Resources

The following links are useful for further reading to accompany this document and for reference to anything not covered in this document:

Vonage

TokBox

Planning Your Migration

Before transitioning from OpenTok to Vonage Video, you should consider the scale of the task to set realistic expectations.

Evaluate Impact

The first question to answer is: how much of your application's code depends on the OpenTok SDK? Make a list of all the files in which the SDK is directly used. That is, any Java source file which contains imports from the com.opentok package. You can search through the files in your project for the statement import com.opentok using an IDE or command-line tool to identify the files affected.

Timeline

Take into account the time required to complete the transition. This will depend on your experience with the project and its impact, as well as testing. It is crucial to have a good test suite in place so that you can verify equivalence between the OpenTok and Vonage Video. The time it will take to complete the transition is roughly proportional to the number of places where the OpenTok SDK is used in your code, as well as the variety of features used. Some API calls will be simpler to replace than others.

Versioning

You should ideally create a new branch on your version control system for the transition, so that you can make changes gradually and frequently without breaking the existing project. You can also use the existing project's tests as an oracle for correctness. Ideally, you should only merge the transition branch into the main branch once you have completed the conversion.

Key Changes and Considerations

New Features and Standards

The Vonage Video API has feature parity with OpenTok, and the Java SDK is actively maintained to be in line with the API specification. One of the differences between the OpenTok and Vonage Java SDKs is that the Java SDK uses a data model with stronger typing rather than plain Strings. It also has greater consistency with other APIs in the SDK and follows conventions which should make using the SDK intuitive. Another key difference is that request and response classes are unified. For example, you would use the Archive class for both creating and retrieving an archive, whereas in OpenTok, you would use ArchiveProperties for the request and Archive for the response. As with the OpenTok SDK, the Java SDK uses the Builder pattern for constructing request objects.

Unlike the OpenTok SDK, the Vonage SDK does not use checked exceptions. Therefore, you no longer need to do a try {...} catch (InvalidArgumentException ex), allowing you to de-clutter your code. If you would like to catch exceptions for unsuccessful (i.e. non-2xx status code) API calls, you can catch VideoResponseException instead of OpenTokException.

Dependency Update

Firstly, you will need to update your build system's dependencies to use the Vonage Java SDK instead of OpenTok. Instructions for how to do this will depend on your build system. Instructions for how to include the latest version of the Vonage Java SDK in your build can be found on Maven Central or mvnrepository.com.

For a gradual migration, you can include both OpenTok and Vonage dependencies in your project, however we strongly recommend that this should be for testing only rather than deployments to production, as the OpenTok SDK tends to use older versions of dependencies which may cause issues at runtime.

Package Name

Once you have added the Vonage Java SDK to your classpath using your build tool, you can then start using it in your code.

You can replace imports from the com.opentok and com.opentok.exception packages with com.vonage.client.video. A Find & Replace using your IDE or code editor on your project should go a long way towards resolving most compilation errors.

Note that there are no further sub-packages for exceptions - the only exception you ever need to catch for dealing with API errors is com.vonage.client.video.VideoResponseException.

Authentication Changes

Authentication in both OpenTok and Vonage Java Server SDKs are handled for you, so you only need to provide your account credentials once upon initialisation. The difference is that OpenTok requires API key & secret, whilst for the Video API in Vonage Java SDK, you need to provide an application ID and its private key. Whilst both Vonage and OpenTok use token-based authentication, Vonage's tokens are JWTs whilst OpenTok uses a custom format. Whilst you can provide an API key and secret to the VonageClient just as with OpenTok, this is used for other Vonage APIs, not Video. Therefore, you will need to create or use an existing application.

You can create an application from the Vonage Dashboard. Ensure that your application has the Video capability enabled. Click 'Edit' for an existing application to view its capabilities and credentials. From here, click 'Generate public and private key'. This should only be done once, as every time you do this, the credentials change and so will break the existing key pair. Clicking this will trigger a download of your private key. You should place this file somewhere secure for testing. NEVER SHARE OR EXPOSE YOUR PRIVATE KEY! The private key is effectively the "password" to your application, so should be treated carefully. It is recommended that you create an environment variable which points to the path of your private key file, so that you can refer to it when setting up the VonageClient, calling the variable something like VONAGE_PRIVATE_KEY_PATH. The same should be done for your application ID (which can be found on the dashboard or in the URL when editing it).

For further guidance on setting up an application, see the Getting Started guide.

Usage

See The Java SDK README for setup instructions.

Instead of this:

Do the following:

Once you have instantiated the VonageClient, you can use the Video API by using the VideoClient, as obtained from the VonageClient (see above).

The API methods on VideoClient are documented using Javadocs, and are roughly analogous to the methods found on the OpenTok class.

For more detailed usage instructions, see the Java Sever SDK video guide.

Method Changes

There are a few small changes to be aware of when migrating to Vonage from OpenTok. Many of these are straightforward and your IDE will help you with auto-completion, but for clarity, consider the following:

projectId is now applicationId where applicable.
Stronger typing used where applicable (e.g. UUID and URI instead of String).
playDTMF renamed to sendDtmf for all applicable DTMF endpoints.
OpenTok#disableForceMute(String) replaced by VideoClient#muteSession(String, boolean, String...). You need to set the active boolean parameter to false to achieve the same effect.
The MuteAllProperties class and parameter in OpenTok has been replaced by using the excludedStreamIds directly in the method parameter of VideoClient#muteSession(String, boolean, Collection<String>) (or VideoClient#muteSession(String, boolean, String...) for convenience). These methods replace OpenTok#forceMuteAll(String, MuteAllProperties).
ArchiveProperties and BroadcastProperties - as used in request parameters in OpenTok - have been replaced by Archive and Broadcast respectively. Both use the builder pattern for construction.
- Archive and Broadcast in Vonage also represent the responses in a similar way to their OpenTok counterparts.
- Thus, the request and response objects representing Archive and Broadcast have been unified in the Vonage implementation.
OpenTok#setBroadcastLayout(String, BroadcastProperties) replaced by VideoClient#updateBroadcastLayout(String, StreamCompositionLayout).
OpenTok#setArchiveLayout(String, ArchiveProperties) replaced by VideoClient#updateArchiveLayout(String, StreamCompositionLayout).
OpenTok#dial(String, String, SipProperties) replaced by VideoClient#sipDial(SipDialRequest).
- Sip replaced with SipResponse.
The listArchives methods with various parameters in OpenTok have been replaced by VideoClient#listArchives(ListStreamCompositionsRequest) for controlling the options.
- The response is a plain List<Archive> instead of ArchiveList. Use Collection#size() instead of ArchiveList#getTotalCount() to obtain the number of elements.
OpenTok#setStreamLayouts(String, StreamListProperties) replaced by VideoClient#setStreamLayout(String, List<SessionStream>) (or VideoClient#setStreamLayout(String, SessionStream...) for convenience).
OpenTok#signal(String, String, SignalProperties) and OpenTok#signal(String, SignalProperties) replaced by VideoClient#signal(String, String, SignalRequest) and VideoClient#signalAll(String, SignalRequest), respectively.
The structure of tokens obtained used the generateToken methods in OpenTok and VideoClient are different. Vonage uses JWTs, whereas OpenTok uses a custom solution.
OpenTok#startCaptions(String, String, CaptionProperties) replaced by VideoClient#startCaptions(CaptionsRequest).
- CaptionProperties replaced withCaptionsRequest.
- Caption replaced with CaptionsResponse.
  - CaptionsRequest uses an enum for the languageCode instead of a plain string.
  - The token and sessionId are still required and set on the CaptionsRequest.Builder object.
OpenTok#connectAudioStream(String, String, AudioConnectorProperties) replaced by VideoClient#connectToWebsocket(ConnectRequest).
- AudioConnectorProperties replaced with ConnectRequest.
- AudioConnector replaced with ConnectResponse.
OpenTok#startRender(String, String, RenderProperties) replaced by VideoClient#startRender(RenderRequest).
- RenderProperties replaced by RenderRequest.
  - name parameter in the inner Properties class is set on the top-level RenderRequest.Builder.
- Render replaced by RenderResponse.
  - resolution is now an enum instead of a plain string.
OpenTok#listRenders(Integer, Integer) replaced by VideoClient#listRenders(ListStreamCompositionsRequest).
- This works similarly to the updated listBroadcasts and listArchives methods (see above).

Testing Recommendations

Thorough testing is essential for a smooth transition, both during and after the migration. This includes not only unit tests but also integration and regression testing. It is also worth manually testing your application flow at least once before and after the migration to ensure that your automated tests do what you think they do, or to pick up on any issues that the tests may not have caught. You may even consider creating equivalence tests. The idea is to create a suite which asserts that both the OpenTok and Vonage Video versions of your application do the same thing. These can then be discarded once your transition is complete and the OpenTok version of your application is removed.

Troubleshooting & Support

The Vonage Java Server SDK endeavours to provide helpful exception messages in stack traces should you encounter runtime errors. Examine these carefully to determine the cause.

Support Channels

For general help and discussion on transitioning to Vonage Video, check out the #video-api channel on our Community Slack, where you can get answers from Vonage staff and fellow users. You can also get in touch with us on X @VonageDev. The primary contact for any issues with the Video API itself is support@api.vonage.com. If you find a bug with the SDK, please file an issue with steps to reproduce on GitHub.