Add Device Sync to an App - Kotlin SDK

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.

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 uses the Realm Kotlin SDK and that you have already defined a data model in your client code.

Because Device Sync connects your client app to the App Services backend through an Atlas App Services App, you need to following before you can get started:

1. An Atlas App Services App with authentication enabled. To learn how, refer to Create an App Services App in the App Services documentation.

2. Confirm that your app can connect to the App Services backend. To learn how, refer to Connect to Atlas App Services - Kotlin SDK.

About the Examples on this Page

The examples on this page refer to an example Kotlin Todo app with an already-defined data model that includes a List object containing a list of Item objects:

class List : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var ownerId: String = ""
    var items: RealmList<Item> = realmListOf()
}
class Item : RealmObject {
    @PrimaryKey
    var _id: ObjectId = ObjectId()
    var name: String = ""
    var complete: Boolean = false
}

Enable Device Sync in App Services

You must first enable Device Sync in your Atlas App Services App 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.

For our example app, we enable Device Sync with Development Mode, and then add the default "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 Compensating Writes.

Add Sync to Your Client App

After you've configured and enabled Sync in Atlas App Services, you can add Sync to your client app.

// Replace `YOUR_APP_ID` with your Atlas App ID
val app = App.create(YOUR_APP_ID)

// Authenticate the Atlas App Services user
val myAuthenticatedUser = app.login(Credentials.anonymous())

// Define the configuration for the synced realm
val config =
    // Pass the authenticated user and the set of
    // all objects types you want to be able to sync
    SyncConfiguration.Builder(
        user = myAuthenticatedUser,
        schema = setOf(List::class, Item::class)
    )
        // Define an initial subscription with queries that include
        // the user's lists with incomplete items
        .initialSubscriptions{ realm ->
            add(realm.query<List>("ownerId == $0", myAuthenticatedUser.id),
                name = "user-lists"
            )
            add(realm.query<Item>("complete = false"),
                name = "incomplete-items"
            )
        }
        .build()

// Open the synced realm with the defined configuration
val realm = Realm.open(config)
Log.v("Successfully opened synced realm: ${realm.configuration.name}")
// Wait for initial subscriptions to sync to Atlas
realm.subscriptions.waitForSynchronization()

Use the Realm

Now that you've open the configured synced realm, you can work with your data in the realm. While you work with local data, a background thread efficiently integrates, uploads, and downloads changesets.

The syntax to read, write, and watch for changes is identical to the syntax for non-synced realms. However, there are additional considerations when writing data to a synced realm. For more information, refer to Write Data to a Synced Realm - Kotlin SDK.

For our example app, we write a new List and Item object, then copy them to the synced realm:

// Write List and Item objects to the synced realm
// Objects that match the subscription query are synced to Atlas
realm.write {
    val list = List().apply {
        name = "My Todo List"
        ownerId = myAuthenticatedUser.id
        items.add(Item().apply {
            name = "Check email"
            complete = false
        })
    }
    copyToRealm(list)
}
realm.syncSession.uploadAllLocalChanges(30.seconds)

The objects successfully write to the device, then sync to Atlas because:

• Both objects are within the parameters of the subscription query (the List is owned by the user and the Item is incomplete).

• The current user has permission to write data to the backend (the role allows authorized users to read and write all data).

If our write operation didn't match the query or the current user didn't have the requisite permissions, then Realm reverts the write with a non-fatal error operation called a compensating write.

Next Steps

Once your app is successfully syncing the desired data to Atlas, you can learn more about how to use Sync with the Kotlin SDK:

• Configure & Open a Synced Realm - Kotlin SDK: Learn about the available App client configuration options, such as setting a debug app name, providing custom request headers, or specifying a dispatcher.

• Manage Sync Subscriptions - Kotlin SDK: Learn how to define and manage the subscription queries in your app.

• Write Data to a Synced Realm - Kotlin SDK: Learn more about how to write to a synced realm, how to handle compensating write errors, and how to group writes for improved performance.

• Manage a Sync Session - Kotlin SDK: Learn how to manage communication with App Services through sync sessions.

• Handle Sync Errors - Kotlin SDK: Learn how to handle sync errors that can occur, including client resets.