Collection migration guide
Sendbird Chat SDK v4 for iOS 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 delegate 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 delegate, the data source for your channel and message views are automatically updated when an event is triggered. You can set your delegate, 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(completionHandler:) 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
GroupChannelCollectionDelegate 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
GroupChannelDelegate methods to keep up with these changes.
With group channel collection, however, all changes from events are already applied to
updatedChannels in the
channelCollection(_:context:updatedChannels:) 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
channelCollection(_:context:updatedChannels:). 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.getMyGroupChannelChangeLogs(token:params:completionHandler:) 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.channelChangelog of 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
createMessageCollection() 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
getMessagesByMessageId 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
MessageCollectionDelegate 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
GroupChannelDelegate methods shown in the code below to handle the events. With message collection, however, all changes from both events are already applied to the
updatedChannels parameter in the
messageCollection(_:context:updatedChannel:). 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
nil and listen to changes to the message collection using the
messageCollection(_:context:channel:updatedMessages:) method of
MessageCollectionDelegate. Through the delegate 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
GroupChannelDelegate delegate 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
messageCollection(_:context:channel:updatedMessages:). 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. Previously, you had to call
channel.refresh(completionHandler:) to manually update the data upon reconnection.
Refresh cached messages upon reconnection
Previously, to keep your cached messages up-to-date, you had to manually call either
getMessageChangeLogs(timestamp:params:completionHandler:) upon reconnection to Sendbird server.
With message collection, however, it automatically fetches the changelogs of message internally. Then, it passes the results onto
context.source set as
Collection event sources
The following table shows a list of
CollectionEventSources that trigger
MessageCollectionDelegate methods to be called. The event sources are passed to
MessageContext inside delegate 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 in the following cases:
A message gap has been filled.
Channel changelog has been received.
A group channel has been refreshed through
A message has been sent in a group channel.
Poll changelog has been received.