Gestionar errores de sincronización - Kotlin SDK

Errores de sincronización irrecuperables

Una excepción de sincronización irrecuperable (UnrecoverableSyncException) ocurre cuando la sincronización del dispositivo falla gravemente. Esto suele indicar un error en el cliente o la aplicación conectada.

Cuando se produce un error de sincronización irrecuperable, debes informar del problema al usuario final. Infórmale que la sincronización del dispositivo no funcionará hasta que se resuelva el problema. Lo mejor es enviarte una alerta para que puedas revisar los registros de la aplicación y solucionar el problema lo antes posible.

Errores de tipo de sincronización incorrecto

Una WrongSyncTypeException ocurre cuando el cliente y la aplicación usan protocolos de sincronización diferentes.

El SDK admite dos tipos de sincronización: sincronizaciónflexible y sincronización basada en particiones. Cuando un cliente se conecta a una aplicación con un tipo de sincronización que no coincide con el de la aplicación, se produce un error de tipo de sincronización incorrecto.

Para solucionar un error de tipo de sincronización incorrecto, actualice el cliente para que use un tipo de sincronización que coincida con el backend. Esto probablemente requerirá que el usuario actualice a una nueva versión de la aplicación que contenga la corrección.

Errores de consulta de sincronización flexible incorrecta

Se produce una BadFlexibleSyncQueryException al intentar suscribirse a una consulta de sincronización flexible no compatible con el backend de la aplicación. Esto puede ocurrir cuando:

• query un campo que no se especifique como un campo consultable en tu configuración flexible de sincronizar

• Cree una consulta de sincronización flexible utilizando operadores no compatibles con la sincronización flexible.

Para solucionar un error de consulta de sincronización flexible, actualice su cliente para que use una consulta de sincronización compatible con la configuración de su aplicación. Esto probablemente requerirá que el usuario actualice a una nueva versión de su aplicación que contenga la corrección.

Reinicios de cliente automáticos vs. manuales

Las estrategias de restablecimiento automático restauran el archivo de dominio local a un estado sincronizable sin cerrarlo ni perder notificaciones. Las diferencias se basan en cómo gestionan los cambios en el dispositivo que aún no se han sincronizado con el backend. Las siguientes estrategias implementan la interfaz AutomaticClientResetStrategy y admiten restablecimientos automáticos de clientes:

• Recuperar o descartar los cambios que no estén sincronizados (por defecto): el gestor de restablecimiento del cliente primero intenta recuperar los cambios no sincronizados. Si la recuperación falla, este gestor recurre a la estrategia de descartar los cambios no sincronizados, lo que borra permanentemente todos los cambios locales no sincronizados. Si la estrategia de descartar los cambios no sincronizados falla, el gestor recurre a la recuperación manual.

• Recuperar cambios no sincronizados: El controlador de restablecimiento del cliente primero intenta recuperar los cambios no sincronizados. Si la recuperación falla, este controlador recurre a la recuperación manual.

• Descartar cambios no sincronizados: Esta estrategia elimina permanentemente todos los cambios locales no sincronizados realizados desde la última sincronización exitosa. Si el descarte falla, este controlador recurre a la recuperación manual. Se recomienda este modo para gestionar cualquier recuperación manual de datos.

Si su aplicación requiere una lógica de reinicio de cliente específica que no se puede manejar automáticamente, es posible que desee o necesite agregar un controlador de reinicio de cliente manual mediante la interfaz ManuallyRecoverUnsyncedChangesStrategy:

• Recuperar manualmente los cambios no sincronizados: Le permite implementar su propia estrategia de recuperación manual. La recuperación manual es la única estrategia que no realiza un restablecimiento automático del cliente. Este modo le permite realizar una copia de seguridad únicamente de su dominio. Recomendamos usar la estrategia "descartar cambios no sincronizados" para gestionar la recuperación manual, si es posible.

Restablecimiento del cliente con recuperación

La recuperación de cliente es una función que se habilita de forma predeterminada cuando configura la sincronización del dispositivo.

Para usar Client Recovery, configure su reino con la estrategia de recuperar cambios no sincronizados o recuperar o descartar cambios no sincronizados, y Realm administrará automáticamente el proceso de restablecimiento del cliente en la mayoría de los casos:

• El cliente puede recuperar cambios no sincronizados cuando no hay cambios de esquema o hay cambios de esquema que no interrumpen el proceso.

• La recuperación automática del cliente no puede ocurrir cuando la aplicación realiza cambios importantes en el esquema. Un cambio importante es un cambio que se puede realizar en el esquema del servidor y que requiere una acción adicional para su gestión. En este caso, la recuperación del cliente recurre a un restablecimiento manual del cliente tras un error.

  Para obtener información sobre cambios de esquema disruptivos y no disruptivos, consulte Referencia rápida sobre cambios disruptivos y no disruptivos en la documentación de App Services.

Reglas de recuperación del cliente

Cuando la Recuperación de Cliente está habilitada, estas reglas determinan cómo se integran los objetos, incluyendo la resolución de conflictos cuando tanto el backend como el cliente realizan cambios en el mismo objeto:

• Se sincronizan los objetos creados localmente que no se sincronizaron antes del reinicio del cliente.

• Si se elimina un objeto en el servidor, pero se modifica en el cliente en recuperación, la eliminación tiene prioridad y el cliente descarta la actualización.

• Si se elimina un objeto en el cliente en recuperación, pero no en el servidor, el cliente aplica la instrucción de eliminación del servidor.

• En el caso de actualizaciones conflictivas en el mismo campo, se aplica la actualización del cliente.

Recuperar o descartar cambios no sincronizados

La estrategia de recuperar o descartar cambios no sincronizados intenta recuperar automáticamente todos los cambios locales no sincronizados durante el restablecimiento del cliente. Para recuperar los cambios no sincronizados, laRecuperación del Cliente debe estar habilitada en la aplicación de Servicios de Aplicaciones (está habilitada de forma predeterminada).

Si el proceso de recuperación automática falla, se recurre a una estrategia de descartar cambios no sincronizados. Si ese proceso falla, se recurre de nuevo a una estrategia de restablecimiento manual.

Esta estrategia proporciona el proceso de recuperación más robusto. Es el comportamiento predeterminado de restablecimiento del cliente si no se especifica una estrategia de restablecimiento.

Para personalizar el uso de la estrategia de recuperación o descarte de cambios no sincronizados, defina una clase que implemente la interfaz RecoverOrDiscardUnsyncedChangesStrategy.

La interfaz proporciona los siguientes métodos de devolución de llamada:

• onBeforeReset: Se invoca antes del reinicio del cliente. Proporciona una instancia del dominio antes del reinicio. Puede usar esta devolución de llamada para notificar al usuario antes de que comience el reinicio del cliente.

• onAfterRecovery: Se invoca solo si el restablecimiento automático se completa correctamente. Proporciona una instancia anterior de solo lectura del dominio y una instancia mutable del dominio final. Puede usar esta devolución de llamada para notificar al usuario que el restablecimiento del cliente se ha completado.

• onAfterDiscard: Se invoca solo si el restablecimiento automático del cliente falla y la estrategia local de descarte se ejecuta correctamente. Si la estrategia de descarte falla, esta devolución de llamada no se invoca. Proporciona una instancia anterior de solo lectura del dominio y una instancia mutable del dominio final. Puede usar esta devolución de llamada para notificar al usuario que el restablecimiento se ha completado.

• onManualResetFallback: Se invoca solo si la recuperación automática y la estrategia de descarte fallan. Descarta los cambios locales y permite crear una copia de seguridad del dominio local. Implemente esta devolución de llamada para gestionar el error de restablecimiento, como se explica en la sección "Respaldo de recuperación manual".

El siguiente ejemplo muestra RecoverOrDiscardUnsyncedChangesStrategy y cada una de sus devoluciones de llamada:

val clientResetStrategy = object : RecoverOrDiscardUnsyncedChangesStrategy {
    override fun onBeforeReset(realm: TypedRealm) {
        Log.i("Client reset: attempting to automatically recover unsynced changes")
    }
    // Executed before the client reset begins.
    // Can be used to notify the user that a reset will happen.
    override fun onAfterRecovery(before: TypedRealm, after: MutableRealm) {
        Log.i("Client reset: successfully recovered all unsynced changes")
    }
    // Executed if and only if the automatic recovery has succeeded.
    override fun onAfterDiscard(before: TypedRealm, after: MutableRealm) {
        Log.i("Client reset: recovery unsuccessful, attempting to manually recover any changes")
        // ... Try to manually recover any unsynced data
        manuallyRecoverUnsyncedData(before, after)
    }
    // Executed if the automatic recovery has failed,
    // but the discard unsynced changes fallback has completed successfully.
    override fun onManualResetFallback(
        session: SyncSession,
        exception: ClientResetRequiredException
    ) {
        Log.i("Client reset: manual reset required")
        // ... Handle the reset manually here
    }
    // Automatic reset failed.
}

Recuperar cambios no sincronizados

La estrategia de recuperación de cambios no sincronizados intenta recuperar automáticamente todos los cambios locales no sincronizados durante el restablecimiento del cliente. Para ello, laRecuperación del Cliente debe estar habilitada en la aplicación de Servicios de Aplicaciones (está habilitada de forma predeterminada).

Sin embargo, a diferencia de la estrategia de recuperar y descartar cambios no sincronizados, esta no descarta los cambios locales si la recuperación automática falla. En su lugar, recupera los cambios manualmente. Puedes elegir esta estrategia de restablecimiento del cliente si tu aplicación no puede perder datos no sincronizados.

Para utilizar la estrategia de recuperación de cambios no sincronizados, defina un controlador que implemente la interfaz RecoverUnsyncedChangesStrategy.

La interfaz proporciona los siguientes métodos de devolución de llamada:

• onBeforeReset: Se invoca antes del reinicio del cliente. Proporciona una instancia del dominio antes del reinicio. Puede usar esta devolución de llamada para notificar al usuario antes de que comience el reinicio del cliente.

• onAfterReset: Se invoca solo si el restablecimiento automático se completa correctamente. Proporciona una instancia anterior de solo lectura del dominio y una instancia mutable del dominio final. Puede usar esta devolución de llamada para notificar al usuario que el restablecimiento del cliente se ha completado.

• onManualResetFallback: Se invoca solo si la recuperación automática falla. Descarta los cambios locales y permite crear una copia de seguridad del dominio local. Implemente esta devolución de llamada para gestionar el error de restablecimiento, como se explica en la sección "Respaldo de recuperación manual".

El siguiente ejemplo muestra RecoverUnsyncedChangesStrategy y cada una de sus devoluciones de llamada:

val clientResetStrategy = object : RecoverUnsyncedChangesStrategy {
    override fun onBeforeReset(realm: TypedRealm) {
        Log.i("Client reset: attempting to automatically recover unsynced changes")
    }
    // Executed before the client reset begins.
    // Can be used to notify the user that a reset will happen.
    override fun onAfterReset(before: TypedRealm, after: MutableRealm) {
        Log.i("Client reset: successfully recovered all unsynced changes")
    }
    // Executed after the client reset is complete.
    // Can be used to notify the user that the reset is done.
    override fun onManualResetFallback(
        session: SyncSession,
        exception: ClientResetRequiredException
    ) {
        Log.i("Client reset: manual reset required")
        // ... Handle the reset manually here
    }
    // Automatic reset failed.
}

Descartar cambios no sincronizados

La estrategia de descartar cambios no sincronizados elimina permanentemente todos los cambios locales no sincronizados realizados desde la última sincronización exitosa. Esta estrategia restaura el archivo de dominio local a un estado sincronizable sin cerrarlo y manteniendo las notificaciones funcionando correctamente. Si este proceso falla, se recurre a una estrategia de restablecimiento manual.

Esta es la estrategia recomendada para manejar cualquier recuperación manual de datos.

Es posible elegir esta estrategia cuando la aplicación requiere una lógica de recuperación de cliente que no es coherente con las reglas de recuperación de cliente de Device Sync o cuando no desea recuperar datos no sincronizados.

Para utilizar la estrategia de descartar cambios no sincronizados, defina un controlador que implemente la interfaz DiscardUnsyncedChangesStrategy.

La interfaz proporciona los siguientes métodos de devolución de llamada:

• onBeforeReset: Se invoca antes del reinicio del cliente. Proporciona una instancia del dominio antes del reinicio. Puede usar esta devolución de llamada para notificar al usuario antes de que comience el reinicio del cliente.

• onAfterReset: Se invoca solo si se completa el restablecimiento. Proporciona una instancia anterior de solo lectura del dominio y una instancia mutable del dominio final. Puede usar esta devolución de llamada para notificar al usuario que el restablecimiento se ha completado.

• onManualResetFallback: Se invoca solo si la recuperación automática y la estrategia de descarte fallan. Descarta los cambios locales y permite crear una copia de seguridad del dominio local. Implemente esta devolución de llamada para gestionar el error de restablecimiento, como se explica en la sección "Respaldo de recuperación manual".

El siguiente ejemplo muestra DiscardUnsyncedChangesStrategy y cada una de sus devoluciones de llamada:

val clientResetStrategy = object : DiscardUnsyncedChangesStrategy {
    override fun onBeforeReset(realm: TypedRealm) {
        Log.i("Client reset: attempting to discard any unsynced changes")
    }
    // Executed before the client reset begins.
    // Can be used to notify the user that a reset will happen.
    override fun onAfterReset(before: TypedRealm, after: MutableRealm) {
        Log.i("Client reset: attempting to manually recover any unsynced changes")
        // ...Try to manually recover any unsynced data 
        manuallyRecoverUnsyncedData(before, after)
    }
    // Executed after the client reset is complete.
    // Can be used to notify the user that the reset is done.
    override fun onManualResetFallback(
        session: SyncSession,
        exception: ClientResetRequiredException
    ) {
        Log.i("Client reset: manual reset required")
        // ... Handle the reset manually here
    }
    // Automatic reset failed.
    override fun onError(
        session: SyncSession,
        exception: ClientResetRequiredException
    ) {
        // No-op
    }
    // Deprecated. onManualResetFallback() used instead.
}

Recuperación manual alternativa

Si el restablecimiento del cliente no puede completarse automáticamente, como cuando hay cambios de esquema importantes, el proceso de restablecimiento del cliente pasa a un controlador de errores manual.

Esto puede ocurrir en cualquiera de las estrategias de reinicio automático del cliente:

• Recuperar cambios no sincronizados

• Recuperar o descartar cambios no sincronizados

• Descartar cambios no sincronizados

Debe proporcionar una implementación de restablecimiento manual del cliente en la devolución de llamada onManualResetFallback del controlador de restablecimiento del cliente para estas estrategias.

La opción de reinicio manual descarta los cambios locales y le permite crear una copia de seguridad del dominio local mediante el método ClientResetRequiredException.executeClientReset.

override fun onManualResetFallback(
    session: SyncSession,
    exception: ClientResetRequiredException
) {
    Log.i("Client reset: manual reset required")
    // You *MUST* close any open Realm instance
    closeAllRealmInstances();
    // `executeClientReset()` creates a backup
    exception.executeClientReset();
    // (Optional) Send backup for analysis
    handleBackup(recoveryFilePath);
    // ... Restore the App state by reopening the realm 
    // or restarting the app
}

Recuperar manualmente los cambios no sincronizados

Utilice la estrategia de recuperación manual de cambios no sincronizados para los casos poco frecuentes en los que necesite personalizar el proceso de recuperación de datos. Recomendamos usar la estrategia "Descartar cambios no sincronizados" siempre que sea posible para gestionar la recuperación manual de datos. Solo debe elegir esta estrategia si la lógica de recuperación automática no es adecuada para su aplicación y no puede descartar los datos locales no sincronizados.

Para utilizar la estrategia de recuperación manual, defina su propio controlador de restablecimiento de cliente utilizando la interfaz ManuallyRecoverUnsyncedChangesStrategy.

Antes de usar este método,debe cerrar todas las instancias del dominio que está restableciendo. Las escrituras en el archivo del dominio realizadas después de la devolución de llamada de recuperación manual y antes de que se ejecute el restablecimiento del cliente no se sincronizarán. También le recomendamos crear una copia de seguridad del archivo e informar de la excepción.

Inicie un restablecimiento de cliente utilizando ClientResetRequiredException.executeClientReset().

Si el reinicio del cliente no se ejecuta manualmente, se ejecutará automáticamente la próxima vez que se cierren y vuelvan a abrir todas las instancias del reino (normalmente cuando se reinicia la aplicación).