동기화 오류 처리 - Kotlin SDK

복구할 수 없는 동기화 오류

UnrecoverableSyncException 은 Device Sync가 치명적으로 실패할 때 발생합니다. 이는 일반적으로 클라이언트 또는 연결된 앱의 버그를 의미합니다.

복구할 수 없는 동기화 오류가 발생하면 최종 사용자에게 문제를 나타내야 합니다. 문제가 해결될 때까지 Device Sync가 작동하지 않는다고 알립니다. 백엔드 앱 로그를 확인하고 가능한 한 빨리 문제를 해결할 수 있도록 자신에게 경고를 보내는 것이 가장 좋습니다.

잘못된 동기화 유형 오류

클라이언트와 앱이 서로 다른 동기화 프로토콜을 사용할 때 WrongSyncTypeException 이 발생합니다.

SDK는 유연한 동기화 와 파티션 기반 동기화의 두 가지 동기화를 지원합니다. 클라이언트가 앱의 동기화 유형과 일치하지 않는 동기화 유형을 사용하여 앱에 연결하면 잘못된 동기화 유형 오류가 발생합니다.

잘못된 동기화 유형 오류를 복구하려면 백엔드와 일치하는 동기화 유형을 사용하도록 클라이언트를 업데이트하세요. 이를 위해서는 사용자가 수정 사항이 포함된 새 버전의 앱으로 업데이트해야 할 가능성이 높습니다.

잘못된 Flexible Sync 쿼리 오류

앱 백엔드에서 지원하지 않는 유연한 동기화 쿼리를 구독하려고 하면 BadFlexibleSyncQueryException 이 발생합니다. 다음과 같은 경우에 발생할 수 있습니다.

• flexible sync 구성에서 쿼리 가능 필드 로 지정되지 않은 필드를 쿼리합니다.

• flexible sync에서 지원되지 않는 연산자를 사용하여 flexible sync 쿼리를 생성합니다.

잘못된 flexible sync 쿼리 오류를 복구하려면 앱 구성과 호환되는 동기화 쿼리를 사용하도록 클라이언트를 업데이트하세요. 이를 위해서는 사용자가 수정 사항이 포함된 새 버전의 앱으로 업데이트해야 할 가능성이 높습니다.

자동 및 수동 클라이언트 재설정

자동 재설정 전략은 영역을 닫거나 알림을 누락하지 않고 로컬 Realm 파일을 동기화 가능한 상태로 복원합니다. 차이점은 아직 백엔드에 동기화되지 않은 기기의 변경 사항을 처리하는 방법에 따라 달라집니다. 다음 전략은 AutomaticClientResetStrategy 인터페이스를 구현하고 자동 클라이언트 재설정을 지원합니다.

• 동기화되지 않은 변경 사항 복구 또는 삭제 (기본값): 클라이언트 재설정 핸들러는 먼저 동기화되지 않은 변경 사항 복구를 시도합니다. 복구가 실패하면 이 핸들러는 동기화되지 않은 모든 로컬 변경 사항을 영구적으로 삭제 하는 동기화되지 않은 변경 사항 삭제 전략으로 돌아갑니다. 동기화되지 않은 변경 사항 삭제 전략이 실패하면 처리기는 수동 복구로 돌아갑니다.

• 동기화되지 않은 변경 사항 복구: 클라이언트 재설정 처리기는 먼저 동기화되지 않은 변경 사항 복구를 시도합니다. 복구가 실패하면 이 핸들러는 수동 복구로 돌아갑니다.

• 동기화되지 않은 변경 사항 삭제 : 이 전략은 마지막 동기화에 성공한 이후 이루어진 모든 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제 합니다. 삭제가 실패하면 이 핸들러는 수동 복구로 돌아갑니다. 이 모드는 모든 수동 데이터 복구를 처리하는 데 권장됩니다.

앱에 자동으로 처리할 수 없는 특정 클라이언트 재설정 로직이 필요한 경우, ManuallyRecoverUnsyncedChangesStrategy 인터페이스를 사용하여 수동 클라이언트 재설정 핸들러를 추가하거나 추가해야 할 수 있습니다.

• 동기화되지 않은 변경 사항 수동 복구: 고유한 수동 복구 전략을 구현할 수 있습니다. 수동 복구는 자동 클라이언트 재설정을 수행하지 않는 유일한 전략입니다. 이 모드에서는 Realm만 백업할 수 있습니다. 가능하면 동기화되지 않은 변경 사항 삭제 전략을 사용하여 수동 복구를 처리하는 것이 좋습니다.

복구를 통한 클라이언트 재설정

클라이언트 복구 는 Device Sync를 구성할 때 기본적으로 활성화되는 기능입니다.

클라이언트 복구를 사용하려면 동기화되지 않은 변경 사항 복구 또는 동기화되지 않은 변경 사항 복구 또는 삭제 전략으로 Realm을 구성하면 대부분의 경우 Realm이 클라이언트 재설정 프로세스를 자동으로 관리합니다.

• 클라이언트는 스키마 변경이 없거나 손상적이지 않은 스키마 변경이 있는 경우 동기화되지 않은 변경 사항을 복구할 수 있습니다.

• 앱에서 호환성이 손상되는 스키마 변경이 있을 때는 자동 클라이언트 복구를 수행 할 수 없습니다 . 단절적 변경은 서버 측 스키마에서 처리할 추가 조치가 필요한 변경 사항입니다. 이 시나리오에서 클라이언트 복구는 수동 오류 클라이언트 재설정 폴백으로 대체됩니다.

  단절적 스키마 변경과 단절적이지 않은 변경에 대한 자세한 내용은 Atlas App Services 문서에서 단절과 단절적이지 않은 변경 비교 빠른 참조 를 참조하세요.

클라이언트 복구 규칙

클라이언트 복구가 활성화된 경우 이러한 규칙은 백엔드와 클라이언트가 모두 동일한 객체를 변경할 때 충돌을 해결하는 방법을 포함하여 객체가 통합되는 방식을 결정합니다.

• 로컬에서 생성되었지만 클라이언트 재설정 전에 동기화되지 않은 객체는 동기화됩니다.

• 객체가 서버에서 삭제되었지만 복구 클라이언트에서 수정된 경우 삭제가 우선적으로 적용되고 클라이언트는 업데이트를 삭제합니다.

• 객체가 복구 중인 클라이언트에서는 삭제되고 서버에서는 삭제되지 않는 경우 클라이언트는 서버의 삭제 명령을 적용합니다.

• 동일한 필드에 대한 업데이트가 충돌하는 경우 클라이언트 업데이트가 적용됩니다.

동기화되지 않은 변경 사항 복구 또는 삭제

동기화되지 않은 변경 사항 복구 또는 삭제 전략은 클라이언트 재설정 중에 동기화되지 않은 모든 로컬 변경 사항을 자동으로 복구하려고 시도합니다. 동기화되지 않은 변경 사항을 복구하려면 App Services App에서 클라이언트 복구 를 활성화해야 합니다(기본적으로 활성화되어 있음).

자동 복구 프로세스가 실패하면 동기화되지 않은 변경 사항 삭제 전략으로 돌아갑니다. 해당 프로세스 프로세스가 실패하면 다시 수동 재설정 전략으로 돌아갑니다.

이 전략은 가장 강력한 복구 프로세스를 제공합니다. 이는 클라이언트 재설정 전략을 지정하지 않은 경우의 기본 클라이언트 재설정 동작입니다.

동기화되지 않은 변경 사항 복구 또는 삭제 전략 사용을 사용자 지정하려면 RecoverOrDiscardUnsyncedChangesStrategy 인터페이스를 구현하는 클래스를 정의합니다.

인터페이스는 다음과 같은 콜백 메서드를 제공합니다.

• onBeforeReset: 클라이언트 재설정 전에 호출됩니다. 재설정 전 영역의 인스턴스를 제공합니다. 이 콜백을 사용하여 클라이언트 재설정이 시작되기 전에 사용자에게 알릴 수 있습니다.

• onAfterRecovery: 자동 재설정이 성공적으로 완료된 경우에만 호출됩니다. Realm의 읽기 전용 이전 인스턴스와 최종 Realm의 변경 가능한 인스턴스를 제공합니다. 이 콜백을 사용하여 클라이언트 재설정이 완료되었음을 사용자에게 알릴 수 있습니다.

• onAfterDiscard: 자동 클라이언트 재설정이 실패 하고 로컬 삭제 전략이 성공한 경우에만 호출됩니다. 폐기 전략이 실패하면 이 콜백이 호출되지 않습니다. Realm의 읽기 전용 이전 인스턴스와 최종 Realm의 변경 가능한 인스턴스를 제공합니다. 이 콜백을 사용하여 사용자에게 재설정이 완료되었음을 알릴 수 있습니다.

• onManualResetFallback: 자동 복구 및 삭제 전략이 실패한 경우에만 호출됩니다. 로컬 변경 사항을 삭제하고 로컬 영역의 백업을 생성할 수 있습니다. 수동 복구 폴백 섹션에 설명된 대로 재설정 실패를 처리하려면 이 콜백을 구현합니다.

다음 예제에서는 RecoverOrDiscardUnsyncedChangesStrategy 및 각 콜백을 보여줍니다.

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

동기화되지 않은 변경 내용 복구

동기화되지 않은 변경 사항 복구 전략은 클라이언트 재설정 중에 동기화되지 않은 모든 로컬 변경 사항을 자동으로 복구하려고 시도합니다. 동기화되지 않은 변경 사항을 복구하려면 App Services App에서 클라이언트 복구 를 활성화해야 합니다(기본적으로 활성화되어 있음).

그러나 동기화되지 않은 변경 사항 복구 및 삭제 전략과 달리 자동 복구가 실패할 경우 로컬 변경 사항을 삭제하지 않습니다. 대신 변경 사항을 수동으로 복구합니다. 앱에서 동기화되지 않은 데이터를 잃을 수 없는 경우 이 클라이언트 재설정 전략을 선택할 수 있습니다.

동기화되지 않은 변경 사항 복구 전략을 사용하려면 RecoverUnsyncedChangesStrategy 인터페이스를 구현하는 핸들러를 정의합니다.

인터페이스는 다음과 같은 콜백 메서드를 제공합니다.

• onBeforeReset: 클라이언트 재설정 전에 호출됩니다. 재설정 전 영역의 인스턴스를 제공합니다. 이 콜백을 사용하여 클라이언트 재설정이 시작되기 전에 사용자에게 알릴 수 있습니다.

• onAfterReset: 자동 재설정이 성공적으로 완료된 경우에만 호출됩니다. Realm의 읽기 전용 이전 인스턴스와 최종 Realm의 변경 가능한 인스턴스를 제공합니다. 이 콜백을 사용하여 클라이언트 재설정이 완료되었음을 사용자에게 알릴 수 있습니다.

• onManualResetFallback: 자동 복구가 실패한 경우에만 호출됩니다. 로컬 변경 사항을 삭제하고 로컬 영역의 백업을 생성할 수 있습니다. 수동 복구 폴백 섹션에 설명된 대로 재설정 실패를 처리하려면 이 콜백을 구현합니다.

다음 예제에서는 RecoverUnsyncedChangesStrategy 및 각 콜백을 보여줍니다.

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

동기화되지 않은 변경 내용 삭제

동기화되지 않은 변경 사항 삭제 전략은 마지막 동기화에 성공한 이후 이루어진 모든 동기화되지 않은 로컬 변경 사항을 영구적으로 삭제합니다. 이 전략은 영역을 닫지 않고 알림이 완전히 작동하도록 유지하면서 로컬 영역 파일을 동기화 가능한 상태로 복원합니다. 이 프로세스가 실패하면 수동 재설정 전략으로 돌아갑니다.

이는 모든 수동 데이터 복구를 처리하는 데 권장되는 전략입니다.

앱에 Device Sync 클라이언트 복구 규칙 과 일치하지 않는 클라이언트 복구 로직이 필요하거나 동기화되지 않은 데이터를 복구하지 않으려는 경우 이 전략을 선택할 수 있습니다.

동기화되지 않은 변경 사항 삭제 전략을 사용하려면 DiscardUnsyncedChangesStrategy 인터페이스를 구현하는 핸들러를 정의하세요.

인터페이스는 다음과 같은 콜백 메서드를 제공합니다.

• onBeforeReset: 클라이언트 재설정 전에 호출됩니다. 재설정 전 영역의 인스턴스를 제공합니다. 이 콜백을 사용하여 클라이언트 재설정이 시작되기 전에 사용자에게 알릴 수 있습니다.

• onAfterReset: 재설정이 완료된 경우에만 호출됩니다. Realm의 읽기 전용 이전 인스턴스와 최종 Realm의 변경 가능한 인스턴스를 제공합니다. 이 콜백을 사용하여 사용자에게 재설정이 완료되었음을 알릴 수 있습니다.

• onManualResetFallback: 자동 복구 및 삭제 전략이 실패한 경우에만 호출됩니다. 로컬 변경 사항을 삭제하고 로컬 영역의 백업을 생성할 수 있습니다. 수동 복구 폴백 섹션에 설명된 대로 재설정 실패를 처리하려면 이 콜백을 구현합니다.

다음 예제에서는 DiscardUnsyncedChangesStrategy 및 각 콜백을 보여줍니다.

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

수동 복구 폴백

손상적인 스키마 변경 이 있는 경우와 같이 클라이언트 재설정을 자동으로 완료할 수 없는 경우 클라이언트 재설정 프로세스는 수동 오류 처리기로 넘어갑니다.

이는 자동 클라이언트 재설정 전략에서 발생할 수 있습니다.

• 동기화되지 않은 변경 내용 복구

• 동기화되지 않은 변경 사항 복구 또는 삭제

• 동기화되지 않은 변경 내용 삭제

이러한 전략을 사용하려면 클라이언트 재설정 핸들러의 onManualResetFallback 콜백에서 수동 클라이언트 재설정 구현을 제공해야 합니다.

수동 재설정 폴백은 로컬 변경 사항을 삭제하고 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
}

동기화되지 않은 변경 사항 수동 복구

드물게 데이터 복구 프로세스를 사용자 지정해야 하는 경우 동기화되지 않은 변경 사항 수동 복구 전략을 사용합니다. 수동 데이터 복구를 처리하려면 가능한 경우 동기화되지 않은 변경 사항 삭제 전략을 사용하는 것이 좋습니다. 자동 복구 로직이 앱 에 적합하지 않고 동기화되지 않은 로컬 데이터를 삭제할 수 없는 경우에만 동기화되지 않은 변경 사항 수동 복구 전략을 선택해야 합니다.

수동 복구 전략을 사용하려면 manuallyRecoverUnsyncedChangesStrategy 인터페이스를 사용하여 자체 클라이언트 재설정 핸들러를 정의하세요.

이 방법을 사용하기 전에 재설정하려는 영역의 모든 인스턴스를 닫아야 합니다. 수동 복구 콜백 이후와 클라이언트 재설정이 실행되기 전에 이루어진 Realm 파일에 대한 모든 쓰기는 동기화되지 않습니다. 또한 파일의 백업을 생성하고 예외를 보고하는 것이 좋습니다.

ClientResetRequiredException.executeClientReset() 을(를) 사용하여 클라이언트 재설정을 시작합니다.

클라이언트 재설정을 수동으로 실행하지 않으면 다음에 모든 영역 인스턴스를 닫았다가 다시 열 때(일반적으로 앱을 다시 시작할 때) 자동으로 실행됩니다.