Collection migration guide
Sendbird Chat SDK v4 for Android has introduced group channel collection and message collection to enhance efficiency and improve developer experience. This guide assists you in transitioning from low-level interface implementations to more efficient, collection-based solutions. We strongly recommend integrating collections into your existing codebase for improved efficiency and user experience.
Key benefits of using collection
View-driven interface: The collection interface organizes handler methods and event callbacks around the currently displayed view. Event callbacks are triggered only for the channels or messages that are currently being displayed.
Effortless event handling: By assigning a collection handler, the data source for your channel and message views are automatically updated when an event is triggered. You can set your handler, and the collection handles the event updates to your data source.
Automated updates upon reconnection: Collections handle channel and message updates automatically upon app reconnection, eliminating the need for manual intervention.
Local caching capabilities: Collections also handle local caching of chat data for offline messaging.
Implementing group channel collection
The following section further explains how to implement and use group channel collection.
Step 1 Create a group channel collection instance
To use the group channel collection interfaces, a
GroupChannelCollection instance must be created first.
Step 2 Retrieve a list of group channels
You can load more channels by using the
loadMore(GroupChannelsCallbackHandler) method of
GroupChannelCollection created in step 1. You don't need to create a
GroupChannelListQuery instance and utilize the query to load the next page anymore.
Step 3 Handle group channel events
With collections, numerous group channel event callbacks have been consolidated into three streamlined
GroupChannelCollectionHandler methods. The new methods are designed to only pass events that are relevant to the group channel list view.
You're managing the channel list view and want to show a typing indicator when a member starts typing and update the last message in real-time.
Before collections, you had to implement different
GroupChannelHandler methods to keep up with these changes.
With group channel collection, however, all changes from events are already applied to
channels in the
onChannelsUpdated(GroupChannelContext, List<GroupChannel> method method. Now, all you need to do is refresh your channel list with the updated channels as shown in the example code below.
To react to specific events, such as when a member starts typing, check
onChannelsUpdated(GroupChannelContext, List<GroupChannel>). The following code is an example of triggering an alert when a member starts typing.
To learn more, see a full list of
Step 4 Keep cached channels synced with the Sendbird server
When a user is online, all data associated with the group channels they are a member of are automatically updated. However, when a user is disconnected from the Sendbird server and reconnects later, data associated with group channels need to be updated.
Previously, you had to call
SendbirdChat.getMyGroupChannelChangeLogsByTimestamp(Long, GroupChannelChangeLogsParams(), GroupChannelChangeLogsHandler) or
SendbirdChat.getMyGroupChannelChangeLogsByToken(String, GroupChannelChangeLogsParams(), GroupChannelChangeLogsHandler) to manually update the data upon reconnection.
With collections, however, it automatically keeps your cached channels' information up-to-date without requiring additional code implementation. If you wish to be notified when this update is completed in order to do any custom updates, you can check
CollectionEventSource.CHANNEL_CHANGELOG inside each
Implementing message collection
The following section explains how to implement and use message collection.
Step 1 Create a message collection instance
To use message collection interfaces, a
MessageCollection instance must be created first. You can do so by calling the
SendbirdChat.createMessageCollection(MessageCollectionCreateParams) method. Then, you must start the collection to load the first batch of messages through
Step 2 Retrieve a list of messages
You can load more messages by using the
hasPrevious method of
MessageCollection created in step 1. Previously, you had to call either
getMessagesByTimestamp(Long, MessageListParams, BaseMessagesHandler) or
getMessagesByMessageId(Long, MessageListParams, BaseMessagesHandler) and manually manage the data source for the message list after loading.
Step 3 Handle channel events
With collections, numerous message event callbacks have been consolidated into six streamlined
MessageCollectionHandler methods. Step 3 explains how to handle events on the currently displayed group channel.
Example of group channel event
If you wanted to handle events when new members join or leave a channel, you had to implement two separate
GroupChannelHandler methods shown in the code below to handle the events. With message collection, however, all changes from both events are already applied to the
channel parameter in the
onMessagesUpdated(MessageContext, GroupChannel, List<BaseMessage>). All you need to do is refresh with the updated channels as shown in the example code below.
For use cases where you need to specifically check whether a member has joined or left a channel separately, you can check
To learn more, see a full list of
Step 4 Handle message events
With collection, you can set the
null and listen to changes to the message collection using the
onMessagesAdded(MessageContext, GroupChannel, List<BaseMessage>) method of
MessageCollectionHandler. Through the handler method, message events are handled accordingly depending on their message status. This allows you to send a message and track their statuses separately, making it easier to manage your implementation.
Other message events
Previously, different events that affect your message list data had to be handled separately. For example, to update your message list data with the latest message update events, reaction events, and poll update events, you had to use three different
GroupChannelHandler handler methods -
channel(_:didUpdatePoll:). In each, you had to separately implement how to handle your message list.
Using message collection, you can handle all message events by simply updating your message data through
onMessagesUpdated(MessageContext,GroupChannel,List<BaseMessage>) handler. This is because
updatedMessages already carries all the updated information from each message update, reaction, and poll update event.
To react to specific events, such as displaying an alert when a poll has been updated, check
To learn more, see a full list of
Step 5 Keep cached channel and messages synced with the Sendbird server
When a user is online, all data associated with the group channels they are a member of and its messages are automatically updated. However, when a user is disconnected from the Sendbird server and reconnects later, data associated with group channels need to be updated.
Refresh cached channel upon reconnection
With message collection, it automatically keeps your cached channel information up-to-date without requiring additional code implementation.
Refresh cached messages upon reconnection
Previously, to keep your cached messages up-to-date, you had to manually call either
channel.getMessageChangeLogsSinceTimestamp(Long, MessageChangeLogsParams, GetMessageChangeLogsHandler) or
channel.getMessageChangeLogsSinceToken(String, MessageChangeLogsParams, GetMessageChangeLogsHandler) upon reconnection to the Sendbird server.
With message collection, however, it automatically fetches the changelogs of message internally. Then, it passes the results onto
onMessagesUpdated(MessageContext, GroupChannel, List<BaseMessage>) or
onMessagesDeleted(MessageContext, GroupChannel, List<BaseMessage>) with
context.collectionEventSource set as
Collection event sources
The following table shows a list of
CollectionEventSources that trigger
MessageCollectionHandler methods to be called. The event sources are passed to
MessageContext inside handler methods.
A message has been received in a group channel.
A message has been updated in a group channel.
A user has been mentioned in a message sent in a group channel.
A user has been muted in a group channel.
A user has been unmuted in a group channel.
A user has been banned from a group channel.
A user has been unbanned from a group channel.
A group channel has been frozen.
A group channel has been unfrozen.
A group channel has the following changes:
A group channel has been deleted.
A message has been deleted in a group channel.
Metadata for a group channel has been created.
Metadata for a group channel has been updated.
Metadata for a group channel has been deleted.
A metacounter for a group channel has been created.
A metacounter for a group channel has been updated.
A metacounter for a group channel has been deleted.
A message reaction has been updated.
A channel operator has been updated.
A reply message has been created or deleted from a thread in a group channel.
A message has been read by a reader who is not the
The delivery status of a message sent to a group channel has been updated.
A user starts typing a message to a group channel.
The member count of one or more group channels has changed.
A user has been invited to a group channel.
A user has declined an invitation to a group channel.
A user has joined a group channel.
A user has left a group channel.
A group channel has been hidden.
A message has been pinned or unpinned in a group channel.
A poll has been updated in a group channel.
A user has voted on a poll in a group channel.
Message changelog has been received.
A message gap has been filled.
Channel changelog has been received.
A pending message has been created.
A message has failed to send.
A message has been canceled.
A failed message has been resent in a group channel.
A group channel has been refreshed through
A message has been sent in a group channel.
Poll changelog has been received.