First, create a SBDMessageCollection through the createMessageCollection() method. Here, you need to set a SBDMessageListParams instance to determine the message order and the starting point of the message list in the chat view.
SwiftObjective-C
import SendBirdSDK
class ChatViewController: UIViewController {
var collection: SBDMessageCollection?
var channel: SBDGroupChannel?
var startingPoint: UInt64?
// Create a SBDMessageCollection instance.
func createMessageCollection() {
// You can use a SBDMessageListParams instance for the SBDMessageCollection.
let params = SBDMessageListParams()
params.reverse = false
// You can add other query setters.
// ...
self.collection = SBDMessageCollection(channel: self.channel, startingPoint: self.startingPoint, params: params)
self.collection?.delegate = self
}
//Initialize messages from the startingPoint.
func initialize() {
self.collection?.start(with: .cacheAndReplaceByApi, cacheResultHandler: { messages, error in
// Messages will be retrieved from the local cache.
// They might be too outdated compared to the startingPoint.
}, apiResultHandler: { messages, error in
// Messages will be retrieved from the Sendbird server through API.
// According to the SBDMessageCollectionInitPolicy.cacheAndReplaceByApi,
// the existing data source needs to be cleared
// before adding retrieved messages to the local cache.
})
}
// ...
}
The startingPoint is the reference point of the message retrieval for a chat view. This should be specified as a timestamp.
If you set the value of startingPoint to the current time, messages in the view will be retrieved in reverse chronological order, showing messages from the most recent to the oldest.
If you set the value of startingPoint to the message last read by the current user, messages in the view will be fetched in chronological order, starting from the last message seen by the user to the latest.
After initializing a SBDMessageCollection instance through the initialize() method, you need to set the SBDMessageCollectionInitPolicy.
The SBDMessageCollectionInitPolicy 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 remote server.
Policy
Description
cacheAndReplaceByApi
Retrieves cached messages from the local cache and then replaces them with the messages pulled from Sendbird server through API calls.
Use the loadPrevious() and loadNext() methods to retrieve messages from the previous page and the next page.
When the loadPrevious() method is called, the Chat SDK first checks whether there're more messages to load from the previous page through the hasPrevious. The same goes for the loadNext().
In Objective-C, the loadPreviousWithCompletionHandler: and loadPreviousWithCompletionHandler: can be used to load paginated messages.
These methods have to be called during initialization as well.
SwiftObjective-C
class ChatViewController: UIViewController {
// ...
// Load the previous messages when the scroll reaches the first message in the chat view.
func loadPrevious() {
if let collection = self.collection {
if collection.hasPrevious {
collection.loadPrevious { messages, error in
if error != nil {
// Handle error.
return
}
}
}
}
}
// Load the next messages when the scroll reaches the last message in the chat view.
func loadNext() {
if let collection = self.collection {
if collection.hasNext {
collection.loadNext { messages, error in
if error != nil {
// Handle error.
return
}
}
}
}
}
// ...
}
- A message is deleted as a real-time event. - Message deletion is detected during changelog sync. - The value of the SBDMessageListParams setter such as custom_type changes.
- A message is updated as a real-time event. - Message update is detected during changelog sync. - The sending status of a pending message changes.
messageCollection:context:updatedChannel:
- The channel information that is included in the user's current chat view is updated as a real-time event. - Channel info update is detected during changelog sync.
messageCollection:context:deletedChannel:
- The current channel is deleted as a real-time event. - Channel deletion is detected during changelog sync. * In both cases, the entire view should be disposed of.
didDetectHugeGap:
- A huge gap is detected through background sync. In this case, you need to dispose of the view and create a new SBDMessageCollection instance.
SwiftObjective-C
extension ChatViewController: SBDMessageCollectionDelegate {
func messageCollection(_ collection: SBDMessageCollection, context: SBDMessageContext, channel: SBDGroupChannel, addedMessages messages: [SBDBaseMessage]) {
switch context.messageSendingStatus {
case .succeeded:
// Add messages to your data source.
case .pending:
// Add pending messages to your data source.
default:
}
}
func messageCollection(_ collection: SBDMessageCollection, context: SBDMessageContext, channel: SBDGroupChannel, updatedMessages messages: [SBDBaseMessage]) {
switch context.messageSendingStatus {
case .succeeded:
// Update the messages status of sent messages.
case .pending: (failed -> pending)
// Update the message status from failed to pending in your data source.
// Remove the failed message from the data source.
case .failed: (pending -> failed)
// Update the message status from pending to failed in your data source.
// Remove the pending message from the data source.
case .canceled: (pending -> canceled)
// Remove the pending message from the data source.
// Implement codes to process canceled messages on your end. The Chat SDK doesn't store canceled messages.
default:
}
}
func messageCollection(_ collection: SBDMessageCollection, context: SBDMessageContext, channel: SBDGroupChannel, deletedMessages messages: [SBDBaseMessage]) {
switch context.messageSendingStatus {
case .succeeded:
// Remove the sent message from your data source.
case .failed:
// Remove the failed message from your data source.
default:
}
}
func messageCollection(_ collection: SBDMessageCollection, context: SBDMessageContext, updatedChannel channel: SBDGroupChannel) {
// Change the chat view with the updated channel information.
}
func messageCollection(_ collection: SBDMessageCollection, context: SBDMessageContext, deletedChannel channelUrl: String) {
// This is called when a channel was deleted. So the current chat view should be cleared.
}
func didDetectHugeGap(_ collection: SBDMessageCollection) {
// The Chat SDK detects more than 300 messages missing.
// Dispose of the current collection.
self.collection.dispose();
// Create a new message collection object.
self.createMessageCollection();
// An additional implementation is required for initialization.
}
}
Depending on the connection status, the client app could miss message events. Especially when new messages or new channels stored in Sendbird server don't reach the Chat SDK in the client app, a gap is created. A gap is a chunk of objects that exist in the remote server but missing in the local cache.
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.
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 Sendbird server to see if there are any new messages. If it detects more than 300 messages missing in the local cache compared to the remote server, the SDK determines that there is a huge gap and the didDetectHugeGap: is called.
Note: To adjust the number, contact support on the Sendbird Dashboard.
In this case, the existing SBDMessageCollection should be cleared through the dispose() method and a new one must be created for better performance.
The dispose() should be called when you need to clear the current chat view. For example, this can be used when the current user leaves the channel or when a new collection has to be created due to huge gap detected by the didDetectHugeGap:.
SwiftObjective-C
class ChatViewController: UIViewController {
// ...
func dispose() {
if let collection = self.collection {
collection.dispose()
}
}
// ...
}