Authentication

Setup

This section is dedicated to authenticate and authorize users to avail support chat in your android app. You can also get instruction to set and update user details such as pre-chat lead collection forms to get user's information before starting the chat, updating user details of an existing user and sending additional details as metadata along with user details.

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.

Registration/Login

1 Logging in as visitors

You might not have the details of all the users coming to chat. You can start the chat with a visitor by calling the below method from the SDK:

  Kommunicate.loginAsVisitor(this, new KMLoginHandler() {
      @Override
      public void onSuccess(RegistrationResponse registrationResponse, Context context) {
            // You can perform operations such as opening the conversation, creating a new conversation or update user details on success
      }

      @Override
      public void onFailure(RegistrationResponse registrationResponse, Exception exception) {
            // You can perform actions such as repeating the login call or throw an error message on failure
      }
  });

Pre-chat 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);
    }
});

2 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.

Register User

You can authorize a user by using the below method:

        KMUser user = new KMUser();
        user.setUserId(<USER_ID>);  // You can set any unique user ID

Post this, call the method as described below:

Kommunicate.login(this, user, new KMLoginHandler() {
      @Override
      public void onSuccess(RegistrationResponse registrationResponse, Context context) {
            // You can perform operations such as opening the conversation, creating a new conversation or update user details on success
      }

      @Override
      public void onFailure(RegistrationResponse registrationResponse, Exception exception) {
            // You can perform actions such as repeating the login call or throw an error message on failure
      }
});

You can also add other optional custom fields such as emails, display name, contact number etc. to the user object:

       user.setDisplayName(<DISPLAY_NAME>); // Pass the display name of the user
       user.setPassword(<PASSWORD>);
       user.setImageLink(<IMAGE_URL>); // Pass the image URL for the user's display image
       user.setContactNumber(<PHONE_NUMBER>); // Pass the user's contact number 
       user.setEmail(<EMAIL_ID>); // Pass the email ID of the user

If at some point, you need to check if the user is logged in, you can use this code snippet:

KMUser.isLoggedIn(context){
      // A check for identifying whether the user is logged in  
}

If you want to get the user details of the logged in user, use this code snippet:

KMUser user = KMUser.getLoggedInUser(context);

Passing on additional details as metadata

Sometimes, you may need to pass additional details for the user apart from the already existing properties of KMUser. You can pass the additional details in metadata of the KMUser object.

Map<String, String> metadata = new HashMap<>();
metadata.put("Department" , "Engineering"); // This is example data. You can set it according to the additional details you want to add
metadata.put("Designation" , "Software Engineer"); // This is example data
metadata.put("Team" , "Device Team"); // This is example data

kmUser.setMetadata(metadata);

Updating the details of logged in users

Once the user has logged in, you can still update some of their properties such as display name, image Url, contact number, metadata, and status.

First, create a KMUser object and set the property you want to update:

KMUser kmUser = new KMUser();
kmUser.setDisplayName(<NEW_DISPLAY_NAME>);
kmUser.setImageLink(<NEW_IMAGE_URL>);

Map<String, String> metadata = new HashMap<>();
metadata.put("Department" , "Mobility"); // This is an example of updating metadata.
metadata.put("Designation" , "Software Engineer II"); // This is an example of updating metadata.

kmUser.setMetadata(metadata);

Then call the below method in a background thread or Async task:

 UserService.getInstance(context).updateLoggedInUser(kmUser);