Chat / Android
Chat Android v4
Chat Android
Chat
Android
Home
/
Chat
/
Android
/
Application
This is the new Docs for Chat SDK v4 for Android. To see the previous Docs, click here.

Authentication

In order to use the features of the Chat SDK for Android in your client apps, a SendbirdChat instance should be initiated in each client app through user authentication with the Sendbird server. The instance communicates and interacts with the server based on the authenticated user account and is allowed to use the Chat SDK's features. This page explains how to authenticate your user with the server.


Initialize the Chat SDK with APP_ID

To use our chat features, you must initialize the SendbirdChat instance by passing APP_ID of your Sendbird application as an argument to a parameter of the SendbirdChat.init() method. The SendbirdChat.init() method must be called once across your client app. Typically, initialization is implemented in the user login view.

With the implementation of local caching, the useCaching property of the InitParams object has been added. The useCaching parameter determines whether or not the client app will use local storage through Sendbird Chat SDK. Since this is optional, the default value is set to false. If you want to build a client app with our local caching functionalities, set the useCaching parameter to true.

Additionally, InitResultHandler() has been added to the initialization code as shown below. The InitResultHandler() gets the initialization status through different event handlers and informs the client app whether the initialization is successful or not. On the other hand, the onMigrationStarted() is called when the migration for local caching has started.

If you don't use local caching, onMigrationStarted() and onInitFailed(e: SendbirdException) in InitResultHandler() won't be called. You'll only be notified if the initialization was successful when onInitSucceeded() is called.

// When useCaching is set to true.
SendbirdChat.init(
    InitParams(APP_ID, applicationContext, useCaching = true),
    object : InitResultHandler {
        override fun onMigrationStarted() {
            Log.i("Application", "Called when there's an update in Sendbird server.")
        }

        override fun onInitFailed(e: SendbirdException) {
            Log.i("Application", "Called when initialize failed. SDK will still operate properly as if useLocalCaching is set to false.")
        }

        override fun onInitSucceed() {
            Log.i("Application", "Called when initialization is completed.")
        }
    }
)

If the initialization fails when you set useCaching to true, the SDK will operate normally and change the value of useCaching to false. If you still wish to use local caching, clear the database using the SendbirdChat.clearCachedData(applicationContext, CompletionHandler) method and try the initialization again with useCaching set to true.


Connect to the Sendbird server with a user ID

By default, the Sendbird server can authenticate a user with just a unique user ID. Then, the server queries the database to check for a match upon connection request. If no matching user ID is found, the server creates a new user account with the user ID. The ID should be unique within a Sendbird application to be distinguishable from other identifiers such as a hashed email address or a phone number in your service.

While authenticating with just the user ID is convenient in the developing and testing stages of a service, a more secure authentication process using tokens is strongly recommended for most production environments.

Note: Go to the event handler page to learn more about the usages of the Chat SDK's handlers and callbacks.

If you initialize the Chat SDK with local caching, you need to get a callback from InitResultHandler in order to connect. When the user is confirmed without any error, the SDK will proceed to connect with the Sendbird server.

When one of the error codes 400300, 400301, 400302, and 400310 returns, the SDK clears all user data cached in the local storage and tries to reconnect to the Sendbird server. Except when these errors occur, the client app can still draw a channel list view and a chat view in an offline mode using locally cached data. The SDK will receive an user object through a callback and try to reconnect later on. When the connection is made, ConnectionHandler.onReconnectSucceeded() will be called.

// When useCaching is set to true.
SendbirdChat.connect(userId) { user, e ->
    if (user != null) {
        if (e != null) {
            // Proceed in offline mode with the data stored in the local database.
            // Later, connection will be established automatically
            // and can be notified through ConnectionHandler.onReconnectSucceeded().
        } else {
            // Proceed in online mode.
        }
    } else {
        // Handle error.
    }
}

For Chat SDKs that don't use local caching, the connection process remains the same. If the user has ever been connected and their data exists in the local storage, the SDK can be connected to the Sendbird server. When an error occurs, the SDK must attempt to reconnect again.

Note: Apart from initializing the SendbirdChat instance, you should connect to the Sendbird server before calling almost every method through the Chat SDK. If you attempt to call a method without connecting, an ERR_CONNECTION_REQUIRED (800101) error will be returned.


Connect to the Sendbird server with a user ID and a token

For a more secure way of authenticating a user, you can require an authentication token, which can be an access token or a session token, in addition to a unique user ID. Any token issued for a user must be provided to the Sendbird server each time the user logs in by passing the token as an argument to the authToken parameter of the SendbirdChat.connect() method.

Using an access token

Through our Chat Platform API, an access token can be generated when creating a user. You can also issue an access token for an existing user. Once an access token is issued, a user is required to provide the access token in the SendbirdChat.connect() method which is used for logging in.

  1. Using the Chat API, create a Sendbird user account with information submitted when a user signs up or logs in to your service.

  2. Save the user ID along with the issued access token to your persistent storage which is securely managed.

  3. When the user attempts to log in to a client app, load the user ID and access token from the storage, and then pass them to the SendbirdChat.connect() method.

  4. Periodically replacing the user's access token is recommended to protect the account.

Note: From Settings > Application > Security > Access token permission setting on your dashboard, you're able to prevent users without an access token from logging in to your Sendbird application or restrict their access to read and write messages.

// The USER_ID argument below should be unique to your Sendbird application.
SendbirdChat.connect(USER_ID, AUTH_TOKEN) { user, e ->
    if (user != null) {
        if (e != null) {
            // Proceed in offline mode with the data stored in the local database.
            // Later, connection will be made automatically.
            // The connection will be notified through ConnectionHandler.onReconnectSucceeded()
        } else {
            // Proceed in online mode.
        }
    } else {
        // Handle error.
    }
}

For Chat SDKs that don't use local caching, the connection process remains the same. If the user has ever been connected and their data exists in the local storage, the SDK can be connected to the Sendbird server. When an error occurs, the SDK must attempt to reconnect again.

Using a session token

You can also use a session token instead of an access token to authenticate a user. Session tokens are a more secure option because they expire after a certain period whereas access tokens don't. See Chat Platform API guides for further explanation about the difference between access token and session token, how to issue a session token, and how to revoke all session tokens.


Set a session handler

When a user is authenticated with a session token, the Chat SDK connects the user to the Sendbird server and can send data requests to the server for ten minutes as long as the session token hasn't expired or hasn't been revoked.

Upon the user's session expiration, the Chat SDK will refresh the session internally using a SessionHandler. However, if the session token has expired or has been revoked, the Chat SDK can't do so. In that case, the client app needs to implement a SessionHandler instance to refresh the token and pass it back to the SDK so that it can refresh the session again.

Note: A SessionHandler instance must be set before the server connection is requested.

The following code shows how to implement the handler methods.

SendbirdChat.setSessionHandler(
    object : SessionHandler() {
        override fun onSessionTokenRequired(sessionTokenRequester: SessionTokenRequester) {
            // A new session token is required in the SDK to refresh the session.
            // Refresh the session token and pass it onto the SDK through sessionTokenRequester.onSuccess(NEW_TOKEN).
            // If you do not want to refresh the session, pass on a null value through sessionTokenRequester.onSuccess(null).
            // If any error occurred while refreshing the token, let the SDK know about it through sessionTokenRequester.onFail().
        }

        override fun onSessionClosed() {
            // The session refresh has been denied from the app.
            // Client apps should guide the user to a login page to log in again.
        }

        override fun onSessionRefreshed() {
            // This is optional and no action is required.
            // This is called when the session is refreshed.
        }

        override fun onSessionError(sendbirdException: SendbirdException) {
            // This is optional and no action is required.
            // This is called when an error occurs during the session refresh.
        }
    }
)

Disconnect from the Sendbird server

A user can be disconnected from the Sendbird server when they no longer need to receive messages from an online state. However, the user will still receive push notifications for new messages from group channels they've joined.

When disconnected, all event handlers in a user's client app registered by SendbirdChat.addChannelHandler() stop receiving event callbacks from the server. Then, all internally cached data in the client app, such as the channels that are cached when the getChannel() method of OpenChannel or GroupChannel is called, are also flushed.

Note: By default, most of the data related to users, channels, and messages are internally cached in the SendbirdChat instance of a user's client app, which are retrieved by the corresponding query instances or received through the event handlers.

SendbirdChat.disconnect {
    // The current user is disconnected from the Sendbird server.
    // ...
}