Let's integrate our SDK in few minutes

Quick Start

Download SDK Files

Download

warning

MirrorFly Chat SDK V1 is no longer supported as a new version is released. Check out our latest Chat SDK V2 here.

To migrate from MirrorFly Chat SDK from V1 to V2 please follow the Migration guide steps.

Audio/Video Call SDKs for Android

With CONTUS MirrorFly Call SDK for Android, you can easily add real-time call features to your client app within 30 minutes.

Through our client SDK, you can initialize and configure call into your app with minimal efforts.

Note : If you're looking for the fastest way to build your app's UI with MirrorFly Call SDKs, you can use our sample apps. To get our sample apps,

click here

Integrate the Call SDK

Requirements

The requirements for call SDK for Android are:

• Android Lollipop 5.0 (API Level 21) or above
• Java 7 or higher
• Gradle 4.1.0 or higher

Things To Be Noted Before You Get Started

SDK License Key

caution

Skip this step if you are already having your license key.

To integrate MirrorFly Call SDK into your app, you will need a SDK License Key. The MirrorFly server will use this license key to authenticate the SDK in your application.

To get the License Key,

Step 1: Register here to get a MirrorFly User account. Registration is subject to verification and would take up to 24 hours.

Step 2: Login to your Account

Step 3: Get the License key from the application Info’ section

Step 4: Download the Android SDK

Getting Started

The SDK is already compiled into an AAR file. To use the SDK, the below AAR file has to be imported into the project. To start integrating the SDK's, follow the below steps. If you already integrated the chat sdk initialization only takes adding few additional changes to chat sdk. Call sdk needs kotlin support in your project.

Step 1: Create a new project or Open an existing project in Android Studio

Step 2: Add the following libraries in app/libs folder in the project

• appbase.aar
• flycommons.aar
• flynetwork.aar
• flydatabase.aar
• videocompression.aar
• xmpp.aar
• flywebrtc.aar

Step 3: Add the below code in the app/build.gradle file.

plugins {

...

id 'kotlin-android'

id 'kotlin-kapt'

}

android {

compileOptions {

sourceCompatibility JavaVersion.VERSION_1_8

targetCompatibility JavaVersion.VERSION_1_8

}

kotlinOptions {

jvmTarget = '1.8'

}

packagingOptions {

exclude 'META-INF/AL2.0'

exclude 'META-INF/DEPENDENCIES'

exclude 'META-INF/LICENSE'

exclude 'META-INF/LICENSE.txt'

exclude 'META-INF/license.txt'

exclude 'META-INF/NOTICE'

exclude 'META-INF/NOTICE.txt'

exclude 'META-INF/notice.txt'

exclude 'META-INF/ASL2.0'

exclude 'META-INF/LGPL2.1'

exclude("META-INF/*.kotlin_module")

}

}

Step 4: Add the following dependencies in the app/build.gradle file.

dependencies {

... // your app dependencies

implementation files('libs/appbase.aar')

implementation files('libs/flycommons.aar')

implementation files('libs/flynetwork.aar')

implementation files('libs/flydatabase.aar')

implementation files('libs/videocompression.aar')

implementation files('libs/xmpp.aar')

implementation files('libs/flywebrtc.aar')

}

Step 5: Add the below dependencies required by the SDK in the app/build.gradle file.

dependencies {

... // your app dependencies

configurations {

all {

exclude group: 'org.json', module: 'json'

exclude group: 'xpp3', module: 'xpp3'

}

}

//For lifecycle listener

implementation 'android.arch.lifecycle:extensions:1.1.1'

annotationProcessor 'android.arch.lifecycle:compiler:1.1.1'

//For GreenDao

implementation 'de.greenrobot:greendao:2.1.0'

//For gson parsing

implementation 'com.google.code.gson:gson:2.8.1'

//for smack implementation

implementation ('org.igniterealtime.smack:smack-android:4.4.6')

implementation ('org.igniterealtime.smack:smack-tcp:4.4.6')

implementation 'org.igniterealtime.smack:smack-im:4.4.6'

implementation 'org.igniterealtime.smack:smack-extensions:4.4.6'

implementation 'org.igniterealtime.smack:smack-sasl-provided:4.4.6'

implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'

implementation 'androidx.multidex:multidex:2.0.1'

implementation 'com.google.android.gms:play-services-location:17.0.0'

//Dagger Dependencies

api 'com.google.dagger:dagger:2.40.5'

kapt 'com.google.dagger:dagger-compiler:2.40.5'

api 'com.google.dagger:dagger-android:2.40.5'

api 'com.google.dagger:dagger-android-support:2.40.5'

kapt 'com.google.dagger:dagger-android-processor:2.40.5'

//coroutines

implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.3'

implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.3.3'

//apicalls

implementation 'com.squareup.retrofit2:retrofit:2.6.1'

implementation 'com.squareup.retrofit2:converter-gson:2.6.1'

implementation 'com.squareup.okhttp3:okhttp:4.2.0'

implementation 'com.jakewharton.retrofit:retrofit2-kotlin-coroutines-adapter:0.9.2'

//stetho interceptor

implementation 'com.facebook.stetho:stetho-okhttp3:1.3.1'

//okhttp interceptor

implementation 'com.squareup.okhttp3:logging-interceptor:3.14.3'

//shared preference encryption

implementation 'androidx.security:security-crypto:1.1.0-alpha03'

//Socket - versions.gradle

implementation 'com.github.nkzawa:socket.io-client:0.6.0'

//Google - versions.gradle

implementation 'org.webrtc:google-webrtc:1.0.32006'

implementation 'androidx.core:core-ktx:+'

implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.4.31'

implementation 'androidx.media:media:1.0.0'

//room database

implementation 'androidx.room:room-runtime:2.2.5'

kapt 'androidx.room:room-compiler:2.2.5'

implementation "androidx.room:room-ktx:2.2.5"

// Lifecycle

implementation 'androidx.lifecycle:lifecycle-extensions:2.2.0'

kapt 'androidx.lifecycle:lifecycle-compiler:2.2.0'

}

Step 6: Add the below line in the gradle.properties file, to avoid imported library conflicts.

android.enableJetifier=true

Step 7: Add the below line in the setting.gradle file, To resolve webrtc dependencies.

dependencyResolutionManagement {

repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

repositories {

google()

mavenCentral()

jcenter()

}

}

Step 8: Open the AndroidManifest.xml and add below permissions.

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

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

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

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

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

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

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

Configure in app/build.gradle file

You can copy the license key from the 'Overview’ section in the Console dashboard.

buildTypes {

debug {

buildConfigField 'String', 'SDK_BASE_URL', '"https://api-preprod-sandbox.mirrorfly.com/api/v1/"'

buildConfigField 'String', 'LICENSE', '"xxxxxxxxxxxxxxxxxxxxxxxxx"'

buildConfigField 'String', 'WEB_CHAT_LOGIN', '"https://webchat-preprod-sandbox.mirrorfly.com/"'

buildConfigField "String", "SUPPORT_MAIL", '"contussupport@gmail.com"'

}

}

Initialize Data for Calls

To start using the call sdk, there are few data that were critical for the Calls SDK to function properly. For which we make use of the ChatSDK builder class to provide data to Calls SDK. In your Application class, inside the onCreate() method use the below ChatSDK Builder to provide the necessary data. An example can be found below.

Java

//For chat logging

LogMessage.enableDebugLogging(BuildConfig.DEBUG);

ChatSDK.Builder()

.setDomainBaseUrl(BuildConfig.SDK_BASE_URL)

.setLicenseKey(BuildConfig.LICENSE)

.setIsTrialLicenceKey(true)

.build();

Kotlin

//For chat logging

LogMessage.enableDebugLogging(BuildConfig.DEBUG)

ChatSDK.Builder()

.setDomainBaseUrl(BuildConfig.SDK_BASE_URL)

.setLicenseKey(BuildConfig.LICENSE)

.setIsTrialLicenceKey(true)

.build()

Chat Builder Function Description

Function	Parameter Type	Description
setDomainBaseUrl	String	Url is provided to make API calls
setLicenseKey	String	License key is required to proceed with registration
setIsTrialLicenceKey	boolean	If the provided license key is for trial version, display the text as ‘true’ else ‘false’
build	n/a	Initializes the chat configuration

caution

The base URL must have the Http/Https protocol which must be closed with a ‘slash (/)’, if not an exception - a bug message will pop up.

Registration

caution

Skip this step if you are already completed the Registration in your application.

The below method to register a user in sandbox Live mode based on setIsTrialLicenceKey provided.

info

Unless you log out the session, make a note that should never call the registration method more than once in an application

Note: While registration, the below registerUser method will accept the FCM_TOKEN,USER_TYPE and FORCE_REGISTER as an optional param and pass it across.

Java

FlyCore.registerUser(USER_IDENTIFIER, (isSuccess, throwable, data ) -> {

if(isSuccess) {

Boolean isNewUser = (Boolean) data.get("is_new_user");

JSONObject responseObject = (JSONObject) data.get("data");

// Get Username and password from the object

} else {

// Register user failed print throwable to find the exception details.

}

});

Kotlin

FlyCore.registerUser(USER_IDENTIFIER) { isSuccess, throwable, data ->

if(isSuccess) {

val isNewUser = data["is_new_user"] as Boolean

val responseObject = data.get("data") as JSONObject

// Get Username and password from the object

} else {

// Register user failed print throwable to find the exception details.

}

}

Argument	Type	Description
USER_IDENTIFIER	String	A unique Id to Register the User. We accept only the AlphaNumeric String
FCM_TOKEN	String	A registration token that is generated by FCM SDK for the user's app instance to send message for free
FORCE_REGISTER	boolean	default value true provide true to force the logout of the old session If the registered user has reached the maximum no of multi-sessions or provide false to allow registration till the maximum no of multi-sessions
USER_TYPE	String	type of the user
CALLBACK	FlyCallback	FlyCallback is used as a callback, implemented and expressed as lambda expression for easy reading

caution

If FORCE_REGISTER is false and it reached the maximum no of multi-sessions then registration will not succeed it will throw a 405 exception, Either FORCE_REGISTER should be true or one of the existing session need to be logged out to continue registration.

Connect to the Chat Server

caution

Skip this step if you are already connected to the Chat server in your application.

In order to send messages using the Chat SDK, at first you need to establish the connection to the server. SDK provides methods for initialize the chat connection.

Note: The ChatManager.connect() method should be called only once in an application. SDK will handle the chat server connection and disconnection automatically.

Java

ChatManager.connect(new ChatConnectionListener() {

@Override

public void onConnected() {

// Write your success logic here to navigate Profile Page or

// To Start your one-one chat with your friends

}

@Override

public void onDisconnected() {

// Connection disconnected

//No need implementations

}

@Override

public void onConnectionNotAuthorized() {

// Connection Not authorized

//No need implementations

}

});

Kotlin

ChatManager.connect(object : ChatConnectionListener {

override fun onConnected() {

// Write your success logic here to navigate Profile Page or

// To Start your one-one chat with your friends

}

override fun onDisconnected() {

// Connection disconnected

//No need implementations

}

override fun onConnectionNotAuthorized() {

// Connection Not authorized

//No need implementations

}

})

Argument	Type	Description
CALLBACK	ChatConnectionListener	callback listener for chat connection

Terminology

Some of the most common terminologies used in Chat SDK with description

keyword	Explanation
userID/userBareID	Unique ID assigned for each user Ex: 12345678 (any alphanumeric). The below characters is not allowed in userId: U+0022 (") U+0026 (&) U+0027 (') U+002F (/) U+003A (:) U+003C (<) U+003E (>) U+0040 (@) userID should follow below specification: https://xmpp.org/extensions/xep-0106.html
userJid (or) JID	userID+@+domain of the chat server Ex. 12345678@xmpp.chatsystem.dev.contus.us
groupID/groupBareID	Unique ID assigned for each group Ex: group123456 (any alphanumeric). GroupJID = groupID +@mix.+domain of the chat server Ex: group123456@mix.xmpp.mirrorfly.dev.contus.us`

info

SDK will have built-in functions to prepare the JID, Group JID, and more.

Initialize Call SDK

In your Application class, inside the onCreate() method add the below lines:

Argument	Type	Description
CALL_UI_ACTIVITY	Class	Activity which needs to be invoked during incoming call. when a incoming call is received Call sdk will start this activity with the call details

Java

@Override

public void onCreate() {

super.onCreate();

//Initialize call manager

CallManager.init(this);

//set your call activity

CallManager.setCallActivityClass(CALL_UI_ACTIVITY.class);

CallManager.setMissedCallListener((isOneToOneCall, userJid, groupId, callType, userList) -> {

//show missed call notification

});

CallManager.setCallHelper(new CallHelper() {

@NonNull

@Override

public String getNotificationContent(@NonNull String callDirection) {

return CallNotificationHelper.getNotificationMessage();

}

@Override

public void sendCallMessage(@NotNull GroupCallDetails details, @NotNull List<String> users, @NotNull List<String> invitedUsers) {

CallMessenger.sendCallMessage(details, users, invitedUsers);

}

});

CallManager.setCallNameHelper(new CallNameHelper() {

@NonNull

@Override

public String getDisplayName(@NonNull String jid) {

return ContactManager.getDisplayName(jid);

}

});

}

Kotlin

@Override

public void onCreate() {

super.onCreate();

//Initialize call manager

CallManager.init(this)

//set your call activity

CallManager.setCallActivityClass(CALL_UI_ACTIVITY::class.java)

CallManager.setMissedCallListener(object : MissedCallListener {

override fun onMissedCall(isOneToOneCall: Boolean, userJid: String, groupId: String?, callType: String, userList: ArrayList<String>) {

//show missed call notification

}

})

CallManager.setCallHelper(object : CallHelper {

override fun getNotificationContent(callDirection: String): String {

return CallNotificationHelper.getNotificationMessage()

}

override fun sendCallMessage(details: GroupCallDetails, users: List<String>, invitedUsers: List<String>) {

CallMessenger.sendCallMessage(details, users, invitedUsers)

}

})

CallManager.setCallNameHelper(object : CallNameHelper {

override fun getDisplayName(jid: String): String {

return ContactManager.getDisplayName(jid)

}

})

}

Note: setCallNameHelper is optional, if it is not configured then user name will be empty in the incomming and ongoing call notification. Note: sendCallMessage method is used to send initial calling payload to the callee

Setup your call activity

Call UI Activity should be defined like below in your manifest

<activity

android:name="YOUR_CALL_ACTIVITY"

android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"

android:excludeFromRecents="true"

android:launchMode="singleTask"

android:resizeableActivity="false"

android:screenOrientation="portrait"

android:supportsPictureInPicture="true"

android:showOnLockScreen="true"

android:turnScreenOn="true"

android:taskAffinity="call.video"

tools:targetApi="o_mr1" />

You need to call the below method on your call activityonCreate() to configure the call activity.

Java

CallManager.configureCallActivity(ACTIVITY);

Kotlin

CallManager.configureCallActivity(ACTIVITY)

Argument	Type	Description
ACTIVITY	Activity	instance of the call activity

You need to call the below method on onStart() from your call activity to notify the call sdk to remove the ongoing call notification.

Java

CallManager.bindCallService();

Kotlin

CallManager.bindCallService()

You need to call the below method on onStop() from your call activity to notify the call sdk to show the ongoing call notification.

Java

CallManager.unbindCallService();

Kotlin

CallManager.unbindCallService()

Make a call

Call feature is essential for the modern day communication. Call sdk allows users to make a one to one audio/video call with the another sdk user.

Note: You need to check the required runtime permissions before calling call sdk methods. if required permissions are not available isSuccess will be false and error message will be given in callback.

Required runtime permissions

For audio call, we need a below permissions:

Manifest.permission.RECORD_AUDIO

Manifest.permission.READ_PHONE_STATE

You can use the below method to check audio call permissions:

Java

CallManager.isAudioCallPermissionsGranted();

Kotlin

CallManager.isAudioCallPermissionsGranted()

From Android 12, ensure that android.permission.BLUETOOTH_CONNECT and android.permission.READ_PHONE_STATE runtime permissions are granted for your app for seameless audio routing and gsm call handling. If the android.permission.BLUETOOTH_CONNECTpermission is not granted, call audio will not be routed to BT Headset even though it is connected. If the android.permission.READ_PHONE_STATE permission is not granted, gsm call related functionalities will not work in sdk.

Note: From Android 13, CallSDK need below permission to show ongoing call notification.

Manifest.permission.POST_NOTIFICATIONS

You can use the below method to check call notification permission:

Java

CallManager.isNotificationPermissionsGranted();

Kotlin

CallManager.isNotificationPermissionsGranted()

Make a voice call

Make voice call feature allows users to make a one to one audio call with the another sdk user. You can make a voice call using the below method.

Java

CallManager.makeVoiceCall("TO_JID", (isSuccess, message) -> {

});

Kotlin

CallManager.makeVoiceCall("TO_JID", object : CallActionListener{

override fun onResponse(isSuccess: Boolean, message: String) {

}

})

Argument	Type	Description
TO_JID	String	jid of the call receiver
CALLBACK	CallActionListener	callback to observe the action status

caution

If one to one call feature unavailable for your plan then it will throw 403 exception.

Receive a call

Whenever you receive the audio call from the another sdk user, call sdk will show notification if device android version is greater than or equal to Android 10 (API level 29), otherwise the activity which you set using the CallManager.setCallActivityClass() method during call sdk initialisation will be started with the call details. sample call ui will be available for quick integration.

caution

Please don't forget to set activity class for call sdk using CallManager.setCallActivityClass().

Answer the call

Whenever you receive the audio call from the another sdk user, depending upon the android version, you activity may be started so whenever user presses accept button from your call UI , you need to call the below sdk method to answer the call and notify the caller.

Note: if the required permissions are not available then call be will be automatically declined even though you answered a call

Argument	Type	Description
CALLBACK	CallActionListener	callback to observe the action status

Java

CallManager.answerCall((isSuccess, message) -> {

});

Kotlin

CallManager.answerCall(object : CallActionListener {

override fun onResponse(isSuccess: Boolean, message: String) {

}

})

Decline the call

Whenever you receive the audio call from the another sdk user, depending upon the android version, you activity may be started so whenever user presses decline button from your call UI , you need to call the below sdk method to decline the call and notify the caller.

Java

CallManager.declineCall();

Kotlin

CallManager.declineCall()

Disconnect the ongoing call

Whenever you make the audio call to the another sdk user and you just want to disconnect the call before getting connected or if you want to just disconnect a connected call after the end of conversation, whenever user presses the disconnect button from your call UI , you need to call the below sdk method to disconnect the call and notify the caller.

Note: The below method accepts CallActionListener as a optional paramter. you can pass the listener to get disconnect success callback

Java

CallManager.disconnectCall();

Kotlin

CallManager.disconnectCall()