@capgo/capacitor-updater 8.49.0 → 8.49.2

package/README.md

@@ -1246,6 +1246,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 +1277,8 @@ CapacitorUpdater.addListener('channelPrivate', (data) => {
 });
 ```
 
-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 +1297,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 +1451,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 +1459,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.0";
+    private final String pluginVersion = "8.49.2";
     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();
+    }
 }