Docs Menu

Legacy Realm Sync Open Methods - iOS SDK

On this page

The examples on this page describe how to work with synced realms in iOS 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.

Note

The 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.

Tip
See also:

If you're using Swift 5.5 with iOS 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 Realm 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 connection.

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 MongoDB Realm 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.

Example

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.

Note

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. Use asyncOpen to sync the realm with the Realm app before opening it.

Example

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 case, 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.

Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.