将 Device Sync 添加到应用程序 - Kotlin SDK

设备同步

Device Sync在客户端设备和Atlas之间同步数据。 即使离线，数据也会持久保存在设备上。 当设备有网络连接时， Device Sync会在背景上传和下载数据并管理冲突解决。

在客户端应用和Atlas之间同步的数据取决于用户访问权限合格数据的权限。 符合条件的数据是以下各项的交集：

• 数据模型：数据类型信息

• 订阅查询：定义要存储哪些数据的条件

• 权限：与满足指定条件的数据进行交互所需的基于角色的权限

有关Device Sync的详细说明，请参阅Atlas App Services文档中的Atlas Device Sync入门。

先决条件

您可以通过多种方式将 Device Sync 添加到应用程序，具体取决于应用程序和数据的状态。 本指南介绍如何使用开发模式将同步添加到现有客户端应用程序。 本指南假定您的应用使用 Realm Kotlin SDK，并且您已经在客户端代码中定义了数据模型。

由于Device Sync通过Atlas App Services应用程序将客户端应用程序连接到Atlas App Services后端，因此在开始之前，您需要执行以下操作：

1. 启用身份验证的 Atlas App Services App。 要了解如何操作，请参阅 App Services AppAtlas App Services文档中的 创建 。

2. 确认您的应用可以连接到Atlas App Services后端。 要了解操作方法，请参阅连接到 Atlas App Services - Kotlin SDK。

关于本页中的示例

本页上的示例指的是一个示例 Kotlin Todo 应用，该应用具有已定义的Realm 数据模型，其中包括一个 List对象，而该对象包含Item对象列表：

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
}

在App Services中启用Device Sync

您必须先在 Atlas App Services App 中启用 Device Sync，然后才能将 Sync 添加到客户端应用程序。

Device Sync要在您的应用中启用 Atlas Device Sync，请完成Atlas App Services 文档中 配置和启用 过程中概述的步骤。

在此进程，您可以选择是否启用开发模式，也可以为应用用户选择默认角色。 有关可用设置的详细信息，请参阅App Services文档中的同步设置。

对于我们的示例应用，我们在开发模式下启用Device Sync ，然后添加默认的“用户可以读取和写入所有数据”默认角色。 这意味着，对于具有网络连接的授权用户， Device Sync会将符合条件的数据下载到客户端， Atlas允许写入到客户端，然后将其同步到后端。 要详细学习；了解授权用户没有网络连接时会发生什么情况，请参阅补偿写入。

将 Sync 添加到客户端应用程序

在 Atlas App Services 中配置并启用 Sync 后，您可以将 Sync 添加到客户端应用程序。

// 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()

使用 Realm

现在您已打开配置的同步域，可以在该域中处理数据。 当您使用本地数据时，背景线程可以高效地集成、上传和下载变更集。

读取、写入和监视变更的语法与非同步 Realm 的语法相同。 但是，将数据写入同步域时，还需要注意其他事项。 有关更多信息，请参阅将数据写入同步Realm - Kotlin SDK。

对于示例应用，我们写入新的List和Item对象，然后将它们复制到同步域：

// 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)

对象成功写入设备，然后同步到 Atlas，因为：

• 这两个对象都在订阅查询的参数内（ List由用户拥有， Item不完整）。

• 当前用户有向后端写入数据的权限（角色允许授权用户读取和写入所有数据）。

如果我们的写入操作与查询不匹配，或者当前用户没有必要的权限， Realm就会使用称为补偿写入。

后续步骤

应用成功将所需数据同步到 Atlas 后，您可以详细了解如何通过 Kotlin SDK 使用 Sync：

• 配置并打开同步Realm - Kotlin SDK ：了解可用的应用客户端配置选项，例如设置调试应用名称、提供自定义请求标头或指定调度程序。

• 管理同步订阅 - Kotlin SDK ：了解如何在应用中定义和管理订阅查询。

• 将数据写入同步Realm - Kotlin SDK ：了解详情了解如何写入同步域、如何处理补偿写入错误以及如何对写入进行群组以提高性能。

• 管理同步会话 - Kotlin SDK ：了解如何通过同步会话管理与App Services的通信。

• 处理同步错误 - Kotlin SDK ：了解如何处理可能发生的同步错误，包括客户端重置。