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: YourActivityName.this

Registration/Login

1. 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
      }
  });

2. Pre chat Lead Collection

There are 2 ways you can create pre-chat lead collection for your users.

1. Create fields from dashboard

If you wish to use this method, the prechat lead collection will be identical throughout all platform.

You can create the fields from here. After creating the fields, you can use this code in your application:

final ProgressDialog progressDialog = new ProgressDialog(YourActivityName.this);
                progressDialog.setTitle("Logging in..");
                progressDialog.setMessage("Please wait...");
                progressDialog.setCancelable(false);
                progressDialog.show();
                Kommunicate.launchConversationWithPreChat(YourActivityName.this, progressDialog, new KmCallback() {
                    @Override
                    public void onSuccess(Object message) {
                        finish(); 
                        progressDialog.dismiss();
                    }

                    @Override
                    public void onFailure(Object error) {
                        progressDialog.dismiss();

                    }
                });

Replace YourActivityName.this with your own Activity name.

2. 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, password and dropdown. If you are creating fields from dashboard, this method is not required.

Follow these steps to create your own custom fields:

1. Create a list of KmPreChatInputModel which will contain the list of fields which are to be shown to user. Example: Email, Phone number.
2. Pass this list to Kommunicate.launchPrechatWithResult(YourActivityName.this, `<list>`, KmPrechatCallback)
3. KmPrechatCallback will return you the data which user entered in Lead collection.
4. Use this data to create new conversation for the user.

  List<KmPrechatInputModel> inputModelList = new ArrayList<>();

                KmPrechatInputModel emailField = new KmPrechatInputModel();
                emailField.setType(KmPrechatInputModel.KmInputType.EMAIL);
                emailField.setRequired(true);
                emailField.setPlaceholder("Enter email");
                emailField.setValidationRegex(EMAIL_VALIDATION_REGEX); //create static value for email regex
                emailField.setField("Email"); //This will be returned as key
                emailField.setCompositeRequiredField("Phone"); //optional: "Either Ehone or Email is required" if you set another field as composite field

                KmPrechatInputModel nameField = new KmPrechatInputModel();
                nameField.setType(KmPrechatInputModel.KmInputType.TEXT);
                nameField.setPlaceholder("Enter Name");
                nameField.setField("Name");

                KmPrechatInputModel contactField = new KmPrechatInputModel();
                contactField.setType(KmPrechatInputModel.KmInputType.NUMBER);
                contactField.setPlaceholder("Enter Phone number");
                contactField.setValidationRegex(PHONE_NUMBER_VALIDATION_REGEX);
                contactField.setField("Phone");

                KmPrechatInputModel dropdownField = new KmPrechatInputModel();
                dropdownField.setOptions(Arrays.asList("Male", "Female")); //list of options to show
                dropdownField.setPlaceholder("Enter your gender");
                dropdownField.setField("Gender");
                dropdownField.setElement("select"); //element must be "select" for dropdown menu

                inputModelList.add(emailField);
                inputModelList.add(nameField);
                inputModelList.add(contactField);
                inputModelList.add(dropdownField);

                Kommunicate.launchPrechatWithResult(MainActivity.this, inputModelList, new KmPrechatCallback< Map < String, String >>() {
                    @Override
                    public void onReceive(Map < String, String > data, Context context, final ResultReceiver finishActivityReceiver) 

                        Utils.printLog(context, "TestPrechat", 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("Phone"))) {    
                            user.setContactNumber(data.get("Phone"));
                        }
    
                        new KmConversationBuilder(MainActivity.this)
                                .setKmUser(user) //this is important to login the 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(MainActivity.this, "TestPrechat", "Error : " + error);
                    }
                });

Replace YourActivityName.this with your activity name. Search for "testPrechat" in your logchat after entering the values in prechat to see the data.

3. Registered User

If you already have your user's detail, there are 2 ways you can log in the user:

1. When you authenticate the user in your app, then login the user to Kommunicate as well. This method is more effective in terms of performance.

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 you want to get the user details of the logged in user, use this code snippet:

KMUser user = KMUser.getLoggedInUser(context);

2. You can login the user when conversations are created/launched using KmConversationBuilder

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.

Pass 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. Your team will see this data in dashboard.

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);

Check if logged in

You do not need to login the user everytime so you can do a check before logging in the user if the user is already logged in. This method returns a boolean value.

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

Update 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);