Sync Changes Between Devices - iOS SDK¶
On this page
- Open a Synced Realm
- Open A Synced Realm Offline
- Synced Realms vs Local Realms
- Open a Synced Realm for the First Time
- Authenticate a User
- Log In and Open a Synced Realm with Data on the Device
- Log In and Download Changes Before Opening a Realm
- Open a Synced Realm with Cached Credentials
- Open a Synced Realm with Data on the Device
- Open a Synced Realm After Downloading Changes
- Sync Changes in the Background
- Suspend or Resume a Sync Session
- Check Upload & Download Progress for a Sync Session
- Check the Network Connection
- Handle Sync Errors
- Delete a Client Realm File
- Set the Client Log Level
Open a Synced Realm¶
The typical flow for opening a synced realm for the first time involves:
- Authenticating the user
- Creating a sync configuration
- Opening the user's synced realm with the configuration.
At authentication, we cache user credentials in a
file on device.
When you open a synced realm after authenticating, you can bypass the login flow and go directly to opening the synced realm, using the same sync configuration you already created.
With cached credentials, you can:
- Open a synced realm immediately with the data that is on the device. You can use this method offline or online.
- Open a synced realm after syncing changes with your Realm app. You can only use this method if the user is online.
Open A Synced Realm Offline¶
You can work with synced realms offline if the user credentials are
cached and you use Realm initializers to open the realms.
If your app requires that a user always have the most up-to-date data,
asyncOpen to open the realm, but that requires a user
to have a network connection.
Synced Realms vs Local Realms¶
Synced realms differ from local Realm Database in a few ways:
- Synced realms attempt to sync changes with your backend Realm app, whereas local realms do not.
- Synced realms can be accessed by authenticated users, while local realms do not require any concept of users or authentication.
- Some methods of opening synced realms require users to be online, while local realms can be used entirely offline.
Open a Synced Realm for the First Time¶
Authenticate a User¶
The first time a user opens a realm, you'll need to authenticate the user. Upon this initial login, we cache login credentials. On subsequent opens, you can check for a logged-in user, and then open new realms. You don't need to complete the login flow while you have a logged-in user.
Depending on your business logic, you may also require the user to download data from MongoDB Realm before opening a synced realm on device.
Log In and Open a Synced Realm with Data on the Device¶
Log In and Download Changes Before Opening a Realm¶
Open a Synced Realm with Cached Credentials¶
After you have authenticated a user and created a sync configuration to open a realm, you can open the same realm again using the sync configuration with cached credentials. You can use two different methods to open the synced realm, depending on your needs:
- Open a synced realm with data that is on the device immediately. This works regardless of network status, and enables the user to start working with the realm without waiting for changes to download from the server. However, data that is on the device may be stale. Additionally, this may result in behavior that seems unexpected or surprising to the user. Data may appear "suddenly" as it syncs in the background after the user has already begun working with the realm. You'll need to account for this in your UI logic.
- Open a synced realm after syncing changes. This requires the user to have a network connection, so you should check the network connection before attempting to open the realm from the server. This method of opening the realm ensures that the user always has the most up-to-date data from the server. The cost of using this method is an upfront pause while loading, and being unable to open the realm offline.
Open a Synced Realm with Data on the Device¶
You can use initializers to open the realm immediately, using the data that is on the device. If you want to open a synced realm offline, use this method. You must have a cached, logged-in user.
Consider the example of a note-taking app. You might decide it's most
important for your user to be able to quickly jot down a note. The user
shouldn't have to wait while downloading changes that a family member made
to a shared note. In this case, opening a realm with
init gets the
user to the UI right away, or while the user is offline. When the user has
a network connection, changes will sync in the background.
In contrast, you might want a store inventory app to always check the server for changes before working with a realm. If you use stale data from the last time the realm was open on the device, the app data could reflect incorrect counts, inaccurate pricing data, or other out-of-date data issues. In that case, you'd want the app to download changes before letting the user work with the data.
A synced realm is not interchangeable with a local Realm Database. If you want to sync a local Realm Database, you'll need to copy the content from the local realm to a synced realm. A local realm lives only on the device and never attempts to sync with the server. A synced realm contains additional Sync-related metadata, and consistently and persistently attempts to connect and sync data with the server.
Open a Synced Realm After Downloading Changes¶
In some apps, such as games, you might want the user to always have current data.
asyncOpen to sync the realm with the Realm app before opening it.
Say a user plays a game on both an iPad and an iPhone. The user progresses
three levels on the iPad. Later, the user opens the game on an iPhone. In this
asyncOpen is a better way to open the realm. Loading with stale
data would get the user into the game faster, but the user's data would be
three levels out of sync.
In contrast, if you had an app that allowed the user to record and save their favorite recipes, you might want to give them the option to create a new recipe without waiting to download updates, or even if they're offline. If you opened a synced realm with data on the device, the user could enter a new recipe, which would sync with the Realm app when they next had a network connection.
A common pattern is to open a realm with
asyncOpen in the login flow,
and then use
init for subsequent opens. If you want users to only interact
with the most up-to-date version of your data, you can exclusively use
asyncOpen. This incurs the cost of additional loading time and prevents
users from opening a realm while offline.
Sync Changes in the Background¶
If you want your app to update data in the background (while the app is minimized), iOS requires you to implement Background App Refresh. Enabling Background App Refresh minimizes the time it takes for the user to see the most recent data; without Background App Refresh, MongoDB Realm updates the data when the user launches the app, potentially resulting in noticeable lag.
To use the realm while the device is locked, you must adjust the file protection settings. See Use Realm When the Device Is Locked.
Suspend or Resume a Sync Session¶
Check Upload & Download Progress for a Sync Session¶
Check the Network Connection¶
MongoDB Realm's offline-first design means that you generally don't
need to check the current network connection state. That said, the
connectionState property is available if your app calls for some
indication of connection state.
Handle Sync Errors¶
While developing an application that uses Realm Sync, you should set an error handler. This error handler will detect and respond to any failed sync-related API calls.
Delete a Client Realm File¶
In some cases, you may want to completely delete a realm file from disk.
Realm avoids copying data into memory except when absolutely required. As a result, all objects managed by a realm have references to the file on disk. Before you can safely delete the file, you must ensure the deallocation of these objects:
- All objects read from or added to the realm
- All List and Results objects
- All ThreadSafeReference objects
- The realm itself
In practice, there are two safe times to delete the realm file:
- On application startup before ever opening the realm.
- After only having opened the realm within an explicit
autoreleasepool, which ensures deallocation of all of objects within it.
To perform a client reset, see Client Resets - iOS SDK.
Set the Client Log Level¶
See RLMSyncLogLevel for a description of each available log level. Note that more logging can negatively affect performance.
To diagnose and troubleshoot errors while developing your application, set the
log level to
trace. For production deployments, decrease the
log level for improved performance.