Installation

Overview

Kommunicate is live chat and chatbots powered customer support software. Kommunicate allows you to add customizable live chat SDK to your Android apps. It enables you to chat with your app users and customers through a customizable chat interface.

Installing Kommunicate in your Android app is easy and fast. We will walk you through the procedure so you can start answering your support queries within a few minutes.

Android sdk

Add the following in your app's(app level) build.gradle dependency:

dependencies {
//...
implementation 'io.kommunicate.sdk:kommunicateui:2.1.0'
}

NOTE: Kommunicate requires minimum Android SDK 16 or higher. Be sure to check if that is what you are using. You can find the minimum android SDK version in your app's build.gradle file, inside defaultConfig. The field is named as minSdkVersion.

Building with ProGuard

If you are using ProGuard in your application, then add the below rules to your proguard-rules.pro file:

#keep JSON classes                
-keep class * extends com.applozic.mobicommons.json.JsonMarker {
    !static !transient <fields>;
}

-keepclassmembernames class * extends com.applozic.mobicommons.json.JsonParcelableMarker {
    !static !transient <fields>;
}

#GSON Config          
-keepattributes Signature          
-keep class sun.misc.Unsafe { *; }           
-keep class com.google.gson.examples.android.model.** { *; }            
-keep class org.eclipse.paho.client.mqttv3.logging.JSR47Logger { *; } 
-keep class android.support.** { *; }
-keep interface android.support.** { *; }
-dontwarn android.support.v4.**
-keep public class com.google.android.gms.* { public *; }
-dontwarn com.google.android.gms.**
-keep class com.google.gson.** { *; }

Get your APP_ID

Sign up for Kommunicate to get your APP_ID. You will get the APP_ID from the Install section. This APP_ID is used to create/launch conversations.

Initialize SDK

After the Gradle sync is finished with Kommunicate dependency, you can initialize the SDK by calling the below method:

 Kommunicate.init(context, APP_ID);

You can initialize the SDK in onCreate() function of your Activity. Just make sure it is initialized before accessing any method from the Kommuniate SDK. The APP_ID parameter will take the application id(APP_ID) you just acquired.

For the context parameter you can pass the application context using the getApplicationContext() method. However if you are unable to get that, you can also pass the activity context.

Launch conversation

Kommunicate provides KmConversationBuilder class to create and launch conversation directly. This way, you can save the extra steps of authentication, creation, initialization and launch. Below are some examples of how you can customize the builder for launching a single conversation thread.

Visitors

If you would like to launch the conversation directly without making the user entering any details, then use the builder as below:

       new KmConversationBuilder(activityContext)
                   .launchConversation(new KmCallback() {
                        @Override
                        public void onSuccess(Object message) {
                            Log.d("Conversation", "Success : " + message);
                        }

                        @Override
                        public void onFailure(Object error) {
                            Log.d("Conversation", "Failure : " + error);
                        }
                    });

For the activityContext parameter you need to pass the activity context. One way to get it is the YourActivityName.this.

Pre-chat lead collection

If you need the user to fill in details such as name, email and phone number before starting the conversation then launch the conversation with withPreChat flag as true. In this case, you wouldn't need to pass the kmUser details.

A screen would open up for the user asking for the details. Once the user fills the valid details (at least either email or phone number is required), the conversation would be launched. Use the builder as below:

     new KmConversationBuilder(activityContext)
                 .setWithPreChat(true)
                 .launchConversation(new KmCallback() {
                        @Override
                        public void onSuccess(Object message) {
                            Log.d("Conversation", "Success : " + message);
                        }

                        @Override
                        public void onFailure(Object error) {
                            Log.d("Conversation", "Failure : " + error);
                        }
                    });

For the activityContext parameter you need to pass the activity context. One way to get it is the YourActivityName.this.

Following screen will be displayed to user when you add .setWithPreChat(true) as explained above:

Pre-chat-lead-collection-form

Set custom fields in Pre-chat lead collection form

We support adding custom fields in pre-chat lead form, the field types currently supported are email, text, number, and the password.

Use the following code to add the custom fields. The changes required are APP_ID and activityContext, mention your APP_ID and for the activityContext parameter you need to pass the activity context. One way to get it is the YourActivityName.this.


//add fields
inputModelList.add(new KmPrechatInputModel()
    .setField("Email") //This will be the label for the field
    .setType(KmPrechatInputModel.KmInputType.EMAIL) //type
    .setValidationError("Please fill this") //Error displayed if text entered is invalidation
    .setValidationRegex("Some email regex") //Regex to validate text
    .setCompositeRequiredField("Mobile number")); //used to set an option of either of the 2 fileds required. This means that the user will have to enter either email or phone number to proceed

inputModelList.add(new KmPrechatInputModel()
    .setField("Mobile number")
    .setType(KmPrechatInputModel.KmInputType.NUMBER)
    .setValidationError("Please fill this")
    .setValidationRegex("Some number regex"));

inputModelList.add(new KmPrechatInputModel()
    .setField("Password")
    .setType(KmPrechatInputModel.KmInputType.PASSWORD)
    .setValidationError("Please fill this")
    .setValidationRegex("Some regex")
    .setRequired(true)); //This makes this field mandatory

Kommunicate.launchPrechatWithResult(activityContext, inputModelList, new KmPrechatCallback < Map < String, String >> () {
    @Override
    public void onReceive(Map < String, String > data, Context context, final ResultReceiver finishActivityReceiver) {
    
        //data map will receive the "filedName: entered Text" map. You can get the texts and create a KMUser object here. Then call KmConversationBuilder with that user object.
        
        
        Utils.printLog(context, "TestPre", GsonUtils.getJsonFromObject(data, Map.class));

        KMUser user = new KMUser();

        if (!TextUtils.isEmpty(data.get("Email"))) {
            user.setUserId(data.get("Email"));
            user.setEmail(data.get("Email"));
        } else if (!TextUtils.isEmpty(data.get("Mobile number"))) {
            user.setUserId(data.get("Mobile number"));
            user.setContactNumber(data.get("Mobile number"));
        }

        if (!TextUtils.isEmpty(data.get("Password"))) {
            user.setPassword(data.get("Password"));
        }

        new KmConversationBuilder(activityContext)
            .setAppId("YOUR APP ID")
            .setKmUser(user)
            .launchConversation(new KmCallback() {
                @Override
                public void onSuccess(Object message) {
                    finishActivityReceiver.send(KmConstants.PRECHAT_RESULT_CODE, null); //To finish the Prechat activity
                    Log.d("Conversation", "Success : " + message);
                }

                @Override
                public void onFailure(Object error) {
                    finishActivityReceiver.send(1000, null); //To dismiss the loading progress bar
                    Log.d("Conversation", "Failure : " + error);
                }
            });

    }

    @Override
    public void onError(String error) {
        Utils.printLog(activityContext, "TestPre", "Error : " + error);
    }
});

Registered users

If you already have the user details then create a KMUser object using the details and launch the conversation. Use the builder as below to create KMUser object with already existing details:

    KMUser user = new KMUser();
    user.setUserId(<USER_ID>); // Pass a unique key
    user.setPassword(<PASSWORD>); //Optional
    user.setImageLink(<IMAGE_URL>); // Optional
    user.setDisplayName(<DISPLAY_NAME>); //Optional

Then pass this user object to the setKmUser method as below:

new KmConversationBuilder(activityContext)
               .setKmUser(user)
               .launchConversation(new KmCallback() {
                        @Override
                        public void onSuccess(Object message) {
                            Log.d("Conversation", "Success : " + message);
                        }

                        @Override
                        public void onFailure(Object error) {
                            Log.d("Conversation", "Failure : " + error);
                        }
                    });

For the activityContext parameter you need to pass the activity context. One way to get it is the YourActivityName.this.

Parameter description:

Below are the description of the paramters used in the KmConversationBuilder. The parameters are passed as arguments in the methods.

Parameter	Parameter type	Method	Description
activityContext	Activity	new KmConversationBuilder(<activityContext>)	Passed in the constructor. Only Activity Context is accepted. Exception is thrown otherwise
APP_ID	String	setAppId(<APP_ID>)	Ignore if you have already initialized the SDK with APP_ID
kmUser	KMUser	setKmUser(<kmUser>)	If you have user details, you can pass them here. Ignore if you do not have user details.
withPreChat	boolean	setWithPreChat(<withPreChat>)	Pass true if you would like the user to fill the details (such as name, email and phone etc.) before starting the chat. If you already have user details, then you can pass false.
isSingleConversation	boolean	setSingleConversation(<isSingleConversation>)	Pass false if you would like to create new conversation every time a particular user starts a conversation. This is true by default which means only one conversation will open for the user every time the user starts a conversation.
conversationAssignee	String		Optional, Pass either the agentId or botId. The conversation created will skip the routing rules and will be assigned to this agent or bot. You also need to pass the agentId in agentIds array or botId in the botIds array, if you are using the conversationAssignee parameter
clientConversationId	String		Optional, Pass the unique id using which you can recognize the conversation. For e.g If you have a shopping app and each order has its specific conversation, the orderId of the order can be used as a clientConversationId. In this case everyId will have its specific conversation.
conversationTitle	String		Optional, Pass the custom title for a conversation. Use this if you would like to display a custom title instead of the conversation assignee name.

If you want to create a new conversation every time then call .setSingleConversation(false) on the builder. Note that, if you are doing so, the conversation history will not be retained.

For all the parameters used with KmConversationBuilder, refer this section.

Note: If you have a different use-case and would like to customize the conversation creation, user creation and conversation launch, you can explore the docs further.