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 Vonage Video API Android SDK reference can be found here.

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.3+, 2.25.4+, and 2.26.0+ requires a minimum Android API level of 23.
  • 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.

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.

Code samples

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

Interoperability

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

  • OpenTok.js
  • iOS SDK
  • Windows SDK
  • macOS SDK
  • Linux SDK
  • React Native SDK

Installation

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

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 SDK is supported on high-speed Wi-Fi and 4G LTE networks.

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/client-sdk-video.

The artifact ID is "client-sdk-video". Modify your app to download the Android SDK from https://search.maven.org/artifact/com.vonage/client-sdk-video. 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.vonage:client-sdk-video:2.32.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:

compileOptions {
      sourceCompatibility JavaVersion.VERSION_17
      targetCompatibility JavaVersion.VERSION_17
}

For Android SDK versions between 2.22.0 and 2.28.1:

compileOptions {
    sourceCompatibility JavaVersion.VERSION_11
    targetCompatibility JavaVersion.VERSION_11
}

Permissions

The Android SDK uses the following permissions:

  • android.permission.ACCESS_NETWORK_STATE -- The Vonage Video Android SDK requires this permission from version 2.29.1 onwards.
  • android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS -- The Vonage Video 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. If you want to use the Bluetooth device with Android SDK DefaultAudioDevice targeting API level 31 and above, please ask for runtime permissions in the app or enable the ("Nearby devices/Bluetooth") permission manually in the app settings.
  • android.permission.READ_PHONE_STATE -- The Vonage Video 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, in API level 21 and higher, 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:

<uses-permission android:name="android.permission.CAMERA" tools:node="remove"/>

ProGuard Rules for the Vonage Video Android SDK

The recommended ProGuard configuration is:

-keeppackagenames
-keep class com.opentok.** { *; }
-keep class com.vonage.** { *; }

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 Video Android SDK is not recommended. The configuration above forces the Vonage Video Android SDK source code to be kept, not disallowing the rest of the app to be shrunk. Preserve the Vonage Video 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:

android.enableR8.fullMode=true

Minifying the Vonage Video Android SDK is not recommended. Shrinking and obfuscating the Vonage Video Android SDK with the preceding optimization will generate warnings. These should be disabled.

# Please add these rules to your existing keep rules in order to suppress warnings.
# This is generated automatically by the Android Gradle plugin.
-dontwarn org.bouncycastle.jsse.BCSSLParameters
-dontwarn org.bouncycastle.jsse.BCSSLSocket
-dontwarn org.bouncycastle.jsse.provider.BouncyCastleJsseProvider
-dontwarn org.conscrypt.Conscrypt$Version
-dontwarn org.conscrypt.Conscrypt
-dontwarn org.conscrypt.ConscryptHostnameVerifier
-dontwarn org.openjsse.javax.net.ssl.SSLParameters
-dontwarn org.openjsse.javax.net.ssl.SSLSocket
-dontwarn org.openjsse.net.ssl.OpenJSSE

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.
<service android:name="com.example.package.MyConnectionService"
    android:label="@string/some_label_for_my_connection_service"
    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.ConnectionService" />
    </intent-filter>
</service>
  • 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.

When using ConnectionService, use the AudioDeviceManager.getAudioFocusManager() method and implement methods of the returned AudioFocusManager instance to delegate audio focus control to your app. These are defined in the Vonage Android SDK:

private AudioDeviceManager audioDeviceManager;
private BaseAudioDevice.AudioFocusManager audioFocusManager;

public void setupAudioFocusManager(Context context) {
    audioDeviceManager = new AudioDeviceManager(context);
    audioFocusManager = audioDeviceManager.getAudioFocusManager();
    audioFocusManager.setRequestAudioFocus(false);
}

public void notifyAudioFocusIsActive() {
    audioFocusManager.audioFocusActivated();
}

public void notifyAudioFocusIsInactive() {
    audioFocusManager.audioFocusDeactivated();
}

When delegating audio focus to the app, the SDK stops its automatic audio routing. Instead, this routing logic is handled by ConnectionService, which notifies the app about available audio devices through the Connection's CallEndpoint and CallAudioState APIs. Your app must implement support for audio device enumeration and selection logic.

This delegation ensures proper audio routing and coordination with the Android Telecom system.

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.

Foreground services

Foreground services in Android are essential for maintaining access to camera and microphone capabilities even when your app is in the background. For video chat apps, this means you can continue to capture video and audio while multitasking. Beginning with Android 14 (API level 34), you must declare an appropriate service type for each foreground service in your app manifest — for example, declaring the service type "camera" along with the corresponding FOREGROUND_SERVICE_CAMERA permission. Additionally, you must request the necessary runtime permissions, such as the CAMERA permission, which is subject to while-in-use restrictions. This setup ensures your app has the required privileges to operate camera and microphone functionalities in the background, aligning with the latest Android requirements and best practices.

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.