Add Device Sync to an App - Kotlin SDK

Device Sync

Device Sync sincroniza los datos entre los dispositivos del cliente y Atlas. Los datos se conservan en un dispositivo, incluso cuando están fuera de línea. Cuando el dispositivo tiene una conexión a la red, Device Sync sube y descarga datos en segundo plano y gestiona la resolución de conflictos.

Los datos que se sincronizan entre tu aplicación cliente y Atlas se determinan por los permisos de un usuario para acceder a datos elegibles. Los datos elegibles son la intersección de:

• Modelo de datos: información sobre su tipo de datos

• Consultas de suscripción: las condiciones que definen qué datos almacenar

• Permisos: los permisos basados en roles necesarios para interactuar con los datos que cumplen con las condiciones especificadas

Para obtener una explicación detallada de la sincronización de dispositivos, consulte Introducción a la sincronización de dispositivos Atlas en la documentación de Atlas App Services.

Requisitos previos

Puedes agregar Device Sync a una aplicación de varias maneras, dependiendo del estado de tu aplicación y tus datos. Esta guía describe cómo agregar la sincronización a una aplicación cliente existente utilizando el modo de desarrollo. Esta guía asume que tu aplicación usa el SDK Realm Kotlin y que ya has definido un modelo de datos en tu código cliente.

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. Confirme que su aplicación pueda conectarse al backend de App Services. Para aprender cómo, consulta Conectarse a Atlas App Services - Kotlin SDK.

Acerca de los ejemplos en esta página

Los ejemplos de esta página se refieren a una aplicación Kotlin Todo de ejemplo con un modelo de datos ya definido que incluye una List objeto que contiene una lista de Item objetos:

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
}

Habilitar la sincronización de dispositivos en los servicios de aplicaciones

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.

Durante este proceso, puede elegir si desea habilitar el modo de desarrollo y seleccionar un rol predeterminado para los usuarios de su aplicación. Para obtener más información sobre las opciones de configuración disponibles, consulte "Configuración de sincronización" en la documentación de App Services.

Para nuestra aplicación de ejemplo, habilitamos la Sincronización de Dispositivos con el Modo de Desarrollo y, a continuación, añadimos el rol predeterminado "El usuario puede leer y escribir todos los datos". Esto significa que, para un usuario autorizado con conexión de red, la Sincronización de Dispositivos descarga los datos válidos al cliente y Atlas permite las escrituras en el cliente y, a continuación, las sincroniza con el backend. Para obtener más información sobre qué sucede cuando un usuario autorizado no tiene conexión de red, consulte Compensación de Escrituras.

Agregar sincronización a tu aplicación cliente

Después de haber configurado y habilitado la sincronización en Atlas App Services, puede agregar la sincronización a su aplicación cliente.

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

Ahora que has abierto el realm configurado y sincronizado, puedes trabajar con sus datos en el realm. Mientras trabajas con datos locales, un hilo en segundo plano integra de forma eficiente, sube y descarga conjuntos de cambios.

La sintaxis para leer, guardar y ver los cambios es idéntica a la sintaxis de los realms no sincronizados. Sin embargo, hay consideraciones adicionales al escribir datos en un realm sincronizado. Para obtener más información, consulta Escribir datos en un Synced Realm: Kotlin SDK.

Para nuestra aplicación de ejemplo, escribimos un nuevo objeto List y Item, luego los copiamos al reino sincronizado:

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

Los objetos se escriben correctamente en el dispositivo y luego se sincronizan con Atlas porque:

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

• El usuario actual tiene permiso para guardar datos en el backend (el rol permite a los usuarios autorizados leer y guardar todos los datos).

Si nuestra operación de escritura no coincide con la consulta o el usuario actual no tiene los permisos necesarios, entonces Realm revierte la escritura con una operación de error no fatal llamada escritura compensatoria.

Próximos pasos

Una vez que su aplicación esté sincronizando exitosamente los datos deseados con Atlas, puede obtener más información sobre cómo usar Sync con el SDK de Kotlin:

• Configurar y abrir un reino sincronizado - SDK de Kotlin: obtenga información sobre las opciones de configuración del cliente de aplicación disponibles, como establecer un nombre de aplicación de depuración, proporcionar encabezados de solicitud personalizados o especificar un despachador.

• Administrar suscripciones de sincronización - SDK de Kotlin: aprenda a definir y administrar las consultas de suscripción en su aplicación.

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

• Gestione una sesión de sincronización - Kotlin SDK: Aprende a gestionar la comunicación con App Services a través de sesiones de sincronización.

• Manejar errores de sincronización - SDK de Kotlin: aprenda a manejar errores de sincronización que pueden ocurrir, incluidos los reinicios del cliente.