Add Device Sync to an App
On this page
This page contains information about Device Sync, its basic concepts, and how to add Sync to a client app using Atlas Device SDK. Once you have added Sync to your app, you can access a synced database from the client.
Already familiar with Device Sync? Skip ahead to the Enable Device Sync in Atlas section to get started.
Device Sync
Device Sync synchronizes data between client devices and Atlas. Data is persisted on a device, even when offline. When the device has a network connection, Device Sync uploads and downloads data in the background and manages conflict resolution.
The data that syncs between your client app and Atlas is determined by a user's permissions to access eligible data. Eligible data is the intersection of:
Data model: your data type information
Subscription queries: the conditions that define what data to store
Permissions: the role-based permissions required to interact with data that meets the specified conditions
For a detailed explanation of Device Sync, refer to Get Started with Atlas Device Sync in the Atlas App Services documentation.
Data Model
The Device Sync data model defines the object types that you can sync. Every SDK object you sync requires a client-side and server-side schema:
Object schema: the object schema in your client app that defines your data in your preferred programming language.
App Services schema: the schema in Atlas App Services that defines your data in BSON.
Both schemas must be consistent with each other to sync data.
You can define the Device Sync data model in a client app first or in Atlas first:
To define your data model through your client app, you first define an object model directly in your client app code. Then, you can use Development Mode to generate a matching App Services schema automatically. Development Mode is a configuration setting that allows Device Sync to infer and update schemas based on client-side data models when you sync data from the client. The Enable Device Sync in Atlas section describes how to enable Device Sync with Development Mode in your client app.
If you already have data in Atlas and would prefer to define your data model through Atlas first, refer to Sync Data in Atlas with a Client Application in the App Services documentation.
Note
Data Model Mapping with Device Sync
To learn more about how data maps between the client and Atlas, refer to Model Data with Device Sync.
Subscriptions
A subscription is a client-side query to objects in your data model. Device Sync only syncs objects that match the query. You can define multiple queries in your client app. You must define at least one query for each object type in your data model.
Device Sync ensures that your client-side queries are consistent with your App Services schema through queryable fields. These are the fields from your data model that can be used in a subscription query. You cannot define a subscription using a field that isn't in your queryable fields.
When Development Mode is enabled, Device Sync automatically adds the fields that appear in your client queries as queryable fields. You can also manually add and remove queryable fields through the Atlas UI. For more information, refer to Queryable Fields in the App Services documentation.
User Permissions
App Services uses role-based permissions to control the data that users can read and write:
When a user has read permissions, Device Sync downloads data matching the subscription query to the client.
When a user has write permissions, Device Sync permits writes to the synced data and uploads locally-written data to the backend.
You can define and manage roles in the Atlas UI. When you enable Sync, you select a default role, which you can modify later. For more information, refer to Role-based Permissions in the App Services documentation.
Prerequisites
You can add Device Sync to an app in several ways, depending on the state of your app and your data. This guide describes how to add Sync to an existing client app using Development Mode. This guide assumes that your app already uses Atlas Device SDK and that you have already defined a data model in your client code.
Because Device Sync connects your client app to the Atlas backend through an Atlas App Services App, you need the following before you can get started:
An Atlas App Services App with authentication enabled. To learn how, refer to Create an App Services App in the App Services documentation.
Confirm that your app can connect to Atlas. To learn how, refer to Connect to Atlas.
Example Data Model
Enable Device Sync in Atlas
You must first enable Device Sync in Atlas before you can add Sync to your client app.
To enable Device Sync in your App, complete the steps outlined in Configure and Enable Atlas Device Sync procedure in the App Services documentation.
During this process, you can choose whether to enable Development Mode and you can select a default role for your app users. For more information on the available settings, refer to Sync Settings in the App Services documentation.
Tip
We recommend enabling Development Mode when you first enable Sync, and then disabling it before your app goes to production. For more information, refer to Development Mode in the App Services documentation.
For our example app, we enable Device Sync with Development Mode, and then add the "User can read and write all data" default role. This means that, for an authorized user with a network connection, Device Sync downloads eligible data to the client and Atlas permits writes to the client and then syncs them the backend. To learn more about what happens when an authorized user does not have a network connection, refer to Write Data to a Synced Database.
Add Sync to Your Client App
After you've configured and enabled Sync in Atlas, you can add Sync to your client app.
Connect to Atlas
Pass your App ID to an App client to initialize the App. To get
your App ID from the App Services UI, refer to
Find Your App ID in the
App Services documentation.
For our example app, we pass our App ID to initialize an App with
default configuration values:
For more information on accessing and configuring the App client, refer to Connect to Atlas.
Authenticate a User
Authenticate a user in your client app using an authentication provider that you have enabled.
For our example app, we log in a user using anonymous authentication:
For more information on authenticating users in your app, refer to Authenticate Users.
Define the Sync Configuration
Important
Object Types in Your Schema
The Sync configuration schema must include all object types that you want to work with in your synced database. If you try to reference or write an object of an object type that isn't in your schema, the SDK returns a schema validation error.
Open the Synced Database
Use the defined configuration to open the synced database. When the database is opened successfully, the initial subscription query determines which data to sync to the client. If Development Mode is enabled, Device Sync automatically adds any queryable fields based on the query defined in your schema.
Use the Synced Database
Now that you've opened the synced database, you can work with your data in the database. While you work with data on the device, a background thread efficiently integrates, uploads, and downloads changesets.
The syntax to perform read and write operations and watch for changes is identical to the syntax for non-synced databases. However, there are additional considerations when writing data to a synced database. For more information, refer to Write Data to a Synced Database.
If our write operation didn't match the query or the current user didn't have the requisite permissions, then the SDK reverts the write with a non-fatal error operation called a compensating write.
Important
When Using Sync, Avoid Synchronous Writes on the Main Thread
The fact that the SDK performs sync integrations on a background thread means that if you write to your database synchronously on the main thread, there's a small chance your UI could appear to hang as it waits for the background sync thread to finish a write transaction. Therefore, it's a best practice not to write on the main thread when using Device Sync. Instead, use your language's implementation of the asynchronous write API.
Every write transaction for a subscription set has a performance cost. If you need to make multiple updates to a database object during a session, consider keeping edited objects in memory until all changes are complete. This improves sync performance by only writing the complete and updated object to your database instead of every change.
Next Steps
Once your app is successfully syncing the desired data to Atlas, you can learn more about how to use Sync in the SDK:
Configure & Open a Synced Database: Learn about the available App client configuration options, such as providing custom request headers, connecting to Edge Server, or platform-idiomatic configuration options.
Manage Sync Subscriptions: Learn how to define and manage the subscription queries in your app.
Write Data to a Synced Database: Learn more about how to write to a synced database, how to handle compensating write errors, and how to group writes for improved performance.
Manage Sync Sessions: Learn how to manage communication with Atlas through sync sessions.
Handle Sync Errors: Learn how to handle sync errors that can occur, including client resets.