Overview

In this guide you learn how to add the Client SDK to your Android app.

Prerequisites

The Client SDK requires a minimum Android API level of 23.

To add the Client SDK to your project

Open you Android project

Open your Android project codebase in your IDE.

Add dependencies

The Vonage Client SDK on Android is distributed as 3 separate SDKs. com.vonage.client-sdk-voice for in-app voice functionality, com.vonage.client-sdk-chat for in-app messaging functionality, and combined as com.vonage.client-sdk. com.vonage.client-sdk-chat does not include the WebRTC dependency, so it is a smaller library. You must only use one SDK at a time in your application.

In-app voice and in-app messaging - install com.vonage.client-sdk only.
In-app voice - install com.vonage.client-sdk-voice only.
In-app messaging - install com.vonage.client-sdk-chat only.

NOTE: There are two languages used to define Gradle build scripts - Groovy (build.gradle file) and Kotlin Gradle Script (build.gradle.kts file). A Kotlin-Android project may still use Groovy as the language for the build scripts. Please check the file extension to determine the language for the build script files.

Now add the Client SDK to your project. Add the following dependency in your app level build.gradle file (typically app/build.gradle):

dependencies {
    implementation 'com.vonage:client-sdk:1.6.0'
}

You may need to increase the memory allocation for the JVM by editing the org.gradle.jvmargs property in your gradle.properties file. We recommend this be set to at least 4GB:

org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8

Set Java 1.8

Set Java 1.8 in your app level build.gradle or build.gradle.kts file (typically app/build.gradle or app/build.gradle.kts):

android {
   
   // ...

   compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
   }

   // Only for Kotlin projects
   kotlinOptions {
       jvmTarget = JavaVersion.VERSION_1_8.toString()
   }
}

Add permissions

To use the In-App Voice features, add audio permissions using the following procedure:

Add the required permissions to the AndroidManifest.xml file:

<manifest ...>
	<uses-permission android:name="android.permission.INTERNET" />
	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
	<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
	<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
	<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
	<uses-permission android:name="android.permission.RECORD_AUDIO" />
	<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
</manifest>

Runtime Permissions

For devices running Android version 6.0 Marshmallow (API level 23) or higher, you should request the RECORD_AUDIO permission at runtime:

// this is the current activity
val callsPermissions = arrayOf(Manifest.permission.RECORD_AUDIO)
ActivityCompat.requestPermissions(this, callsPermissions, 123)

For devices running Android version 12 (API level 31) or higher, you should also request the READ_PHONE_STATE permission at runtime:

// this is the current activity
val callsPermissions = arrayOf(Manifest.permission.RECORD_AUDIO, Manifest.permission.READ_PHONE_STATE)
ActivityCompat.requestPermissions(this, callsPermissions, 123)

Read more about requesting runtime permissions on Android here.

ProGuard Rules

Optionally, if you are using ProGuard you will need to configure the tool to skip over the Vonage Client SDK. Shrinking and/or obfuscating the Vonage Client SDK is not recommended and could cause conflicts with other libraries. The recommended ProGuard configuration is:

-keep class org.webrtc.**  { *; }
-keep class org.vonage.**  { *; }
-keep class com.vonage.**  { *; }

The configuration above forces the Vonage Client SDK source code to be kept as is, while allowing the rest of the app to be shrunk. The compiler automatically performs a set of optimizations by default, but it is possible to enable additional optimizations which may require you to include additional ProGuard rules to avoid runtime issues. You can do so by adding the following in the project’s gradle properties file:

android.enableR8.fullMode=true

For more on information on optomizing your Android app, please refer to the official Android documentation.

Using the Client SDK in your app

Now you have installed the Client SDK and requested audio permissions you can now start using it.

Create a Session

Sessions are a live communication stream between the Client SDK and the Vonage servers. Create a VoiceClient object, then create a session with a user JWT token.

var client = VoiceClient(this.application.applicationContext)

client.createSession("JWT_TOKEN") { error, sessionId ->
    ...     
}

If the session creation is successful, you will receive a session ID.

Session Status

If there are any errors with the session after it has been successfully created, you will receive them on the SessionErrorListener on the VoiceClient object.

client.setSessionErrorListener { reason ->
    //Reason for error
}

Conclusion

You added the Client SDK to your Android app, and created a session. You can now use the VoiceClient client in your app, and use the Client SDK functionality.