@capgo/capacitor-updater 8.49.1 → 8.49.3

package/README.md

@@ -79,7 +79,7 @@ First follow the migration guide of Capacitor:
 - **Channel storage change**: `setChannel()` now stores channel assignments locally on the device instead of in the cloud. This provides better offline support and reduces backend load.
   - Channel assignments persist between app restarts
   - Use `unsetChannel()` to clear the local assignment and revert to `defaultChannel`
-  - Old devices (< v7.34.0) will continue using cloud-based storage
+  - Old devices (< v7.34.0) use now a KV storage to prevent overload the primary DB of Capgo
 - **New event**: Listen to the `channelPrivate` event to handle cases where a user tries to assign themselves to a private channel (one that doesn't allow self-assignment). See example in the `setChannel()` documentation above.
 
 ## Migration to v7
@@ -133,6 +133,20 @@ We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bun
 
 ## Installation
 
+You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
+
+```bash
+npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
+```
+
+Then use the following prompt:
+
+```text
+Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-updater` plugin in my project.
+```
+
+If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
+
 Step by step here: [Getting started](https://capgo.app/docs/getting-started/add-an-app/)
 
 Or
@@ -1246,6 +1260,11 @@ Assign this device to a specific update channel at runtime.
 Channels allow you to distribute different bundle versions to different groups of users
 (e.g., "production", "beta", "staging"). This method switches the device to a new channel.
 
+**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the
+selected channel locally on the device. It does not create or update a backend Device Override,
+so the device will not appear as overridden in the Capgo dashboard. Only assignments created
+from the dashboard or the Public API are shown in the Device Override UI.
+
 **Requirements:**
 - The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
 - The backend may accept or reject the request based on channel settings
@@ -1272,7 +1291,8 @@ CapacitorUpdater.addListener('channelPrivate', (data) =&gt; {
 });
 ```
 
-This sends a request to the Capgo backend linking your device ID to the specified channel.
+This sends a request to the Capgo backend to validate the specified channel, then stores the
+channel locally on the device.
 
 | Param         | Type                                                            | Description                                                                                                                  |
 | ------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@@ -1291,11 +1311,12 @@ This sends a request to the Capgo backend linking your device ID to the specifie
 unsetChannel(options: UnsetChannelOptions) => Promise<void>
 ```
 
-Remove the device's channel assignment and return to the default channel.
+Remove the plugin-managed local channel assignment and return to the default channel.
 
-This unlinks the device from any specifically assigned channel, causing it to fall back to:
+This clears only the channel stored locally by {@link setChannel}; it does not delete Dashboard or Public API Device Override records. After the local assignment is cleared, normal channel precedence applies:
+- An existing Dashboard or Public API Device Override, if one exists
 - The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
-- Your backend's default channel for this app
+- Your backend default channel for this app
 
 Use this when:
 - Users opt out of beta/testing programs
@@ -1444,7 +1465,7 @@ It's automatically generated and stored securely by the plugin.
 **Privacy & Security characteristics:**
 - Generated as a UUID (not based on hardware identifiers)
 - Stored securely in platform-specific secure storage
-- Android: Android Keystore (persists across app reinstalls on API 23+)
+- Android: mirrored into backup-restorable app preferences for reinstall restore
 - iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
 - Not synced to cloud (iOS)
 - Follows Apple and Google privacy best practices
@@ -1452,7 +1473,9 @@ It's automatically generated and stored securely by the plugin.
 
 **Persistence:**
 The device ID persists across app reinstalls to maintain consistent device identity
-for update tracking and analytics.
+for update tracking and analytics when platform storage is preserved. On Android,
+apps with custom backup rules must keep the plugin app preferences eligible for
+backup/restore; disabling Android backup or clearing app data creates a new ID.
 
 Use this to:
 - Debug update delivery issues (check what ID the server sees)

package/android/src/main/java/ee/forgr/capacitor_updater/CapacitorUpdaterPlugin.java

@@ -119,6 +119,11 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private static final String LAST_FAILED_BUNDLE_PREF_KEY = "CapacitorUpdater.lastFailedBundle";
     private static final String LAST_REPORTED_APP_EXIT_TIMESTAMP_PREF_KEY = "CapacitorUpdater.lastReportedAppExitTimestamp";
     private static final String LAST_WEBVIEW_RENDER_PROCESS_GONE_PREF_KEY = "CapacitorUpdater.lastWebViewRenderProcessGone";
+    private static final String LAST_VERSION_OS_PREF_KEY = "CapacitorUpdater.lastVersionOs";
+    private static final String LAST_VERSION_BUILD_PREF_KEY = "CapacitorUpdater.lastVersionBuild";
+    private static final String LAST_VERSION_CODE_PREF_KEY = "CapacitorUpdater.lastVersionCode";
+    private static final String OS_VERSION_CHANGED_ACTION = "os_version_changed";
+    private static final String NATIVE_APP_VERSION_CHANGED_ACTION = "native_app_version_changed";
     private static final String SPLASH_SCREEN_PLUGIN_ID = "SplashScreen";
     private static final int SPLASH_SCREEN_RETRY_DELAY_MS = 100;
     private static final int SPLASH_SCREEN_MAX_RETRIES = 20;
@@ -137,7 +142,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     static final int APPLICATION_EXIT_REASON_USER_REQUESTED = 10;
     static final int APPLICATION_EXIT_REASON_DEPENDENCY_DIED = 12;
 
-    private final String pluginVersion = "8.49.1";
+    private final String pluginVersion = "8.49.3";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -857,6 +862,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
             this.clearPreviewSessionForNativeBuildChange();
         }
         this.leavePreviewSessionForLaunchIntentIfNeeded();
+        this.reportNativeVersionStatsIfChanged();
         this.reportPreviousAppExitReasons();
         this.reportPreviousWebViewRenderProcessGone();
         this.installWebViewStatsReporter();
@@ -1299,6 +1305,109 @@ public class CapacitorUpdaterPlugin extends Plugin {
         return !lastKnownVersion.isEmpty() && !lastKnownVersion.equals(this.currentBuildVersion);
     }
 
+    void reportNativeVersionStatsIfChanged() {
+        if (this.implementation == null || this.prefs == null || this.editor == null) {
+            return;
+        }
+
+        this.reportNativeVersionStatsIfChanged(
+            this.implementation.versionBuild,
+            this.implementation.versionCode,
+            this.implementation.versionOs
+        );
+    }
+
+    void reportNativeVersionStatsIfChanged(
+        final String currentVersionBuild,
+        final String currentVersionCode,
+        final String currentVersionOs
+    ) {
+        if (this.implementation == null || this.prefs == null || this.editor == null) {
+            return;
+        }
+
+        final String normalizedVersionBuild = this.normalizedStatsValue(currentVersionBuild);
+        final String normalizedVersionCode = this.normalizedStatsValue(currentVersionCode);
+        final String normalizedVersionOs = this.normalizedStatsValue(currentVersionOs);
+        final String previousVersionOs = this.prefs.getString(LAST_VERSION_OS_PREF_KEY, "");
+        final String previousVersionBuild = this.prefs.getString(LAST_VERSION_BUILD_PREF_KEY, "");
+        final String previousVersionCode = this.prefs.getString(LAST_VERSION_CODE_PREF_KEY, "");
+        final boolean osVersionChanged =
+            !normalizedVersionOs.isEmpty() &&
+            previousVersionOs != null &&
+            !previousVersionOs.isEmpty() &&
+            !previousVersionOs.equals(normalizedVersionOs);
+
+        if (osVersionChanged) {
+            final Map<String, String> metadata = new HashMap<>();
+            metadata.put("previous_version_os", previousVersionOs);
+            metadata.put("current_version_os", normalizedVersionOs);
+            this.implementation.sendStats(
+                OS_VERSION_CHANGED_ACTION,
+                this.implementation.getCurrentBundle().getVersionName(),
+                "",
+                metadata,
+                () -> this.persistLastVersionOs(normalizedVersionOs)
+            );
+        }
+
+        final boolean hasPreviousNativeVersion =
+            (previousVersionBuild != null && !previousVersionBuild.isEmpty()) ||
+            (previousVersionCode != null && !previousVersionCode.isEmpty());
+        final boolean nativeVersionChanged =
+            hasPreviousNativeVersion &&
+            (!Objects.equals(previousVersionBuild, normalizedVersionBuild) || !Objects.equals(previousVersionCode, normalizedVersionCode));
+
+        if (nativeVersionChanged) {
+            final Map<String, String> metadata = new HashMap<>();
+            metadata.put("previous_version_build", previousVersionBuild == null ? "" : previousVersionBuild);
+            metadata.put("current_version_build", normalizedVersionBuild);
+            metadata.put("previous_version_code", previousVersionCode == null ? "" : previousVersionCode);
+            metadata.put("current_version_code", normalizedVersionCode);
+            this.implementation.sendStats(
+                NATIVE_APP_VERSION_CHANGED_ACTION,
+                this.implementation.getCurrentBundle().getVersionName(),
+                "",
+                metadata,
+                () -> this.persistLastNativeAppVersion(normalizedVersionBuild, normalizedVersionCode)
+            );
+        }
+
+        if (!osVersionChanged || !nativeVersionChanged) {
+            if (!osVersionChanged) {
+                this.editor.putString(LAST_VERSION_OS_PREF_KEY, normalizedVersionOs);
+            }
+            if (!nativeVersionChanged) {
+                this.editor.putString(LAST_VERSION_BUILD_PREF_KEY, normalizedVersionBuild);
+                this.editor.putString(LAST_VERSION_CODE_PREF_KEY, normalizedVersionCode);
+            }
+            this.editor.apply();
+        }
+    }
+
+    private void persistLastVersionOs(final String versionOs) {
+        if (this.editor == null) {
+            return;
+        }
+
+        this.editor.putString(LAST_VERSION_OS_PREF_KEY, versionOs);
+        this.editor.apply();
+    }
+
+    private void persistLastNativeAppVersion(final String versionBuild, final String versionCode) {
+        if (this.editor == null) {
+            return;
+        }
+
+        this.editor.putString(LAST_VERSION_BUILD_PREF_KEY, versionBuild);
+        this.editor.putString(LAST_VERSION_CODE_PREF_KEY, versionCode);
+        this.editor.apply();
+    }
+
+    private String normalizedStatsValue(final String value) {
+        return value == null ? "" : value;
+    }
+
     private void reportPreviousAppExitReasons() {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R || this.implementation == null || this.implementation.statsUrl.isEmpty()) {
             return;

package/android/src/main/java/ee/forgr/capacitor_updater/CapgoUpdater.java

@@ -102,11 +102,22 @@ public class CapgoUpdater {
     private static volatile boolean rateLimitStatisticSent = false;
 
     // Stats batching - queue events and send max once per second
-    private final List<JSONObject> statsQueue = new CopyOnWriteArrayList<>();
+    private final List<QueuedStatsEvent> statsQueue = new CopyOnWriteArrayList<>();
     private final ScheduledExecutorService statsScheduler = Executors.newSingleThreadScheduledExecutor();
     private ScheduledFuture<?> statsFlushTask = null;
     private static final long STATS_FLUSH_INTERVAL_MS = 1000;
 
+    private static final class QueuedStatsEvent {
+
+        private final JSONObject event;
+        private final Runnable onSent;
+
+        private QueuedStatsEvent(final JSONObject event, final Runnable onSent) {
+            this.event = event;
+            this.onSent = onSent;
+        }
+    }
+
     private final Map<String, CompletableFuture<BundleInfo>> downloadFutures = new ConcurrentHashMap<>();
     private final ExecutorService io = Executors.newSingleThreadExecutor();
 
@@ -2086,6 +2097,16 @@ public class CapgoUpdater {
     }
 
     public void sendStats(final String action, final String versionName, final String oldVersionName, final Map<String, String> metadata) {
+        this.sendStats(action, versionName, oldVersionName, metadata, null);
+    }
+
+    public void sendStats(
+        final String action,
+        final String versionName,
+        final String oldVersionName,
+        final Map<String, String> metadata,
+        final Runnable onSent
+    ) {
         if (this.previewSession) {
             if (logger != null) {
                 logger.debug("Skipping sendStats during preview session.");
@@ -2120,7 +2141,7 @@ public class CapgoUpdater {
             return;
         }
 
-        statsQueue.add(json);
+        statsQueue.add(new QueuedStatsEvent(json, onSent));
         ensureStatsTimerStarted();
     }
 
@@ -2147,7 +2168,7 @@ public class CapgoUpdater {
         }
 
         // Copy and clear the queue atomically using synchronized block
-        List<JSONObject> eventsToSend;
+        List<QueuedStatsEvent> eventsToSend;
         synchronized (statsQueue) {
             if (statsQueue.isEmpty()) {
                 return;
@@ -2157,8 +2178,8 @@ public class CapgoUpdater {
         }
 
         JSONArray jsonArray = new JSONArray();
-        for (JSONObject event : eventsToSend) {
-            jsonArray.put(event);
+        for (QueuedStatsEvent queuedEvent : eventsToSend) {
+            jsonArray.put(queuedEvent.event);
         }
 
         Request request = new Request.Builder()
@@ -2186,6 +2207,7 @@ public class CapgoUpdater {
                         if (response.isSuccessful()) {
                             logger.info("Stats batch sent successfully");
                             logger.debug("Sent " + eventCount + " events");
+                            runStatsCallbacks(eventsToSend);
                         } else {
                             logger.error("Error sending stats batch");
                             logger.debug("Response code: " + response.code());
@@ -2196,6 +2218,23 @@ public class CapgoUpdater {
         );
     }
 
+    private void runStatsCallbacks(final List<QueuedStatsEvent> sentEvents) {
+        for (final QueuedStatsEvent sentEvent : sentEvents) {
+            if (sentEvent.onSent == null) {
+                continue;
+            }
+
+            try {
+                sentEvent.onSent.run();
+            } catch (Exception e) {
+                if (logger != null) {
+                    logger.error("Error running stats sent callback");
+                    logger.debug("Error: " + e.getMessage());
+                }
+            }
+        }
+    }
+
     public BundleInfo getBundleInfo(final String id) {
         String trueId = BundleInfo.VERSION_UNKNOWN;
         if (id != null) {

package/android/src/main/java/ee/forgr/capacitor_updater/DeviceIdHelper.java

@@ -26,10 +26,10 @@ import javax.crypto.spec.GCMParameterSpec;
 
 /**
  * Helper class to manage device ID persistence across app installations.
- * Uses Android Keystore to persist the device ID across reinstalls.
+ * Uses Android Keystore-backed storage and backup-restorable SharedPreferences.
  *
- * The device ID is a random UUID stored in the Android Keystore, which persists
- * even after app uninstall/reinstall on Android 6.0+ (API 23+).
+ * The device ID is a random UUID stored in encrypted preferences and mirrored
+ * to appUUID so Android backup/restore can keep it across reinstalls.
  */
 public class DeviceIdHelper {
 
@@ -45,10 +45,10 @@ public class DeviceIdHelper {
      * Gets or creates a device ID that persists across reinstalls.
      *
      * This method:
-     * 1. First checks for an existing ID in Keystore-encrypted storage (persists across reinstalls)
-     * 2. Falls back to legacy SharedPreferences (for migration)
+     * 1. First checks for an existing ID in Keystore-encrypted storage
+     * 2. Falls back to legacy SharedPreferences restored by Android backup
      * 3. Generates a new UUID if neither exists
-     * 4. Stores the ID in Keystore-encrypted storage for future use
+     * 4. Stores the ID synchronously in both stores for future use
      *
      * @param context Application context
      * @param legacyPrefs Legacy SharedPreferences (for migration)
@@ -60,7 +60,9 @@ public class DeviceIdHelper {
             String deviceId = getDeviceIdFromKeystore(context);
 
             if (deviceId != null && !deviceId.isEmpty()) {
-                return deviceId.toLowerCase();
+                deviceId = deviceId.toLowerCase();
+                saveLegacyDeviceId(legacyPrefs, deviceId);
+                return deviceId;
             }
 
             // Migration: Check legacy SharedPreferences for existing device ID
@@ -74,7 +76,8 @@ public class DeviceIdHelper {
             // Ensure lowercase for consistency
             deviceId = deviceId.toLowerCase();
 
-            // Save to Keystore storage
+            // Save to backup-restorable preferences and Keystore storage
+            saveLegacyDeviceId(legacyPrefs, deviceId);
             saveDeviceIdToKeystore(context, deviceId);
 
             return deviceId;
@@ -90,31 +93,35 @@ public class DeviceIdHelper {
      * @param context Application context
      * @return Device ID string or null if not found
      */
-    private static String getDeviceIdFromKeystore(Context context) throws Exception {
-        SharedPreferences prefs = context.getSharedPreferences(DEVICE_ID_PREFS, Context.MODE_PRIVATE);
-        String encryptedDeviceId = prefs.getString(DEVICE_ID_KEY, null);
-        String ivString = prefs.getString(IV_KEY, null);
+    private static String getDeviceIdFromKeystore(Context context) {
+        try {
+            SharedPreferences prefs = context.getSharedPreferences(DEVICE_ID_PREFS, Context.MODE_PRIVATE);
+            String encryptedDeviceId = prefs.getString(DEVICE_ID_KEY, null);
+            String ivString = prefs.getString(IV_KEY, null);
 
-        if (encryptedDeviceId == null || ivString == null) {
-            return null;
-        }
+            if (encryptedDeviceId == null || ivString == null) {
+                return null;
+            }
 
-        // Get the encryption key from Keystore
-        SecretKey key = getOrCreateKey();
-        if (key == null) {
-            return null;
-        }
+            // Get the encryption key from Keystore
+            SecretKey key = getOrCreateKey();
+            if (key == null) {
+                return null;
+            }
 
-        // Decrypt the device ID
-        byte[] encryptedBytes = android.util.Base64.decode(encryptedDeviceId, android.util.Base64.DEFAULT);
-        byte[] iv = android.util.Base64.decode(ivString, android.util.Base64.DEFAULT);
+            // Decrypt the device ID
+            byte[] encryptedBytes = android.util.Base64.decode(encryptedDeviceId, android.util.Base64.DEFAULT);
+            byte[] iv = android.util.Base64.decode(ivString, android.util.Base64.DEFAULT);
 
-        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
-        GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH, iv);
-        cipher.init(Cipher.DECRYPT_MODE, key, spec);
+            Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+            GCMParameterSpec spec = new GCMParameterSpec(GCM_TAG_LENGTH, iv);
+            cipher.init(Cipher.DECRYPT_MODE, key, spec);
 
-        byte[] decryptedBytes = cipher.doFinal(encryptedBytes);
-        return new String(decryptedBytes, StandardCharsets.UTF_8);
+            byte[] decryptedBytes = cipher.doFinal(encryptedBytes);
+            return new String(decryptedBytes, StandardCharsets.UTF_8);
+        } catch (Exception e) {
+            return null;
+        }
     }
 
     /**
@@ -146,7 +153,7 @@ public class DeviceIdHelper {
             .edit()
             .putString(DEVICE_ID_KEY, android.util.Base64.encodeToString(encryptedBytes, android.util.Base64.DEFAULT))
             .putString(IV_KEY, android.util.Base64.encodeToString(iv, android.util.Base64.DEFAULT))
-            .apply();
+            .commit();
     }
 
     /**
@@ -207,9 +214,17 @@ public class DeviceIdHelper {
 
         if (deviceId == null || deviceId.isEmpty()) {
             deviceId = UUID.randomUUID().toString();
-            legacyPrefs.edit().putString(LEGACY_PREFS_KEY, deviceId).apply();
+            saveLegacyDeviceId(legacyPrefs, deviceId);
         }
 
         return deviceId.toLowerCase();
     }
+
+    private static void saveLegacyDeviceId(SharedPreferences legacyPrefs, String deviceId) {
+        if (legacyPrefs == null || deviceId == null || deviceId.isEmpty()) {
+            return;
+        }
+
+        legacyPrefs.edit().putString(LEGACY_PREFS_KEY, deviceId).commit();
+    }
 }

package/dist/docs.json

@@ -846,7 +846,7 @@
             "text": "4.7.0"
           }
         ],
-        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend linking your device ID to the specified channel.",
+        "docs": "Assign this device to a specific update channel at runtime.\n\nChannels allow you to distribute different bundle versions to different groups of users\n(e.g., \"production\", \"beta\", \"staging\"). This method switches the device to a new channel.\n\n**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the\nselected channel locally on the device. It does not create or update a backend Device Override,\nso the device will not appear as overridden in the Capgo dashboard. Only assignments created\nfrom the dashboard or the Public API are shown in the Device Override UI.\n\n**Requirements:**\n- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)\n- The backend may accept or reject the request based on channel settings\n\n**When to use:**\n- After the app is ready and the user has interacted (e.g., opted into beta program)\n- To implement in-app channel switching (beta toggle, tester access, etc.)\n- For user-driven channel changes\n\n**When NOT to use:**\n- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead\n- Before user interaction\n\n**Important: Listen for the `channelPrivate` event**\n\nWhen a user attempts to set a channel that doesn't allow device self-assignment, the method will\nthrow an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event\nto provide appropriate feedback to users:\n\n```typescript\nCapacitorUpdater.addListener('channelPrivate', (data) => {\n  console.warn(`Cannot access channel \"${data.channel}\": ${data.message}`);\n  // Show user-friendly message\n});\n```\n\nThis sends a request to the Capgo backend to validate the specified channel, then stores the\nchannel locally on the device.",
         "complexTypes": [
           "ChannelRes",
           "SetChannelOptions"
@@ -886,7 +886,7 @@
             "text": "4.7.0"
           }
         ],
-        "docs": "Remove the device's channel assignment and return to the default channel.\n\nThis unlinks the device from any specifically assigned channel, causing it to fall back to:\n- The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or\n- Your backend's default channel for this app\n\nUse this when:\n- Users opt out of beta/testing programs\n- You want to reset a device to standard update distribution\n- Testing channel switching behavior",
+        "docs": "Remove the plugin-managed local channel assignment and return to the default channel.\n\nThis clears only the channel stored locally by {@link setChannel}; it does not delete Dashboard or Public API Device Override records. After the local assignment is cleared, normal channel precedence applies:\n- An existing Dashboard or Public API Device Override, if one exists\n- The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or\n- Your backend default channel for this app\n\nUse this when:\n- Users opt out of beta/testing programs\n- You want to reset a device to standard update distribution\n- Testing channel switching behavior",
         "complexTypes": [
           "UnsetChannelOptions"
         ],
@@ -1013,7 +1013,7 @@
             "text": "{Error} If the operation fails."
           }
         ],
-        "docs": "Get the unique, privacy-friendly identifier for this device.\n\nThis ID is used to identify the device when communicating with update servers.\nIt's automatically generated and stored securely by the plugin.\n\n**Privacy & Security characteristics:**\n- Generated as a UUID (not based on hardware identifiers)\n- Stored securely in platform-specific secure storage\n- Android: Android Keystore (persists across app reinstalls on API 23+)\n- iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`\n- Not synced to cloud (iOS)\n- Follows Apple and Google privacy best practices\n- Users can clear it via system settings (Android) or keychain access (iOS)\n\n**Persistence:**\nThe device ID persists across app reinstalls to maintain consistent device identity\nfor update tracking and analytics.\n\nUse this to:\n- Debug update delivery issues (check what ID the server sees)\n- Implement device-specific features\n- Correlate server logs with specific devices",
+        "docs": "Get the unique, privacy-friendly identifier for this device.\n\nThis ID is used to identify the device when communicating with update servers.\nIt's automatically generated and stored securely by the plugin.\n\n**Privacy & Security characteristics:**\n- Generated as a UUID (not based on hardware identifiers)\n- Stored securely in platform-specific secure storage\n- Android: mirrored into backup-restorable app preferences for reinstall restore\n- iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`\n- Not synced to cloud (iOS)\n- Follows Apple and Google privacy best practices\n- Users can clear it via system settings (Android) or keychain access (iOS)\n\n**Persistence:**\nThe device ID persists across app reinstalls to maintain consistent device identity\nfor update tracking and analytics when platform storage is preserved. On Android,\napps with custom backup rules must keep the plugin app preferences eligible for\nbackup/restore; disabling Android backup or clearing app data creates a new ID.\n\nUse this to:\n- Debug update delivery issues (check what ID the server sees)\n- Implement device-specific features\n- Correlate server logs with specific devices",
         "complexTypes": [
           "DeviceId"
         ],

package/dist/esm/definitions.d.ts

@@ -938,6 +938,11 @@ export interface CapacitorUpdaterPlugin {
      * Channels allow you to distribute different bundle versions to different groups of users
      * (e.g., "production", "beta", "staging"). This method switches the device to a new channel.
      *
+     * **Device Override UI:** `setChannel()` validates the channel with the backend, then stores the
+     * selected channel locally on the device. It does not create or update a backend Device Override,
+     * so the device will not appear as overridden in the Capgo dashboard. Only assignments created
+     * from the dashboard or the Public API are shown in the Device Override UI.
+     *
      * **Requirements:**
      * - The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
      * - The backend may accept or reject the request based on channel settings
@@ -964,7 +969,8 @@ export interface CapacitorUpdaterPlugin {
      * });
      * ```
      *
-     * This sends a request to the Capgo backend linking your device ID to the specified channel.
+     * This sends a request to the Capgo backend to validate the specified channel, then stores the
+     * channel locally on the device.
      *
      * @param options The {@link SetChannelOptions} containing the channel name and optional auto-update trigger.
      * @returns {Promise<ChannelRes>} Channel operation result with status and optional error/message.
@@ -973,11 +979,12 @@ export interface CapacitorUpdaterPlugin {
      */
     setChannel(options: SetChannelOptions): Promise<ChannelRes>;
     /**
-     * Remove the device's channel assignment and return to the default channel.
+     * Remove the plugin-managed local channel assignment and return to the default channel.
      *
-     * This unlinks the device from any specifically assigned channel, causing it to fall back to:
+     * This clears only the channel stored locally by {@link setChannel}; it does not delete Dashboard or Public API Device Override records. After the local assignment is cleared, normal channel precedence applies:
+     * - An existing Dashboard or Public API Device Override, if one exists
      * - The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
-     * - Your backend's default channel for this app
+     * - Your backend default channel for this app
      *
      * Use this when:
      * - Users opt out of beta/testing programs
@@ -1088,7 +1095,7 @@ export interface CapacitorUpdaterPlugin {
      * **Privacy & Security characteristics:**
      * - Generated as a UUID (not based on hardware identifiers)
      * - Stored securely in platform-specific secure storage
-     * - Android: Android Keystore (persists across app reinstalls on API 23+)
+     * - Android: mirrored into backup-restorable app preferences for reinstall restore
      * - iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
      * - Not synced to cloud (iOS)
      * - Follows Apple and Google privacy best practices
@@ -1096,7 +1103,9 @@ export interface CapacitorUpdaterPlugin {
      *
      * **Persistence:**
      * The device ID persists across app reinstalls to maintain consistent device identity
-     * for update tracking and analytics.
+     * for update tracking and analytics when platform storage is preserved. On Android,
+     * apps with custom backup rules must keep the plugin app preferences eligible for
+     * backup/restore; disabling Android backup or clearing app data creates a new ID.
      *
      * Use this to:
      * - Debug update delivery issues (check what ID the server sees)