Agregar sincronización de dispositivos a una aplicación - SDK de Kotlin

Sincronización de dispositivos

Device Sync sincroniza los datos entre los dispositivos cliente y Atlas. Los datos se conservan en el dispositivo, incluso sin conexión. Cuando el dispositivo tiene conexión de red, Device Sync carga 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 datos que cumplen 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 añadir Device Sync a una aplicación de varias maneras, según el estado de la aplicación y los datos. Esta guía describe cómo añadir Sync a una aplicación cliente existente mediante el modo de desarrollo. Se asume que tu aplicación utiliza el SDK de Kotlin de Realm y que ya has definido un modelo de datos en el código cliente.

Debido a que Device Sync conecta su aplicación cliente al backend de App Services a través de una aplicación Atlas App Services, debe seguir estos pasos antes de poder comenzar:

1. Una aplicación de Atlas App Services con autenticación habilitada. Para saber cómo hacerlo, consulta "Crear una aplicación de App Services" en la documentación de App Services.

2. Confirma que tu aplicación pueda conectarse al backend de App Services. Para saber cómo, consulta Conectarse a Atlas App Services - SDK de Kotlin.

Acerca de los ejemplos de 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

Primero debe habilitar la sincronización de dispositivos en su aplicación Atlas App Services antes de poder agregar la sincronización a su aplicación cliente.

Para habilitar la sincronización de dispositivos en su aplicación, complete los pasos descritos en el procedimiento Configurar y habilitar la sincronización de dispositivos Atlas en la documentación de Servicios de la aplicación.

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

Utilice el reino

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:

• Ambos objetos están dentro de los parámetros de la consulta de suscripción (el List es propiedad del usuario y el Item está incompleto).

• El usuario actual tiene permiso para escribir datos en el backend (el rol permite a los usuarios autorizados leer y escribir 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.

• Escribir datos en un reino sincronizado - SDK de Kotlin: obtenga más información sobre cómo escribir en un reino sincronizado, cómo manejar errores de escritura compensatorios y cómo agrupar escrituras para mejorar el rendimiento.

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