In order to use the features of the Chat SDK in your client apps, a
SendBird instance must be initiated in each client app through user authentication with Sendbird server. The instance communicates and interacts with the server using an authenticated user account, and is allowed to use the Chat SDK's features. This page explains how to authenticate your user with the server.
To use our chat features, you must initialize a
SendBird instance by passing the
APP_ID of your Sendbird application as an argument to a parameter in the
SendBird.init() method. The
SendBird.init() must be called once in the
onCreate() method of
Application instance of your client app.
Note: The code above will be deprecated soon. Use the new code with or without local caching instead.
With local caching, two new parameters have been added to the
SendBird.init() method, which are
InitResultHandler(). The following will show how you can initialize the Chat SDK with or without local caching.
useLocalCaching determines whether the client app will use the local storage through Sendbird Chat SDK or not. If you want to build a client app with our local caching functionalities, set the
useLocalCaching to true.
InitResultHandler() gets the initialization status through different event handlers. The
onMigrationStarted() is called when there's an upgrade in the local database. Meanwhile, the
onInitSucceeded() informs the client app whether the initialization is successful or not.
Note: If you are not using Local caching, the
InitResultHandler()won't be called.
onInitFailed() is called when you set the
useLocalCaching to true, the SDK will operate normally and change the value of the
useLocalCaching to false. If you still wish to use the local caching, clear the database using the
SendBird.clearCachedData(getApplicationContext(), CompletionHandler); and try the
SendBird.init() again with the
useLocalCaching set to true.
Note: Under this circumstance, the SDK will automatically change the value to false. When the
useLocalCachingis set to false, you can use all the local caching functionalities except offline write.
By default, Sendbird server can authenticate a user just by a unique user ID. Then the server queries the database to check for a match upon the request for connection. If no matching user ID is found, the server creates a new user account with the user ID. The ID must be unique within a Sendbird application to be distinguished from others, such as a hashed email address or phone number in your service. This authentication procedure is useful when in development or if your service doesn't require additional security.
As local caching has been introduced in the Chat SDK, the connection codes may require the result of the
If you initialize the Chat SDK with local caching, you need to get a callback from the
InitResultHandler in order to connect. When the user is confirmed without any error, the SDK will proceed to connect with Sendbird server.
When one of the error codes 400300, 400301, 400302, and 400310 returns, you should clear all user data cached in the local storage and then reconnect to Sendbird server. Except when these errors occur, the client app can still draw a channel list view and a chat view in the 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, the
ConnectionHandler.onReconnectSucceeded() will be called.
Note: The user object can be passed in a callback only when the client app has succeeded in making the connection with the same user ID in the past. Go to the Event handler page to learn more about the usages of the Chat SDK's handlers and callbacks.
For the Chat SDK that doesn'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 Sendbird server.
When an error occurs, the SDK must attempt to reconnect again.
Note: You must receive the result of the
InitResultHandler()before calling the
connect(). Any methods can be called once the user is connected to Sendbird server. Otherwise, an
ERR_CONNECTION_REQUIRED (800101)error would return.
Using Chat Platform API, you can create a user along with their own access token, or 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
SendBird.connect() method which is used for logging in.
- Using the Chat API, create a Sendbird user account with the information submitted when a user signs up or in to your service.
- Save the user ID along with the issued access token to your persistent storage which is securely managed.
- When the user attempts to log in to the Sendbird application, load the user ID and access token from the storage, and then pass them to the
- Periodically replacing the user's access token is recommended to protect the account.
Note: Go to Settings > Application > Security > Access token permission on your dashboard to prevent users without an access token from logging in to your Sendbird application or restrict their access to read and write messages.
Note: For security reasons, you can also use a session token when a user logs in to Sendbird server instead of an access token. Go to the Access token vs. Session token section from the Chat API guide to learn more.
A user should be disconnected from 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 the
SendBird.addConnectionHandler() 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
GroupChannel.getChannel() is called, are also flushed.
Note: By default, most of the data related to users, channels, and messages are internally cached in the
SendBirdinstance of a user's client app, which are retrieved by the corresponding query instances or received through the event handlers.
updateCurrentUserInfo() method, you can update a user's nickname and profile image with a URL.
Or, you can upload a profile image directly using
Note: A user's profile image can be a
PNG(.png) file of up to 25 MB.