On this page
- Open A Synced Realm Offline
- 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
The examples on this page describe how to work with synced realms in Swift SDK versions prior to 10.15.0. Alternately, if you're building apps for iOS targets prior to 15.0, with Swift versions older than 5.5, or with Objective-C, you can use these methods and code examples to work with realms asynchronously.
OpenBehavior enum, and the ability to specify whether to download
data before opening a realm, do not
apply to the legacy examples on this page. If you want to require
downloading changes before opening a realm with this older syntax,
you must use
asyncOpen, which always downloads changes before
opening a realm.
If you're using Swift 5.5 with Swift SDK 10.15.0 or newer, see the Sync Changes Between Devices page.
You can work with synced realms offline if the user credentials are
cached and you use App Services initializers to open the realms.
If you use
asyncOpen instead of initializers to open the realm,
the user always has the most up-to-date data, but must have a network
The first time a user opens a realm, you must authenticate the user. Upon this initial login, Realm caches login credentials. On subsequent opens, check for a logged-in user, and then open new realms. You can skip 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 Atlas App Services before opening a synced realm on device.
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 must 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.
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 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 must 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.
In some apps, such as games, you might want the user to always have current data.
asyncOpen to sync the realm with the 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 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.