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 is available online.

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.34.1 can interoperate with Vonage Video apps written with version 2.32+ 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.

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.34.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
}

System requirements

For reliable video streaming, ensure your Android device meets these recommended specs:

  • CPU: A recent dual-core processor; ARM64 (ARMv8) Quad-core or higher at 2.0 GHz+ (e.g., Qualcomm Snapdragon 600+ series, Samsung Exynos 7 series or higher, Google Tensor (Pixel devices)).
  • GPU: Adreno 500+ series (Qualcomm), Mali-G71+ (ARM); for hardware-accelerated video encoding/decoding.
  • RAM: At least 6 GB RAM for group calls and multitasking.
  • Display: 5"+ for better user experience.
  • Battery capacity: 3000+ mAh for extended video calls.
  • Network: Reliable internet connectivity; works over Wi‑Fi or cellular.

These recommendations ensure stable playback, lower CPU usage, and smooth performance when streaming video.

Device examples by category: Samsung Galaxy A12, Moto G Play, and Nokia G10 are entry-level; Google Pixel 6a, Samsung Galaxy A52/A53, and OnePlus Nord are mid-range; and Samsung Galaxy S23/S24, Google Pixel 8 Pro, and OnePlus 11 are high-end.

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 vonage-video-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.

Set up Foreground Services

What is a Foreground Service

Foreground services let you asynchronously perform operations that are noticeable to the user. Foreground services show a status bar notification, to make users aware that your app is performing a task in the foreground and is consuming system resources.

Examples of use cases that use foreground services include:

  • Keep capturing and sending audio to peers even when the user opens a different app.
  • Allow a user to share their screen while switching between apps.
  • Allow users to turn off their screen while still listening to a video call.

Foreground Services Types

Android 10 introduced the android:foregroundServiceType attribute within the <service> element. The idea of it is to explicitly specify what kind of work the service does.

Android 14 makes specifying the foreground service type mandatory. This is to ensure the correct usage of foreground services and consistency across device manufacturers.

The currently supported types are:

  • camera (required in Android 11) — when accessing the camera from the background, such as video calling apps
  • connectedDevice — when interacting with external device, such as Bluetooth fitness device
  • dataSync — when uploading or downloading data, will be deprecated and alternatives like DownloadManager, BackupManager, or WorkManager should be used instead
  • health (new in Android 14) — for fitness apps such as exercise trackers
  • location (required in Android 10) — when location is required, such as navigation
  • mediaPlayback — when continuing audio or video playback from the background, like Spotify or Netflix
  • mediaProjection — when projecting content to external devices or screens
  • microphone (required in Android 11) — when accessing the microphone from the background, such as calling apps
  • phoneCall — when continuing an ongoing call
  • remoteMessaging (new in Android 14) — when transferring text messages from one device to another
  • shortService — when it’s required to quickly finish critical work that can’t be interrupted, can only run for about 3 minutes
  • specialUse — when other types don’t cover your use case
  • systemExempted — reserved for system apps

Declare foreground service type

The first step in supporting Android 14 is to update your service declaration in the AndroidManifest file and specify the correct foreground service type.

If your service requires multiple types, you can combine them using the | operator like this:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
    <service
        android:name=".MyForegroundService"
        android:foregroundServiceType="microphone|camera"
        android:exported="false">
    </service>
</manifest>

If you try to start a foreground service without declaring its type in the manifest, the system will throw a MissingForegroundServiceTypeException upon calling startForeground().

Request specific foreground service permission

From Android 9 (API 28) onwards apps had to request FOREGROUND_SERVICE permission in the app manifest, which was granted automatically by the system.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

Starting from Android 14 (API 34) apps need to additionally request specific permission depending on the type of the foreground service. So, if your service keeps accessing the microphone from the background you would need to specify FOREGROUND_SERVICE_MICROPHONE. The permission is automatically granted by the system.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>

If your service requires multiple types, you have to declare this permission for every type.

If you forget to declare either of the two permissions, you will receive a SecurityException with the exact reason why.

On Android 13 (API 33) and above, also declare POST_NOTIFICATIONS and request it at runtime if you need the foreground-service notification to appear reliably. This sample includes that flow.

Launch a foreground service

From your Activity or other Context, start the service with AndroidX so the correct API is used on all supported versions (this matches MainActivity in this project):

import android.Manifest
import android.content.Intent
import android.content.pm.PackageManager
import androidx.core.content.ContextCompat

fun startMyForegroundService() {
    val serviceIntent = Intent(this, MyForegroundService::class.java)
    if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO)
        == PackageManager.PERMISSION_GRANTED
    ) {
        ContextCompat.startForegroundService(applicationContext, serviceIntent)
    }
}

ContextCompat.startForegroundService() calls startForegroundService() on API 26+ and startService() on older APIs.

The code snippet launches a service. However, the service is not yet running in the foreground. Inside the service itself, you must call startForeground() promptly. With AndroidX, prefer ServiceCompat.startForeground() so you can pass a foregroundServiceType bitmask that matches your manifest (see MyForegroundService in this project):

import android.app.Notification
import android.content.pm.ServiceInfo
import android.os.Build
import androidx.core.app.NotificationCompat
import androidx.core.app.ServiceCompat

val notification: Notification = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("Audio Call in Progress")
    .setContentText("Your microphone is active while the app is in the background.")
    .setPriority(NotificationCompat.PRIORITY_HIGH)
    .setOngoing(true)
    .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
    .build()

ServiceCompat.startForeground(
    this,
    NOTIFICATION_ID,
    notification,
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
    } else {
        0
    },
)

Create a NotificationChannel (Android 8.0+) before building the notification, and catch ForegroundServiceStartNotAllowedException on API 31+ if the app is not allowed to start a foreground service from the current state.

Note: If you pass a foreground service type to startForeground / ServiceCompat.startForeground that you did not declare in the manifest, the system throws IllegalArgumentException.

Provide details of your use case on Google Play Console

After you upload the new version of the app that targets Android 14 and uses a foreground service type to the Google Play Console, you will see a prompt in your console to provide additional details about your usage.

As Google wants to make sure that apps are using foreground services appropriately, you will need to submit a new declaration on the App content page (Policy -> App content).

For each foreground service type you declare, you’ll need to do the following:

  • Describe the app functionality that is using that foreground service type.
  • Describe the user impact if the task is deferred or interrupted by the system.
  • Include a link to a video demonstrating each foreground service feature. The video should demonstrate the steps the user needs to take in your app to trigger the feature.
  • Choose your specific use case for each foreground service type. You can choose from a pre-set list of use cases listed here or enter it manually.

Sample app

See the Basic-Video-Chat-With-ForegroundServices sample in the vonage-video-android-sdk-samples repo.

Read more in the Android Foreground Services Overview documentation.

More information

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

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