Let's integrate our SDK in few minutes

Quick Start#

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

Getting Started#

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
targetSdkVersion,compileSdk 34 or above

Note : If you're utilizing Call SDK version 7.11.4 or higher, it's necessary to adjust the target SDK version to 34. This is due to the migration of Call SDK to Android 14.

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

license-key

Integrate the Call SDK#

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

Step 2: If using Gradle 6.8 or higher, add the following code to your settings.gradle file. If using Gradle 6.7 or lower, add the following code to your root build.gradle file. See this release note to learn more about updates to Gradle.

Gradle 6.8 or higher
Gradle 6.7 or lower

dependencyResolutionManagement {
    repositories {
        jcenter()
        maven {
            url "https://repo.mirrorfly.com/release"
        }
    }
}

Jcenter

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

dependencies {
    implementation 'com.mirrorfly.sdk:mirrorflysdk:7.12.1'
 }

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

android.enableJetifier=true

Step 5: Add required runtime permissions for calls click here

Initialize SDK For Calls#

To start using the sdk, there is a need for some basic requirements before proceeding with the initialization process. In your Application class, inside the onCreate() method use the below method from ChatManager to provide the necessary data.

configscyAar

Java
Kotlin

ChatManager.initializeSDK("LICENSE_KEY", (isSuccess, throwable, data) -> {
            if(isSuccess){
                Log.d("TAG", "initializeSDK success ");
            }else{
                Log.d("TAG", "initializeSDK failed with reason "+data.get("message"));
            }
        });

ChatManager initializeSDK Function Description#

Function	Parameter Type	Description
licenseKey	`String`	License key is required to proceed with registration
CALLBACK	`FlyCallback`	`FlyCallback` is implemented and expressed as lambda expression

Add MyApplication#

Add the created MyApplication to AndroidManifest.xml.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.uikitapplication">

    <application
        android:name=".MyApplication"  // Add this line.
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                ...
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

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, FORCE_REGISTER, USER_TYPE and LIST<METADATA> as an optional param and pass it across.

Java
Kotlin

  FlyCore.registerUser(USER_IDENTIFIER, (isSuccess, throwable, data ) -> {
        if(isSuccess) {
            Boolean isNewUser = (Boolean) data.get("is_new_user");
            String userJid = (String) data.get("userJid");
            JSONObject responseObject = (JSONObject) data.get("data");
            String username = responseObject.getString("username");
            String password = responseObject.getString("password");
        } else {
           // Register user failed print throwable to find the exception details.
        }
   });

Argument	Type	Description
USER_IDENTIFIER	`String`	Unique Id to Register the User. SDK only accepts the AlphaNumeric String, hyphens(-) and underscores(_)
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
META_DATA	`List<MetaData>`	list of key - value pair of metadata object. `Maximum size is 3`
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#

Once Registration was successful, ChatSDK automatically attempts to connect to the Chat Server and ChatSDK also observe the changes in application lifecycle, and accordingly it will try to connect and disconnect the Chat Server.

Observe Connection Events#

Once the ChatConnectionListener has been set, you will be able to receive the connection status in the callback method as mentioned below.

Java
Kotlin

ChatManager.setConnectionListener(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
    }

    @Override
    public void onConnectionFailed(@NonNull FlyException e) {
        // Connection Not authorized or Unable to establish connection with server
    }

    @Override
    public void onReconnecting() {
        // Automatic reconnection enabled
    }
});

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
Kotlin

@Override
public void onCreate() {
super.onCreate();

//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();
      }

  });

CallManager.setCallNameHelper(new CallNameHelper() {
      @NonNull
      @Override
      public String getDisplayName(@NonNull String jid) {
          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.

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
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
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
Kotlin

CallManager.unbindCallService();

Preparing user jid#

Almost all the sdk methods expect jid as a input parameter, so sdk provides below utility method to prepare the jid. The method prepares the user's jid from the username which we get in the Register response.

Note: The below characters is not allowed in uniqueId: U+0022 (") U+0026 (&) U+0027 (') U+002F (/) U+003A (:) U+003C (<) U+003E (>) U+0040 (@).

Argument	Type	Description
USER_NAME	String	unique username for preparing JID

Java
Kotlin

FlyUtils.getJid(USER_NAME)

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.

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
Kotlin

CallManager.makeVoiceCall("TO_JID", (isSuccess, flyException) -> {
            if(isSuccess){
                 //SDK will take care of presenting the Call UI. It will present the activity that is passed using the method `CallManager.setCallActivityClass()`
                Log.d("MakeCall","call success");
            }else{
                if(flyException!=null){
                    String errorMessage = flyException.getMessage();
                    Log.d("MakeCall","Call failed with error: "+errorMessage);
                    //toast error message
                }
            }
        });

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
Kotlin

  CallManager.answerCall((isSuccess, flyException) -> {
            if(isSuccess){
                Log.d("AnswerCall","call answered success");
            }else{
                if(flyException!=null){
                    String errorMessage = flyException.getMessage();
                    Log.d("AnswerCall","Call answered failed with error: "+errorMessage);
                    //toast error message
                }
            }
        });

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
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
Kotlin

CallManager.disconnectCall();