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 in
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, you must determine whether you would like to use local caching and configure its settings during SDK initialization. The params contains properties such as
localCacheEncryption. First, set
true so that the SDK can use local cache for its collection instances. Then configure its database settings through
localCacheConfig, which determines how much space in local cache the SDK can use and in which order it should clear cached data when the cached data reaches the limit. As for data protection, you can encrypt and decrypt cached data with a third party library of your choice and implement it during initialization. To learn more, see the Database management and Data encryption sections under Local caching.
localCacheEnabled parameter determines whether or not the client app will use local cache 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
localCacheEnabled parameter to
localCacheEnabled is set to
true, different data stores are utilized depending on the app environment. It employs indexedDB in a browser environment while using AsyncStorage in a React Native environment. For those who are using local caching in React Native, put
useAsyncStorageStore to the
SendbirdChat.init() method as a parameter to set
AsyncStorage as the database storage.
Note: If indexedDBstore isn't available in the browser, 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.
With the launch of Chat SDK v4.0.0., modules have been introduced to Sendbird Chat SDK to reduce the page loading time and allow users to choose Chat features they would like to import. You can import the
@sendbird/chat package first, which adds
MessageModule. Depending on which chat features you would like to use, you can provide
OpenChannelModule from the
@sendbird/chat/openChannel packages respectively as a parameter of the
SendbirdChat.init() method. You can also set them in
SendbirdChatParams and pass it to the
With TypeScript, each module provides a wrapper type of the
SendbirdChat instance which allows the module to access
sb.openChannel respectively. You can cast the
SendbirdChat instance to
SendbirdOpenChat to access the modules.
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.
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 the 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 a 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. Since the
sb.connect()method now requires a callback, use
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.
For Chat SDKs that don't use local caching, the connection process remains the same. When an error occurs, the SDK must attempt to reconnect again.
Note: Apart from initializing the
SendbirdChatinstance, 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, a
CONNECTION_REQUIRED (800101)error would be returned.
Manage connections with the Sendbird server
disconnect() methods explicitly depending on how you implement your use cases.
One user ID can make connections to up to 30 devices or browsers simultaneously. All connections from the single user ID are counted and reflected in your application’s concurrent connection number, which is used to calculate your service billing.
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
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 information submitted when a user signs up or log 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 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.
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 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
SessionHandler instance to refresh the token and pass it back to the SDK so that it can refresh the session again.
SessionHandlerinstance must be set before the server connection is requested.
The following code shows how to implement the handler.
SessionHandler.onSessionTokenRequired() is invoked, the SDK waits for a specific amount of time to receive a new session token from the client app.
reject() are called within the specified timeout period, the socket connection will be disconnected. If this occurs, the client app has to manually call
sb.connect(USER_ID, AUTH_TOKEN) for a new socket connection.
The timeout period can be set using the
sessionTokenRefreshTimeout method as shown in the code below.
Disconnect from the Sendbird server
Disconnect a user 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 a client app is disconnected, all event handlers registered through
sb.addConnectionHandler() stop receiving event callbacks from the server. Then, all internally cached data in the client app are flushed. This includes channels that are cached when
sb.groupChannel.getChannel() is called, as well as locally cached channels and messages.
Disconnect the WebSocket only
SendbirdChat.disconnect() disconnects the WebSocket as well as clear local cache data, you can call
SendbirdChat.disconnectWebSocket to disconnect the WebSocket only and keep the locally cached data.
To reconnect after calling
disconnectWebSocket, use the
SendbirdChat.connect() method as shown in the code below.