@capgo/capacitor-updater 5.41.1 → 5.42.3

package/Package.swift

@@ -10,9 +10,9 @@ let package = Package(
             targets: ["CapacitorUpdaterPlugin"])
     ],
     dependencies: [
-        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0"),
-        .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.10.2")),
-        .package(url: "https://github.com/weichsel/ZIPFoundation.git", from: "0.9.0"),
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "5.0.0"),
+        .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.11.0")),
+        .package(url: "https://github.com/weichsel/ZIPFoundation.git", from: "0.9.20"),
         .package(url: "https://github.com/mrackwitz/Version.git", exact: "0.8.0"),
         .package(url: "https://github.com/attaswift/BigInt.git", from: "5.7.0")
     ],

package/README.md

@@ -100,6 +100,8 @@ Starting from v8, the plugin uses [ZIPFoundation](https://github.com/weichsel/ZI
 | v3.\*.\*       | v3.\*.\*                | ⚠️ Deprecated     |
 | > 7            | v4.\*.\*                | ⚠️ Deprecated, our CI got crazy and bumped too much version     |
 
+> **Note:** Versions 5, 6, 7, and 8 all share the same features. The major version simply follows your Capacitor version. You can safely use any of these versions that matches your Capacitor installation.
+
 ### iOS
 
 #### Privacy manifest
@@ -140,6 +142,24 @@ npm install @capgo/capacitor-updater
 npx cap sync
 ```
 
+### Install a specific version
+
+Use npm tags to install the version matching your Capacitor version:
+
+```bash
+# For Capacitor 8 (latest)
+npm install @capgo/capacitor-updater@latest
+
+# For Capacitor 7
+npm install @capgo/capacitor-updater@lts-v7
+
+# For Capacitor 6
+npm install @capgo/capacitor-updater@lts-v6
+
+# For Capacitor 5
+npm install @capgo/capacitor-updater@lts-v5
+```
+
 ## Auto-update setup
 
 Create your account in [capgo.app](https://capgo.app) and get your [API key](https://console.capgo.app/dashboard/apikeys)
@@ -252,6 +272,10 @@ Capacitor Updater works by unzipping a compiled app bundle to the native device
 - Do not password encrypt the bundle zip file, or it will fail to unpack.
 - Make sure the bundle does not contain any extra hidden files or folders, or it may fail to unpack.
 
+### Downgrading to a previous version of the updater plugin
+
+Downgrading to a previous version of the updater plugin is not supported.
+
 ## Updater Plugin Config
 
 <docgen-config>
@@ -294,6 +318,7 @@ CapacitorUpdater can be configured with these options:
 | **`appId`**                   | <code>string</code>                                           | Configure the app id for the app in the config.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | <code>undefined</code>                                                        | 6.0.0   |
 | **`keepUrlPathAfterReload`**  | <code>boolean</code>                                          | Configure the plugin to keep the URL path after a reload. WARNING: When a reload is triggered, 'window.history' will be cleared.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | <code>false</code>                                                            | 6.8.0   |
 | **`disableJSLogging`**        | <code>boolean</code>                                          | Disable the JavaScript logging of the plugin. if true, the plugin will not log to the JavaScript console. only the native log will be done                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | <code>false</code>                                                            | 7.3.0   |
+| **`osLogging`**               | <code>boolean</code>                                          | Enable OS-level logging. When enabled, logs are written to the system log which can be inspected in production builds. - **iOS**: Uses os_log instead of Swift.print, logs accessible via Console.app or Instruments - **Android**: Logs to Logcat (android.util.Log) When set to false, system logging is disabled on both platforms (only JavaScript console logging will occur if enabled). This is useful for debugging production apps (App Store/TestFlight builds on iOS, or production APKs on Android).                                                                                                                                                                                                                                                                                                                                  | <code>true</code>                                                             | 8.42.0  |
 | **`shakeMenu`**               | <code>boolean</code>                                          | Enable shake gesture to show update menu for debugging/testing purposes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | <code>false</code>                                                            | 7.5.0   |
 
 ### Examples
@@ -337,6 +362,7 @@ In `capacitor.config.json`:
       "appId": undefined,
       "keepUrlPathAfterReload": undefined,
       "disableJSLogging": undefined,
+      "osLogging": undefined,
       "shakeMenu": undefined
     }
   }
@@ -386,6 +412,7 @@ const config: CapacitorConfig = {
       appId: undefined,
       keepUrlPathAfterReload: undefined,
       disableJSLogging: undefined,
+      osLogging: undefined,
       shakeMenu: undefined,
     },
   },

package/android/build.gradle

@@ -50,8 +50,10 @@ repositories {
 
 dependencies {
     def work_version = "2.10.5"
+    def lifecycle_version = "2.10.0"
     implementation "androidx.work:work-runtime:$work_version"
-    implementation "com.google.android.gms:play-services-tasks:18.4.0"
+    implementation "androidx.lifecycle:lifecycle-process:$lifecycle_version"
+    implementation "com.google.android.gms:play-services-tasks:18.4.1"
     implementation "com.google.guava:guava:33.5.0-android"
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
@@ -61,7 +63,7 @@ dependencies {
     implementation 'com.google.android.play:app-update:2.1.0'
     implementation 'com.google.android.play:app-update-ktx:2.1.0'
     testImplementation "junit:junit:$junitVersion"
-    testImplementation 'org.mockito:mockito-core:5.20.0'
+    testImplementation 'org.mockito:mockito-core:5.21.0'
     testImplementation 'org.json:json:20250517'
     testImplementation 'org.robolectric:robolectric:4.13'
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"

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

@@ -0,0 +1,88 @@
+/*
+ * 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 androidx.annotation.NonNull;
+import androidx.lifecycle.DefaultLifecycleObserver;
+import androidx.lifecycle.LifecycleOwner;
+import androidx.lifecycle.ProcessLifecycleOwner;
+
+/**
+ * Observes app-level lifecycle events using ProcessLifecycleOwner.
+ * This provides reliable detection of when the entire app (not just an activity)
+ * moves to foreground or background.
+ *
+ * Unlike activity lifecycle callbacks, this won't trigger false positives when:
+ * - Opening a native camera view
+ * - Opening share sheets
+ * - Any other native activity overlays within the app
+ *
+ * The ON_STOP event is dispatched with a ~700ms delay after the last activity
+ * passes through onStop(), which helps avoid false triggers during configuration
+ * changes or quick activity transitions.
+ */
+public class AppLifecycleObserver implements DefaultLifecycleObserver {
+
+    public interface AppLifecycleListener {
+        void onAppMovedToForeground();
+        void onAppMovedToBackground();
+    }
+
+    private final AppLifecycleListener listener;
+    private final Logger logger;
+    private boolean isRegistered = false;
+
+    public AppLifecycleObserver(AppLifecycleListener listener, Logger logger) {
+        this.listener = listener;
+        this.logger = logger;
+    }
+
+    public void register() {
+        if (isRegistered) {
+            return;
+        }
+        try {
+            ProcessLifecycleOwner.get().getLifecycle().addObserver(this);
+            isRegistered = true;
+            logger.info("AppLifecycleObserver registered with ProcessLifecycleOwner");
+        } catch (Exception e) {
+            logger.error("Failed to register AppLifecycleObserver: " + e.getMessage());
+        }
+    }
+
+    public void unregister() {
+        if (!isRegistered) {
+            return;
+        }
+        try {
+            ProcessLifecycleOwner.get().getLifecycle().removeObserver(this);
+            isRegistered = false;
+            logger.info("AppLifecycleObserver unregistered from ProcessLifecycleOwner");
+        } catch (Exception e) {
+            logger.error("Failed to unregister AppLifecycleObserver: " + e.getMessage());
+        }
+    }
+
+    @Override
+    public void onStart(@NonNull LifecycleOwner owner) {
+        // App moved to foreground (at least one activity is visible)
+        logger.info("ProcessLifecycleOwner: App moved to foreground");
+        if (listener != null) {
+            listener.onAppMovedToForeground();
+        }
+    }
+
+    @Override
+    public void onStop(@NonNull LifecycleOwner owner) {
+        // App moved to background (no activities are visible)
+        // Note: This is called with a ~700ms delay to avoid false triggers
+        logger.info("ProcessLifecycleOwner: App moved to background");
+        if (listener != null) {
+            listener.onAppMovedToBackground();
+        }
+    }
+}

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

@@ -7,7 +7,6 @@
 package ee.forgr.capacitor_updater;
 
 import android.app.Activity;
-import android.app.ActivityManager;
 import android.content.Context;
 import android.content.Intent;
 import android.content.SharedPreferences;
@@ -71,7 +70,7 @@ import org.json.JSONObject;
 @CapacitorPlugin(name = "CapacitorUpdater")
 public class CapacitorUpdaterPlugin extends Plugin {
 
-    private final Logger logger = new Logger("CapgoUpdater");
+    private Logger logger;
 
     private static final String updateUrlDefault = "https://plugin.capgo.app/updates";
     private static final String statsUrlDefault = "https://plugin.capgo.app/stats";
@@ -85,7 +84,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 pluginVersion = "5.41.1";
+    private final String pluginVersion = "5.42.3";
     private static final String DELAY_CONDITION_PREFERENCES = "";
 
     private SharedPreferences.Editor editor;
@@ -116,6 +115,7 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private Boolean allowManualBundleError = false;
     private Boolean allowSetDefaultChannel = true;
 
+    // Used for activity-based foreground/background detection on Android < 14
     private Boolean isPreviousMainActivity = true;
 
     private volatile Thread backgroundDownloadTask;
@@ -138,6 +138,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
     private FrameLayout splashscreenLoaderOverlay;
     private Runnable splashscreenTimeoutRunnable;
 
+    // App lifecycle observer using ProcessLifecycleOwner for reliable foreground/background detection
+    private AppLifecycleObserver appLifecycleObserver;
+
     // Play Store In-App Updates
     private AppUpdateManager appUpdateManager;
     private AppUpdateInfo cachedAppUpdateInfo;
@@ -216,6 +219,13 @@ public class CapacitorUpdaterPlugin extends Plugin {
     @Override
     public void load() {
         super.load();
+
+        // Initialize logger with osLogging config
+        // Default to true for both platforms to enable system logging by default
+        boolean osLogging = this.getConfig().getBoolean("osLogging", true);
+        Logger.Options loggerOptions = new Logger.Options(osLogging);
+        this.logger = new Logger("CapgoUpdater", loggerOptions);
+
         this.prefs = this.getContext().getSharedPreferences(WebView.WEBVIEW_PREFS_NAME, Activity.MODE_PRIVATE);
         this.editor = this.prefs.edit();
 
@@ -431,6 +441,31 @@ public class CapacitorUpdaterPlugin extends Plugin {
         this.delayUpdateUtils.checkCancelDelay(DelayUpdateUtils.CancelDelaySource.KILLED);
 
         this.checkForUpdateAfterDelay();
+
+        // On Android 14+ (API 34+), topActivity in RecentTaskInfo returns null due to
+        // security restrictions (StrandHogg task hijacking mitigations). Use ProcessLifecycleOwner
+        // for reliable app-level foreground/background detection on these versions.
+        // On older versions, we use the traditional activity lifecycle callbacks in handleOnStart/handleOnStop.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            this.appLifecycleObserver = new AppLifecycleObserver(
+                new AppLifecycleObserver.AppLifecycleListener() {
+                    @Override
+                    public void onAppMovedToForeground() {
+                        CapacitorUpdaterPlugin.this.appMovedToForeground();
+                    }
+
+                    @Override
+                    public void onAppMovedToBackground() {
+                        CapacitorUpdaterPlugin.this.appMovedToBackground();
+                    }
+                },
+                logger
+            );
+            this.appLifecycleObserver.register();
+            logger.info("Using ProcessLifecycleOwner for foreground/background detection (Android 14+)");
+        } else {
+            logger.info("Using activity lifecycle callbacks for foreground/background detection (Android <14)");
+        }
     }
 
     private void semaphoreWait(Number waitTime) {
@@ -2081,6 +2116,9 @@ public class CapacitorUpdaterPlugin extends Plugin {
     }
 
     public void appMovedToBackground() {
+        // Reset timeout flag at start of each background cycle
+        this.autoSplashscreenTimedOut = false;
+
         final BundleInfo current = CapacitorUpdaterPlugin.this.implementation.getCurrentBundle();
 
         // Show splashscreen FIRST, before any other background work to ensure launcher shows it
@@ -2129,16 +2167,22 @@ public class CapacitorUpdaterPlugin extends Plugin {
         }
     }
 
+    /**
+     * Check if the current activity is the main activity.
+     * Used for activity-based foreground/background detection on Android < 14.
+     * On Android 14+, topActivity returns null due to security restrictions, so we use
+     * ProcessLifecycleOwner instead.
+     */
     private boolean isMainActivity() {
         try {
             Context mContext = this.getContext();
-            ActivityManager activityManager = (ActivityManager) mContext.getSystemService(Context.ACTIVITY_SERVICE);
-            List<ActivityManager.AppTask> runningTasks = activityManager.getAppTasks();
+            android.app.ActivityManager activityManager = (android.app.ActivityManager) mContext.getSystemService(Context.ACTIVITY_SERVICE);
+            java.util.List<android.app.ActivityManager.AppTask> runningTasks = activityManager.getAppTasks();
             if (runningTasks.isEmpty()) {
                 return false;
             }
-            ActivityManager.RecentTaskInfo runningTask = runningTasks.get(0).getTaskInfo();
-            String className = Objects.requireNonNull(runningTask.baseIntent.getComponent()).getClassName();
+            android.app.ActivityManager.RecentTaskInfo runningTask = runningTasks.get(0).getTaskInfo();
+            String className = java.util.Objects.requireNonNull(runningTask.baseIntent.getComponent()).getClassName();
             if (runningTask.topActivity == null) {
                 return false;
             }
@@ -2152,12 +2196,17 @@ public class CapacitorUpdaterPlugin extends Plugin {
     @Override
     public void handleOnStart() {
         try {
-            if (isPreviousMainActivity) {
-                logger.info("handleOnStart: appMovedToForeground");
-                this.appMovedToForeground();
-            }
             logger.info("handleOnStart: onActivityStarted " + getActivity().getClass().getName());
-            isPreviousMainActivity = true;
+
+            // On Android < 14, use activity lifecycle for foreground detection
+            // On Android 14+, ProcessLifecycleOwner handles this via AppLifecycleObserver
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+                if (isPreviousMainActivity) {
+                    logger.info("handleOnStart: appMovedToForeground (Android <14 path)");
+                    this.appMovedToForeground();
+                }
+                isPreviousMainActivity = true;
+            }
 
             // Initialize shake menu if enabled and activity is BridgeActivity
             if (shakeMenuEnabled && getActivity() instanceof com.getcapacitor.BridgeActivity && shakeMenu == null) {
@@ -2176,10 +2225,16 @@ public class CapacitorUpdaterPlugin extends Plugin {
     @Override
     public void handleOnStop() {
         try {
-            isPreviousMainActivity = isMainActivity();
-            if (isPreviousMainActivity) {
-                logger.info("handleOnStop: appMovedToBackground");
-                this.appMovedToBackground();
+            logger.info("handleOnStop: onActivityStopped");
+
+            // On Android < 14, use activity lifecycle for background detection
+            // On Android 14+, ProcessLifecycleOwner handles this via AppLifecycleObserver
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+                isPreviousMainActivity = isMainActivity();
+                if (isPreviousMainActivity) {
+                    logger.info("handleOnStop: appMovedToBackground (Android <14 path)");
+                    this.appMovedToBackground();
+                }
             }
         } catch (Exception e) {
             logger.error("Failed to run handleOnStop: " + e.getMessage());
@@ -2604,6 +2659,17 @@ public class CapacitorUpdaterPlugin extends Plugin {
                     logger.error("Failed to clean up shake menu: " + e.getMessage());
                 }
             }
+
+            // Clean up app lifecycle observer
+            if (appLifecycleObserver != null) {
+                try {
+                    appLifecycleObserver.unregister();
+                    appLifecycleObserver = null;
+                    logger.info("AppLifecycleObserver cleaned up");
+                } catch (Exception e) {
+                    logger.error("Failed to clean up AppLifecycleObserver: " + e.getMessage());
+                }
+            }
         } catch (Exception e) {
             logger.error("Failed to run handleOnDestroy: " + e.getMessage());
         }

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

@@ -35,8 +35,11 @@ import java.util.Objects;
 import java.util.Set;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CopyOnWriteArrayList;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ScheduledFuture;
 import java.util.concurrent.TimeUnit;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipInputStream;
@@ -91,6 +94,12 @@ public class CapgoUpdater {
     // Flag to track if we've already sent the rate limit statistic - prevents infinite loop
     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 ScheduledExecutorService statsScheduler = Executors.newSingleThreadScheduledExecutor();
+    private ScheduledFuture<?> statsFlushTask = null;
+    private static final long STATS_FLUSH_INTERVAL_MS = 1000;
+
     private final Map<String, CompletableFuture<BundleInfo>> downloadFutures = new ConcurrentHashMap<>();
     private final ExecutorService io = Executors.newSingleThreadExecutor();
 
@@ -153,12 +162,25 @@ public class CapgoUpdater {
     }
 
     public void setPublicKey(String publicKey) {
-        this.publicKey = publicKey;
-        if (!publicKey.isEmpty()) {
-            this.cachedKeyId = CryptoCipher.calcKeyId(publicKey);
-        } else {
+        // Empty string means no encryption - proceed normally
+        if (publicKey == null || publicKey.isEmpty()) {
+            this.publicKey = "";
             this.cachedKeyId = "";
+            return;
         }
+
+        // Non-empty: must be a valid RSA key or crash
+        try {
+            CryptoCipher.stringToPublicKey(publicKey);
+        } catch (Exception e) {
+            throw new RuntimeException(
+                "Invalid public key in capacitor.config.json: failed to parse RSA key. Remove the key or provide a valid PEM-formatted RSA public key.",
+                e
+            );
+        }
+
+        this.publicKey = publicKey;
+        this.cachedKeyId = CryptoCipher.calcKeyId(publicKey);
     }
 
     public String getKeyId() {
@@ -239,13 +261,90 @@ public class CapgoUpdater {
         }
         if (entries.length == 1 && !"index.html".equals(entries[0])) {
             final File child = new File(sourceFile, entries[0]);
-            child.renameTo(destinationFile);
+            if (!child.renameTo(destinationFile)) {
+                throw new IOException("Failed to move bundle contents: " + child.getPath() + " -> " + destinationFile.getPath());
+            }
         } else {
-            sourceFile.renameTo(destinationFile);
+            if (!sourceFile.renameTo(destinationFile)) {
+                throw new IOException("Failed to move bundle contents: " + sourceFile.getPath() + " -> " + destinationFile.getPath());
+            }
         }
         sourceFile.delete();
     }
 
+    private void cacheBundleFilesAsync(final String id) {
+        io.execute(() -> cacheBundleFiles(id));
+    }
+
+    private void cacheBundleFiles(final String id) {
+        if (this.activity == null) {
+            logger.debug("Skip delta cache population: activity is null");
+            return;
+        }
+
+        final File bundleDir = this.getBundleDirectory(id);
+        if (!bundleDir.exists()) {
+            logger.debug("Skip delta cache population: bundle dir missing");
+            return;
+        }
+
+        final File cacheDir = new File(this.activity.getCacheDir(), "capgo_downloads");
+        if (cacheDir.exists() && !cacheDir.isDirectory()) {
+            logger.debug("Skip delta cache population: cache dir is not a directory");
+            return;
+        }
+        if (!cacheDir.exists() && !cacheDir.mkdirs()) {
+            logger.debug("Skip delta cache population: failed to create cache dir");
+            return;
+        }
+
+        final List<File> files = new ArrayList<>();
+        collectFiles(bundleDir, files);
+        for (File file : files) {
+            final String checksum = CryptoCipher.calcChecksum(file);
+            if (checksum.isEmpty()) {
+                continue;
+            }
+            final String cacheName = checksum + "_" + file.getName();
+            final File cacheFile = new File(cacheDir, cacheName);
+            if (cacheFile.exists()) {
+                continue;
+            }
+            try {
+                copyFile(file, cacheFile);
+            } catch (IOException e) {
+                logger.debug("Delta cache copy failed: " + file.getPath());
+            }
+        }
+    }
+
+    private void collectFiles(final File dir, final List<File> files) {
+        final File[] entries = dir.listFiles();
+        if (entries == null) {
+            return;
+        }
+        for (File entry : entries) {
+            if (!this.filter.accept(dir, entry.getName())) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                collectFiles(entry, files);
+            } else if (entry.isFile()) {
+                files.add(entry);
+            }
+        }
+    }
+
+    private void copyFile(final File source, final File dest) throws IOException {
+        try (final FileInputStream input = new FileInputStream(source); final FileOutputStream output = new FileOutputStream(dest)) {
+            final byte[] buffer = new byte[1024 * 1024];
+            int length;
+            while ((length = input.read(buffer)) != -1) {
+                output.write(buffer, 0, length);
+            }
+        }
+    }
+
     private void observeWorkProgress(Context context, String id) {
         if (!(context instanceof LifecycleOwner)) {
             logger.error("Context is not a LifecycleOwner, cannot observe work progress");
@@ -460,6 +559,7 @@ public class CapgoUpdater {
                 this.notifyDownload(id, 91);
                 final String idName = bundleDirectory + "/" + id;
                 this.flattenAssets(extractedDir, idName);
+                this.cacheBundleFilesAsync(id);
             } else {
                 this.notifyDownload(id, 91);
                 final String idName = bundleDirectory + "/" + id;
@@ -1437,30 +1537,74 @@ public class CapgoUpdater {
         if (statsUrl == null || statsUrl.isEmpty()) {
             return;
         }
+
         JSONObject json;
         try {
             json = this.createInfoObject();
             json.put("version_name", versionName);
             json.put("old_version_name", oldVersionName);
             json.put("action", action);
+            json.put("timestamp", System.currentTimeMillis());
         } catch (JSONException e) {
             logger.error("Error preparing stats");
             logger.debug("JSONException: " + e.getMessage());
             return;
         }
 
+        statsQueue.add(json);
+        ensureStatsTimerStarted();
+    }
+
+    private synchronized void ensureStatsTimerStarted() {
+        if (statsFlushTask == null || statsFlushTask.isCancelled() || statsFlushTask.isDone()) {
+            statsFlushTask = statsScheduler.scheduleAtFixedRate(
+                this::flushStatsQueue,
+                STATS_FLUSH_INTERVAL_MS,
+                STATS_FLUSH_INTERVAL_MS,
+                TimeUnit.MILLISECONDS
+            );
+        }
+    }
+
+    private void flushStatsQueue() {
+        if (statsQueue.isEmpty()) {
+            return;
+        }
+
+        String statsUrl = this.statsUrl;
+        if (statsUrl == null || statsUrl.isEmpty()) {
+            statsQueue.clear();
+            return;
+        }
+
+        // Copy and clear the queue atomically using synchronized block
+        List<JSONObject> eventsToSend;
+        synchronized (statsQueue) {
+            if (statsQueue.isEmpty()) {
+                return;
+            }
+            eventsToSend = new ArrayList<>(statsQueue);
+            statsQueue.clear();
+        }
+
+        JSONArray jsonArray = new JSONArray();
+        for (JSONObject event : eventsToSend) {
+            jsonArray.put(event);
+        }
+
         Request request = new Request.Builder()
             .url(statsUrl)
-            .post(RequestBody.create(json.toString(), MediaType.get("application/json")))
+            .post(RequestBody.create(jsonArray.toString(), MediaType.get("application/json")))
             .build();
 
+        final int eventCount = eventsToSend.size();
         DownloadService.sharedClient
             .newCall(request)
             .enqueue(
                 new okhttp3.Callback() {
                     @Override
                     public void onFailure(@NonNull Call call, @NonNull IOException e) {
-                        logger.error("Failed to send stats");
+                        logger.error("Failed to send stats batch");
                         logger.debug("Error: " + e.getMessage());
                     }
 
@@ -1473,10 +1617,10 @@ public class CapgoUpdater {
                             }
 
                             if (response.isSuccessful()) {
-                                logger.info("Stats sent successfully");
-                                logger.debug("Action: " + action + ", Version: " + versionName);
+                                logger.info("Stats batch sent successfully");
+                                logger.debug("Sent " + eventCount + " events");
                             } else {
-                                logger.error("Error sending stats");
+                                logger.error("Error sending stats batch");
                                 logger.debug("Response code: " + response.code());
                             }
                         }
@@ -1610,4 +1754,30 @@ public class CapgoUpdater {
         this.editor.commit();
         return true;
     }
+
+    /**
+     * Shuts down the stats scheduler and flushes any pending stats.
+     * Should be called when the plugin is destroyed to prevent resource leaks.
+     */
+    public void shutdown() {
+        // Cancel the scheduled task
+        if (statsFlushTask != null) {
+            statsFlushTask.cancel(false);
+            statsFlushTask = null;
+        }
+
+        // Flush any remaining stats before shutdown
+        flushStatsQueue();
+
+        // Shutdown the scheduler
+        statsScheduler.shutdown();
+        try {
+            if (!statsScheduler.awaitTermination(2, TimeUnit.SECONDS)) {
+                statsScheduler.shutdownNow();
+            }
+        } catch (InterruptedException e) {
+            statsScheduler.shutdownNow();
+            Thread.currentThread().interrupt();
+        }
+    }
 }