Let's integrate our SDK in few minutes
#
Quick Start#
Audio/Video Call SDKs for AndroidWith 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#
RequirementsThe 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 Keycaution
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: Sign up for a MirrorFly Account
Step 2: Log into your Account
Step 3: Get the License key from the application Info
’ section
#
Integrate the Call SDKStep 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
Step 3: Add the following dependencies in the app/build.gradle file.
Step 4: Add the below line in the gradle.properties file, to avoid imported library conflicts.
Step 5: Open the AndroidManifest.xml and add below permissions.
#
Initialize Chat SDKTo start using the sdk, there is a need for some basic requirements before proceeding with the initialization process. Thus, the ChatSDK builder class is used to provide the necessary data to the SDK. In your Application
class, inside the onCreate() method use the below ChatSDK Builder to provide the necessary data.
- Java
- Kotlin
#
Chat Builder Function DescriptionFunction | 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.
#
Registrationcaution
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 theFCM_TOKEN
,FORCE_REGISTER
,USER_TYPE
andLIST<METADATA>
as an optional param and pass it across.
- Java
- Kotlin
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 |
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 ServerOnce 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 EventsOnce the ChatConnectionListener
has been set, you will be able to receive the connection status in the callback method as mentioned below.
- Java
- Kotlin
Argument | Type | Description |
---|---|---|
CALLBACK | ChatConnectionListener | callback listener for chat connection |
#
TerminologySome 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 SDKIn 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
Note:
setCallNameHelper
is optional, if it is not configured then user name will be empty in theincomming
andongoing
call notification. Note:sendCallMessage
method is used to send initial calling payload to the callee
#
Setup your call activityCall UI Activity should be defined like below in your manifest
You need to call the below method on your call activityonCreate()
to configure the call activity.
- Java
- Kotlin
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
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
#
Make a callCall 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 befalse
and error message will be given in callback.
#
Required runtime permissionsFor audio call, we need a below permissions:
You can use the below method to check audio call permissions:
- Java
- Kotlin
From Android 12, ensure that
android.permission.BLUETOOTH_CONNECT
andandroid.permission.READ_PHONE_STATE
runtime permissions are granted for your app for seameless audio routing and gsm call handling. If theandroid.permission.BLUETOOTH_CONNECT
permission is not granted, call audio will not be routed to BT Headset even though it is connected. If theandroid.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.
You can use the below method to check call notification permission:
- Java
- Kotlin
#
Make a voice callMake 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
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 callWhenever 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 callWhenever 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
#
Decline the callWhenever 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
#
Disconnect the ongoing callWhenever 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