Troubleshooting Automatic Account Recovery (AAR)

This article covers common failure modes and troubleshooting strategies for Automatic Account Recovery (AAR) (also known as Account Migration) when users switch devices or reinstall your application. (add a link to the original KB AAR article)

Core Requirements for AAR

Before troubleshooting specific errors, ensure these baseline conditions are met:

• Feature: AAR must be enabled in the Admin Dashboard under Settings > Features. (If disabled, contact support@futurae.com)
• Fresh Installation: The app on the new (target) device must be a fresh install with no other accounts enrolled. The automatic recovery process will not run if it detects an account on the device.
• System Backups:
  • iOS: iCloud Keychain must be enabled on both the source and target devices. If migrating via a physical computer, the iTunes backup must be encrypted.
  • Android: The app must implement a BackupAgent to include the Futurae SDK's data in the Android Backup service.

The End-to-End AAR Lifecycle

The Automatic Account Recovery lifecycle generally follows four phases:

iOS Troubleshooting

Platform Prerequisites

• iCloud Keychain: Must be explicitly turned ON in iOS Settings on both source and target devices.
• iTunes Backup Encryption: If backing up via a physical computer (macOS/PC), the iTunes backup must be encrypted for Keychain items to persist.
• SDK Version: Requires iOS SDK v3.x.x or higher to ensure cryptographic key persistence during iCloud restore cycles.

iOS Error Reference (SDKMigrationErrorCode)

When a migration fails on iOS, the SDKMigrationError object provides an sdkCode property mapped to SDKMigrationErrorCode.

*For a complete list of all enumeration cases (including noDeviceUDID and noMigrationToken), please refer to the official Futurae iOS SDK Documentation.

Testing on iOS

• Physical Device Testing (Recommended): Use two physical test devices signed into the same Apple ID with iCloud Keychain active.
• Simulated Local Wipe (Single Device): To clear historical SDK data and prepare a device for testing without corrupting synchronized keys, do not attempt manual Keychain deletion snippets (SecItemDelete). Deleting specific key classes alone leaves generic-password items (like device tokens and UDIDs) behind, which causes the SDK to throw an accountPreviouslyEnrolledError. Instead, invoke the SDK reset method to cleanly wipe local SDK state

Android Troubleshooting

Platform Prerequisites

• Manifest Configuration: Ensure android:allowBackup="true" is set in <application> and your custom BackupAgent is correctly registered.
• Cloud Backup Active: The user must have Cloud Backup enabled under Android System Settings (e.g., Google One, Samsung Cloud, etc.).

Android Error Reference (FTAccountsMigrationException)

Testing on Android

You do not need to wait for automatic OS backup schedules during testing. Use the Android Debug Bridge (ADB) to force immediate backup and restore cycles. For reference: https://developer.android.com/tools/adb, (specifically: https://developer.android.com/tools/bmgr)

1. Force a Backup (Source Device)

After you have enrolled an account and ensured your BackupAgent is implemented, run these commands to push the data to the cloud:

# Initialize and enable the backup manager
adb shell bmgr run
adb shell bmgr enabled

# Force an immediate backup for your app package
adb shell bmgr backupnow <your.package.name>

2. Force a Restore (Target/New Device)

To test the recovery flow without physically switching phones, you can uninstall and reinstall the app, then force a restore:

# List available backup sets to locate your <token>
adb shell bmgr list sets

# Force restore the backup payload to your app
adb shell bmgr restore <token> <your.package.name>

Ecosystem Limitation: Google Backup vs. Manufacturer Backups (e.g., Samsung Cloud)

A common point of confusion during both testing and production support is how different Android device manufacturers handle system backups.

• The Dependency: The Futurae Automatic Account Recovery solution relies strictly on the native Cloud Android Backup Service (Google Drive / Google Cloud).
• The Problem: Many Android device manufacturers implement their own parallel cloud ecosystems. For example, Samsung devices default to Samsung Cloud / Smart Switch backup systems, while other vendors utilize alternative proprietary cloud environments.
• The Reality: Proprietary manufacturer clouds (like Samsung Cloud) may not route data through the standard Android Backup Manager APIs. If an end-user backs up their old device using Samsung Cloud and attempts to restore it on a new device (especially a non-Samsung device like a Google Pixel), cross-cloud restoration will fail, and the Futurae recovery payload will be completely missing.

Trusted Binding Issues

If your Futurae implementation utilizes Trusted Binding and the migration stalls or fails on Android without a clear local exception, ensure that your application backend is successfully generating and providing a valid binding token to the client app during the recovery handshake.

Error Code Quick Reference (iOS/Android)

Advanced Testing & OS Edge Cases

Testing Automatic Account Recovery can be challenging because it relies on native OS backup managers, which operate asynchronously. Below are the specific commands and methods to force these processes for testing.

Android: Cross-Device Hardware Constraints

When simulating a two-device account migration environment, several native Android OS constraints outside of the Futurae SDK's control can prevent the onRestore() lifecycle method from executing successfully:

• Version Matching (android:restoreAnyVersion): By default, the android:restoreAnyVersion manifest attribute is set to false. This explicitly prevents Android from restoring backup archives that were originally generated by a newer version code of your application onto an older version installation. Ensure your test build version numbers match or surpass the backup source version.
• Per-Device Backup Sets: Google Backup Services partitions backup data pools per device hardware signature. The native OS cloud coordinator dynamically establishes which backup set to prioritize based on device synchronization logs, idle times, and payload metadata, meaning a target device may not immediately pull down data generated by a separate source testing device.
• Cloud Transport Fragmentation: Backup restoration pathways are strictly bound to the device manufacturer's cloud transport ecosystem. For example, Google Pixel hardware utilizes Google Cloud transport pools, whereas Samsung devices frequently prioritize Samsung Cloud architectures. Cross-cloud restore cycles between contrasting vendor infrastructures are fundamentally unsupported by the underlying Android operating system.

iOS: Simulating the Recovery Environment

Because true iCloud syncing requires two separate physical iPhones signed into the same Apple ID, you can simulate a restore lifecycle on a single device or simulator:

The "Simulated Migration" Flow

To test how your app handles the FTRAccountMigrationErrorNoMigrationInfo error or successful decryption:

1. Enroll an account in your app.
2. Uninstall the app (this simulates a "fresh" state) and reinstall.
3. The "iCloud" Simulation (Optional): If you want to simulate a new device where local (non-sync) keys are missing, use the SDK reset method: 'FTRClient.reset(...)' to delete only non-synchronizable items before the SDK initializes.
4. Initialize SDK: Call getMigratableAccounts. If the sync-keys (version 2.6.5+) are present, migration should be possible.

Best Practices & Troubleshooting Checklist for Developers

• Verify User Presence: If the SDK is configured with lock configuration type BIOMETRICS_ONLY, BIOMETRICS_OR_DEVICE_CREDENTIALS, or SDK_PIN_WITH_BIOMETRICS_OPTIONAL, always verify user presence (FaceID/TouchID/SDK PIN) before calling migrateAccounts.
• Two-Layered App Data (iOS): If you need to migrate your own app-specific data alongside Futurae accounts:
  • For Backups: Store a file in the app container and encrypt it with a kSecAttrSynchronizable = true key.
  • For Reinstalls: Store data directly in the Keychain with default settings.

Useful references:
Secure keychain syncing: https://support.apple.com/guide/security/secure-keychain-syncing-sec0a319b35f/web