Gerenciar erros do Sync - React Native SDK

Adicionar um manipulador de erros de sincronização genérico

Um manipulador de erros de sincronização genérico é uma boa maneira de acompanhar os erros de sincronização. Usando FlexibleSyncConfiguration, você pode definir seu comportamento de tratamento de erros.

Para adicionar um manipulador de erros de sincronização genérico:

1. Escreva uma função de manipulador de erros.

2. Crie um objeto FlexibleSyncConfiguration para seu RealmProvider.

3. Passe seu manipulador de erros para a propriedade onError do objeto FlexibleSyncConfiguration .

const syncConfigWithErrorHandling = {
  flexible: true,
  onError: (_session, error) => {
    console.log(error);
  },
};
function RealmWithErrorHandling() {
  return (
    <RealmProvider sync={syncConfigWithErrorHandling}>
      <RestOfApp />
    </RealmProvider>
  );
}

Lidar com erros de gravação compensatórios

Talvez você queira que seu manipulador de erros de sincronização aborde especificamente os erros de escrita compensatórios de uma forma que faça sentido para o seu aplicativo. A classe CompensatingWriteError pode ajudá-lo a identificar e reagir a erros de escrita compensatórios em seu manipulador de erros personalizado.

Para lidar com erros de gravação compensatórios:

1. Escreva uma função de manipulador de erros que use CompensatingWriteError para identificar erros de gravação compensatórios.

2. Crie um objeto FlexibleSyncConfiguration para seu RealmProvider.

3. Passe seu manipulador de erros para a propriedade onError do objeto FlexibleSyncConfiguration .

export const CompensatingWriteErrorHandling = () => {
  const [error, setError] = useState<CompensatingWriteError | undefined>(
    undefined,
  );
  // Create a callback for sync error handling using CompensatingWriteError
  const errorCallback: ErrorCallback = (_session, error) => {
    if (error instanceof CompensatingWriteError) {
      // Handle the compensating write error as needed
      console.debug({
        code: error.code,
        name: error.name,
        category: error.category,
        message: error.message,
        url: error.logUrl,
        writes: error.writes,
      });
      setError(error);
    }
  };
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={LogIn}>
        <RealmProvider
          schema={[Person, Turtle]}
          sync={{
            flexible: true,
            onError: errorCallback,
          }}>
          <CompensatingWriteErrorHandler error={error} />
        </RealmProvider>
      </UserProvider>
    </AppProvider>
  );
};

Modos de reinício do cliente

Você pode especificar qual reinício do cliente seu aplicativo deve usar para restaurar o Realm para um estado sincronizável:

• Modo de recuperação de alterações não sincronizadas: ao escolher esse modo, o cliente tenta recuperar as alterações não sincronizadas. Escolha este modo quando não quiser descartar alterações não sincronizadas.

• Modo de recuperação ou descarte de alterações não sincronizadas : o cliente primeiro tenta recuperar as alterações que ainda não foram sincronizadas. Se o cliente não conseguir recuperar dados não sincronizados, ele falhará no descarte das alterações não sincronizadas, mas continuará executando automaticamente o reinício do cliente. Escolha este modo quando quiser ativar a recuperação automática do cliente para voltar a descartar alterações não sincronizadas.

• Modo de descartar alterações não sincronizadas : restaura o realm para um estado sincronizável descartando as alterações feitas desde a última sincronização.

• Modo de recuperação manual: baixa uma nova cópia do domínio e move o domínio não sincronizável para um backup. Migre dados não sincronizados da cópia de backup do domínio para a nova cópia sincronizável.

reinício do cliente automático versus manual

Os SDKs do Realm oferecem modos de reinício do cliente que lidam automaticamente com a maioria dos erros de reinício do cliente.

Os modos automáticos de redefinição do cliente restauram seu arquivo de domínio local para um estado sincronizável sem fechar o domínio ou perder notificações. Os seguintes modos de reinício do cliente são compatíveis com o reinício do cliente automático:

• Recuperar modo de alterações não sincronizadas

• Recuperar ou descartar o modo de alterações não sincronizadas

• Descartar modo de alterações não sincronizadas

As diferenças entre esses modos são baseadas em como eles lidam com alterações no dispositivo que ainda não foram sincronizadas com o backend. Somente o modo de recuperação manual não executa um reinício automático do cliente.

Escolha o modo recuperar alterações não sincronizadas para lidar com a maioria dos cenários de redefinição de cliente automaticamente. Isso tenta recuperar alterações não sincronizadas quando ocorre uma redefinição de cliente.

Se o seu aplicativo exigir uma lógica específica de redefinição de cliente que não possa ser tratada automaticamente, convém ou precise adicionar um manipulador manual de redefinição de cliente ao modo de redefinição automática de cliente.

Redefinição do cliente com recuperação

A recuperação do cliente é um recurso habilitado por padrão quando você configura o Realm Mobile Sync. Quando a Recuperação de Cliente está habilitada, o Realm gerencia automaticamente o processo de redefinição do cliente na maioria dos casos. O cliente pode recuperar alterações não sincronizadas quando não há alterações no esquema ou alterações no esquema não significativas.

Para usar a Recuperação de Cliente, configure seu domínio com um dos seguintes modos de redefinição de cliente:

• Recuperar modo de alterações não sincronizadas

• Recuperar ou descartar alterações não sincronizadas

Quando a Recuperação de Cliente está habilitada, essas regras determinam como os objetos são integrados, incluindo como os conflitos são resolvidos quando o backend e o cliente fazem alterações no mesmo objeto:

• Objetos criados localmente que não foram sincronizados antes da redefinição do cliente são sincronizados.

• Se um objeto for excluído no servidor, mas for modificado no cliente de recuperação, a exclusão terá precedência e o cliente descartará a atualização.

• Se um objeto for excluído no cliente em recuperação, mas não no servidor, o cliente aplicará a instrução de exclusão do servidor.

• No caso de atualizações conflitantes no mesmo campo, a atualização do cliente é aplicada.

Para obter mais informações sobre como configurar a Recuperação de Cliente, consulte Recuperação de Cliente na documentação do App Services.

A Recuperação de Cliente não pode ser bem-sucedida quando seu aplicativo faz alterações de esquema de quebra. Uma alteração significativa é uma alteração que você pode fazer no esquema do lado do servidor que requer uma ação adicional com a qual lidar. Nesse cenário, a redefinição do cliente volta para um fallback de redefinição do cliente com erro manual.

Para obter informações sobre alterações de esquema significativas e não significativas, consulte Referência rápida de alterações significativas e não significativas na documentação do App Services.

Modo de descartar alterações não sincronizadas

O modo Descartar alterações não sincronizadas exclui permanentemente todas as alterações locais não sincronizadas feitas desde a última sincronização bem-sucedida. Você pode usar esse modo quando seu aplicativo exigir uma lógica de recuperação do cliente que não seja consistente com a Recuperação automática do cliente ou quando não quiser recuperar dados não sincronizados.

Não use o modo de descarte de alterações não sincronizadas se o aplicativo não puder perder dados locais que ainda não foram sincronizados com o backend.

Para gerenciar as redefinições do cliente com o modo de descartar alterações não sincronizadas, passe um ClientResetConfiguration para o campo clientReset do seu FlexibleSyncConfiguration. Inclua estas propriedades no ClientResetConfiguration:

• mode: Defina como "discardUnsyncedChanges".

• onBefore: Opcional. Função de retorno de chamada invocada antes do SDK executar esse modo, quando o SDK recebe um erro de redefinição do cliente do backend. Fornece uma cópia do domínio.

• onAfter: Opcional. Função de chamada de resposta invocada após o SDK executar com sucesso este modo. Fornece instâncias do Realm antes e depois do reinício do cliente.

O exemplo a seguir implementa o modo de descarte de alterações não sincronizadas:

Modo manual

No modo manual , você define seu próprio manipulador de redefinição do cliente. Talvez você queira usar um manipulador de redefinição manual do cliente se a lógica de recuperação automática não funcionar para seu aplicativo e você não puder descartar dados locais não sincronizados.

Para gerenciar as redefinições do cliente com o modo manual, passe um ClientResetConfiguration para o campo clientReset do seu FlexibleSyncConfiguration. Inclua estas propriedades no ClientResetConfiguration:

• mode: Defina como "manual".

• onManual: Opcional. Função de retorno de chamada invocada quando ocorre a redefinição do cliente. Fornece informações sobre a sessão de sincronização e o caminho para o realm atual. Se você não definir o manipulador de erros onManual, o reinício do cliente voltará para o manipulador de erros de sincronização geral.

Tratamento de reinício do cliente de teste

Você pode testar manualmente o tratamento de redefinição do cliente do seu aplicativo encerrando e reativando o Device Sync.

Quando você encerra e reativa a sincronização, os clientes que se conectaram anteriormente à sincronização não conseguem se conectar até depois de fazerem um reinício do cliente. O encerramento da sincronização exclui os metadados do servidor que permitem ao cliente sincronizar. O cliente deve baixar uma nova cópia do Realm do servidor. O servidor envia um erro de reinício do cliente para esses clientes. Então, ao encerrar a sincronização, você trigger a condição de reinício do cliente.

Para testar o tratamento de reinício do cliente:

1. Escreva dados de um aplicativo cliente e aguarde a sincronização.

2. Encerre e reative o Realm Mobile Sync.

3. Run the client app again. O aplicativo deve receber um erro de reinício do cliente ao tentar se conectar ao servidor.