iOS
Sync Manager Message Sync

Message Sync

This page provides an overview of how messages can be synchronized by using the SBSMMessageCollection together with other classes. The SBSMMessageCollection is a class that subscribes to message-related events through the SBSMMessageCollectionDelegate. The delegate listens to cached events and real-time events in order to direct the way of view implementation.

For example, if SyncManager receives a real-time event that a message has been deleted, it creates a collection event which has the remove action for the message and delivers it to the collection delegate. At the same time, cached events are also given to the delegate. The collection automatically fetches messages from the cache and delivers a collection event which has the insert action for the message to the collection delegate.


Initialization

The following shows how to initialize and use a SBSMMessageCollection instance:

Objective-C
Swift
Light Color Skin
Copy
SBSMMessageFilter *filter = [SBSMMessageFilter filterWithMessageType:SBDMessageTypeFilterAll customType:nil senderUserIds:nil];
SBSMMessageCollection *collection = [SBSMMessageCollection collectionWithChannel:channel filter:filter viewpointTimestamp:LLONG_MAX];
collection.delegate = self;

[collection fetchInDirection:SBSMMessageDirectionPrevious completionHandler:^(BOOL hasMore, SBDError *error) {
    [collection fetchInDirection:SBSMMessageDirectionNext completionHandler:^(BOOL hasMore, SBDError *error) {
    }];
}];

// Message collection delegates
- (void)collection:(nonnull SBSMMessageCollection *)collection didReceiveEventAction:(SBSMMessageEventAction)action succeededMessages:(nonnull NSArray<SBDBaseMessage *> *)succeededMessages {
    switch (action) {
        case SBSMMessageEventActionInsert: {
            // TODO: Add messages to the view.
            break;
        }
        case SBSMMessageEventActionUpdate: {
            // TODO: Update messages in the view.
            break;
        }
        case SBSMMessageEventActionRemove: {
            // TODO: Remove messages from the view.
            break;
        }
        case SBSMMessageEventActionClear: {
            // TODO: Clear the view.
            break;
        }
        case SBSMMessageEventActionNone:
        default: {
            // Pass
            break;
        }
    }
}
Light Color Skin
Copy
let filter = SBSMMessageFilter(messageType: .all, customType: nil, senderUserIds: nil)
let collection = SBSMMessageCollection(channel: channel, filter: filter, viewpointTimestamp: LLONG_MAX)
collection?.delegate = self
collection.fetch(in: .previous, completionHandler: { (hasMore, error) in
    collection.fetch(in: .next, completionHandler: { (hasMore, error) in

    })
})

// SBSMMessageCollectionDelegate
func collection(_ collection: SBSMMessageCollection, didReceive action: SBSMMessageEventAction, pendingMessages: [SBDBaseMessage]) {
    switch (action) {
        case .insert:
            // TODO: Add messages to the view.
            break
        case .update:
            // TODO: Update messages in the view.
            break
        case .remove:
            // TODO: Remove messages from the view.
            break
        case .clear:
            // TODO: Clear the view.
            break
        case .none:
            // Pass
            break
    }
}

In the above code sample, the collection instance sets the collection delegate to listen to message events and call the fetchSucceededMessage method after initialization. At runtime, according to your caching status, the insert event can return multiple times. The first few events are called to fetch the messages from the local cache. If not enough messages are cached, SyncManager waits until background sync synchronizes with the server before delivering the rest of the messages. Then, you may get more events with those messages.


Viewpoint

A viewpoint is a timestamp option that sets the starting point of the current user’s view. The default value is the LLONG_MAX, which means that the user sees the most recent messages in the chat room. If the viewpoint is set to the middle of the conversation, then the view starts from the middle of the conversation to enable the user to scroll up and down to see the previous and next messages. The viewpoint can be set at initialization, and can be reset anytime by calling the resetViewpointTimestamp method.

Objective-C
Swift
Light Color Skin
Copy
// Set the viewpoint during initialization.
SBSMMessageCollection *collection = [SBSMMessageCollection collectionWithChannel:channel filter:filter viewpointTimestamp:LLONG_MAX];

...
// Reset the viewpoint.
[collection resetViewpointTimestamp:newViewpointTimestamp];
Light Color Skin
Copy
// Set the viewpoint during initialization.
let collection: SBSMMessageCollection = SBSMMessageCollection(channel: channel, filter: filter, viewpointTimestamp: LLONG_MAX)

...
// Reset the viewpoint.
collection.resetViewpointTimestamp(newViewpointTimestamp)

Direction

The direction parameter denotes direction and is provided by the SBSMMessageCollection’s fetchInDirection. The collection can fetch messages from two directions: previous and next. Previous messages are fetched in the direction of past messages, while next messages are fetched in the direction of the most recent, real-time messages.

Note: If the current user isn’t seeing the most recent messages, real-time event messages may not be being delivered to the collection delegate. SyncManager assumes that real-time event messages are shown through the fetchInDirection method in the next direction.


Real-time events

SyncManager listens to real-time events from the Chat SDK in order to apply changes and notify the current user. Below is the list of real-time message events that SyncManager listens to through the SBSMMessageCollectionDelegate's didReceiveEventAction: callback method:

EventAction with description

channel:didReceiveMessage:

SBSMMessageEventActionInsert: A new message has been sent. If the view doesn't show the last message, the collection defers the delivery of the event.

channel:didUpdateMessage:

SBSMMessageEventActionUpdate: A message has been updated. If the collection doesn't have the message in the message list, the event is ignored.

channel:messageWasDeleted:

SBSMMessageEventActionRemove: A message has been deleted. If the collection doesn't have the message in the message list, the event is ignored.

Note: The collection has an array that holds all the messages that should be shown in the view. If a message isn’t shown in the view, it means that the collection isn’t holding it because background sync synchronization hasn’t been completed at that time.


fetchInDirection method

The fetchInDirection method fetches messages from the local cache and delivers them to the delegate. If not enough messages are cached, it waits until background sync synchronizes with SendBird server before bringing the retrieved messages. The fetchInDirection should be called when:

  • A collection is created.
  • A connection is established.
  • The app goes to the foreground.
  • The scroll reaches the top or the bottom.
  • The app returns from a locked screen when still in the foreground.

The fetchInDirection subscribes to background sync to pull data from the local cache. As this method doesn’t directly interact with SendBird server, while online, it waits until background sync synchronizes data in the server to the cache before retrieving new data. However, after synchronization is completed by background sync, the fetchInDirection can refresh the view with new data. Therefore, the fetchInDirection can not only read cached data, but also update data in the view.

The fetchAllNextMessages behaves similarly to fetchInDirection(SBSMMessageDirectionNext), except it fetches the most recent messages, regardless of the fetch limit set in the SBSMMessageCollection instance. This method can be used to fetch messages when a user, who had scrolled to the bottom of the screen and was looking at the most recent messages, comes online.

The method to fetch messages when a user comes online from offline should depend on their scroll point. Regardless of whether the user is connecting to a network, coming to the foreground from the background, or turning on their screen, this should be implemented in the SBDConnectionDelegate, which listens for state changes from offline to online.

Objective-C
Swift
Light Color Skin
Copy
- (void)didSucceedReconnection {
    [SBSMSyncManager resumeSynchronize];
    [self.collection fetchAllNextMessages:^(BOOL hasMore, SBDError *error) {}];
}
Light Color Skin
Copy
func didSucceedReconnection() {
    SBSMSyncManager.resumeSynchronize()
    self.collection.fetchAllNextMessages { hasMore, error in }
}

Message lifecycle

Once a message is created, it has its own lifecycle. When a message has been sent but not yet received any response from SendBird server through its callback, the requestState of the message is pending. Once the server responds, the requestState of the message is set as succeeded or failed. SyncManager internally keeps track of the request state of a message so as to update the view accordingly.

For each requestState, a message in a view can be displayed as follows:

  • pending: displays the message content with a progress animation.
  • failed: displays the message content with a context menu such as resend or delete.
  • succeeded: displays the message content with its read receipt.

Note: Pending and failed messages temporarily have a messageId of 0. When they are successfully sent to the server, they get their own unique message ID, and are delivered and replaced as succeeded messages in the collection delegate by their reqId. The purpose of a reqId is to ensure messages are listed in the order of their time sent.


Send a message

As messages are sent by the Chat SDK, SyncManager cannot check whether a message has been successfully sent. Therefore, the SBSMMessageCollection provides the handleSendMessageResponse block so that SyncManager recognizes the delivery status.

Objective-C
Swift
Light Color Skin
Copy
SBDBaseMessage *pendingMessage = [channel sendUserMessage:MESSAGE completionHandler:^(SBDUserMessage *userMessage, SBDError *error) {
    collection.handleSendMessageResponse(userMessage, error);
}];

[collection appendMessage:pendingMessage];
Light Color Skin
Copy
SBDBaseMessage *pendingMessage = channel.sendUserMessage(MESSAGE, completionHandler: { (userMessage, error) in
    collection.handleSendMessageResponse(userMessage, error)
})
collection.appendMessage(pendingMessage)

The handleSendMessageResponse block conducts different jobs based on the set message resend policy. Below is the the list of acceptable values:

ValueDescription

none

If delivery succeeded: performs the remove event for the pending message and the insert event for the succeeded message.
If delivery failed: performs the remove event for the pending message.

manual

If delivery succeeded: performs the remove event for the pending message and the insert event for the succeeded message.
If delivery failed: performs the remove event for the pending message and the insert event for the failed message. The failed message can be manually resent by calling the following SDK methods in a SendBird instance.
- resendUserMessageWithMessage:completionHandler:
- resendFileMessageWithMessage:binaryData:completionHandler:

automatic

If delivery succeeded: performs the remove event for the pending event and the insert event for the succeeded message.
If delivery failed: performs the remove event for the pending message and the insert event for the failed message. Automatically resends the failed message.


Update a message

As previously mentioned, SyncManager can't check whether a message has been successfully sent because messages are sent through the Chat SDK. Therefore, the SBSMMessageCollection provides the updateMessage method so that SyncManager recognizes the delivery status.

Objective-C
Swift
Light Color Skin
Copy
SBDUserMessageParams *params = [[SBDUserMessageParams alloc]; initWithMessage:UPDATED_MESSAGE];
[groupChannel updateUserMessageWithMessageId:message.messageId userMessageParams:params completionHandler:^(SBDUserMessage *message, SBDError *error) {
    [collection updateMessage:message];
}];
Light Color Skin
Copy
let params = SBDUserMessageParams(message: UPDATED_MESSAGE)
groupChannel.updateUserMessage(withMessageId: message.messageId, userMessageParams: params, completionHandler: { (message, error) in
    collection.updateMessage(message)
})

Note: Only succeeded messages can be updated.


Remove a message

Messages can be deleted using the deleteMessage method in the Chat SDK.

Objective-C
Swift
Light Color Skin
Copy
[channel deleteMessage:message completionHandler:^(SBDError *error) {
    // This gets the 'remove' event for the message
    // so no further job is required.
}];
Light Color Skin
Copy
channel.delete(message, completionHandler: { (error) in
    // This gets the 'remove' event for the message
    // so no further job is required.
})

Handle a failed message

According to the request state, the SBSMMessageCollectionDelegate instance listens to message events through the following callbacks:

Event callbackMessage delivery status & how SyncManager handles a message

collection:didReceiveEventAction:succeededMessages:

succeeded: A message has been successfully sent to SendBird server and automatically stored in the local cache.

collection:didReceiveEventAction:pendingMessages:

pending: The Chat SDK's method has sent a message, but not yet received any response from SendBird server through its callback. SyncManager will wait for a certain period of time to define the delivery status of the message by either succeeded or failed. pending refers to when the message remains unprocessed and SyncManager is waiting for a response.

collection:didReceiveEventAction:failedMessages:

failed: A message has failed to be sent to SendBird server and the Chat SDK's method receives an error through its callback. The message should be either appended to or deleted from the SBSMMessageCollection instance using the appendMessage: or deleteMessage: method.
If the messageResendPolicy is automatic, SyncManager will attempt to resend the message automaticMessageResendRetryCount times. Otherwise, you should resend the message by manually calling the Chat SDK's resendUserMessageWithMessage:completionHandler: method.

Suppose that a new message is requested and successfully sent. In order for this to happen, the insert event should be given to the collection:didReceiveEventAction:pendingMessages: first. Once the message delivery status is determined as succeeded via the callback, the remove event is given to the collection:didReceiveEventAction:pendingMessages: while the insert event is also given to the collection:didReceiveEventAction:succeededMessages:.


Close the view

As the message list view is closed, the SBSMMessageCollection instance should be cleared. A SBSMMessageCollection has the remove method, which clears all the messages managed by the collection and stops synchronization processes in the collection. If the collection isn’t explicitly dropped, the applicable memory won’t be released and could lead to performance slowdown.

Objective-C
Swift
Light Color Skin
Copy
- (void)dealloc {
    collection.delegate = nil;
    [collection remove];
}
Light Color Skin
Copy
deinit {
    collection.delegate = nil
    collection.remove()
}