Gestionar errores de sincronización - SDK de C++

Reinicio automático vs. manual del cliente

El SDK ofrece modos de restablecimiento de cliente que gestionan automáticamente la mayoría de los errores de restablecimiento. Los modos de restablecimiento automático restauran el archivo de base de datos de su dispositivo a un estado sincronizable sin cerrar la base de datos ni perder notificaciones.

Todos los modos de reinicio del cliente excepto manual() Realizar un restablecimiento automático del cliente. Las diferencias entre los modos se basan en cómo gestionan los cambios en el dispositivo que aún no se han sincronizado con el backend.

Elige recover_unsynced_changes() para gestionar automáticamente la mayoría de los escenarios de restablecimiento del cliente. Esto intenta recuperar los cambios no sincronizados cuando ocurre un restablecimiento del cliente.

En algunos casos, puede que quieras o necesites configurar un controlador de reinicio manual del cliente. Esto es recomendable si tu aplicación requiere una lógica de reinicio específica que no se puede gestionar automáticamente.

Especificar un modo de reinicio del cliente

El SDK de C++ permite especificar un controlador de restablecimiento de cliente en la configuración de la base de datos. Este controlador puede usar una base de modo de restablecimiento de cliente (client_reset_mode_base). Esta estructura permite especificar:

• Un bloque para ejecutar antes del reinicio del cliente

• Un bloque para ejecutar después del reinicio del cliente

• El modo a utilizar al gestionar el restablecimiento del cliente

auto user = app.login(realm::App::credentials::anonymous()).get();
auto syncConfig = user.flexible_sync_configuration();
// Set the client reset handler with your preferred client reset mode.
syncConfig.set_client_reset_handler(
    realm::client_reset::recover_unsynced_changes(beforeReset, afterReset));
auto syncedRealm = realm::db(syncConfig);

Puede utilizar uno de los modos de restablecimiento de cliente disponibles para especificar cómo debe el SDK intentar resolver cualquier dato no sincronizado en el dispositivo durante un restablecimiento de cliente:

• recover_unsynced_changes()

• recover_or_discard_unsynced_changes()

• discard_unsynced_changes()

• manual()

Puede especificar un bloque antes y después para que se ejecute durante el proceso de restablecimiento automático del cliente. Puede usarlo para ejecutar la lógica de recuperación importante para su aplicación.

/* You can define blocks to call before and after the client reset occur
   if you need to execute specific logic, such as reporting or debugging. */
auto beforeReset = [&](realm::db before) {
  /* A block called after a client reset error is detected, but before the
     client recovery process is executed. You could use this block for any
     custom logic, reporting, debugging etc. You have access to the database
     before the client reset occurs in this block. */
};
auto afterReset = [&](realm::db device, realm::db server) {
  /* A block called after the client recovery process has executed.
     This block could be used for custom recovery, reporting, debugging etc.
     You have access to the database that is currently on the device - the
     one that can no longer sync - and the new database that has been
     restored from the server. */
};

Si su aplicación tiene necesidades específicas de recuperación de clientes, puede especificar el manual() modo de restablecimiento de cliente y configurar un controlador manual de restablecimiento de cliente. Puede hacerlo si su aplicación debe ejecutar una lógica personalizada específica durante un restablecimiento de cliente o si las reglas de recuperación de cliente no funcionan.

Manejar cambios de esquema

La función de Recuperación de Cliente se habilita de forma predeterminada al configurar la Sincronización de Dispositivos. Cuando está habilitada, el SDK puede administrar automáticamente el proceso de restablecimiento del cliente en la mayoría de los casos. Al realizar cambios en el esquema:

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

• Al realizar cambios de esquema disruptivos, los modos de restablecimiento automático del cliente recurren a un gestor de errores manual. Puede configurar un gestor de errores de restablecimiento manual del cliente para este caso. La recuperación automática del cliente no puede ocurrir cuando su aplicación realiza cambios de esquema disruptivos.

Para obtener información sobre cambios de esquema disruptivos y no disruptivos, consulte Referencia rápida sobre cambios disruptivos y no disruptivos.

Recuperar cambios no sincronizados

Durante un restablecimiento de cliente, las aplicaciones cliente pueden intentar recuperar datos de la base de datos sincronizada en el dispositivo que aún no se ha sincronizado con el backend. Para recuperar los cambios no sincronizados, laRecuperación de Cliente debe estar habilitada en la aplicación de Servicios de Aplicaciones (está habilitada por defecto).

Si desea que su aplicación recupere los cambios que aún no se han sincronizado, utilice uno de estos modos de recuperación de cliente:

• recover_unsynced_changes()El cliente intenta recuperar los cambios no sincronizados. Seleccione este modo si no desea descartar los cambios no sincronizados.

• recover_or_discard_unsynced_changes()El cliente primero intenta recuperar los cambios que aún no se han sincronizado. Si no puede recuperar los datos no sincronizados, descarta los cambios no sincronizados, pero continúa reiniciando el cliente automáticamente. Seleccione este modo si desea habilitar la recuperación automática del cliente para descartar los cambios no sincronizados.

auto user = app.login(realm::App::credentials::anonymous()).get();
auto syncConfig = user.flexible_sync_configuration();
// Set the client reset handler with your preferred client reset mode.
syncConfig.set_client_reset_handler(
    realm::client_reset::recover_unsynced_changes(beforeReset, afterReset));
auto syncedRealm = realm::db(syncConfig);

Es posible que en ocasiones la operación de restablecimiento del cliente no se complete en recover_unsynced_changes() modo, como cuando se producen cambios de esquema importantes o la recuperación del cliente está deshabilitada en la configuración de sincronización de dispositivos. Para solucionar este problema, la aplicación puede gestionar un error de restablecimiento del cliente en el controlador de errores de sincronización. Para obtener más información, consulte la sección sobre el modo de restablecimiento manual del cliente en esta página.

Descartar cambios no sincronizados

El discard_unsynced_changes() modo de restablecimiento de cliente elimina permanentemente todos los cambios no sincronizados en el dispositivo desde la última sincronización exitosa. Puedes usar este modo cuando tu aplicación requiere una lógica de recuperación de cliente que no coincide con las reglas de recuperación de cliente de Device Sync o cuando no deseas recuperar datos no sincronizados.

No utilice el modo de descartar cambios no sincronizados si su aplicación no puede perder datos del dispositivo que aún no se han sincronizado con el backend.

Para realizar un restablecimiento automático del cliente que descarte los cambios no sincronizados, utilice el modo de restablecimiento del cliente discard_unsynced_changes().

auto user = app.login(realm::App::credentials::anonymous()).get();
auto syncConfig = user.flexible_sync_configuration();
// Set the client reset handler with your preferred client reset mode.
syncConfig.set_client_reset_handler(
    realm::client_reset::discard_unsynced_changes(beforeReset, afterReset));
auto syncedRealm = realm::db(syncConfig);

Es posible que, en ocasiones, la operación de restablecimiento del cliente no pueda completarse en discard_unsynced_changes() modo, como cuando se producen cambios de esquema importantes. Para solucionar este problema, la aplicación puede gestionar un error de restablecimiento del cliente en el controlador de errores de sincronización. Para obtener más información, consulte la sección "Modo de restablecimiento manual del cliente" en esta página.

Modo de restablecimiento manual del cliente

Al manual() usar el modo de restablecimiento de cliente, debe implementar un controlador de restablecimiento de cliente personalizado en el controlador de errores de sincronización. Recomendamos usar los modos de recuperación automática de cliente siempre que sea posible y elegir el manual() modo solo si la lógica de recuperación automática no es adecuada para su aplicación.

auto user = app.login(realm::App::credentials::anonymous()).get();
auto syncConfig = user.flexible_sync_configuration();
// Set the client reset handler to manual client reset mode.
syncConfig.set_client_reset_handler(realm::client_reset::manual());
// Define a Sync error handler for handling the client reset.
syncConfig.sync_config().set_error_handler(
    [&](realm::sync_session session, realm::sync_error error) {
      if (error.is_client_reset_requested()) {
        /* You might use this for reporting or to instruct the user to delete
           and re-install the app. */
      };
    });
auto syncedRealm = realm::db(syncConfig);

Si la operación de restablecimiento del cliente no puede completarse automáticamente, como cuando hay cambios de esquema disruptivos, el proceso de restablecimiento del cliente recae en el manejador de errores manual. Esto puede ocurrir en cualquiera de estos modos automáticos de restablecimiento de cliente:

• recover_unsynced_changes()

• recover_or_discard_unsynced_changes()

• discard_unsynced_changes()

Recomendamos tratar el controlador manual como una herramienta para situaciones de recuperación de errores fatales en las que se recomienda a los usuarios que actualicen la aplicación o realicen alguna otra acción.

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:

1. Escriba datos desde una aplicación cliente y espere a que se sincronicen.

2. Termina y vuelve a habilitar Device Sync.

3. Ejecute la aplicación cliente nuevamente. La aplicación debería mostrar un error de restablecimiento de cliente al intentar conectarse al servidor.