This section will guide you in authenticating users for the pre-built customizable chat UI in your Android app which can be a Java or Kotlin android project.

SDK Initialization

Prior to sending the first message, the user requires authentication. This is a two-step process.

First, initialize the SDK with the Company Key and App ID as shown below. Contact Khoros Support for your Company Key and App ID if you do not have them.

Even before initializing the SDK, there are a few URLs that can be set by the user. For example:
Initialize the SDK using the Company Key and Application Id:

BrandMessengerUserPreference.getInstance(this).setUrl("your-base-url");
BrandMessengerUserPreference.getInstance(this).setCustomAuthHandlerUrl("auth-handler-url");

These URLs are region based. A list of URLs depending on regions is listed below:

For US region ->
Base URL: brandmessenger.usw2.khoros.com
Auth-handler URL: messaging-auth-us-west-2.prod.aws.lcloud.com

For Europe region ->
Base URL: brandmessenger.euw1.khoros.com
Auth-handler URL: messaging-auth-eu-west-1.prod.aws.lcloud.com

For APAC region ->
Base URL: brandmessenger.apse2.khoros.com
Auth-handler URL: messaging-auth-ap-southeast-2.prod.aws.lcloud.com

The SDK will authenticate with Khoros Auth Handler endpoint during login. Depending on the region, the customer can optionally set the region. Options are "US" or "APAC". Default is "APAC" when not set.

BrandMessengerManager.setRegion(context, "US");

BrandMessengerManager.setRegion(context, "US")

Then, initialize the SDK with one of the two methods below:

BrandMessengerManager.init(this, BrandMessenger.getInstance(this).getCompanyKey(), BrandMessenger.getInstance(this).getApplicationKey());
// Or if you do not have the application key or want to use widget configuration in the SDK
BrandMessengerManager.init(this, "companyKey", "", "widgetId", new KBMCallback() {
                @Override
                public void onSuccess(Object response) {
                    
                }

                @Override
                public void onError(Object error) {

                }
});

BrandMessengerManager.init(context, BrandMessenger.getInstance(context).companyKey, BrandMessenger.getInstance(context).applicationKey)

🚧
Note
User logins are persistent. Once a user is logged in, they won't be required to log in again until and unless they have logged out.

Checking login status

You can check if the user's login status to Brand Messenger using the following:

if (BrandMessengerManager.isAuthenticated(context, false)){
  //do something
}

if (BrandMessenger.isAuthenticated(context, false)) {
    //do something
}

Depending on the integration, the SDK provides various ways of logging in.

Login using access-token

Here is how to log in to Brand Messenger using an access token:

BrandMessengerManager.login(context, "access_token", new KBMLoginHandler() {
    @Override
    public void onSuccess(@NonNull RegistrationResponse registrationResponse, @Nullable Context context) {
    }
    @Override
    public void onFailure(@Nullable RegistrationResponse registrationResponse, @Nullable Exception exception) {
    }
})

BrandMessengerManager.login(context, "access_token", object : KBMLoginHandler {
    override fun onSuccess(registrationResponse: RegistrationResponse, context: Context?) {
    }
    override fun onFailure(registrationResponse: RegistrationResponse?, exception: Exception?) {
    }
}

Login using jwt-token

Generating jwt-token requires API_KEY_ID and API_KEY_SECRET which can be requested by contacting Khoros support.
As this required API_KEY_SECRET, JWT token should be generated on a server instead of being included in the application. The app then can make an API request to fetch the jwt-token and login.

Example of generating jwt-token in java:

final Map<String, Object> customProperties = new HashMap<>();
customProperties.put("userId", userID);
customProperties.put("scope", "appUser");
customProperties.put("platform", "android");
customProperties.put("givenName", loginName);

try {
    String jwtString =
    Jwts.builder()
        .addClaims(customProperties)
        .setHeaderParam("kid", API_KEY_ID)
        .setHeaderParam("typ", "JWT")
        .setIssuedAt(new Date(1420070400000l))
        .signWith(SignatureAlgorithm.HS256, API_KEY_SECRET.getBytes("UTF-8"))
        .compact();

    return jwtString;
} catch (UnsupportedEncodingException e) {
    return "There was an error while generating Smooch JSON Web Token";
}

The jwt-string then is used for login

BrandMessengerManager.loginWithJWT(context, jwtString, userId, new KBMLoginHandler() {
    @Override
    public void onSuccess(@NonNull RegistrationResponse registrationResponse, @Nullable Context context) { }
    @Override
    public void onFailure(@Nullable RegistrationResponse registrationResponse, @Nullable Exception exception) { }
});

In the event that this is a new user, a new user account is created. Existing users are logged in to the application.

To set the user attributes, see Set User Attributes in Android.

You can perform further actions based on the callback methods. In onSuccess you could launch the chat screen for the user, onFailure you could throw some error message based on the exception and the response received in the callback method.

Login as anonymous user

Business may want to let users access chat before logging into their application. The SDK provides login as anonymous users, which can be merged into authenticated users later in the flow.

if (BrandMessengerManager.isAnonymousUserExpired(context)) { // check if a valid anonymous user exists.
    BrandMessengerManager.loginAnonymousUser(context, loginCallback); // login as anonymous user
}
...
/* Login from anonymous user to authenticated access-token user */
BrandMessengerManager.login(context, "access-token", loginCallback); // Login as normal to merge anonymous user's chat history to authenticated user
// or
BrandMessengerManager.login(context, "access-token", false,  loginCallback); // Customer can opt to not merge chat history of an anonymous user

/* Login from anonymous user to authenticated jwt-token user */
BrandMessengerManager.loginWithJWT(context, "jwt", "userId", loginCallback); // Login as normal to merge anonymous user's chat history to authenticated user
// or
BrandMessengerManager.loginWithJWT(context, "jwt", "userId", false, loginCallback); // Customer can opt to not merge chat history of an anonymous user

📘
Note
You need to call the login method only once. However, the method internally checks if the user is logged in, if the user is already logged in you would still receive the RegistrationResponse in onSuccess callback with a "User already logged in" message.

Authentication Delegate

When the auth token expires and SDK's refresh/token API fails, the sdk offers a way to re-establish login auth during operation via a delegate object.

Access-token login authenticationDelegate

BrandMessenger.getInstance(context).setAuthenticationDelegate(new KBMAuthenticationDelegate() {
    @Override
    public void onRefreshFail(KBMAuthenticationDelegateCallback callback) {
        callback.updateToken(<accesstoken>);
    }
});

BrandMessenger.getInstance(context).setAuthenticationDelegate { object: KBMAuthenticationDelegate {
    override fun onRefreshFail(callback: KBMAuthenticationDelegateCallback?) {
        callback?.updateToken(<accesstoken>)
    }

}}

On onRefreshFail, the application can generate a new accesstoken and pass it back in callback.updateToken. The SDK will re-login and continue operation.

JWT-token login authenticationDelegate

BrandMessenger.getInstance(this).setJWTAuthenticationDelegate(this);
@Override
public void onRefreshFail(KBMJWTAuthenticationDelegateCallback callback) {
        callback.updateJWT("jwt", "userId");
}

On onRefreshFail, the application can fetch a new jwt-token and pass it back in callback.updateToken. The SDK will re-login and continue operation.

Authentication and Authorization in Android

SDK Initialization

Checking login status

Login using access-token

Login using jwt-token

Login as anonymous user

Authentication Delegate

Access-token login authenticationDelegate

JWT-token login authenticationDelegate

Alternate Auth flow using Customer iDP