SyncManager SDKs Android v1
SyncManager SDKs Android
SyncManager SDKs
Android
Version 1

Install SyncManager

Copy link

This page provides a guide that demonstrates how to integrate Sendbird SyncManager onto a client app. Sendbird SyncManager can be installed through Gradle. Start building the add-on to your Chat SDK by clicking the Download SyncManager button below.

Note: Sendbird Chat SDK is required in order to use Sendbird SyncManager because it is an add-on feature.


Download SyncManager

Copy link

Download SyncManager


Install SyncManager

Copy link

Installing the SyncManager SDK is simple if you're familiar with using external libraries or SDKs. First, add the following code to your root build.gradle file:

allprojects {
    repositories {
        ...
        maven { url "https://repo.sendbird.com/public/maven" }
    }
}

Note: Make sure the above code block isn't added to your module bundle.gradle file.

Then, add the dependency to your module build.gradle file.

dependencies {
    // SyncManager SDK for Android (Latest, embeds Sendbird Chat SDK 3.0.170)
    implementation 'com.sendbird.sdk:sendbird-syncmanager:1.1.31'

    // Chat SDK for Android (If you want to use higher version than the version embedded in the SyncManager)
    implementation 'com.sendbird.sdk:sendbird-android-sdk:3.1.27'
}

Note: SyncManager SDK versions 1.1.30 or lower can be downloaded from JCenter until February 1, 2022. SDK versions higher than 1.1.30 will be available on Sendbird's remote repository.


How it works

Copy link

SyncManager is designed to simplify the process of integrating chat in your Android client app by leveraging local caching. While Sendbird Chat SDK for Android is highly customizable with a number of atomic features, SyncManager facilitates SDK integration by managing most background operations needed to run chat in your Android client app.

Event-driven structure

Copy link

SyncManager has an event-driven architecture that updates the chatting view based on data events. Events received through the WebSocket connection as well as processed data in the cache are delivered to the client app by the SyncManager’s collection handlers and can be leveraged when implementing your view.

Collection

Copy link

As a key component that can be used for view implementation, the Collection holds items that comprise channel or message data. In your view, a collection instance can be binded to an event handler to subscribe to events. In the callbacks of the event handler, you can implement what jobs to execute when a specific type of event happens. The following shows a simple example of how you can create a channel collection and bind it to a collection event handler:

ChannelCollectionHandler channelCollectionHandler = new ChannelCollectionHandler() {
    @Override
    public void onChannelEvent(ChannelCollection channelCollection, List<GroupChannel> list, ChannelEventAction channelEventAction) {
        switch (channelEventAction) {
            case INSERT:
                break;
            case UPDATE:
                break;
            case MOVE:
                break;
            case REMOVE:
                break;
            case CLEAR:
                break;
        }
    }
};

GroupChannelListQuery listQuery = GroupChannel.createMyGroupChannelListQuery();

ChannelCollection channelCollection = new ChannelCollection(listQuery);
channelCollection.setCollectionHandler(channelCollectionHandler);

Background sync

Copy link

Background sync is a feature of SyncManager that automatically stores data fetched from Sendbird server in the local cache. When a collection is created, the background sync process starts running with the given conditions. Background sync should follow the lifecycle of a connection: the pauseSync() method is called when a connection is lost and the resumeSync() method is called when a connection is established.

For example, even if only 2 out of 12 channels are cached, background sync feeds the uncached Sendbird server data to the chatting view so that all 12 channels are displayed. In order for this to happen, the channel collection’s fetch() should be called, and the collection brings the insert event for the two channels from the cache. Then, the uncached 10 channels are synchronized through background sync. After synchronization is completed, another insert event is given for the uncached 10 channels. Through this process, all 12 channels are displayed in the view.

Real-time event sync

Copy link

Real-time event sync is a feature of SyncManager that listens for real-time events received through the WebSocket connection. When an event arrives, SyncManager identifies it, stores it in the cache, and delivers it to the collection handler with the appropriate action such as insert or remove.

Offline mode

Copy link

SyncManager ensures your client app is operational during offline mode. If background sync isn’t running because a connection with the server hasn’t been established, the view can display cached data provided by SyncManager. Once a connection is re-established, the resumeSync() resumes background sync for data synchronization.


Implementation guide

Copy link

This section describes how to implement SyncManager in your Android client app.

Initialization

Copy link

Initialize and set up the database for SyncManager as below:

SendBirdSyncManager.Options options = new SendBirdSyncManager.Options.Builder()
                    .setMessageResendPolicy(SendBirdSyncManager.MessageResendPolicy.AUTOMATIC)
                    .setAutomaticMessageResendRetryCount(5)
                    .build();

SendBirdSyncManager.setup(context, userId, options, new CompletionHandler() {
    @Override
    public void onCompleted(SendBirdException e) {
        if (e != null) {    // Error occurred during setup.
            return;
        }
        // Setup succeeded.
    }
});

SyncManager database

Copy link
FieldTypeDescription

userId

string

Specifies the ID of the user.

options

SendBirdSyncManager.Options

Specifies the options for how SyncManager works.

handler

CompletionHandler

Called after the setup is completed.

The SendBirdSyncManager.Options has the following properties:

List of properties

Copy link
Property nameDescription

messageCollectionCapacity

Determines the maximum capacity of messages in a collection related to a chat view. Messages that exceed the maximum capacity are removed. Acceptable values are from 200 to 2,147,483,647. (Default: 2,147,483,647)

messageResendPolicy

Determines the policy for handling failed messages. If delivery of a message fails, SyncManager performs different actions based on the configured policy. Acceptable values are:
- none (default): removes the pending message.
- manual: stores the failed message in the local cache and updates the pending message state as failed.
- automatic: performs the same actions as manual, but also tries to automatically resend the failed message.

automaticMessageResendRetryCount

Determines the maximum number of attempts to resend a failed message. Resend attempts are stopped for messages that have been resent the maximum number of attempts and they remain as failed. The messageResendPolicy value must be set as automatic for this to be applicable. (Default: 2,147,483,647)

maxFailedMessageCountPerChannel

Determines the maximum number of failed messages allowed in a channel. SyncManager deletes the earliest failed message and delivers the remove event through the MessageCollectionHandler if the number of failed messages exceeds this limit. (Default: 20)

failedMessageRetentionDays

Determines the number of days to retain failed messages. Once failed messages have been retained for the retention period, they are automatically removed. (Default: 7)

Connection handling

Copy link

When the Chat SDK is connected to Sendbird server, SyncManager fetches the current user’s chat-related data from the server to update the local cache. This enables SyncManager to synchronize the local cache with the channel and message data.

Additional jobs, which detect changes in connection status and notify SyncManager, are needed when data is fetched from the server through the Chat SDK’s connection event handler: calling the resumeSync() and pauseSync() methods. The resumeSync() should be called in the onReconnectSucceeded() to run background processes for data synchronization when connected, whereas the pauseSync() should be called in the onReconnectStarted() to pause the background processes when disconnected. Adding and removing the connection handler is suggested to be done in onResume() and onPause().

@Override
protected void onResume() {
    super.onResume();

    SendBird.addConnectionHandler(YOUR_CONNECTION_HANDLER_ID, new SendBird.ConnectionHandler() {
        @Override
        public void onReconnectStarted() {
            SendBirdSyncManager.getInstance().pauseSync();
        }

        @Override
        public void onReconnectSucceeded() {
            SendBirdSyncManager.getInstance().resumeSync();
        }

        @Override
        public void onReconnectFailed() {
        }
    });
}

@Override
protected void onPause() {
    super.onPause();

    SendBird.removeConnectionHandler(YOUR_CONNECTION_HANDLER_ID);
}

Note: The SendBird.removeAllConnectionHandlers() or SendBird.removeAllChannelHandlers() method shouldn’t be called because they remove not only the handlers you’ve added, but also the other handlers internally managed by SyncManager.

Clear local cache

Copy link

The cache can be cleared regardless of connection to Sendbird server using the clearCache() method.

SendBirdSyncManager.getInstance().clearCache();

Note: The clearCache() is designed for debugging purposes only. Using it for other purposes isn’t recommended.