Local caching

Local caching is a better option than SyncManager for iOS for rapid access to the data from the local cache and Sendbird server. If you are currently using SyncManager, we strongly encourage you to migrate to the Chat SDK with local caching for enhanced usability and easier maintenance.

Note: SyncManager will be deprecated soon.

The following table displays the full range of differences between local caching and SyncManager.

One distinct advantage of local caching over SyncManager is that it provides an event context and a callback for identifying what changes are made to which group channels and messages. This facilitates locating and debugging issues in those channels.

SyncManager relies on an event-driven architecture where its collection handlers receive all events that pass through the WebSocket connection along with the data in the local cache. In contrast, local caching relies on a view-driven structure where only those events that directly affect the user’s channel list and chat view are delivered to their respective collections.

Another advantage of local caching is that messages that were not sent the first time are automatically resent at a later time. When the WebSocket connection is lost, messages considered “pending” are stored locally until the connection comes back on, at which point the pending messages are automatically sent. This new functionality unique to local caching is called auto resend.

Note: SyncManager will continue to work if the dependency to SyncManager is not removed. The dependency should be deleted once the migration to local caching is completed.

You can initialize the Chat SDK with or without local caching. The useCaching is the boolean that determines if you are going to be using local caching. By default, the Chat SDK is initialized without local caching, the useCaching set to false. If the useCaching is set to true, the Chat SDK is initialized with local caching.

In local caching, the completionHandler: callbacks are added to the initWithApplicationId method, which receives the initialization status through different event handlers. For Objective-C, the migrationStartHandler: is called when there's a change in the local cache. Meanwhile, the completionHandler: lets the client app know whether the Chat SDK has been successfully initialized.

Note: If initialization fails to complete while the useCaching is set to true, Chat SDK will operate as if the useCaching is set to false.

Local caching and SyncManager are alike in keeping chat in the client app up-to-date even when the app is not connected to Sendbird server. The key difference between SyncManager and local caching at the initialization stage is that local caching requires calling the SBDMain.connect() after the initWithApplicationId. Calling the SBDMain.connect() after the initWithApplicationId is optional when using SyncManager because the SBSMSyncManager.setup is called immediately after the initWithApplicationId during the initialization process. Calling the SBDMain.connect() after the initWithApplicationId is required when using local caching because some platforms receive the result of initWithApplicationId as a callback.

// Initialize with the useLocalCaching set to true.
SBDMain.initWithApplicationId(APP_ID, useCaching: true) {
    os_log(.info, "Application: Called when there's a change in the local database.")
} completionHandler: { error in
    if error != nil {
        os_log(.info, "Application: Called when initialization failed.")
    }
    else {
        os_log(.info, "Application: Called when initialization is done.")
    }
}

SBDMain.connect(withUserId: userId) { user, error in
    if user != nil {
        if error != nil {
            // Proceed in offline mode with the data stored in the local database.
            // Later, connection will be made automatically
            // and can be notified through the SBDConnectionDelegate.didSucceedReconnection().
        }
        else {
            // Proceed in online mode.
        }
    }
    else {
        // No user is available.
        // Handle error.
    }
}

// Initialize with the useLocalCaching set to true.
[SBDMain initWithApplicationId:APP_ID useCaching:YES migrationStartHandler:^{
    NSLog(@"Application: Called when there's a change in the local database.");
} completionHandler:^(SBDError * _Nullable error) {
    if (error != nil) {
        NSLog(@"Application: Called when initialization failed.");
    }
    else {
        NSLog(@"Application: Called when initialization is done.");
    }
}];

[SBDMain connectWithUserId:USER_ID completionHandler:^(SBDUser * _Nullable user, SBDError * _Nullable error) {
    if (user != nil) {
        if (error != nil) {
            // Proceed in offline mode with the data stored in the local database.
            // Later, connection will be made automatically
            // and can be notified through the `didStartReconnection` of `SBDConnectionDelegate`.
        }
        else {
            // Proceed in online mode.
        }
    }
    else {
        // No user is available.
        // Handle error.
    }
}];

Below you will find the new cache-related interfaces that come with local caching. Local caching’s SBDMain.clearCachedData() replaces the functionality of SyncManager’s SBSMSyncManager.clearCache(), which deletes the entire data file. In addition, the SBDMain.clearCachedMessages() and the SBDMain.getCachedDataSize() are available in local caching. The following table displays a full description of each method and if the method should be called before or after the initWithApplicationId.

SBDMain.clearCachedData {  
}

SBDMain.clearCachedMessages(CHANNEL_URL) { error in
}

let cacheDataSize = SBDMain.getCachedDataSize()

[SBDMain clearCachedDataWithCompletionHandler:^{
        
}];

[SBDMain clearCachedMessages:CHANNEL_URL completionHandler:^(SBDError * _Nullable error) {
        
}];

NSUInteger cacheDataSize = [SBDMain getCachedDataSize];