@capgo/capacitor-updater 7.23.13 → 7.25.0

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

@@ -71,7 +71,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private static final String[] BREAKING_EVENT_NAMES = { "breakingAvailable", "majorAvailable" };
     private static final String LAST_FAILED_BUNDLE_PREF_KEY = "CapacitorUpdater.lastFailedBundle";
 
-    private final String PLUGIN_VERSION = "7.23.13";
+    private final String pluginVersion = "7.25.0";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -97,6 +97,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private Boolean autoSplashscreenTimedOut = false;
     private String directUpdateMode = "false";
     private Boolean wasRecentlyInstalledOrUpdated = false;
+    private Boolean onLaunchDirectUpdateUsed = false;
     Boolean shakeMenuEnabled = false;
     private Boolean allowManualBundleError = false;
 
@@ -219,14 +220,30 @@ public class CapacitorUpdaterPlugin extends Plugin {
             this.implementation.activity = this.getActivity();
             this.implementation.versionBuild = this.getConfig().getString("version", pInfo.versionName);
             this.implementation.CAP_SERVER_PATH = WebView.CAP_SERVER_PATH;
-            this.implementation.PLUGIN_VERSION = this.PLUGIN_VERSION;
+            this.implementation.pluginVersion = this.pluginVersion;
             this.implementation.versionCode = Integer.toString(pInfo.versionCode);
             // Removed unused OkHttpClient creation - using shared client in DownloadService instead
             // Handle directUpdate configuration - support string values and backward compatibility
             String directUpdateConfig = this.getConfig().getString("directUpdate", null);
             if (directUpdateConfig != null) {
                 this.directUpdateMode = directUpdateConfig;
-                this.implementation.directUpdate = directUpdateConfig.equals("always") || directUpdateConfig.equals("atInstall");
+                this.implementation.directUpdate =
+                    directUpdateConfig.equals("always") || directUpdateConfig.equals("atInstall") || directUpdateConfig.equals("onLaunch");
+                // Validate directUpdate value
+                if (
+                    !directUpdateConfig.equals("false") &&
+                    !directUpdateConfig.equals("always") &&
+                    !directUpdateConfig.equals("atInstall") &&
+                    !directUpdateConfig.equals("onLaunch")
+                ) {
+                    logger.error(
+                        "Invalid directUpdate value: \"" +
+                            directUpdateConfig +
+                            "\". Supported values are: false, \"always\", \"atInstall\", \"onLaunch\". Defaulting to false."
+                    );
+                    this.directUpdateMode = "false";
+                    this.implementation.directUpdate = false;
+                }
             } else {
                 Boolean directUpdateBool = this.getConfig().getBoolean("directUpdate", false);
                 if (directUpdateBool) {
@@ -308,12 +325,11 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.implementation.prefs = this.prefs;
         this.implementation.editor = this.editor;
         this.implementation.versionOs = Build.VERSION.RELEASE;
-        this.implementation.deviceID = this.prefs.getString("appUUID", UUID.randomUUID().toString()).toLowerCase();
-        this.editor.putString("appUUID", this.implementation.deviceID);
-        this.editor.apply();
+        // Use DeviceIdHelper to get or create device ID that persists across reinstalls
+        this.implementation.deviceID = DeviceIdHelper.getOrCreateDeviceId(this.getContext(), this.prefs);
 
         // Update User-Agent for shared OkHttpClient with OS version
-        DownloadService.updateUserAgent(this.implementation.appId, this.PLUGIN_VERSION, this.implementation.versionOs);
+        DownloadService.updateUserAgent(this.implementation.appId, this.pluginVersion, this.implementation.versionOs);
 
         if (Boolean.TRUE.equals(this.persistCustomId)) {
             final String storedCustomId = this.prefs.getString(CUSTOM_ID_PREF_KEY, "");
@@ -626,7 +642,17 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     return true;
                 }
                 return false;
+            case "onLaunch":
+                if (!this.onLaunchDirectUpdateUsed) {
+                    return true;
+                }
+                return false;
             default:
+                logger.error(
+                    "Invalid directUpdateMode: \"" +
+                        this.directUpdateMode +
+                        "\". Supported values are: \"false\", \"always\", \"atInstall\", \"onLaunch\". Defaulting to false behavior."
+                );
                 return false;
         }
     }
@@ -636,6 +662,10 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     private void directUpdateFinish(final BundleInfo latest) {
+        if ("onLaunch".equals(this.directUpdateMode)) {
+            this.onLaunchDirectUpdateUsed = true;
+            this.implementation.directUpdate = false;
+        }
         CapacitorUpdaterPlugin.this.implementation.set(latest);
         CapacitorUpdaterPlugin.this._reload();
         sendReadyToJs(latest, "update installed", true);
@@ -810,7 +840,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     public void getPluginVersion(final PluginCall call) {
         try {
             final JSObject ret = new JSObject();
-            ret.put("version", this.PLUGIN_VERSION);
+            ret.put("version", this.pluginVersion);
             call.resolve(ret);
         } catch (final Exception e) {
             logger.error("Could not get plugin version " + e.getMessage());
@@ -1940,9 +1970,17 @@ public class CapacitorUpdaterPlugin extends Plugin {
             }
 
             if (!this.shouldUseDirectUpdate()) {
-                logger.warn(
-                    "autoSplashscreen is enabled but directUpdate is not configured for immediate updates. Set directUpdate to 'always' or 'atInstall', or disable autoSplashscreen."
-                );
+                if ("false".equals(this.directUpdateMode)) {
+                    logger.warn(
+                        "autoSplashscreen is enabled but directUpdate is not configured for immediate updates. Set directUpdate to 'always' or disable autoSplashscreen."
+                    );
+                } else if ("atInstall".equals(this.directUpdateMode) || "onLaunch".equals(this.directUpdateMode)) {
+                    logger.info(
+                        "autoSplashscreen is enabled but directUpdate is set to \"" +
+                            this.directUpdateMode +
+                            "\". This is normal. Skipping autoSplashscreen logic."
+                    );
+                }
                 canShowSplashscreen = false;
             }
 

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

@@ -66,7 +66,7 @@ public class CapgoUpdater {
     public File documentsDir;
     public Boolean directUpdate = false;
     public Activity activity;
-    public String PLUGIN_VERSION = "";
+    public String pluginVersion = "";
     public String versionBuild = "";
     public String versionCode = "";
     public String versionOs = "";
@@ -353,7 +353,7 @@ public class CapgoUpdater {
             manifest != null,
             this.isEmulator(),
             this.appId,
-            this.PLUGIN_VERSION
+            this.pluginVersion
         );
 
         if (manifest != null) {
@@ -775,7 +775,7 @@ public class CapgoUpdater {
         json.put("version_code", this.versionCode);
         json.put("version_os", this.versionOs);
         json.put("version_name", this.getCurrentBundle().getVersionName());
-        json.put("plugin_version", this.PLUGIN_VERSION);
+        json.put("plugin_version", this.pluginVersion);
         json.put("is_emulator", this.isEmulator());
         json.put("is_prod", this.isProd());
         json.put("defaultChannel", this.defaultChannel);

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

@@ -0,0 +1,221 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+package ee.forgr.capacitor_updater;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.os.Build;
+import android.security.keystore.KeyGenParameterSpec;
+import android.security.keystore.KeyProperties;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.security.KeyStore;
+import java.security.KeyStoreException;
+import java.security.NoSuchAlgorithmException;
+import java.security.NoSuchProviderException;
+import java.security.UnrecoverableEntryException;
+import java.security.cert.CertificateException;
+import java.util.UUID;
+import javax.crypto.Cipher;
+import javax.crypto.KeyGenerator;
+import javax.crypto.SecretKey;
+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.
+ *
+ * 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+).
+ */
+public class DeviceIdHelper {
+
+    private static final String KEYSTORE_ALIAS = "capgo_device_id_key";
+    private static final String ANDROID_KEYSTORE = "AndroidKeyStore";
+    private static final String LEGACY_PREFS_KEY = "appUUID";
+    private static final String DEVICE_ID_PREFS = "capgo_device_id";
+    private static final String DEVICE_ID_KEY = "deviceId";
+    private static final String IV_KEY = "iv";
+    private static final int GCM_TAG_LENGTH = 128;
+
+    /**
+     * 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)
+     * 3. Generates a new UUID if neither exists
+     * 4. Stores the ID in Keystore-encrypted storage for future use
+     *
+     * @param context Application context
+     * @param legacyPrefs Legacy SharedPreferences (for migration)
+     * @return Device ID as a lowercase UUID string
+     */
+    public static String getOrCreateDeviceId(Context context, SharedPreferences legacyPrefs) {
+        // API 23+ required for Android Keystore
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.M) {
+            return getFallbackDeviceId(legacyPrefs);
+        }
+
+        try {
+            // Try to get device ID from Keystore storage
+            String deviceId = getDeviceIdFromKeystore(context);
+
+            if (deviceId != null && !deviceId.isEmpty()) {
+                return deviceId.toLowerCase();
+            }
+
+            // Migration: Check legacy SharedPreferences for existing device ID
+            deviceId = legacyPrefs.getString(LEGACY_PREFS_KEY, null);
+
+            if (deviceId == null || deviceId.isEmpty()) {
+                // Generate new device ID if none exists
+                deviceId = UUID.randomUUID().toString();
+            }
+
+            // Ensure lowercase for consistency
+            deviceId = deviceId.toLowerCase();
+
+            // Save to Keystore storage
+            saveDeviceIdToKeystore(context, deviceId);
+
+            return deviceId;
+        } catch (Exception e) {
+            // Fallback to legacy method if Keystore fails
+            return getFallbackDeviceId(legacyPrefs);
+        }
+    }
+
+    /**
+     * Retrieves the device ID from Keystore-encrypted storage.
+     *
+     * @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);
+
+        if (encryptedDeviceId == null || ivString == 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);
+
+        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);
+    }
+
+    /**
+     * Saves the device ID to Keystore-encrypted storage.
+     *
+     * The device ID is encrypted using AES/GCM with a key stored in Android Keystore.
+     * The Keystore key persists across reinstalls on Android 6.0+ (API 23+).
+     *
+     * @param context Application context
+     * @param deviceId The device ID to save
+     */
+    private static void saveDeviceIdToKeystore(Context context, String deviceId) throws Exception {
+        // Get or create encryption key in Keystore
+        SecretKey key = getOrCreateKey();
+        if (key == null) {
+            throw new Exception("Failed to get encryption key");
+        }
+
+        // Encrypt the device ID
+        Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
+        cipher.init(Cipher.ENCRYPT_MODE, key);
+
+        byte[] iv = cipher.getIV();
+        byte[] encryptedBytes = cipher.doFinal(deviceId.getBytes(StandardCharsets.UTF_8));
+
+        // Store encrypted device ID and IV in SharedPreferences
+        SharedPreferences prefs = context.getSharedPreferences(DEVICE_ID_PREFS, Context.MODE_PRIVATE);
+        prefs
+            .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();
+    }
+
+    /**
+     * Gets or creates the encryption key in Android Keystore.
+     *
+     * The key is configured to persist across reinstalls and not require user authentication.
+     *
+     * @return SecretKey from Keystore or null if failed
+     */
+    private static SecretKey getOrCreateKey() {
+        try {
+            KeyStore keyStore = KeyStore.getInstance(ANDROID_KEYSTORE);
+            keyStore.load(null);
+
+            // Check if key already exists
+            if (keyStore.containsAlias(KEYSTORE_ALIAS)) {
+                KeyStore.SecretKeyEntry entry = (KeyStore.SecretKeyEntry) keyStore.getEntry(KEYSTORE_ALIAS, null);
+                return entry.getSecretKey();
+            }
+
+            // Create new key
+            KeyGenerator keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, ANDROID_KEYSTORE);
+
+            KeyGenParameterSpec keySpec = new KeyGenParameterSpec.Builder(
+                KEYSTORE_ALIAS,
+                KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT
+            )
+                .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+                .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+                .setKeySize(256)
+                .setRandomizedEncryptionRequired(true)
+                .build();
+
+            keyGenerator.init(keySpec);
+            return keyGenerator.generateKey();
+        } catch (
+            KeyStoreException
+            | CertificateException
+            | NoSuchAlgorithmException
+            | IOException
+            | NoSuchProviderException
+            | UnrecoverableEntryException e
+        ) {
+            return null;
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    /**
+     * Fallback method using legacy SharedPreferences if Keystore fails or API < 23.
+     *
+     * @param legacyPrefs Legacy SharedPreferences
+     * @return Device ID string
+     */
+    private static String getFallbackDeviceId(SharedPreferences legacyPrefs) {
+        String deviceId = legacyPrefs.getString(LEGACY_PREFS_KEY, null);
+
+        if (deviceId == null || deviceId.isEmpty()) {
+            deviceId = UUID.randomUUID().toString();
+            legacyPrefs.edit().putString(LEGACY_PREFS_KEY, deviceId).apply();
+        }
+
+        return deviceId.toLowerCase();
+    }
+}

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

@@ -63,7 +63,7 @@ public class DownloadService extends Worker {
     public static final String PUBLIC_KEY = "publickey";
     public static final String IS_MANIFEST = "is_manifest";
     public static final String APP_ID = "app_id";
-    public static final String PLUGIN_VERSION = "plugin_version";
+    public static final String pluginVersion = "plugin_version";
     private static final String UPDATE_FILE = "update.dat";
 
     // Shared OkHttpClient to prevent resource leaks

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

@@ -80,7 +80,7 @@ public class DownloadWorkerManager {
             .putBoolean(DownloadService.IS_MANIFEST, isManifest)
             .putString(DownloadService.PUBLIC_KEY, publicKey)
             .putString(DownloadService.APP_ID, appId)
-            .putString(DownloadService.PLUGIN_VERSION, pluginVersion)
+            .putString(DownloadService.pluginVersion, pluginVersion)
             .build();
 
         // Create network constraints - be more lenient on emulators

package/dist/docs.json

@@ -679,7 +679,7 @@
             "text": "{Error}"
           }
         ],
-        "docs": "Get unique ID used to identify device (sent to auto update server), this ID is made following Apple and Google privacy best practices, and not persisted between installs",
+        "docs": "Get unique ID used to identify device (sent to auto update server).\n\nThis ID is privacy-friendly and follows Apple and Google best practices:\n- Generated as a UUID and stored securely\n- Android: Uses EncryptedSharedPreferences with Auto Backup (persists across reinstalls)\n- iOS: Uses Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly (persists across reinstalls)\n- Data stays on device (not synced to cloud on iOS)\n- Can be cleared by user via system settings (Android) or keychain access (iOS)\n\nThe device ID now persists between app reinstalls to maintain consistent device identity.",
         "complexTypes": [
           "DeviceId"
         ],
@@ -2559,9 +2559,9 @@
               "name": "since"
             }
           ],
-          "docs": "Configure when the plugin should direct install updates. Only for autoUpdate mode.\nWorks well for apps less than 10MB and with uploads done using --partial flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates (default behavior)\n- atInstall: Direct update only when app is installed/updated from store, otherwise use normal background update\n- always: Always do direct updates immediately when available\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nOnly available for Android and iOS.",
+          "docs": "Configure when the plugin should direct install updates. Only for autoUpdate mode.\nWorks well for apps less than 10MB and with uploads done using --partial flag.\nZip or apps more than 10MB will be relatively slow for users to update.\n- false: Never do direct updates (use default behavior: download at start, set when backgrounded)\n- atInstall: Direct update only when app is installed, updated from store, otherwise act as directUpdate = false\n- onLaunch: Direct update only on app installed, updated from store or after app kill, otherwise act as directUpdate = false\n- always: Direct update in all previous cases (app installed, updated from store, after app kill or app resume), never act as directUpdate = false\n- true: (deprecated) Same as \"always\" for backward compatibility\n\nOnly available for Android and iOS.",
           "complexTypes": [],
-          "type": "boolean | 'always' | 'atInstall' | undefined"
+          "type": "boolean | 'always' | 'atInstall' | 'onLaunch' | undefined"
         },
         {
           "name": "autoSplashscreen",
@@ -2575,7 +2575,7 @@
               "name": "since"
             }
           ],
-          "docs": "Automatically handle splashscreen hiding when using directUpdate. When enabled, the plugin will automatically hide the splashscreen after updates are applied or when no update is needed.\nThis removes the need to manually listen for appReady events and call SplashScreen.hide().\nOnly works when directUpdate is set to \"atInstall\", \"always\", or true.\nRequires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false.\nRequires autoUpdate and directUpdate to be enabled.\n\nOnly available for Android and iOS.",
+          "docs": "Automatically handle splashscreen hiding when using directUpdate. When enabled, the plugin will automatically hide the splashscreen after updates are applied or when no update is needed.\nThis removes the need to manually listen for appReady events and call SplashScreen.hide().\nOnly works when directUpdate is set to \"atInstall\", \"always\", \"onLaunch\", or true.\nRequires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false.\nRequires autoUpdate and directUpdate to be enabled.\n\nOnly available for Android and iOS.",
           "complexTypes": [],
           "type": "boolean | undefined"
         },

package/dist/esm/definitions.d.ts

@@ -109,9 +109,10 @@ declare module '@capacitor/cli' {
              * Configure when the plugin should direct install updates. Only for autoUpdate mode.
              * Works well for apps less than 10MB and with uploads done using --partial flag.
              * Zip or apps more than 10MB will be relatively slow for users to update.
-             * - false: Never do direct updates (default behavior)
-             * - atInstall: Direct update only when app is installed/updated from store, otherwise use normal background update
-             * - always: Always do direct updates immediately when available
+             * - false: Never do direct updates (use default behavior: download at start, set when backgrounded)
+             * - atInstall: Direct update only when app is installed, updated from store, otherwise act as directUpdate = false
+             * - onLaunch: Direct update only on app installed, updated from store or after app kill, otherwise act as directUpdate = false
+             * - always: Direct update in all previous cases (app installed, updated from store, after app kill or app resume), never act as directUpdate = false
              * - true: (deprecated) Same as "always" for backward compatibility
              *
              * Only available for Android and iOS.
@@ -119,11 +120,11 @@ declare module '@capacitor/cli' {
              * @default false
              * @since  5.1.0
              */
-            directUpdate?: boolean | 'atInstall' | 'always';
+            directUpdate?: boolean | 'atInstall' | 'always' | 'onLaunch';
             /**
              * Automatically handle splashscreen hiding when using directUpdate. When enabled, the plugin will automatically hide the splashscreen after updates are applied or when no update is needed.
              * This removes the need to manually listen for appReady events and call SplashScreen.hide().
-             * Only works when directUpdate is set to "atInstall", "always", or true.
+             * Only works when directUpdate is set to "atInstall", "always", "onLaunch", or true.
              * Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false.
              * Requires autoUpdate and directUpdate to be enabled.
              *
@@ -516,7 +517,16 @@ export interface CapacitorUpdaterPlugin {
      */
     getBuiltinVersion(): Promise<BuiltinVersion>;
     /**
-     * Get unique ID used to identify device (sent to auto update server), this ID is made following Apple and Google privacy best practices, and not persisted between installs
+     * Get unique ID used to identify device (sent to auto update server).
+     *
+     * This ID is privacy-friendly and follows Apple and Google best practices:
+     * - Generated as a UUID and stored securely
+     * - Android: Uses EncryptedSharedPreferences with Auto Backup (persists across reinstalls)
+     * - iOS: Uses Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly (persists across reinstalls)
+     * - Data stays on device (not synced to cloud on iOS)
+     * - Can be cleared by user via system settings (Android) or keychain access (iOS)
+     *
+     * The device ID now persists between app reinstalls to maintain consistent device identity.
      *
      * @returns {Promise<DeviceId>} A Promise with id for this device
      * @throws {Error}