Message collection
A MessageCollection
instance allows you to swiftly create a chat view that includes all data. This page explains how to make a view using the collection.
Initialization
First, create a MessageCollection
instance through the createMessageCollection(channel:startingPoint:params:)
method. Here, you need to set a MessageListParams
instance to determine the message order and the starting point of the message list in the chat view.
Starting point
The startingPoint
parameter is the reference point of message retrieval for a chat view. This should be specified in the form of timestamp
.
If you set the value of startingPoint
to the current time, messages in the view are retrieved in reverse chronological order, showing messages from most to least recent.
If you set the value of startingPoint
to the message last read by the current user, messages in the view are fetched in chronological order, starting from the last message seen by the user to the latest.
Policy
After initializing a MessageCollection
instance through the startCollection(initPolicy:cacheResultHandler:apiResultHandler:)
method, you need to set the MessageCollectionInitPolicy
parameter.
The argument of MessageCollectionInitPolicy
determines how initialization deals with the message data retrieved from the local cache and API calls. Because we only support cacheAndReplaceByApi
as of now, messages in the local cache must be cleared prior to adding the messages from the Sendbird server.
Policy | Description |
---|---|
cacheAndReplaceByApi | Retrieves cached messages from the local cache and then replaces them with the messages pulled from the Sendbird server through API calls. |
Pagination
Use the loadPrevious(completionHandler:)
and loadNext(completionHandler:)
methods to retrieve messages from the previous page and the next page.
When the loadPrevious(completionHandler:)
method is called, the Chat SDK first checks whether there're more messages to load from the previous page through hasPrevious
. The same goes for loadNext(completionHandler:)
.
These methods have to be called during initialization as well.
Message events
Use the MessageCollectionDelegate
methods to determine how the client app reacts to message-related events.
The following table shows possible cases where each event handler can be called.
Delegate | Called when |
---|---|
messageCollection(_:context:channel:addedMessages:) | - A new message is created as a real-time event. |
messageCollection(_:context:channel:deletedMessages:) | - A message is deleted as a real-time event. |
messageCollection(_:context:channel:updatedMessages:) | - A message is updated as a real-time event. |
messageCollection(_:channelContext:updatedChannel:) | - The channel information that is included in the user's current chat view is updated as a real-time event. |
messageCollection(_:channelContext:deletedChannel:) | - The current channel is deleted as a real-time event. |
didDetectHugeGap(_:) | - A huge gap is detected through background sync. In this case, you need to dispose of the view and create a new |
Gap
In local caching, a gap refers to a chunk of objects that are created and logged on the Sendbird server but missing from the local cache. Depending on the connection status, the client app could miss message events and new messages stored in the Sendbird server may not reach the Chat SDK in the client app. In such cases, a gap is created.
Small gaps can be filled in through changelog sync. However, if the client app has been disconnected for a while, too big of a gap can be created.
Huge gap
A gap can be created for many reasons, such as when a user has been offline for days. When the client app comes back online, the Chat SDK checks with the Sendbird server to see if there are any new messages. If it detects that more than 300 messages are missing in the local cache compared to the Sendbird server, the SDK determines that there is a huge gap and the didDetectHugeGap(_:)
delegate is called.
Note: To adjust the number of missing messages that result in a call for the
didDetectHugeGap(_:)
delegate, contact our support team.
In this case, the existing MessageCollection
instance should be cleared through the dispose()
method and a new one must be created for better performance.
Dispose of the collection
The dispose()
method should be called when you destroy the chat screen to notify the SDK that this collection is no longer visible.
For example, this should be used when the current user exits from the chat screen or when a new collection has to be created due to a huge gap detected by didDetectHugeGap(_:)
.