SendBird instance should be initiated in each client app through user authentication with Sendbird server. The instance communicates and interacts with the server based on 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.
Initialize the Chat SDK with APP_ID
The initialization code has been updated. Refer to the new code below.
To use our chat features, you should initialize a
SendBird instance by passing the
APP_ID of your Sendbird application as an argument to a parameter in the
new SendBird(). The
new SendBird() must be called once across your client app. Typically, initialization is implemented in the user login view.
With local caching, a new optional parameter has been added to the
SendBird() method, which is
localCacheEnabled determines whether the client app will use the local storage through Sendbird Chat SDK or not. Because this is optional, the default value will be false. If you want to build a client app with our local caching functionalities, set the
localCacheEnabled to true.
localCacheEnabled is set to true, different data stores are utilized depending on the app environment. It employees indexedDB in a browser environment while using AsyncStorage in a React Native environment. For those who are using local caching in React Native, call
connect() to set AsyncStorage as the database storage.
Note: If indexedDBstore isn't available in the browser or you don't set the AsyncStorage as the database storage, the Chat SDK will fall back to use the device's memory, not the local cache, even if
localCacheEnabledis set to true. When this happens, a warning will show in the Logger to notify the situation.
Connect to Sendbird server with a user ID
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 should 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.
If you are using local caching, the connection process will differ depending on the callback. 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.
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. Because the
sb.connect()now requires a callback, use the
sb.currentUserto fetch the user data. Go to the Event handler page to learn more about the usages of the Chat SDK's handlers and callbacks.
Note: You must connect to Sendbird server before calling any methods through the Chat SDK (apart from initializing your
SendBirdinstance). If you attempt to call a method without connecting, a
CONNECTION_REQUIRED (800101)error would be returned.
Connect to Sendbird server with a user ID and a token
When a user logs in to a client app using the Chat SDK, you can choose how to authenticate a user. A user authentication can be done with just their own user ID, but also with either an access token or a session token. If any token is issued for a user, it must be provided to Sendbird server each time the user logs in by using the
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
sb.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 a client app, 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: From Settings > Application > Security > Access token permission setting in your dashboard, you are able to prevent users without an access token from logging in to your Sendbird application or restrict their access to read and write messages.
Using a session token
You can also use a session token instead of an access token to authenticate a user. It's a more secure option because session tokens expire after a certain period whereas access tokens don't. Our Chat Platform API guide further explains 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 logs in to a client app using the Chat SDK, a user can be authenticated with a session token. If a user is authenticated with a session token, the Chat SDK connects the user to the Sendbird server and can send data requests to it 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. 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
sb.SessionHandler() instance to refresh the token and pass it back to the SDK so that it can refresh the session again.
sb.SessionHandler()instance must be set before the server connection is requested.
The following code shows how to implement the handler.
Disconnect from Sendbird server
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 types of event handlers in a user's client app registered by the
sb.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
sb.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.
Update user profile
updateCurrentUserInfo() method, you can update a user's nickname and profile image with a URL.
Or, you can upload a profile image directly using the
Note: A user's profile image can be a
PNG(.png) file of up to 5 MB.