Al desarrollar una aplicación que utiliza Sincronización de dispositivos: debe configurar un controlador de errores. Este controlador detectará y responderá a cualquier llamada a la API relacionada con la sincronización fallida.
Agregar un syncErrorHandlerpropiedad a FlexibleSyncConfiguration al crear un reino sincronizado. syncErrorHandler Es una función de devolución de llamada SyncErrorHandler. SyncErrorHandler acepta un SyncError como parámetro. Siempre que SyncError se produce un en el dominio, se invoca la función de devolución de llamada con el SyncError como argumento.
final config = Configuration.flexibleSync(currentUser, [Car.schema], syncErrorHandler: (SyncError error) { print("Error message${error.message}"); }); final realm = Realm(config);
Si no especifica un syncErrorHandler, el comportamiento predeterminado es imprimir el SyncError en la consola.
Tip
Para obtener una lista de errores comunes de sincronización de dispositivos y cómo solucionarlos, consulte Errores de sincronización en la documentación de sincronización de dispositivos de App Services.
Compensación de errores de escritura
A partir de Realm Flutter SDK v1.3, puedes obtener información detallada sobre cómo compensar errores de escritura.
void handleCompensatingWrite( CompensatingWriteError compensatingWriteError) { final writeReason = compensatingWriteError.compensatingWrites!.first; print("Error message: ${writeReason.reason}"); // ... handle compensating write error as needed. } final config = Configuration.flexibleSync(currentUser, [Car.schema], syncErrorHandler: (syncError) { if (syncError is CompensatingWriteError) { handleCompensatingWrite(syncError); } }); final realm = Realm(config);
Para obtener más detalles, consulte la documentación de referencia de la clase CompensatingWriteError.
Restablecimiento del cliente
Al usar Device Sync, el restablecimiento del cliente es una tarea de recuperación de errores que su aplicación cliente debe realizar cuando el servidor Device Sync ya no puede sincronizarse con el ámbito del cliente.
Los clientes en este estado pueden seguir ejecutándose y guardando datos localmente, pero no pueden enviar ni recibir conjuntos de cambios de sincronización hasta que restablezcan el cliente. El cliente debe restablecer su dominio a un estado que coincida con el del servidor para poder restaurar la sincronización. El dominio no sincronizable del cliente puede contener datos que aún no se han sincronizado con el servidor.
El SDK de Realm puede intentar recuperar o descartar esos datos durante el proceso de restablecimiento del cliente. El SDK de Realm proporciona métodos para gestionar automáticamente los restablecimientos del cliente en la mayoría de los casos.
Para obtener más información sobre qué puede provocar que se restablezca un cliente, vaya a Restablecimientos de cliente en la documentación de Servicios de aplicaciones.
Modos de reinicio del cliente
Para administrar el proceso de restablecimiento del cliente, puede especificar un modo de restablecimiento en la propiedad FlexibleSyncConfiguration.clientResetHandler al configurar un dominio. Puede usar los siguientes modos de restablecimiento:
Modo de recuperación o descarte de cambios no sincronizados (predeterminado): En este modo de restablecimiento del cliente, el controlador de restablecimiento del cliente primero intenta recuperar los cambios no sincronizados. Si la recuperación falla, este controlador recurre al modo de descarte de cambios no sincronizados, que elimina todos los cambios locales no sincronizados. Si este modo falla, el controlador recurre al modo de recuperación manual.
Modo de recuperación de cambios no sincronizados: En este modo de restablecimiento del cliente, el controlador de restablecimiento del cliente primero intenta recuperar los cambios no sincronizados. Si la recuperación falla, este controlador vuelve al modo de recuperación manual.
Descartar el modo de cambios no sincronizados: Este modo de restablecimiento del cliente elimina permanentemente todos los cambios locales no sincronizados realizados desde la última sincronización exitosa. Si la recuperación falla, este controlador recurre a un modo de recuperación manual.
Modo de recuperación manual: este modo de restablecimiento del cliente le proporciona una manera de implementar su propia estrategia de recuperación.
Las siguientes secciones describen cómo utilizar estos modos de restablecimiento de cliente.
Reinicio automático vs. manual del cliente
Los SDK de Realm proporcionan modos de restablecimiento de cliente que manejan automáticamente la mayoría de los errores de restablecimiento de cliente.
Los modos de restablecimiento automático del cliente restauran el archivo de dominio local a un estado sincronizable sin cerrar el dominio ni perder notificaciones. Los siguientes modos de restablecimiento del cliente admiten restablecimientos automáticos:
Recuperar el modo de cambios no sincronizados
Recuperar o descartar el modo de cambios no sincronizados
Descartar el modo de cambios no sincronizados
Las diferencias entre estos modos se basan en cómo gestionan los cambios en el dispositivo que aún no se han sincronizado con el backend. Solo el modo de recuperación manual no realiza un restablecimiento automático del cliente.
Seleccione el modo de recuperación de cambios no sincronizados para gestionar automáticamente la mayoría de los casos de restablecimiento del cliente. Este modo intenta recuperar los cambios no sincronizados al restablecer el cliente.
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 al modo de reinicio de cliente automático.
Restablecimiento del cliente con recuperación
La recuperación de cliente es una función que se habilita de forma predeterminada al configurar la sincronización de dispositivos. Cuando está habilitada, Realm gestiona automáticamente el proceso de restablecimiento del cliente en la mayoría de los casos. Al realizar cambios de esquema, el cliente puede recuperar los cambios no sincronizados cuando no hay cambios de esquema o cambios de esquema permanentes.
Para utilizar la Recuperación de cliente, configure su reino con los modos de restablecimiento de cliente para recuperar cambios no sincronizados o recuperar o descartar cambios no sincronizados.
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.
Para obtener más información sobre cómo configurar la Recuperación de cliente, consulte Recuperación de cliente en la documentación de Servicios de aplicaciones.
La recuperación del cliente no se puede realizar 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, el cliente se reinicia con un recurso de respaldo manual 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.
Modo Recuperar o Descartar Cambios No Sincronizados
El modo "Recuperar o descartar cambios no sincronizados" intenta recuperar automáticamente todos los cambios locales no sincronizados durante el restablecimiento del cliente. Si no se especifica un modo de restablecimiento, el comportamiento predeterminado es recuperar o descartar los cambios no sincronizados. Si el proceso de recuperación automática falla, se recurre al modo "Descartar cambios no sincronizados". Si este proceso falla, se recurre de nuevo al modo de restablecimiento manual.
El modo "Recuperar o descartar cambios no sincronizados" ofrece el proceso de recuperación más robusto. Sin embargo, no lo use si su aplicación no puede recuperar datos locales que aún no se hayan sincronizado con el backend.
Para personalizar el uso del modo de recuperación o descarte de cambios no sincronizados, pase una devolución de llamada RecoverOrDiscardUnsyncedChangesHandler Configure.clientResetHandler a. Agregue los siguientes métodos de devolución de llamada opcionales para ampliar la funcionalidad del controlador:
onBeforeReset, que el SDK invoca antes del reinicio del cliente. Puede usar esta devolución de llamada para notificar al usuario antes de que comience el reinicio del cliente.
onAfterRecovery, que el SDK invoca solo si el restablecimiento automático se completa correctamente. Puede usarlo para notificar al usuario que el restablecimiento del cliente se ha completado.
onAfterDiscard, que el SDK invoca solo si falla el restablecimiento automático del cliente y la estrategia local de descarte tiene éxito. Si la estrategia de descarte falla, no se invoca esta devolución de llamada.
onManualResetFallback, que el SDK invoca solo si la recuperación automática y la estrategia de descarte fallan. 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 el uso de RecoverOrDiscardUnsyncedChangesHandler y cada una de sus devoluciones de llamada:
final config = Configuration.flexibleSync(currentUser, schema, clientResetHandler: RecoverOrDiscardUnsyncedChangesHandler( // All the following callbacks are optional onBeforeReset: (beforeResetRealm) { // Executed before the client reset begins. // Can be used to notify the user that a reset is going // to happen. }, onAfterRecovery: (beforeResetRealm, afterResetRealm) { // Executed if and only if the automatic recovery has succeeded. }, onAfterDiscard: (beforeResetRealm, afterResetRealm) { // Executed if the automatic recovery has failed // but the discard unsynced changes fallback has completed // successfully. }, onManualResetFallback: (clientResetError) { // Automatic reset failed. Handle the reset manually here. // Refer to the "Manual Client Reset Fallback" documentation // for more information on what you can include here. }, ));
Modo Recuperar cambios no sincronizados
El modo de recuperación de cambios no sincronizados intenta recuperar automáticamente todos los cambios locales no sincronizados durante el restablecimiento del cliente. Sin embargo, a diferencia del modo de recuperación o descarte de cambios no sincronizados, este modo no recurre a la opción de descarte de cambios locales si falla la recuperación automática. En su lugar, recurre a la recuperación manual de los cambios.
Para usar el modo de recuperación de cambios no sincronizados, pase una devolución de llamada RecoverUnsyncedChangesHandler Configure.clientResetHandler a. Este controlador proporciona los siguientes métodos de devolución de llamada:
onBeforeReset, que el SDK invoca antes del reinicio del cliente. Puede usar esta devolución de llamada para notificar al usuario antes de que comience el reinicio.
onAfterReset, que el SDK invoca solo si el restablecimiento automático se completa correctamente. Puede usar esta función para notificar al usuario cuando el restablecimiento se haya completado correctamente.
onManualResetFallback, que el SDK invoca solo si la recuperación automática y la estrategia de descarte fallan. Esta devolución de llamada se implementa para gestionar el error de restablecimiento, como se explica en la sección "Respaldo de recuperación manual".
El siguiente ejemplo muestra el uso de RecoverUnsyncedChangesHandler y cada una de sus devoluciones de llamada:
final config = Configuration.flexibleSync(currentUser, schema, clientResetHandler: RecoverUnsyncedChangesHandler( // All the following callbacks are optional onBeforeReset: (beforeResetRealm) { // Executed before the client reset begins. // Can be used to notify the user that a reset is going // to happen. }, onAfterReset: (beforeResetRealm, afterResetRealm) { // Executed after the client reset is complete. // Can be used to notify the user that the reset is done. }, onManualResetFallback: (clientResetError) { // Automatic reset failed. Handle the reset manually here. // Refer to the "Manual Client Reset Fallback" documentation // for more information on what you can include here. }, ));
Modo Descartar cambios no sincronizados
El modo Descartar cambios no sincronizados elimina permanentemente todos los cambios locales no sincronizados realizados desde la última sincronización exitosa. Si elige este modo de restablecimiento del cliente, el SDK restaura el archivo de dominio local a un estado sincronizable sin cerrarlo y manteniendo las notificaciones funcionando correctamente. Si este proceso falla, se vuelve al modo de recuperación manual.
No utilice el modo de recuperación o descartar cambios no sincronizados si su aplicación no puede perder datos locales que aún no se han sincronizado con el backend.
Para usar el modo de descartar cambios no sincronizados, pase una devolución de llamada DiscardUnsyncedChangesHandler Configure.clientResetHandler a. Este controlador proporciona los siguientes métodos de devolución de llamada:
onBeforeReset, que el SDK invoca antes del reinicio del cliente. Puede usar esta devolución de llamada para notificar al usuario antes de que comience el reinicio.
onAfterReset, que el SDK invoca solo si el restablecimiento se completa correctamente. Puede usarlo para notificar al usuario cuando se complete el restablecimiento.
onManualResetFallback, que el SDK invoca solo si la recuperación automática y la estrategia de descarte fallan. Esta devolución de llamada se implementa para gestionar el error de restablecimiento, como se explica en la sección Recuperación manual.
El siguiente ejemplo muestra el uso de DiscardUnsyncedChangesHandler y cada una de sus devoluciones de llamada:
final config = Configuration.flexibleSync(currentUser, schema, clientResetHandler: DiscardUnsyncedChangesHandler( onBeforeReset: (beforeResetRealm) { // Executed before the client reset begins. // Can be used to notify the user that a reset is going // to happen. }, onAfterReset: (beforeResetRealm, afterResetRealm) { // Executed after the client reset is complete. // Can be used to notify the user that the reset is done. }, onManualResetFallback: (clientResetError) { // Automatic reset failed. Handle the reset manually here. // Refer to the "Manual Client Reset Fallback" documentation // for more information on what you can include here. }, ));
Recuperación manual alternativa
Si el restablecimiento del cliente con recuperación no se puede completar automáticamente, como cuando hay cambios de esquema importantes, el proceso de restablecimiento del cliente se deriva a un gestor de errores manual. Esto puede ocurrir en cualquiera de los modos de restablecimiento automático del cliente:
Recuperar el modo de cambios no sincronizados
Recuperar o descartar el modo de cambios no sincronizados
Descartar el modo de cambios no sincronizados
Debe proporcionar una implementación de reinicio manual del cliente en la devolución de llamada onManualResetFallback del controlador de reinicio del cliente para estos modos.
En,onManualResetFallback inicie un restablecimiento del cliente mediante el método ClientResetError.resetRealm() del ClientResetError parámetro de la devolución de llamada. ClientResetError.resetRealm() realiza un restablecimiento del cliente eliminando el dominio en el dispositivo y descargando los datos relevantes del servidor. Antes de usar este método, debe cerrar todas las instancias del dominio que está restableciendo.
El siguiente ejemplo demuestra cómo se puede manejar manualmente un caso de error descartando todos los cambios no sincronizados:
// Lazily initialize `realm` so that it can be used in the callback // before the realm has been opened. late Realm realm; final config = Configuration.flexibleSync(currentUser, schema, // This example uses the `RecoverOrDiscardUnsyncedChangesHandler`, // but the same logic could also be used with the `RecoverUnsyncedChangesHandler` // or the `DiscardUnsyncedChangesHandler`. clientResetHandler: RecoverOrDiscardUnsyncedChangesHandler( onManualResetFallback: (clientResetError) { // Prompt user to perform a client reset immediately. If they don't, // they won't receive any data from the server until they restart the app // and all changes they make will be discarded when the app restarts. var didUserConfirmReset = showUserAConfirmationDialog(); if (didUserConfirmReset) { // You must close the Realm before attempting the client reset. realm.close(); // Attempt the client reset. try { clientResetError.resetRealm(); // Navigate the user back to the main page or reopen the // the Realm and reinitialize the current page. } catch (err) { // Reset failed. // Notify user that they'll need to update the app } } }, ));
Modo de recuperación manual
Usa el modo de recuperación manual para los casos poco habituales en los que necesitas personalizar el proceso de recuperación de datos. En la mayoría de los casos, debes utilizar una de las otras estrategias para el restablecimiento del cliente. Puedes querer usar un gestor de restablecimiento manual del cliente si la lógica de recuperación automática no funciona para tu aplicación y no puedes descartar los datos locales no sincronizados.
Para utilizar el modo de recuperación manual, pase una devolución de llamada ManualRecoveryHandler Configure.clientResetHandler a.
El controlador proporciona la devolución de llamada onManualReset, que permite restablecer el cliente. onManualReset En, inicie un restablecimiento del cliente mediante el método ClientResetError.resetRealm() del ClientResetError parámetro de la devolución de llamada. ClientResetError.resetRealm() realiza un restablecimiento del cliente eliminando el dominio en el dispositivo y descargando los datos relevantes del servidor. Antes de usar este método, debe cerrar todas las instancias del dominio que se está restableciendo.
// Lazily initialize `realm` so that it can be used in the callback // before the realm has been opened. late Realm realm; final config = Configuration.flexibleSync(currentUser, schema, clientResetHandler: ManualRecoveryHandler((clientResetError) { // You must close the Realm before attempting the client reset. realm.close(); // Handle manual client reset here... // Then perform the client reset. clientResetError.resetRealm(); }));
Manejo del restablecimiento del cliente de prueba
Puede probar manualmente el manejo de restablecimiento del cliente de su aplicación finalizando y volviendo a habilitar la sincronización del dispositivo.
Al finalizar y reactivar Sync, los clientes que se conectaron previamente con Sync no podrán hacerlo hasta que restablezcan el cliente. Al finalizar Sync, se eliminan los metadatos del servidor que permiten la sincronización. El cliente debe descargar una nueva copia del dominio desde el servidor. El servidor envía un error de restablecimiento de cliente a estos clientes. Por lo tanto, al finalizar Sync, se activa la condición de restablecimiento de cliente.
Para probar el manejo del restablecimiento del cliente:
Escriba datos desde una aplicación cliente y espere a que se sincronicen.
Termina y vuelve a habilitar Device Sync.
Ejecute la aplicación cliente nuevamente. La aplicación debería mostrar un error de restablecimiento de cliente al intentar conectarse al servidor.
Advertencia
Mientras itera sobre la gestión del restablecimiento de clientes en su aplicación cliente, es posible que tenga que finalizar y volver a habilitar la sincronización repetidamente. Esto impide que todos los clientes existentes puedan sincronizar hasta después de completar un restablecimiento. Para evitar esto en producción, pruebe la gestión del restablecimiento de clientes en un entorno de desarrollo.