OpenTok React Native

Important notes:

Important note for TypeScript developers: Version 2.33.0 fixes broken TypeScript support introduced in version 2.31.1. This change does not introduce any functional changes to the SDK. However, after upgrading, your application may need to address typing issues that were previously hidden due to the missing type definitions. We strongly recommend reviewing your codebase for any TypeScript errors that surface after upgrading to version 2.33.0 or later.

New architecture support: Starting from version 2.31, the Vonage Video API React Native SDK is built with the React Native new architecture. This version requires React Native 0.81.1 or later and is only compatible with the new architecture. It is not supported on older React Native versions using the legacy architecture. Applications currently using older versions of this SDK will need to migrate to React Native's new architecture before upgrading. Please ensure you follow the installation instructions below.

React Native 0.86 support: Version 2.34.0 of the OpenTok React Native SDK adds support for React Native 0.86.

Android 17 support: Version 2.34.0 has been validated on Android 17 devices. No project configuration updates are required.

This page includes the following sections:

Apps written with the OpenTok React Native SDK 2.33+ can interoperate with OpenTok apps written with version 2.31+ of the OpenTok client SDKs:

  • OpenTok.js
  • OpenTok Android SDK
  • OpenTok iOS SDK
  • OpenTok Windows SDK
  • OpenTok macOS SDK
  • OpenTok Linux SDK

The OpenTok React Native SDK is built on top of the OpenTok Android SDK and iOS SDK. For details, see the following:

Prerequisites

  1. Install node.js

  2. Install and update Xcode (you will need a Mac). (See the React Native iOS installation instructions.)

  3. Install and update Android Studio. (See the React Native Android installation instructions.)

System requirements

See the system requirements for the OpenTok Android SDK and OpenTok iOS SDK. (The OpenTok React Native SDK has the same requirements for Android and iOS.)

Installation

Installation via GitHub Packages

In addition to installing from the npm registry, the Vonage Video API Client SDK packages are also available through GitHub Packages' NPM registry. This provides an alternative distribution channel for enterprise environments that require GitHub-based package management.

Available Packages

The following package is published to GitHub Packages:

Setup Instructions

To install packages from GitHub Packages' NPM registry, you need to configure npm to authenticate with GitHub:

1. Create a GitHub Personal Access Token (PAT)

Generate a personal access token with read:packages scope from your GitHub account settings.

2. Configure your .npmrc file

Add the following configuration to your project's .npmrc file or your user-level ~/.npmrc file:

//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
@opentok:registry= https://npm.pkg.github.com

Replace YOUR_GITHUB_TOKEN with your GitHub personal access token.

3. Install the package

Once configured, you can install the package using the standard npm install command as explained below.

Note on Package Availability

Both the traditional npm registry and GitHub Packages registry are kept in sync. You can choose either distribution method based on your organization's package management preferences. The traditional npm installation method (via npm install opentok-react-native from the default registry) remains fully supported and requires no additional configuration.

For more information about working with GitHub Packages' NPM registry, see the GitHub Packages documentation.

For Expo projects

If you're using Expo, the setup is simplified with the config plugin:

1. Install the package:

npx expo install @opentok/opentok-react-native

2. Add the plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "opentok-react-native",
        {
          "cameraPermission": "Allow $(PRODUCT_NAME) to use your camera for video calls",
          "microphonePermission": "Allow $(PRODUCT_NAME) to use your microphone for audio calls"
        }
      ]
    ]
  }
}

Plugin iOS Configuration Options:

Option Type Default Description
cameraPermission string "Allow $(PRODUCT_NAME) to access your camera for video calls" iOS camera permission message (NSCameraUsageDescription)
microphonePermission string "Allow $(PRODUCT_NAME) to access your microphone for audio calls" iOS microphone permission message (NSMicrophoneUsageDescription)

3. Rebuild your app:

npx expo prebuild npx expo run:ios # or npx expo run:android

What the config plugin does automatically:

Adds iOS camera and microphone permissions to Info.plist
Adds all required Android permissions to AndroidManifest.xml:

  • BLUETOOTH
  • REQUEST_IGNORE_BATTERY_OPTIMIZATIONS
  • BLUETOOTH_CONNECT
  • BROADCAST_STICKY
  • CAMERA
  • INTERNET
  • MODIFY_AUDIO_SETTINGS
  • READ_PHONE_STATE
  • RECORD_AUDIO
  • ACCESS_NETWORK_STATE

Configures hardware features for Android

No manual native configuration needed! When using Expo with the config plugin, you can skip the iOS Installation and Android Installation sections below.

For React Native CLI projects

In your terminal, change into your React Native project's directory.

Add the library using npm or yarn:

npm install @opentok/opentok-react-native@<VERSION>

Note: Replace <VERSION> with the target version to use.

After installing the package, continue with the iOS Installation and Android Installation sections below.

iOS Installation

  1. Install the iOS pods:

    npx pod-install

  2. Ensure you have enabled both camera and microphone usage by adding the following entries to the Info.plist file:

    <key>NSCameraUsageDescription</key>
<string>Your message to user when the camera is accessed for the first time</string>
<key>NSMicrophoneUsageDescription</key>
<string>Your message to user when the microphone is accessed for the first time</string>

When you create an archive of your app, the privacy manifest settings required by Apple's App store are added automatically with this version of the OpenTok React Native SDK.

  1. Register the OpenTok OTPublisherViewNative and OTSubscriberViewNative classes. Do this by modifying the AppDelegate implementation.

    • If you app has an Objective-C++ AppDelegate file (AppDelegate.mm), add these classes to the list of packages in the NSMutableDictionary returned by the thirdPartyFabricComponents() function:

      #import "OTPublisherViewNativeComponentView.h" #import "OTSubscriberViewNativeComponentView.h"

      @implementation AppDelegate

         // ...

   - (NSDictionary> *)thirdPartyFabricComponents
   {
     NSMutableDictionary * dictionary = [super thirdPartyFabricComponents].mutableCopy;
     dictionary[@"OTRNPublisher"] = [OTRNPublisherComponentView class];
     dictionary[@"OTRNSubscriber"] = [OTRNSubscriberComponentView class];
     return dictionary;
   }

      @end

    • If your app uses a Swift AppDelegate file (AppDelegate.swift), you will need to have its implementation of the RCTAppDelegate.application(_, didFinishLaunchingWithOptions) method use a bridging header to call a method in an Objective-C++ file that calls the [RCTComponentViewFactory registerComponentViewClass:] method, passing in the OTRNPublisherComponentView and OTRNSubscriberComponentView classes. You will also need to add the bridging header path in the project's build settings in Xcode, under Objective-C Bridging Header.

      For example, add a bridging header for your app:

      #ifndef BasicVideoTS_Bridging_Header_h #define BasicVideoTS_Bridging_Header_h

      #import "FabricComponentRegistrar.h"

      #endif

      Then create FabricComponentRegistrar.h and FabricComponentRegistrar.cpp files:

      // FabricComponentRegistrar.hpp

      #import <Foundation/Foundation.h>

      @interface FabricComponentRegistrar : NSObject

      • (void)registerCustomComponents; @end

      // FabricComponentRegistrar.mm #include "FabricComponentRegistrar.h" #import <React/RCTComponentViewFactory.h> #import <React/RCTViewComponentView.h> #import "OTRNPublisherComponentView.h" #import "OTRNSubscriberComponentView.h"

      @implementation FabricComponentRegistrar

      • (void)registerCustomComponents { RCTComponentViewFactory *factory = [RCTComponentViewFactory currentComponentViewFactory]; [factory registerComponentViewClass:[OTRNPublisherComponentView class]]; [factory registerComponentViewClass:[OTRNSubscriberComponentView class]]; }

      Finally, call the FabricComponentRegistrar.registerCustomComponents() method in the AppDelegate.swift RCTAppDelegate.application(_, didFinishLaunchingWithOptions) method:

      override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { self.moduleName = "BasicVideoTS" self.dependencyProvider = RCTAppDependencyProvider()

      // You can add your custom initial props in the dictionary below.
// They will be passed down to the ViewController used by React Native.
self.initialProps = [:]

      return super.application(application, didFinishLaunchingWithOptions: launchOptions) let result = super.application(application, didFinishLaunchingWithOptions: launchOptions) FabricComponentRegistrar.registerCustomComponents() return result }

    Register the FabricComponentRegistrar.mm file as a build file in XCode.

  2. If your app will use the OTPublisher.setVideoTransformers() or OTPublisher.setAudioTransformers() method, you need to include the following in your Podfile:

    pod 'VonageClientSDKVideoTransformers', '= 2.33.0'

If you try to archive the app and it fails, please do the following:

  1. Go to Target.

  2. Click Build Phases.

  3. Under the Link Binary With Libraries section, remove libOpenTokReactNative.a and add it again.

Android Installation

  1. In your terminal, change into your project directory.

  2. Run bundle install.

  3. Make sure the following in your app's gradle compileSdkVersion, buildToolsVersion, minSdkVersion, and targetSdkVersion are greater than or equal to versions specified in the OpenTok React Native library.

  4. The SDK automatically adds Android permissions it requires. You do not need to add these to your app manifest. However, certain permissions require you to prompt the user. See the full list of required permissions in the Vonage Video API Android SDK documentation.

  5. In the MainApplication.kt file for your app, import and register the OpentokReactNativePackage, OTRNPublisherPackage, and OTRNSubscriberPackage packages. Do this by modifying the MainApplication file by adding these to the list of packages returned by the getPackages() function:

    import com.opentokreactnative.OTRNPublisherPackage
import com.opentokreactnative.OTRNSubscriberPackage
import com.opentokreactnative.OpentokReactNativePackage;

// ... 
override fun getPackages(): List<ReactPackage> =
    PackageList(this).packages.apply {
		add(OTRNPublisherPackage())
		add(OTRNSubscriberPackage())
        add(OpentokReactNativePackage())
    }
    // ...

  6. If your app will use the OTPublisher.setVideoTransformers() or OTPublisher.setAudioTransformers() method, you need to include the following in your app/build.gradle file:

    implementation "com.vonage:client-sdk-video-transformers:2.33.0"

Bintray sunset

Bintray support has ended (official announcement: https://jfrog.com/blog/into-the-sunset-bintray-jcenter-gocenter-and-chartcenter/). In your app build.gradle file you need to remove reference to jcenter and replace it with mavenCentral. Example:

// Top-level build file where you can add configuration options common to all sub-projects/modules.

buildscript {
    ...
    repositories {
        google()
        mavenCentral()
    }
    ...
}

allprojects {
    repositories {
        maven {
            // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm
            url("$rootDir/../node_modules/react-native/android")
        }
        maven {
            // Android JSC is installed from npm
            url("$rootDir/../node_modules/jsc-android/dist")
        }
        mavenCentral {
            // We don't want to fetch react-native from Maven Central as there are
            // older versions over there.
            content {
                excludeGroup "com.facebook.react"
            }
        }
        google()
        maven { url 'https://www.jitpack.io' }
    }
}

Basic sample

This simplest use of these opentok-react-native components:

<OTSession apiKey="your-api-key" sessionId="your-session-id" token="your-session-token">
  <OTPublisher style={{ width: 100, height: 100 }}/>
  <OTSubscriber style={{ width: 100, height: 100 }} />
</OTSession>

Replace your-api-key, your-session-id, and your-session-token with your OpenTok project API key, an OpenTok session ID, and a token for the session.

Note that you add the OTPublisher and OTSubscriber components and children of the OTSession component. Use the style and className properties to use CSS to adjust publisher and subscriber layout.

Unsupported features

The OpenTok React Native library provides a React interface for using the OpenTok Android and iOS client SDKs. The following advanced features of the OpenTok Android and iOS client SDKs are unsupported in the OpenTok React Native library:

  • Custom audio drivers -- An application using OpenTok React Native use the device microphone to capture audio to transmit to a published stream. And it uses the device speakers (or headphones) to play back audio from subscribed streams. However, you can set the enableStereoOutput property of the OTSession object to enable stereo output.

  • Custom video capturers -- (BaseVideoCapturer) -- The OpenTok React Native OTPublisher uses the standard video capturer that uses video directly from the device's camera. However, you can set the videoSource property of an OTPublisher component to "screen" to publish a screen-sharing stream.

  • Custom video renderers -- The OTSubscriber and OTPublisher components implement a standard video renderer that renders streams and provides user interface controls for displaying the stream name and muting the microphone or camera. Publishers and subscribers use mPublisher.setStyle(BaseVideoRenderer.STYLE_VIDEO_SCALE, BaseVideoRenderer.STYLE_VIDEO_FILL)

  • iOS delegate callback queue -- For iOS, you cannot assign the delegate callback queue (the GCD queue). See the docs for the OTSession.apiQueue property in the OpenTok iOS SDK.

  • CallKit API -- Version 2.31.0 of the OpenTok iOS SDK added API enhancements to use iOS CallKit without implementing a custom audio driver. This is not implemented in the React Native SDK.

  • Android ConnectionService API -- Version 2.31.0 of the OpenTok Android SDK added support for integrating Android ConnectionService without implementing a custom audio driver. This is not implemented in the React Native SDK.

To build Android and iOS apps that use these features, use the OpenTok Android SDK and the OpenTok iOS SDK.

More samples

To see this library in action, check out the opentok-react-native-samples repo.