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. 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
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);
}
});
3. Registered User
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);