Vonage Video Transition Guide for Node

Transitioning from `opentok` to `@vonage/video` or `@vonage/server-sdk`

Introduction

Purpose

The OpenTok Node SDK is in maintenance mode, as we have transitioned to a new Video SDK where Vonage credentials can be used in our Node SDK across all APIs.

Scope

To keep the @vonage/server-sdk package as small as possible, the Node SDK was broken up into smaller modules. This means that you can install just the @vonage/video into your project rather than the whole SDK. Whichever route you choose, only LTS versions of NodeJS will be supported (at time of writing, the minimum version is 18). The SDK can also support both ESM and CJS Node modules.

For the purposes of this document all examples will be done using the full SDK as a CJS module. async/await will also be used as it is less verbose than using promises. Keep in mind that async/await is just syntactic sugar around promises. There is no difference in functionality. This document will also use the latest ECMAScript support for const and let as well as use "fat-arrow" functions.

The NodeSDK is written in Typescript however it is not a requirement. Typescript provides definition files for your respected IDE to properly display usage.

Assumptions

In order to migrate from OpenTok to the Node SDK, you will need to know how promises (or async/await) work. Callbacks are no longer supported.

Resources

Vonage Video SDK Source Code Vonage Video API Documentation Vonage Video API Specifications

Planning Your Migration

Evaluate Impact

OpenTok SDK was written using callbacks. This means that migration will require significant changes to your project. Depending on how you structured your functions, this could prove challenging. Take for example, lets look at creating a session

For the node SDK it is as simple as:

try {
    const session = await vonage.video.createSession(
        {} // session options
    );
    console.log(session.sessionId);
} catch (err) {
    console.error(err);
}

While in the past, this required callbacks in order to accomplish the same task:

OT.createSession(
    {}, // session options
    function (err, session) {
        if (err) {
            console.error(err)
            return;
        }
        
        console.log(session.sessionId);
    }
);

As you can see, this is a major design paradime shift in how your project will function. If your project relies on another package that does not support promises, you can use Promise.resolve to force the promise to resolve. However, this could come at some performance cost as the application will have to wait for the SDK to complete the API call before it can continue.

If you absolutely cannot convert to async/await, you will not be able to migrate.

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 SDKs. 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.

Package Update

To update the video package, you can install using npm or yarn like so:

npm install @vonage/server-sdk

yarn install @vonage/server-sdk

If you want to install the stand alone module (Typescript users will also need to import @vonage/auth in order to create the video client):

npm install @vonage/video

yarn install @vonage/video

Authentication Changes

Authentication in both OpenTok and Node 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 Node 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.

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

Once you have created the application and downloaded the private key, you then pass that information into the client:

const { Vonage } = require('@vonage/server-sdk')

const vonage = new Vonage({
  appId: 'Your application id',
  privateKey: 'Your private key',
});

Migration Strategies

Migrating from callback to promises is no easy task. Chances are that your entire project is using callbacks. You might also be using third-party packages that are also written using callbacks. It is best that you take each API call one at a time.

Please note that using the built-in util.promisify utility, might not always work. There are some callback that return multiple parameters which util.promisify is unable to handle.

Changed Methods

OpenTok Method	Vonage Method	Notes
`createSession()`	`createSession()`	The `mediaMode` option is currently "enabled" or "disable"
`generateToken()`	`generateClientToken()`	This method was renamed to better reflect what it does
`listArchives()`	`searchArchives()`	This method was renamed to better reflect what it does. Auto pagination is not enabled
`setArchiveLayout()`	`updateArchiveLayout()`	This method was renamed to better reflect what it does. The multiple parameters for the layout have been replaced with a single argument that takes an `ArchiveLayout`
`signal()`	`sendSignal()`	This method was renamed to better reflect what it does
`forceDisconnect()`	`disconnectClient()`	This method was renamed to better reflect what it does
`getStream()`	`getStreamInfo()`	This method was renamed to better reflect what it does
`listStreams()`	`getStreamInfo()`	This method was removed, `getStreamInfo()` will return all streams if one is not supplied as a second argument

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.

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.

Direct Support via. Slack: Vonage Developer Slack

If you find a bug with the SDK, Raise a ticket in file an issue with steps to reproduce on Github

Finally, the video module has auto generated documentation hosted in the wiki section of the GitHub repo.