Android SDK

The Vonage Video API Android SDK lets you use Vonage Video API-powered video sessions in apps you build for Android devices. The Android SDK provides the following functionalities:

  • Connecting to session
  • Publishing streams to a session
  • Subscribing to streams in a session

Important notes:

  • Android SDK 2.30.0+ supports both 4 KB and 16 KB page size devices.
  • Android SDK 2.29.1+ requires permission ACCESS_NETWORK_STATE and on Android API level 35+ also requires permission REQUEST_IGNORE_BATTERY_OPTIMIZATIONS. Check out the full list of permissions.
  • Android SDK 2.28.0+ requires a minimum Android API level of 24.
  • Android SDK 2.24.0 and above no longer support 32-bit x86 architectures.
  • Applications targeting API level 31 and above now require permission READ_PHONE_STATE. Check out the full list of permissions.

The Android SDK is supported on Wi-Fi, 4G/LTE, and 5G connections. The Android SDK supports one published audio-video stream, one subscribed audio-video stream, and up to five additional subscribed audio-only streams simultaneously (this is the baseline support on a Samsung Galaxy S3). To connect more than two clients in a session using the Android SDK, create a session that uses the Vonage Video Media Router (a session with the media mode set to routed).See The Vonage Video Media Router and media modes.

The Android SDK is supported on armeabi-v7a, armeabi64-v8a, x86, and x86_64 architectures. The SDK, version depending, works with any Android 6.0+ device (Marshmallow, API Level 23) that has a camera (for publishing video) and adequate CPU and memory support. Client SDKs are also available for web, iOS, Windows, macOS, Linux, and React Native. All Client SDKs can interact with one another. You can learn more about the basics of Vonage Video clients, servers, sessions, and more on the Video API Basics page.

Installing the SDK

The library (an aar file) is included in the root of the SDK bundle. A Maven version is available at https://search.maven.org/artifact/com.vonage/vonage-video-sdk. The artifact ID is "opentok-android-sdk", the library is provided in the vonage-video-android-sdk-2.28.3.aar file. You no longer need to include architecture-dependent .so files (which was required in previous versions). This file is included in the root of the SDK package. Place the aar file into your project in Android Studio. Then modify the gradle file for your project to reference the aar file.

Once you understand the basics of building with the Android SDK, you can get more detailed information and learn how to customize your application with the Vonage Video developer guides.

To investigate specific API classes and methods, see the Android SDK API reference.

Code samples

For sample code, visit our vonage-video-android-sdk-samples repo on GitHub.

Interoperability

Apps written with the Video Android SDK 2.30.0 can interoperate with Vonage Video apps written with version 2.28+ of the Video client SDKs:

  • OpenTok.js (Web)
  • Android SDK
  • iOS SDK
  • Windows SDK
  • Linux SDK

Installation

The library (an aar file) is included in the root of the SDK bundle. A Maven version is available at https://search.maven.org/artifact/com.vonage/vonage-video-sdk.

The artifact ID is "opentok-android-sdk". For more information, see Creating your own app using the Android SDK.

Developer and client requirements

The Android SDK supports one published audio-video stream, one subscribed audio-video stream, and up to five additional subscribed audio-only streams simultaneously (this is the baseline support on a Samsung Galaxy S3).

To connect more than two clients in a session using the Android SDK, create a session that uses the Vonage Video Media Router (a session with the media mode set to routed).See The Vonage Video Media Router and media modes.

The Android SDK is supported on armeabi-v7a, armeabi64-v8a, and x86_64 architectures.

The SDK supports both 4 KB and 16 KB page size devices from version 2.30.0 onwards. This ensures functionality, enhances compatibility, and prevents crashes. For more information, see this Android documentation on page sizes.

The Android SDK works with any Android 7.0+ device (Nougat, API Level 24) that has a camera (for publishing video) and adequate CPU and memory support.

Creating your own app using the Android SDK

A Maven version is available at https://search.maven.org/artifact/com.vonage/vonage-video-sdk.

The artifact ID is "opentok-android-sdk". Modify your app to download the Android SDK from https://search.maven.org/artifact/com.vonage/vonage-video-sdk. For example:

  1. Edit the build.gradle for your project and add the following code snippet to the allprojects/repositories section: mavenCentral()
  2. Modify the app's build.gradle file and add the following code snippet to the dependencies section: implementation 'com.opentok.android:opentok-android-sdk:2.30.0'
  3. Make sure the app's build.gradle file contains the following code snippet within android section (starting from Android Studio 4.1 this snippet is present when creating a new project).

For Android SDK versions greater 2.28.1:

For Android SDK versions between 2.22.0 and 2.28.1:

Permissions

The Android SDK uses the following permissions:

  • android.permission.ACCESS_NETWORK_STATE -- The OpenTok Android SDK requires this permission from version 2.29.1 onwards.
  • android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS -- The OpenTok Android SDK requires this permission from version 2.29.1 onwards in API level 35 and above.
  • android.permission.BLUETOOTH_CONNECT -- You need to enable this for API level 31 and above.o
  • android.permission.READ_PHONE_STATE -- The Android SDK requests this permission in API level 22 and lower, and 31 and above.
  • android.permission.CAMERA -- If your app does not use the default video capturer and does not access the camera, you can remove this permission.
  • android.permission.INTERNET -- Required.
  • android.permission.RECORD_AUDIO -- If your app does not use the default audio device and does not access the microphone, you can remove this permission.
  • android.permission.MODIFY_AUDIO_SETTINGS -- If your app does not use the default audio device and does not access the microphone, you can remove this permission.
  • android.permission.BLUETOOTH -- The default audio device supports Bluetooth audio. If your app does not use the default audio device and does not use Bluetooth, you can remove this permission.
  • android.permission.BROADCAST_STICKY -- We have determined that this is unused by the Android SDK, and we will remove this permission from an upcoming release.

You do not need to add these to your app manifest. The Android SDK adds them automatically. However, if you use Android 21+, certain permissions require you to prompt the user.

Your app can remove any of these permissions that will not be required. See this post and this Android documentation. For example, this removes the android.permission.CAMERA permission:

ProGuard Rules for the Vonage Android SDK

The Vonage Android SDK uses the following packages:

  • com.opentok
  • com.vonage (v2.22.1+)
  • org.webrtc * org.otwebrtc (v2.17+)

The recommended ProGuard configuration is:

When using Android Studio 3.4 or Android Gradle plugin 3.4.0+, shrinking, obfuscation and optimization are, by default, automatically enabled. Shrinking and obfuscating the Vonage Android SDK is not recommended. The configuration above forces the Vonage Android SDK source code to be kept, not disallowing the rest of the app to be shrunk. Don't obfuscate the Vonage Android SDK to prevent conflicts with other libraries. Preserve the Vonage Android SDK package names with the flag -keeppackagenames. The compiler automatically performs a set of optimizations by default. Any other optimizations are not recommended, but it is possible to enable additional optimizations, which may require to include additional ProGuard rules to avoid runtime issues, by adding the following in the project’s gradle.properties file:

See this Android documentation to have a better understanding of the overall ProGuard rules and its functionalities.

Integrating Android ConnectionService

Use Android's ConnectionService to create a VoIP app that uses the audio-video capabilities of the Android SDK. To create a basic VoIP app:

  • Register the android.telecom.ConnectionService in the AndroidManifest.xml file.
  • Create a class that extends the android.telecom.ConnectionService class. Implement methods of the ConnectionService class, including onCreateIncomingConnection(), onCreateOutgoingConnection, onCreateIncomingConnectionFailed(), and onCreateOutgoingConnectionFailed().
  • Create a class that extends the android.telecom.Connection class. Implement methods of the Connection class, including onAnswer() and onDisconnect. In the implementation of the onAnswer() method, you can connect to a Vonage Video session, publish a stream to the session, and enable code to subscribe to streams created in the session. In the implementation of the onDisconnect() method, you can disconnect from the session (and stop publishing and subscribing to streams).
  • You can use service like Google Firebase to implement push notifications for the app. You can set up notifications to know when your app is in the background or closed. This way, your app can receive a VoIP call while the app is in the closed state.

See the sample VOIP app in the opentok-android-sdk-samples repo. It shows how to implement the ConnectionService class to create a VoIP app that uses the Android SDK

Sample Apps

For sample code, visit our vonage-video-android-sdk-samples repo on GitHub.

Documentation

You can find detailed documentation of each Android method in the reference guide.

More information

For a list of new features and known issues, see the release notes.