托管同步会话 - Kotlin SDK
本页介绍同步会话以及如何使用 Flexible Sync 在应用程序中管理同步会话。 有关 Flexible Sync 的详细信息，请参阅App Services文档中的 Atlas Device Sync 。
同步会话
当您使用 Flexible Sync 时，Realm Kotlin SDK 会使用同步会话在背景与 Atlas 同步数据。每当您打开同步域时，同步会话就会启动。
val app = App.create(YOUR_APP_ID) val user = app.login(credentials) val config = SyncConfiguration.Builder(user, setOf(Task::class)) .build() // Open the synced realm val realm = Realm.open(config) // Sync session is now active // ... do something with the synced realm
同步会话管理以下内容：
上传和下载对 Realm 的更改
暂停和恢复同步
监控网络连接
您可以通过 realm.syncSession 属性访问单个同步 Realm 的 SyncSession 。
连接状态与会话状态
Kotlin SDK 在两个级别托管与 App Services 的通信：
连接状态：客户端设备和后端应用程序之间的网络连接状态。
session state ：单个用户的同步状态，可以在 SDK 中随意暂停和恢复（请参阅暂停和恢复同步会话部分）。
这两个状态都确定用户的本地更改是否同步到后端。 仅当SyncSession.ConnectionState为 CONNECTED且SyncSession.State为ACTIVE或DYING时，才会发生同步。
等待更改上传和下载
要异步等待所有更改从同步 Realm 上传到 Atlas，请调用uploadAllLocalChanges 。 上传所有更改后，此方法会返回true 。
要异步等待 Atlas 上的所有更改从 Device Sync 服务器下载到同步 Realm，请调用downloadAllServerChanges 。 下载所有更改后，此方法会返回true 。
您还可以在任一方法中包含一个可选的timeout参数，以确定返回false之前的最长时间。 请注意，即使返回false后，上传或下载也会在背景继续。
以下示例演示了如何在定义超时的情况下调用这两种方法：
// Wait to download all pending changes from Atlas realm.syncSession.downloadAllServerChanges(1.minutes) // Add data locally realm.write { this.copyToRealm(Task().apply { taskName = "Review proposal" assignee = "Emma" progressMinutes = 0 }) } // Wait for local changes to be uploaded to Atlas realm.syncSession.uploadAllLocalChanges(1.minutes)
暂停和恢复同步会话
要暂停会话同步，请调用syncSession.pause() 。 会话暂停时，Realm 不会与 Atlas 同步更改。
要恢复同步更改，请调用syncSession.resume()。
您必须为要暂停和重新启动同步会话的每个 Realm 手动调用syncSession.pause()和syncSession.resume() 。 一个会话的同步状态对其他打开的会话没有影响。
以下代码块演示了如何调用这些方法：
// Pause the sync session // Data that you write while session is paused does not sync to Atlas realm.syncSession.pause() // Add data locally realm.write { this.copyToRealm(Task().apply { taskName = "Submit expense report" assignee = "Kevin" progressMinutes = 0 }) } // Resume sync session // Local changes now sync to Atlas realm.syncSession.resume()
何时暂停同步会话
对于大多数应用程序，无需手动暂停和恢复同步会话。 但是，在某些情况下，您可能希望暂停或暂停同步会话：
您只想在用户执行特定操作后进行同步
您只想在一天中的特定时间进行同步
您不想在网络连接较差时尝试同步
您想要显式强制同步会话连接
在网络连接较差的情况下，不断尝试建立网络连接可能会耗尽用户的设备电池。
显式强制同步会话连接的情况最常见与离线一段时间有关。同步客户端尝试连接，一旦失败，就会Go指数退避状态。长时间离线后，客户端可能无法立即重新连接。 暂停和恢复同步会话会显式强制连接。
当您暂停同步会话时，请记住以下事项：
暂停同步会话会使其在两个方向上暂停。您的应用在设备上所做的更改不会与后端同步，对后端或其他设备上的数据的更改也不会同步到设备。 无法仅暂停上传或仅暂停下载。
如果您希望客户端永久停止与后端同步，请勿暂停同步会话。 要永久停止同步，请将同步 Realm 的内容复制到非同步 Realm，并在客户端中使用该非同步 Realm。
请勿在不确定的时间段或以月和年为单位的时间范围内通过暂停同步来停止同步。 该功能不是针对这些使用案例而设计或测试的。 以这种方式使用时，您可能会遇到一系列问题。
监控网络连接
您可以通过检查SyncSession.connectionState来获取当前网络连接的状态 属性。 这将返回一个ConnectionState枚举值，该值指示网络连接的状态。 可能的状态有： CONNECTED 、 DISCONNECTED或CONNECTING 。
if (realm.syncSession.connectionState == ConnectionState.CONNECTED) { Log.i("Connected to network") // ... do something }
使用connectionStateAsFlow监控网络连接的状态。 此属性返回ConnectionStateChange对象流，该对象流会在网络连接更改时更新。 您可以从 访问新旧ConnectionState ConnectionStateChange。
val connectionFlow = realm.syncSession.connectionStateAsFlow() connectionFlow.collect { ConnectionStateChange -> if (ConnectionStateChange.newState == ConnectionState.CONNECTED) { Log.i("Connected to Atlas Device Sync server") } }
手动重新连接所有同步会话
1.11.0 版本中的新增功能。
Realm 会自动检测设备何时在离线后重新获得连接，并尝试使用增量退避策略重新连接。
在Kotlin SDK版本 1.11.0 及更高版本中，您可以选择使用trigger () 而不是等待增量退避的持续时间。 如果您对网络状况有更准确的了解（例如，在 Android 上使用ConnectivityManager监控网络变化时）并且不想依赖 Realm 的自动重新连接检测，则这非常有用。 当设备关闭飞行模式时，SDK 还会自动调用此方法。
要手动trigger重新连接尝试，请调用App.Sync.reconnect() 方法，该方法可通过App.Sync接口访问。 与允许您访问单个 Realm 同步会话的SyncSession不同， App.Sync接口控制应用程序的所有同步会话。
app.sync.reconnect()
调用此方法时，SDK 会强制所有同步会话立即尝试重新连接，并重置用于增量退避的任何计时器。
重要
无法在套接字读取超时时间内重新连接
Realm 的内部默认套接字读取超时为 2 分钟，如果读取操作在 2 分钟窗口内未收到任何数据，Realm 将超时。 如果您在该窗口内调用App.Sync.reconnect() ，Kotlin SDK不会尝试重新连接。