@capgo/capacitor-updater 7.43.3 → 7.50.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/Package.swift +5 -2
  2. package/README.md +643 -115
  3. package/android/build.gradle +3 -3
  4. package/android/src/main/java/ee/forgr/capacitor_updater/AndroidAppExitReporter.java +92 -0
  5. package/android/src/main/java/ee/forgr/capacitor_updater/CapacitorUpdaterPlugin.java +3121 -353
  6. package/android/src/main/java/ee/forgr/capacitor_updater/CapgoUpdater.java +924 -290
  7. package/android/src/main/java/ee/forgr/capacitor_updater/DelayUpdateUtils.java +49 -13
  8. package/android/src/main/java/ee/forgr/capacitor_updater/DeviceIdHelper.java +45 -30
  9. package/android/src/main/java/ee/forgr/capacitor_updater/DownloadService.java +75 -32
  10. package/android/src/main/java/ee/forgr/capacitor_updater/DownloadWorkerManager.java +2 -0
  11. package/android/src/main/java/ee/forgr/capacitor_updater/ShakeDetector.java +3 -3
  12. package/android/src/main/java/ee/forgr/capacitor_updater/ShakeMenu.java +401 -27
  13. package/android/src/main/java/ee/forgr/capacitor_updater/ThreeFingerPinchDetector.java +323 -0
  14. package/dist/docs.json +1590 -196
  15. package/dist/esm/definitions.d.ts +755 -66
  16. package/dist/esm/definitions.js.map +1 -1
  17. package/dist/esm/web.d.ts +11 -2
  18. package/dist/esm/web.js +59 -5
  19. package/dist/esm/web.js.map +1 -1
  20. package/dist/plugin.cjs.js +59 -5
  21. package/dist/plugin.cjs.js.map +1 -1
  22. package/dist/plugin.js +59 -5
  23. package/dist/plugin.js.map +1 -1
  24. package/ios/Sources/CapacitorUpdaterPlugin/AES.swift +0 -1
  25. package/ios/Sources/CapacitorUpdaterPlugin/AppHealthTracker.swift +82 -0
  26. package/ios/Sources/CapacitorUpdaterPlugin/BigInt.swift +0 -16
  27. package/ios/Sources/CapacitorUpdaterPlugin/BundleInfo.swift +2 -2
  28. package/ios/Sources/CapacitorUpdaterPlugin/BundleStatus.swift +78 -2
  29. package/ios/Sources/CapacitorUpdaterPlugin/CapacitorUpdaterPlugin.swift +2732 -417
  30. package/ios/Sources/CapacitorUpdaterPlugin/CapgoUpdater.swift +1191 -363
  31. package/ios/Sources/CapacitorUpdaterPlugin/CryptoCipher.swift +0 -1
  32. package/ios/Sources/CapacitorUpdaterPlugin/DelayUpdateUtils.swift +37 -16
  33. package/ios/Sources/CapacitorUpdaterPlugin/InternalUtils.swift +80 -1
  34. package/ios/Sources/CapacitorUpdaterPlugin/ShakeMenu.swift +438 -39
  35. package/ios/Sources/CapacitorUpdaterPlugin/WebViewStatsReporter.swift +276 -0
  36. package/package.json +24 -9
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  # Capacitor updater
2
- <a href="https://capgo.app/"><img src='https://raw.githubusercontent.com/Cap-go/capgo/main/assets/capgo_banner.png' alt='Capgo - Instant updates for capacitor'/></a>
2
+ <a href="https://capgo.app/"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-updater" alt="Capgo - Instant updates for Capacitor" /></a>
3
3
  [![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.com/invite/VnYRvBfgA6)
4
4
  <a href="https://discord.com/invite/VnYRvBfgA6"><img src="https://img.shields.io/discord/912707985829163099?color=%237289DA&label=Discord" alt="Discord">
5
5
  [![npm](https://img.shields.io/npm/dm/@capgo/capacitor-updater)](https://www.npmjs.com/package/@capgo/capacitor-updater)
@@ -50,7 +50,7 @@ Perfect for fixing bugs immediately, A/B testing features, and maintaining contr
50
50
  - ⚔️ **Battle-Tested**: Used in more than 3000 projects.
51
51
  - 📊 View your deployment statistics
52
52
  - 🔋 Supports Android and iOS
53
- - ⚡️ Capacitor 6/7 support
53
+ - ⚡️ Capacitor 4/5/6/7/8 support
54
54
  - 🌐 **Open Source**: Licensed under the Mozilla Public License 2.0
55
55
  - 🌐 **Open Source Backend**: Self install [our backend](https://github.com/Cap-go/capgo) in your infra
56
56
 
@@ -79,7 +79,7 @@ First follow the migration guide of Capacitor:
79
79
  - **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.
80
80
  - Channel assignments persist between app restarts
81
81
  - Use `unsetChannel()` to clear the local assignment and revert to `defaultChannel`
82
- - Old devices (< v7.34.0) will continue using cloud-based storage
82
+ - Old devices (< v7.34.0) use now a KV storage to prevent overload the primary DB of Capgo
83
83
  - **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.
84
84
 
85
85
  ## Migration to v7
@@ -96,11 +96,11 @@ Starting from v8, the plugin uses [ZIPFoundation](https://github.com/weichsel/ZI
96
96
  | v7.\*.\* | v7.\*.\* | ✅ |
97
97
  | v6.\*.\* | v6.\*.\* | ✅ |
98
98
  | v5.\*.\* | v5.\*.\* | ✅ |
99
- | v4.\*.\* | v4.\*.\* | ⚠️ Deprecated |
99
+ | v4.\*.\* | v4.\*.\* | ✅ |
100
100
  | v3.\*.\* | v3.\*.\* | ⚠️ Deprecated |
101
101
  | > 7 | v4.\*.\* | ⚠️ Deprecated, our CI got crazy and bumped too much version |
102
102
 
103
- > **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.
103
+ > **Note:** Versions 4, 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.
104
104
 
105
105
  ### iOS
106
106
 
@@ -133,6 +133,20 @@ We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bun
133
133
 
134
134
  ## Installation
135
135
 
136
+ You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
137
+
138
+ ```bash
139
+ npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
140
+ ```
141
+
142
+ Then use the following prompt:
143
+
144
+ ```text
145
+ Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-updater` plugin in my project.
146
+ ```
147
+
148
+ If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
149
+
136
150
  Step by step here: [Getting started](https://capgo.app/docs/getting-started/add-an-app/)
137
151
 
138
152
  Or
@@ -158,6 +172,9 @@ npm install @capgo/capacitor-updater@lts-v6
158
172
 
159
173
  # For Capacitor 5
160
174
  npm install @capgo/capacitor-updater@lts-v5
175
+
176
+ # For Capacitor 4
177
+ npm install @capgo/capacitor-updater@lts-v4
161
178
  ```
162
179
 
163
180
  ## Auto-update setup
@@ -283,44 +300,46 @@ Downgrading to a previous version of the updater plugin is not supported.
283
300
 
284
301
  CapacitorUpdater can be configured with these options:
285
302
 
286
- | Prop | Type | Description | Default | Since |
287
- | ------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------- |
288
- | **`appReadyTimeout`** | <code>number</code> | Configure the number of milliseconds the native plugin should wait before considering an update 'failed'. Only available for Android and iOS. | <code>10000 // (10 seconds)</code> | |
289
- | **`responseTimeout`** | <code>number</code> | Configure the number of seconds the native plugin should wait before considering API timeout. Only available for Android and iOS. | <code>20 // (20 second)</code> | |
290
- | **`autoDeleteFailed`** | <code>boolean</code> | Configure whether the plugin should use automatically delete failed bundles. Only available for Android and iOS. | <code>true</code> | |
291
- | **`autoDeletePrevious`** | <code>boolean</code> | Configure whether the plugin should use automatically delete previous bundles after a successful update. Only available for Android and iOS. | <code>true</code> | |
292
- | **`autoUpdate`** | <code>boolean</code> | Configure whether the plugin should use Auto Update via an update server. Only available for Android and iOS. | <code>true</code> | |
293
- | **`resetWhenUpdate`** | <code>boolean</code> | Automatically delete previous downloaded bundles when a newer native app bundle is installed to the device. Setting this to false can broke the auto update flow if the user download from the store a native app bundle that is older than the current downloaded bundle. Upload will be prevented by channel setting downgrade_under_native. Only available for Android and iOS. | <code>true</code> | |
294
- | **`updateUrl`** | <code>string</code> | Configure the URL / endpoint to which update checks are sent. Only available for Android and iOS. | <code>https://plugin.capgo.app/updates</code> | |
295
- | **`channelUrl`** | <code>string</code> | Configure the URL / endpoint for channel operations. Only available for Android and iOS. | <code>https://plugin.capgo.app/channel_self</code> | |
296
- | **`statsUrl`** | <code>string</code> | Configure the URL / endpoint to which update statistics are sent. Only available for Android and iOS. Set to "" to disable stats reporting. | <code>https://plugin.capgo.app/stats</code> | |
297
- | **`publicKey`** | <code>string</code> | Configure the public key for end to end live update encryption Version 2 Only available for Android and iOS. | <code>undefined</code> | 6.2.0 |
298
- | **`version`** | <code>string</code> | Configure the current version of the app. This will be used for the first update request. If not set, the plugin will get the version from the native code. Only available for Android and iOS. | <code>undefined</code> | 4.17.48 |
299
- | **`directUpdate`** | <code>boolean \| 'always' \| 'atInstall' \| 'onLaunch'</code> | Configure when the plugin should direct install updates. Only for autoUpdate mode. Works well for apps less than 10MB and with uploads done using --delta flag. Zip or apps more than 10MB will be relatively slow for users to update. - 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 Activate this flag will automatically make the CLI upload delta in CICD envs and will ask for confirmation in local uploads. Only available for Android and iOS. | <code>false</code> | 5.1.0 |
300
- | **`autoSplashscreen`** | <code>boolean</code> | 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", "onLaunch", or true. Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false. Requires autoUpdate and directUpdate to be enabled. Only available for Android and iOS. | <code>false</code> | 7.6.0 |
301
- | **`autoSplashscreenLoader`** | <code>boolean</code> | Display a native loading indicator on top of the splashscreen while automatic direct updates are running. Only takes effect when {@link autoSplashscreen} is enabled. Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false. Only available for Android and iOS. | <code>false</code> | 7.19.0 |
302
- | **`autoSplashscreenTimeout`** | <code>number</code> | Automatically hide the splashscreen after the specified number of milliseconds when using automatic direct updates. If the timeout elapses, the update continues to download in the background while the splashscreen is dismissed. Set to `0` (zero) to disable the timeout. When the timeout fires, the direct update flow is skipped and the downloaded bundle is installed on the next background/launch. Requires {@link autoSplashscreen} to be enabled. Only available for Android and iOS. | <code>10000 // (10 seconds)</code> | 7.19.0 |
303
- | **`periodCheckDelay`** | <code>number</code> | Configure the delay period for period update check. the unit is in seconds. Only available for Android and iOS. Cannot be less than 600 seconds (10 minutes). | <code>0 (disabled)</code> | |
304
- | **`localS3`** | <code>boolean</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
305
- | **`localHost`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
306
- | **`localWebHost`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
307
- | **`localSupa`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
308
- | **`localSupaAnon`** | <code>string</code> | Configure the CLI to use a local server for testing. | <code>undefined</code> | 4.17.48 |
309
- | **`localApi`** | <code>string</code> | Configure the CLI to use a local api for testing. | <code>undefined</code> | 6.3.3 |
310
- | **`localApiFiles`** | <code>string</code> | Configure the CLI to use a local file api for testing. | <code>undefined</code> | 6.3.3 |
311
- | **`allowModifyUrl`** | <code>boolean</code> | Allow the plugin to modify the updateUrl, statsUrl and channelUrl dynamically from the JavaScript side. | <code>false</code> | 5.4.0 |
312
- | **`allowModifyAppId`** | <code>boolean</code> | Allow the plugin to modify the appId dynamically from the JavaScript side. | <code>false</code> | 7.14.0 |
313
- | **`allowManualBundleError`** | <code>boolean</code> | Allow marking bundles as errored from JavaScript while using manual update flows. When enabled, {@link CapacitorUpdaterPlugin.setBundleError} can change a bundle status to `error`. | <code>false</code> | 7.20.0 |
314
- | **`persistCustomId`** | <code>boolean</code> | Persist the customId set through {@link CapacitorUpdaterPlugin.setCustomId} across app restarts. Only available for Android and iOS. | <code>false (will be true by default in a future major release v8.x.x)</code> | 7.17.3 |
315
- | **`persistModifyUrl`** | <code>boolean</code> | Persist the updateUrl, statsUrl and channelUrl set through {@link CapacitorUpdaterPlugin.setUpdateUrl}, {@link CapacitorUpdaterPlugin.setStatsUrl} and {@link CapacitorUpdaterPlugin.setChannelUrl} across app restarts. Only available for Android and iOS. | <code>false</code> | 7.20.0 |
316
- | **`allowSetDefaultChannel`** | <code>boolean</code> | Allow or disallow the {@link CapacitorUpdaterPlugin.setChannel} method to modify the defaultChannel. When set to `false`, calling `setChannel()` will return an error with code `disabled_by_config`. | <code>true</code> | 7.34.0 |
317
- | **`defaultChannel`** | <code>string</code> | Set the default channel for the app in the config. Case sensitive. This will setting will override the default channel set in the cloud, but will still respect overrides made in the cloud. This requires the channel to allow devices to self dissociate/associate in the channel settings. https://capgo.app/docs/public-api/channels/#channel-configuration-options | <code>undefined</code> | 5.5.0 |
318
- | **`appId`** | <code>string</code> | Configure the app id for the app in the config. | <code>undefined</code> | 6.0.0 |
319
- | **`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 |
320
- | **`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 |
321
- | **`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 |
322
- | **`shakeMenu`** | <code>boolean</code> | Enable shake gesture to show update menu for debugging/testing purposes | <code>false</code> | 7.5.0 |
323
- | **`allowShakeChannelSelector`** | <code>boolean</code> | Enable the shake gesture to show a channel selector menu for switching between update channels. When enabled AND `shakeMenu` is true, the shake gesture shows a channel selector instead of the default debug menu (Go Home/Reload/Close). After selecting a channel, the app automatically checks for updates and downloads if available. Only works if channels have `allow_self_set` enabled on the backend. Only available for Android and iOS. | <code>false</code> | 8.43.0 |
303
+ | Prop | Type | Description | Default | Since |
304
+ | ------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------- |
305
+ | **`appReadyTimeout`** | <code>number</code> | Configure the number of milliseconds the native plugin should wait before considering an update 'failed'. Only available for Android and iOS. | <code>10000 // (10 seconds)</code> | |
306
+ | **`responseTimeout`** | <code>number</code> | Configure the number of seconds the native plugin should wait before considering API timeout. Only available for Android and iOS. | <code>20 // (20 second)</code> | |
307
+ | **`autoDeleteFailed`** | <code>boolean</code> | Configure whether the plugin should use automatically delete failed bundles. Only available for Android and iOS. | <code>true</code> | |
308
+ | **`autoDeletePrevious`** | <code>boolean</code> | Configure whether the plugin should use automatically delete previous bundles after a successful update. Only available for Android and iOS. | <code>true</code> | |
309
+ | **`autoUpdate`** | <code>boolean \| 'always' \| 'off' \| 'atBackground' \| 'atInstall' \| 'onLaunch' \| 'onlyDownload'</code> | Configure how the plugin checks for, downloads, and applies live updates. The plugin checks for updates when the app moves to the foreground and, if {@link periodCheckDelay} is set, on a repeating timer while the app stays open. Boolean values keep their existing behavior: - `true`: Same as `"atBackground"`. - `false`: Same as `"off"`. String values merge the previous Auto Update and Direct Update configuration: - `"off"`: Disable automatic update checks. - `"atBackground"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background. - `"atInstall"`: Apply immediately only after a fresh install or native app store update; otherwise use `"atBackground"` behavior. - `"onLaunch"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `"atBackground"` behavior. - `"always"`: Check on every foreground transition and apply immediately whenever an update is available. - `"onlyDownload"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically. Only available for Android and iOS. | <code>true</code> | |
310
+ | **`resetWhenUpdate`** | <code>boolean</code> | Automatically delete previous downloaded bundles when a newer native app bundle is installed to the device. Setting this to false can broke the auto update flow if the user download from the store a native app bundle that is older than the current downloaded bundle. Upload will be prevented by channel setting downgrade_under_native. Only available for Android and iOS. | <code>true</code> | |
311
+ | **`updateUrl`** | <code>string</code> | Configure the URL / endpoint to which update checks are sent. Only available for Android and iOS. | <code>https://plugin.capgo.app/updates</code> | |
312
+ | **`channelUrl`** | <code>string</code> | Configure the URL / endpoint for channel operations. Only available for Android and iOS. | <code>https://plugin.capgo.app/channel_self</code> | |
313
+ | **`statsUrl`** | <code>string</code> | Configure the URL / endpoint to which update statistics are sent. Only available for Android and iOS. Set to "" to disable stats reporting. Native stats include update lifecycle events, app health signals such as crashes, Android ANRs, low-memory exits, iOS memory warnings, and WebView health signals such as JavaScript errors, unhandled promise rejections, resource load failures, WebView renderer exits, and unclean WebView restarts when available. | <code>https://plugin.capgo.app/stats</code> | |
314
+ | **`publicKey`** | <code>string</code> | Configure the public key for end to end live update encryption Version 2 Only available for Android and iOS. | <code>undefined</code> | 6.2.0 |
315
+ | **`version`** | <code>string</code> | Configure the current version of the app. This will be used for the first update request. If not set, the plugin will get the version from the native code. Only available for Android and iOS. | <code>undefined</code> | 4.17.48 |
316
+ | **`directUpdate`** | <code>boolean \| 'always' \| 'atInstall' \| 'onLaunch'</code> | Configure when the plugin should direct install updates. Only for autoUpdate mode. | <code>false</code> | 5.1.0 |
317
+ | **`autoSplashscreen`** | <code>boolean</code> | 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 autoUpdate is set to "atInstall", "always", or "onLaunch", or when the deprecated directUpdate option is set to "atInstall", "always", "onLaunch", or true. Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false. Requires Auto Update and Direct Update behavior to be enabled. Only available for Android and iOS. | <code>false</code> | 7.6.0 |
318
+ | **`autoSplashscreenLoader`** | <code>boolean</code> | Display a native loading indicator on top of the splashscreen while automatic direct updates are running. Only takes effect when {@link autoSplashscreen} is enabled. Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false. Only available for Android and iOS. | <code>false</code> | 7.19.0 |
319
+ | **`autoSplashscreenTimeout`** | <code>number</code> | Automatically hide the splashscreen after the specified number of milliseconds when using automatic direct updates. If the timeout elapses, the update continues to download in the background while the splashscreen is dismissed. Set to `0` (zero) to disable the timeout. When the timeout fires, the direct update flow is skipped and the downloaded bundle is installed on the next background/launch. Requires {@link autoSplashscreen} to be enabled. Only available for Android and iOS. | <code>10000 // (10 seconds)</code> | 7.19.0 |
320
+ | **`periodCheckDelay`** | <code>number</code> | Configure the delay period for period update check. the unit is in seconds. Only available for Android and iOS. Cannot be less than 600 seconds (10 minutes). | <code>0 (disabled)</code> | |
321
+ | **`localS3`** | <code>boolean</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
322
+ | **`localHost`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
323
+ | **`localWebHost`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
324
+ | **`localSupa`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
325
+ | **`localSupaAnon`** | <code>string</code> | Configure the CLI to use a local server for testing. | <code>undefined</code> | 4.17.48 |
326
+ | **`localApi`** | <code>string</code> | Configure the CLI to use a local api for testing. | <code>undefined</code> | 6.3.3 |
327
+ | **`localApiFiles`** | <code>string</code> | Configure the CLI to use a local file api for testing. | <code>undefined</code> | 6.3.3 |
328
+ | **`allowModifyUrl`** | <code>boolean</code> | Allow the plugin to modify the updateUrl, statsUrl and channelUrl dynamically from the JavaScript side. | <code>false</code> | 5.4.0 |
329
+ | **`allowModifyAppId`** | <code>boolean</code> | Allow the plugin to modify the appId dynamically from the JavaScript side. | <code>false</code> | 7.14.0 |
330
+ | **`allowManualBundleError`** | <code>boolean</code> | Allow marking bundles as errored from JavaScript while using manual update flows. When enabled, {@link CapacitorUpdaterPlugin.setBundleError} can change a bundle status to `error`. | <code>false</code> | 7.20.0 |
331
+ | **`allowPreview`** | <code>boolean</code> | Allow JavaScript to start a native preview session and temporarily request updates for another app id. This is intended for trusted container apps that implement Expo Go-style preview flows. Only available for Android and iOS. | <code>false</code> | 8.47.0 |
332
+ | **`persistCustomId`** | <code>boolean</code> | Persist the customId set through {@link CapacitorUpdaterPlugin.setCustomId} across app restarts. Only available for Android and iOS. | <code>false (will be true by default in a future major release v8.x.x)</code> | 7.17.3 |
333
+ | **`persistModifyUrl`** | <code>boolean</code> | Persist the updateUrl, statsUrl and channelUrl set through {@link CapacitorUpdaterPlugin.setUpdateUrl}, {@link CapacitorUpdaterPlugin.setStatsUrl} and {@link CapacitorUpdaterPlugin.setChannelUrl} across app restarts. Only available for Android and iOS. | <code>false</code> | 7.20.0 |
334
+ | **`allowSetDefaultChannel`** | <code>boolean</code> | Allow or disallow the {@link CapacitorUpdaterPlugin.setChannel} method to modify the defaultChannel. When set to `false`, calling `setChannel()` will return an error with code `disabled_by_config`. | <code>true</code> | 7.34.0 |
335
+ | **`defaultChannel`** | <code>string</code> | Set the default channel for the app in the config. Case sensitive. This will setting will override the default channel set in the cloud, but will still respect overrides made in the cloud. This requires the channel to allow devices to self dissociate/associate in the channel settings. https://capgo.app/docs/public-api/channels/#channel-configuration-options | <code>undefined</code> | 5.5.0 |
336
+ | **`appId`** | <code>string</code> | Configure the app id for the app in the config. | <code>undefined</code> | 6.0.0 |
337
+ | **`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 |
338
+ | **`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 |
339
+ | **`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 |
340
+ | **`shakeMenu`** | <code>boolean</code> | Enable the native preview menu gesture while a preview session is active. Outside preview sessions this preview menu is ignored, unless {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled. | <code>false</code> | 7.5.0 |
341
+ | **`shakeMenuGesture`** | <code><a href="#shakemenugesture">ShakeMenuGesture</a></code> | Choose which native gesture opens the preview/channel menu. This applies to both {@link PluginsConfig.CapacitorUpdater.shakeMenu} and {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}. Only available for Android and iOS. | <code>'shake'</code> | 8.48.0 |
342
+ | **`allowShakeChannelSelector`** | <code>boolean</code> | Enable the native menu gesture to show a channel selector menu for switching between update channels. If {@link PluginsConfig.CapacitorUpdater.shakeMenu} is also enabled while a preview session is active, the shake menu includes both preview actions and channel switching. The native gesture can be changed with {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}. Only available for Android and iOS. | <code>false</code> | 8.43.0 |
324
343
 
325
344
  ### Examples
326
345
 
@@ -334,7 +353,7 @@ In `capacitor.config.json`:
334
353
  "responseTimeout": 10 // (10 second),
335
354
  "autoDeleteFailed": false,
336
355
  "autoDeletePrevious": false,
337
- "autoUpdate": false,
356
+ "autoUpdate": "onlyDownload",
338
357
  "resetWhenUpdate": false,
339
358
  "updateUrl": https://example.com/api/auto_update,
340
359
  "channelUrl": https://example.com/api/channel,
@@ -356,6 +375,7 @@ In `capacitor.config.json`:
356
375
  "allowModifyUrl": undefined,
357
376
  "allowModifyAppId": undefined,
358
377
  "allowManualBundleError": undefined,
378
+ "allowPreview": undefined,
359
379
  "persistCustomId": undefined,
360
380
  "persistModifyUrl": undefined,
361
381
  "allowSetDefaultChannel": undefined,
@@ -365,6 +385,7 @@ In `capacitor.config.json`:
365
385
  "disableJSLogging": undefined,
366
386
  "osLogging": undefined,
367
387
  "shakeMenu": undefined,
388
+ "shakeMenuGesture": undefined,
368
389
  "allowShakeChannelSelector": undefined
369
390
  }
370
391
  }
@@ -385,7 +406,7 @@ const config: CapacitorConfig = {
385
406
  responseTimeout: 10 // (10 second),
386
407
  autoDeleteFailed: false,
387
408
  autoDeletePrevious: false,
388
- autoUpdate: false,
409
+ autoUpdate: "onlyDownload",
389
410
  resetWhenUpdate: false,
390
411
  updateUrl: https://example.com/api/auto_update,
391
412
  channelUrl: https://example.com/api/channel,
@@ -407,6 +428,7 @@ const config: CapacitorConfig = {
407
428
  allowModifyUrl: undefined,
408
429
  allowModifyAppId: undefined,
409
430
  allowManualBundleError: undefined,
431
+ allowPreview: undefined,
410
432
  persistCustomId: undefined,
411
433
  persistModifyUrl: undefined,
412
434
  allowSetDefaultChannel: undefined,
@@ -416,6 +438,7 @@ const config: CapacitorConfig = {
416
438
  disableJSLogging: undefined,
417
439
  osLogging: undefined,
418
440
  shakeMenu: undefined,
441
+ shakeMenuGesture: undefined,
419
442
  allowShakeChannelSelector: undefined,
420
443
  },
421
444
  },
@@ -438,6 +461,13 @@ export default config;
438
461
  * [`download(...)`](#download)
439
462
  * [`next(...)`](#next)
440
463
  * [`set(...)`](#set)
464
+ * [`startPreviewSession(...)`](#startpreviewsession)
465
+ * [`listPreviews()`](#listpreviews)
466
+ * [`setPreview(...)`](#setpreview)
467
+ * [`resetPreview()`](#resetpreview)
468
+ * [`deletePreview(...)`](#deletepreview)
469
+ * [`checkPreviewUpdate(...)`](#checkpreviewupdate)
470
+ * [`updatePreview(...)`](#updatepreview)
441
471
  * [`delete(...)`](#delete)
442
472
  * [`setBundleError(...)`](#setbundleerror)
443
473
  * [`list(...)`](#list)
@@ -446,7 +476,10 @@ export default config;
446
476
  * [`reload()`](#reload)
447
477
  * [`setMultiDelay(...)`](#setmultidelay)
448
478
  * [`cancelDelay()`](#canceldelay)
479
+ * [`triggerUpdateCheck()`](#triggerupdatecheck)
449
480
  * [`getLatest(...)`](#getlatest)
481
+ * [`getMissingBundleFiles(...)`](#getmissingbundlefiles)
482
+ * [`getBundleDownloadSize(...)`](#getbundledownloadsize)
450
483
  * [`setChannel(...)`](#setchannel)
451
484
  * [`unsetChannel(...)`](#unsetchannel)
452
485
  * [`getChannel()`](#getchannel)
@@ -459,11 +492,14 @@ export default config;
459
492
  * [`removeAllListeners()`](#removealllisteners)
460
493
  * [`addListener('download', ...)`](#addlistenerdownload-)
461
494
  * [`addListener('noNeedUpdate', ...)`](#addlistenernoneedupdate-)
495
+ * [`addListener('updateCheckResult', ...)`](#addlistenerupdatecheckresult-)
462
496
  * [`addListener('updateAvailable', ...)`](#addlistenerupdateavailable-)
463
497
  * [`addListener('downloadComplete', ...)`](#addlistenerdownloadcomplete-)
464
498
  * [`addListener('breakingAvailable', ...)`](#addlistenerbreakingavailable-)
465
499
  * [`addListener('majorAvailable', ...)`](#addlistenermajoravailable-)
466
500
  * [`addListener('updateFailed', ...)`](#addlistenerupdatefailed-)
501
+ * [`addListener('set', ...)`](#addlistenerset-)
502
+ * [`addListener('setNext', ...)`](#addlistenersetnext-)
467
503
  * [`addListener('downloadFailed', ...)`](#addlistenerdownloadfailed-)
468
504
  * [`addListener('appReloaded', ...)`](#addlistenerappreloaded-)
469
505
  * [`addListener('appReady', ...)`](#addlistenerappready-)
@@ -620,6 +656,11 @@ The bundle must include an `index.html` file at the root level.
620
656
  For encrypted bundles, provide the `sessionKey` and `checksum` parameters.
621
657
  For multi-file delta updates, provide the `manifest` array.
622
658
 
659
+ **Android Background Runner note:** `@capacitor/background-runner` loads its
660
+ configured runner script from native APK assets. Live updates cannot replace
661
+ that runner script. Keep it stable across OTA updates and ship a native app
662
+ update when the runner code changes.
663
+
623
664
  | Param | Type | Description |
624
665
  | ------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
625
666
  | **`options`** | <code><a href="#downloadoptions">DownloadOptions</a></code> | The {@link <a href="#downloadoptions">DownloadOptions</a>} for downloading a new bundle zip. |
@@ -688,6 +729,161 @@ For other state preservation needs, save your data before calling this method (e
688
729
  --------------------
689
730
 
690
731
 
732
+ #### startPreviewSession(...)
733
+
734
+ ```typescript
735
+ startPreviewSession(options?: StartPreviewSessionOptions | undefined) => Promise<void>
736
+ ```
737
+
738
+ Start a temporary preview/testing session.
739
+
740
+ This stores the currently active bundle as the pending fallback, enables the
741
+ native shake menu, and makes the next applied bundle show a native notice
742
+ explaining that shaking the device can reload or leave the preview.
743
+ Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
744
+ When `appId` is provided, the preview session temporarily uses that app id
745
+ for update checks until the user leaves the preview. Native updater stats are
746
+ skipped while the preview session is active.
747
+
748
+ Use this before calling {@link set} for Expo Go-style preview flows.
749
+ Use {@link listPreviews}, {@link setPreview}, {@link resetPreview},
750
+ {@link deletePreview}, {@link checkPreviewUpdate}, and
751
+ {@link updatePreview} to manage saved local previews.
752
+
753
+ | Param | Type | Description |
754
+ | ------------- | --------------------------------------------------------------------------------- | --------------------------------- |
755
+ | **`options`** | <code><a href="#startpreviewsessionoptions">StartPreviewSessionOptions</a></code> | Optional preview session options. |
756
+
757
+ **Since:** 8.47.0
758
+
759
+ --------------------
760
+
761
+
762
+ #### listPreviews()
763
+
764
+ ```typescript
765
+ listPreviews() => Promise<PreviewListResult>
766
+ ```
767
+
768
+ Get every locally available preview bundle that was registered by
769
+ {@link startPreviewSession} and later applied with {@link set}.
770
+
771
+ This only returns previews whose bundles are still available locally. It is
772
+ safe to show this in a preview switcher or native debug menu.
773
+
774
+ **Returns:** <code>Promise&lt;<a href="#previewlistresult">PreviewListResult</a>&gt;</code>
775
+
776
+ **Since:** 8.49.0
777
+
778
+ --------------------
779
+
780
+
781
+ #### setPreview(...)
782
+
783
+ ```typescript
784
+ setPreview(options: BundleId) => Promise<void>
785
+ ```
786
+
787
+ Switch to a locally available preview bundle and reload the WebView.
788
+
789
+ If the app is not already in a preview session, the current live bundle is
790
+ saved as the fallback so {@link resetPreview} or the native shake menu can
791
+ return to it later.
792
+
793
+ | Param | Type | Description |
794
+ | ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
795
+ | **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
796
+
797
+ **Since:** 8.49.0
798
+
799
+ --------------------
800
+
801
+
802
+ #### resetPreview()
803
+
804
+ ```typescript
805
+ resetPreview() => Promise<void>
806
+ ```
807
+
808
+ Leave the active preview session and reload the saved live bundle.
809
+
810
+ This does not delete any saved previews. Use {@link deletePreview} to remove
811
+ a preview from local storage.
812
+
813
+ **Since:** 8.49.0
814
+
815
+ --------------------
816
+
817
+
818
+ #### deletePreview(...)
819
+
820
+ ```typescript
821
+ deletePreview(options: BundleId) => Promise<DeletePreviewResult>
822
+ ```
823
+
824
+ Delete a locally saved preview and its bundle when possible.
825
+
826
+ Active previews cannot be deleted until you switch away from them or call
827
+ {@link resetPreview}. If only the preview metadata can be removed, the
828
+ method still resolves with `deleted: false`.
829
+
830
+ | Param | Type | Description |
831
+ | ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
832
+ | **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
833
+
834
+ **Returns:** <code>Promise&lt;<a href="#deletepreviewresult">DeletePreviewResult</a>&gt;</code>
835
+
836
+ **Since:** 8.49.0
837
+
838
+ --------------------
839
+
840
+
841
+ #### checkPreviewUpdate(...)
842
+
843
+ ```typescript
844
+ checkPreviewUpdate(options: BundleId) => Promise<PreviewUpdateResult>
845
+ ```
846
+
847
+ Check whether a saved preview's payload URL points to a newer preview bundle.
848
+
849
+ Only previews started with a `payloadUrl` can be checked natively. Direct URL
850
+ previews can still be switched or deleted locally, but the updater does not
851
+ know where to check for newer versions.
852
+
853
+ | Param | Type | Description |
854
+ | ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
855
+ | **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
856
+
857
+ **Returns:** <code>Promise&lt;<a href="#previewupdateresult">PreviewUpdateResult</a>&gt;</code>
858
+
859
+ **Since:** 8.49.0
860
+
861
+ --------------------
862
+
863
+
864
+ #### updatePreview(...)
865
+
866
+ ```typescript
867
+ updatePreview(options: BundleId) => Promise<PreviewUpdateResult>
868
+ ```
869
+
870
+ Download the newest bundle for a saved preview payload URL.
871
+
872
+ If the preview being updated is active, the new bundle is applied and the
873
+ WebView reloads. Otherwise, the saved preview entry is moved to the newly
874
+ downloaded bundle and can be selected later with {@link setPreview}.
875
+
876
+ | Param | Type | Description |
877
+ | ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
878
+ | **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
879
+
880
+ **Returns:** <code>Promise&lt;<a href="#previewupdateresult">PreviewUpdateResult</a>&gt;</code>
881
+
882
+ **Since:** 8.49.0
883
+
884
+ --------------------
885
+
886
+
691
887
  #### delete(...)
692
888
 
693
889
  ```typescript
@@ -901,6 +1097,33 @@ This is useful when:
901
1097
  --------------------
902
1098
 
903
1099
 
1100
+ #### triggerUpdateCheck()
1101
+
1102
+ ```typescript
1103
+ triggerUpdateCheck() => Promise<TriggerUpdateCheckResult>
1104
+ ```
1105
+
1106
+ Trigger the native auto-update check/download pipeline immediately.
1107
+
1108
+ This starts the same background update flow used when the app moves to the
1109
+ foreground with auto-update enabled. It is useful for native integrations
1110
+ such as a silent push notification asking the app to check for a Capgo
1111
+ bundle without reimplementing the update protocol in JavaScript.
1112
+
1113
+ The promise resolves after the native background work has been queued, not
1114
+ after the update has been downloaded or installed. Listen to updater events
1115
+ such as `updateAvailable`, `downloadComplete`, `downloadFailed`, and
1116
+ `noNeedUpdate` for the final result.
1117
+
1118
+ Native support is available on iOS and Android. On Web, this method returns
1119
+ a result with `status: 'unavailable'`. Native platforms also return
1120
+ `unavailable` when the native auto-update system is disabled.
1121
+
1122
+ **Returns:** <code>Promise&lt;<a href="#triggerupdatecheckresult">TriggerUpdateCheckResult</a>&gt;</code>
1123
+
1124
+ --------------------
1125
+
1126
+
904
1127
  #### getLatest(...)
905
1128
 
906
1129
  ```typescript
@@ -924,27 +1147,23 @@ After receiving the latest version info, you can:
924
1147
  2. Download it using {@link download}
925
1148
  3. Apply it using {@link next} or {@link set}
926
1149
 
927
- **Important: Error handling for "no new version available"**
1150
+ **Important: Handling "no new version available"**
928
1151
 
929
1152
  When the device's current version matches the latest version on the server (i.e., the device is already
930
1153
  up-to-date), the server returns a 200 response with `error: "no_new_version_available"` and
931
- `message: "No new version available"`. **This causes `getLatest()` to throw an error**, even though
932
- this is a normal, expected condition.
1154
+ `message: "No new version available"`. This is a normal, expected condition and resolves with
1155
+ `kind: "up_to_date"` when the backend provides that classification.
933
1156
 
934
- You should catch this specific error to handle it gracefully:
1157
+ You should check `kind` and `error` before attempting to download:
935
1158
 
936
1159
  ```typescript
937
- try {
938
- const latest = await CapacitorUpdater.getLatest();
1160
+ const latest = await CapacitorUpdater.getLatest();
1161
+ if (latest.kind === 'up_to_date') {
1162
+ console.log('Already up to date');
1163
+ } else if (latest.kind === 'blocked') {
1164
+ console.log('Update is blocked:', latest.error);
1165
+ } else if (latest.url) {
939
1166
  // New version is available, proceed with download
940
- } catch (error) {
941
- if (error.message === 'No new version available') {
942
- // Device is already on the latest version - this is normal
943
- console.log('Already up to date');
944
- } else {
945
- // Actual error occurred
946
- console.error('Failed to check for updates:', error);
947
- }
948
1167
  }
949
1168
  ```
950
1169
 
@@ -963,6 +1182,73 @@ In this scenario, the server:
963
1182
  --------------------
964
1183
 
965
1184
 
1185
+ #### getMissingBundleFiles(...)
1186
+
1187
+ ```typescript
1188
+ getMissingBundleFiles(options: GetMissingBundleFilesOptions) => Promise<GetMissingBundleFilesResult>
1189
+ ```
1190
+
1191
+ Return the manifest entries that still need to be downloaded for a partial update.
1192
+
1193
+ Pass the result from {@link getLatest} directly when it includes a `manifest`.
1194
+ The native plugin compares each manifest entry with the files already available
1195
+ in the builtin bundle and the local delta cache. Entries that can be reused are
1196
+ omitted from the returned `missing` list.
1197
+
1198
+ For encrypted manifests, pass the `sessionKey` returned by {@link getLatest} so
1199
+ encrypted file hashes can be checked against local files.
1200
+
1201
+ ```typescript
1202
+ const latest = await CapacitorUpdater.getLatest();
1203
+ const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
1204
+ ```
1205
+
1206
+ | Param | Type | Description |
1207
+ | ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1208
+ | **`options`** | <code><a href="#getmissingbundlefilesoptions">GetMissingBundleFilesOptions</a></code> | A {@link <a href="#getmissingbundlefilesoptions">GetMissingBundleFilesOptions</a>} object, or a {@link <a href="#latestversion">LatestVersion</a>} response containing `manifest`. |
1209
+
1210
+ **Returns:** <code>Promise&lt;<a href="#getmissingbundlefilesresult">GetMissingBundleFilesResult</a>&gt;</code>
1211
+
1212
+ **Since:** 8.47.0
1213
+
1214
+ --------------------
1215
+
1216
+
1217
+ #### getBundleDownloadSize(...)
1218
+
1219
+ ```typescript
1220
+ getBundleDownloadSize(options: GetBundleDownloadSizeOptions) => Promise<GetBundleDownloadSizeResult>
1221
+ ```
1222
+
1223
+ Estimate the download size for manifest entries before downloading them.
1224
+
1225
+ This method sends the provided manifest entries to the Capgo update endpoint
1226
+ once and reads the stored manifest `file_size` metadata. It does not perform
1227
+ per-file `HEAD` requests from the app.
1228
+
1229
+ Use this after {@link getMissingBundleFiles} to estimate only the files this
1230
+ device still needs:
1231
+
1232
+ ```typescript
1233
+ const latest = await CapacitorUpdater.getLatest();
1234
+ const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
1235
+ const size = await CapacitorUpdater.getBundleDownloadSize({
1236
+ version: latest.version,
1237
+ manifest: missing.missing,
1238
+ });
1239
+ ```
1240
+
1241
+ | Param | Type | Description |
1242
+ | ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
1243
+ | **`options`** | <code><a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a></code> | A {@link <a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a>} object containing manifest entries. |
1244
+
1245
+ **Returns:** <code>Promise&lt;<a href="#getbundledownloadsizeresult">GetBundleDownloadSizeResult</a>&gt;</code>
1246
+
1247
+ **Since:** 8.47.0
1248
+
1249
+ --------------------
1250
+
1251
+
966
1252
  #### setChannel(...)
967
1253
 
968
1254
  ```typescript
@@ -974,6 +1260,11 @@ Assign this device to a specific update channel at runtime.
974
1260
  Channels allow you to distribute different bundle versions to different groups of users
975
1261
  (e.g., "production", "beta", "staging"). This method switches the device to a new channel.
976
1262
 
1263
+ **Device Override UI:** `setChannel()` validates the channel with the backend, then stores the
1264
+ selected channel locally on the device. It does not create or update a backend Device Override,
1265
+ so the device will not appear as overridden in the Capgo dashboard. Only assignments created
1266
+ from the dashboard or the Public API are shown in the Device Override UI.
1267
+
977
1268
  **Requirements:**
978
1269
  - The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
979
1270
  - The backend may accept or reject the request based on channel settings
@@ -1000,7 +1291,8 @@ CapacitorUpdater.addListener('channelPrivate', (data) =&gt; {
1000
1291
  });
1001
1292
  ```
1002
1293
 
1003
- This sends a request to the Capgo backend linking your device ID to the specified channel.
1294
+ This sends a request to the Capgo backend to validate the specified channel, then stores the
1295
+ channel locally on the device.
1004
1296
 
1005
1297
  | Param | Type | Description |
1006
1298
  | ------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@@ -1019,11 +1311,12 @@ This sends a request to the Capgo backend linking your device ID to the specifie
1019
1311
  unsetChannel(options: UnsetChannelOptions) => Promise<void>
1020
1312
  ```
1021
1313
 
1022
- Remove the device's channel assignment and return to the default channel.
1314
+ Remove the plugin-managed local channel assignment and return to the default channel.
1023
1315
 
1024
- This unlinks the device from any specifically assigned channel, causing it to fall back to:
1316
+ 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:
1317
+ - An existing Dashboard or Public API Device Override, if one exists
1025
1318
  - The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
1026
- - Your backend's default channel for this app
1319
+ - Your backend default channel for this app
1027
1320
 
1028
1321
  Use this when:
1029
1322
  - Users opt out of beta/testing programs
@@ -1058,6 +1351,9 @@ Use this to:
1058
1351
  - Check if a device is on a specific channel before showing features
1059
1352
  - Verify channel assignment after calling {@link setChannel}
1060
1353
 
1354
+ On native platforms, a successful response also refreshes the locally persisted
1355
+ default channel used by update checks.
1356
+
1061
1357
  **Returns:** <code>Promise&lt;<a href="#getchannelres">GetChannelRes</a>&gt;</code>
1062
1358
 
1063
1359
  **Since:** 4.8.0
@@ -1169,7 +1465,7 @@ It's automatically generated and stored securely by the plugin.
1169
1465
  **Privacy & Security characteristics:**
1170
1466
  - Generated as a UUID (not based on hardware identifiers)
1171
1467
  - Stored securely in platform-specific secure storage
1172
- - Android: Android Keystore (persists across app reinstalls on API 23+)
1468
+ - Android: mirrored into backup-restorable app preferences for reinstall restore
1173
1469
  - iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
1174
1470
  - Not synced to cloud (iOS)
1175
1471
  - Follows Apple and Google privacy best practices
@@ -1177,7 +1473,9 @@ It's automatically generated and stored securely by the plugin.
1177
1473
 
1178
1474
  **Persistence:**
1179
1475
  The device ID persists across app reinstalls to maintain consistent device identity
1180
- for update tracking and analytics.
1476
+ for update tracking and analytics when platform storage is preserved. On Android,
1477
+ apps with custom backup rules must keep the plugin app preferences eligible for
1478
+ backup/restore; disabling Android backup or clearing app data creates a new ID.
1181
1479
 
1182
1480
  Use this to:
1183
1481
  - Debug update delivery issues (check what ID the server sees)
@@ -1246,6 +1544,7 @@ Remove all event listeners registered for this plugin.
1246
1544
  This unregisters all listeners added via {@link addListener} for all event types:
1247
1545
  - `download`
1248
1546
  - `noNeedUpdate`
1547
+ - `updateCheckResult`
1249
1548
  - `updateAvailable`
1250
1549
  - `downloadComplete`
1251
1550
  - `downloadFailed`
@@ -1303,6 +1602,31 @@ Listen for no need to update event, useful when you want force check every time
1303
1602
  --------------------
1304
1603
 
1305
1604
 
1605
+ #### addListener('updateCheckResult', ...)
1606
+
1607
+ ```typescript
1608
+ addListener(eventName: 'updateCheckResult', listenerFunc: (state: UpdateCheckResultEvent) => void) => Promise<PluginListenerHandle>
1609
+ ```
1610
+
1611
+ Listen for update check results before the updater decides whether to download.
1612
+ The backend can classify the <a href="#updatecheckresultevent">UpdateCheckResultEvent</a> payload as `up_to_date`, `blocked`, or `failed`.
1613
+
1614
+ This event is emitted alongside legacy events. For `up_to_date` and `blocked`, it is emitted before
1615
+ `noNeedUpdate` and does not emit `downloadFailed`. For `failed`, it is emitted before the legacy
1616
+ `downloadFailed` event and keeps the existing failure stats behavior.
1617
+
1618
+ | Param | Type |
1619
+ | ------------------ | --------------------------------------------------------------------------------------------- |
1620
+ | **`eventName`** | <code>'updateCheckResult'</code> |
1621
+ | **`listenerFunc`** | <code>(state: <a href="#updatecheckresultevent">UpdateCheckResultEvent</a>) =&gt; void</code> |
1622
+
1623
+ **Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
1624
+
1625
+ **Since:** 8.45.11
1626
+
1627
+ --------------------
1628
+
1629
+
1306
1630
  #### addListener('updateAvailable', ...)
1307
1631
 
1308
1632
  ```typescript
@@ -1404,6 +1728,48 @@ Listen for update fail event in the App, let you know when update has fail to in
1404
1728
  --------------------
1405
1729
 
1406
1730
 
1731
+ #### addListener('set', ...)
1732
+
1733
+ ```typescript
1734
+ addListener(eventName: 'set', listenerFunc: (state: SetEvent) => void) => Promise<PluginListenerHandle>
1735
+ ```
1736
+
1737
+ Listen for set event in the App, let you know when a bundle has been applied successfully.
1738
+ This event is retained natively until JavaScript consumes it, so if the app reloads before your
1739
+ listener is attached, the last pending `set` event is delivered once the listener subscribes.
1740
+
1741
+ | Param | Type |
1742
+ | ------------------ | ----------------------------------------------------------------- |
1743
+ | **`eventName`** | <code>'set'</code> |
1744
+ | **`listenerFunc`** | <code>(state: <a href="#setevent">SetEvent</a>) =&gt; void</code> |
1745
+
1746
+ **Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
1747
+
1748
+ **Since:** 8.43.12
1749
+
1750
+ --------------------
1751
+
1752
+
1753
+ #### addListener('setNext', ...)
1754
+
1755
+ ```typescript
1756
+ addListener(eventName: 'setNext', listenerFunc: (state: SetNextEvent) => void) => Promise<PluginListenerHandle>
1757
+ ```
1758
+
1759
+ Listen for set next event in the App, let you know when a bundle is queued as the next bundle to install.
1760
+
1761
+ | Param | Type |
1762
+ | ------------------ | ------------------------------------------------------------------------- |
1763
+ | **`eventName`** | <code>'setNext'</code> |
1764
+ | **`listenerFunc`** | <code>(state: <a href="#setnextevent">SetNextEvent</a>) =&gt; void</code> |
1765
+
1766
+ **Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
1767
+
1768
+ **Since:** 6.14.0
1769
+
1770
+ --------------------
1771
+
1772
+
1407
1773
  #### addListener('downloadFailed', ...)
1408
1774
 
1409
1775
  ```typescript
@@ -1450,7 +1816,9 @@ Listen for reload event in the App, let you know when reload has happened
1450
1816
  addListener(eventName: 'appReady', listenerFunc: (state: AppReadyEvent) => void) => Promise<PluginListenerHandle>
1451
1817
  ```
1452
1818
 
1453
- Listen for app ready event in the App, let you know when app is ready to use, this event is retain till consumed.
1819
+ Listen for app ready event in the App, let you know when app is ready to use.
1820
+ This event is retained natively until JavaScript consumes it, so it can still be delivered after
1821
+ a reload even if the listener is attached later in app startup.
1454
1822
 
1455
1823
  | Param | Type |
1456
1824
  | ------------------ | --------------------------------------------------------------------------- |
@@ -1618,23 +1986,20 @@ Use this to:
1618
1986
  setShakeMenu(options: SetShakeMenuOptions) => Promise<void>
1619
1987
  ```
1620
1988
 
1621
- Enable or disable the shake gesture menu for debugging and testing.
1989
+ Enable or disable the native preview menu gesture.
1622
1990
 
1623
- When enabled, users can shake their device to open a debug menu that shows:
1624
- - Current bundle information
1625
- - Available bundles
1626
- - Options to switch bundles manually
1627
- - Update status
1991
+ During preview sessions, users can use the configured native gesture to:
1992
+ - Reload the current preview
1993
+ - Leave the test app and return to the fallback bundle
1994
+ - Switch update channel, when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is also enabled
1628
1995
 
1629
- This is useful during development and testing to:
1630
- - Quickly test different bundle versions
1631
- - Debug update flows
1632
- - Switch between production and test bundles
1633
- - Verify bundle installations
1996
+ Outside preview sessions, this preview menu is ignored. The channel selector can still be
1997
+ shown outside preview sessions when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled.
1634
1998
 
1635
1999
  **Important:** Disable this in production builds or only enable for internal testers.
1636
2000
 
1637
- Can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
2001
+ This can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
2002
+ The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.
1638
2003
 
1639
2004
  | Param | Type |
1640
2005
  | ------------- | ------------------------------------------------------------------- |
@@ -1651,7 +2016,7 @@ Can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
1651
2016
  isShakeMenuEnabled() => Promise<ShakeMenuEnabled>
1652
2017
  ```
1653
2018
 
1654
- Check if the shake gesture debug menu is currently enabled.
2019
+ Check if the native preview menu gesture is currently enabled.
1655
2020
 
1656
2021
  Returns the current state of the shake menu feature that can be toggled via
1657
2022
  {@link setShakeMenu} or configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
@@ -1674,16 +2039,14 @@ Use this to:
1674
2039
  setShakeChannelSelector(options: SetShakeChannelSelectorOptions) => Promise<void>
1675
2040
  ```
1676
2041
 
1677
- Enable or disable the shake channel selector at runtime.
2042
+ Enable or disable the channel selector menu gesture at runtime.
1678
2043
 
1679
- When enabled AND shakeMenu is true, shaking the device shows a channel
1680
- selector instead of the debug menu. This allows users to switch between
1681
- update channels by shaking their device.
2044
+ When enabled, the configured native gesture can show a channel selector, including outside preview sessions.
2045
+ If {@link setShakeMenu} is also enabled while a preview session is active, the shake menu includes
2046
+ both preview actions and channel switching.
1682
2047
 
1683
- After selecting a channel, the app automatically checks for updates
1684
- and downloads if available.
1685
-
1686
- Can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
2048
+ This can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
2049
+ The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.
1687
2050
 
1688
2051
  | Param | Type |
1689
2052
  | ------------- | ----------------------------------------------------------------------------------------- |
@@ -1998,6 +2361,61 @@ If you don't use backend, you need to provide the URL and version of the bundle.
1998
2361
  | **`id`** | <code>string</code> |
1999
2362
 
2000
2363
 
2364
+ ##### StartPreviewSessionOptions
2365
+
2366
+ | Prop | Type | Description | Default | Since |
2367
+ | ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
2368
+ | **`appId`** | <code>string</code> | App id to use while the preview session is active. The previous app id is restored when leaving the preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.47.0 |
2369
+ | **`payloadUrl`** | <code>string</code> | HTTP(S) URL returning a preview download payload. When provided, the native shake reload action fetches this payload again before reloading so channel previews can move to the latest bundle. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.48.0 |
2370
+ | **`name`** | <code>string</code> | Human-readable preview name stored with the next preview bundle applied by {@link set}. Native preview menus and {@link listPreviews} can display it. | <code>undefined</code> | 8.49.0 |
2371
+ | **`source`** | <code>string</code> | Optional source label for the preview, such as `channel`, `bundle`, `url`, or `payload`. This is stored as metadata only. | <code>undefined</code> | 8.49.0 |
2372
+
2373
+
2374
+ ##### PreviewListResult
2375
+
2376
+ | Prop | Type | Description | Since |
2377
+ | ------------------- | --------------------------------------------------- | ------------------------------------------------------- | ------ |
2378
+ | **`previews`** | <code>PreviewInfo[]</code> | Locally available preview bundles. | 8.49.0 |
2379
+ | **`current`** | <code><a href="#previewinfo">PreviewInfo</a></code> | Current preview when a preview session is active. | 8.49.0 |
2380
+ | **`currentBundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Bundle currently loaded by the WebView. | 8.49.0 |
2381
+ | **`liveBundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Bundle that will be restored when leaving preview mode. | 8.49.0 |
2382
+
2383
+
2384
+ ##### PreviewInfo
2385
+
2386
+ | Prop | Type | Description | Since |
2387
+ | ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------ |
2388
+ | **`id`** | <code>string</code> | Preview bundle id. | 8.49.0 |
2389
+ | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Locally downloaded bundle backing this preview. | 8.49.0 |
2390
+ | **`name`** | <code>string</code> | Human-readable name supplied when the preview was started. | 8.49.0 |
2391
+ | **`source`** | <code>string</code> | Metadata source label supplied when the preview was started. | 8.49.0 |
2392
+ | **`appId`** | <code>string</code> | Preview app id, when the session uses an app id override. | 8.49.0 |
2393
+ | **`payloadUrl`** | <code>string</code> | Payload URL used to refresh this preview. | 8.49.0 |
2394
+ | **`createdAt`** | <code>string</code> | ISO timestamp for when this preview was first saved. | 8.49.0 |
2395
+ | **`updatedAt`** | <code>string</code> | ISO timestamp for the last metadata or bundle update. | 8.49.0 |
2396
+ | **`lastUsedAt`** | <code>string</code> | ISO timestamp for the last time this preview was activated. | 8.49.0 |
2397
+ | **`isActive`** | <code>boolean</code> | Whether this preview is the currently active bundle in a preview session. | 8.49.0 |
2398
+
2399
+
2400
+ ##### DeletePreviewResult
2401
+
2402
+ | Prop | Type | Description | Since |
2403
+ | ------------- | -------------------- | ------------------------------------------------ | ------ |
2404
+ | **`removed`** | <code>boolean</code> | Whether preview metadata was removed. | 8.49.0 |
2405
+ | **`deleted`** | <code>boolean</code> | Whether the underlying local bundle was deleted. | 8.49.0 |
2406
+
2407
+
2408
+ ##### PreviewUpdateResult
2409
+
2410
+ | Prop | Type | Description | Since |
2411
+ | ------------------- | --------------------------------------------------- | --------------------------------------------------------------------- | ------ |
2412
+ | **`preview`** | <code><a href="#previewinfo">PreviewInfo</a></code> | Saved preview metadata after the check or update. | 8.49.0 |
2413
+ | **`latestVersion`** | <code>string</code> | Latest version returned by the preview payload endpoint. | 8.49.0 |
2414
+ | **`upToDate`** | <code>boolean</code> | Whether the saved preview already matches the latest payload version. | 8.49.0 |
2415
+ | **`updated`** | <code>boolean</code> | Whether a newer bundle was downloaded and saved. | 8.49.0 |
2416
+ | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | New bundle when {@link updatePreview} downloaded one. | 8.49.0 |
2417
+
2418
+
2001
2419
  ##### BundleListResult
2002
2420
 
2003
2421
  | Prop | Type |
@@ -2014,9 +2432,10 @@ If you don't use backend, you need to provide the URL and version of the bundle.
2014
2432
 
2015
2433
  ##### ResetOptions
2016
2434
 
2017
- | Prop | Type |
2018
- | ---------------------- | -------------------- |
2019
- | **`toLastSuccessful`** | <code>boolean</code> |
2435
+ | Prop | Type | Description | Default |
2436
+ | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
2437
+ | **`toLastSuccessful`** | <code>boolean</code> | Reset to the last successfully loaded bundle instead of the builtin one. | <code>false</code> |
2438
+ | **`usePendingBundle`** | <code>boolean</code> | Apply the pending bundle set via {@link next} while resetting. When `true`, the plugin will switch to the pending bundle immediately and clear the pending flag. If no pending bundle exists, the reset will fail. | <code>false</code> |
2020
2439
 
2021
2440
 
2022
2441
  ##### CurrentBundleResult
@@ -2042,29 +2461,93 @@ If you don't use backend, you need to provide the URL and version of the bundle.
2042
2461
  | **`value`** | <code>string</code> | |
2043
2462
 
2044
2463
 
2464
+ ##### TriggerUpdateCheckResult
2465
+
2466
+ Result returned after requesting an immediate native auto-update check.
2467
+
2468
+ | Prop | Type | Description |
2469
+ | ------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2470
+ | **`status`** | <code>'queued' \| 'already_running' \| 'unavailable'</code> | Native trigger state: `queued` when a check was queued, `already_running` when the native update pipeline is already active, or `unavailable` on Web or when native auto-update is disabled. |
2471
+ | **`queued`** | <code>boolean</code> | Whether a new native update check was queued. This is `true` only when `status` is `queued`; otherwise it is `false`. |
2472
+
2473
+
2045
2474
  ##### LatestVersion
2046
2475
 
2047
- | Prop | Type | Description | Since |
2048
- | ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
2049
- | **`version`** | <code>string</code> | Result of getLatest method | 4.0.0 |
2050
- | **`checksum`** | <code>string</code> | | 6 |
2051
- | **`breaking`** | <code>boolean</code> | Indicates whether the update was flagged as breaking by the backend. | 7.22.0 |
2052
- | **`major`** | <code>boolean</code> | | |
2053
- | **`message`** | <code>string</code> | Optional message from the server. When no new version is available, this will be "No new version available". | |
2054
- | **`sessionKey`** | <code>string</code> | | |
2055
- | **`error`** | <code>string</code> | Error code from the server, if any. Common values: - `"no_new_version_available"`: Device is already on the latest version (not a failure) - Other error codes indicate actual failures in the update process | |
2056
- | **`old`** | <code>string</code> | The previous/current version name (provided for reference). | |
2057
- | **`url`** | <code>string</code> | Download URL for the bundle (when a new version is available). | |
2058
- | **`manifest`** | <code>ManifestEntry[]</code> | File list for delta updates (when using multi-file downloads). | 6.1 |
2059
- | **`link`** | <code>string</code> | Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release). | 7.35.0 |
2060
- | **`comment`** | <code>string</code> | Optional comment or description for this bundle version. | 7.35.0 |
2476
+ | Prop | Type | Description | Since |
2477
+ | ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
2478
+ | **`version`** | <code>string</code> | Result of getLatest method | 4.0.0 |
2479
+ | **`checksum`** | <code>string</code> | | 6 |
2480
+ | **`breaking`** | <code>boolean</code> | Indicates whether the update was flagged as breaking by the backend. | 7.22.0 |
2481
+ | **`major`** | <code>boolean</code> | | |
2482
+ | **`message`** | <code>string</code> | Optional message from the server. When no new version is available, this will be "No new version available". | |
2483
+ | **`sessionKey`** | <code>string</code> | | |
2484
+ | **`error`** | <code>string</code> | Error code from the server, if any. Use `kind` for classification instead of parsing this value. | |
2485
+ | **`kind`** | <code><a href="#updateresponsekind">UpdateResponseKind</a></code> | Classification for this response, provided by the backend. | 8.45.11 |
2486
+ | **`statusCode`** | <code>number</code> | HTTP status code returned by the update server for classified update-check responses. | 8.45.11 |
2487
+ | **`old`** | <code>string</code> | The previous/current version name (provided for reference). | |
2488
+ | **`url`** | <code>string</code> | Download URL for the bundle (when a new version is available). | |
2489
+ | **`manifest`** | <code>ManifestEntry[]</code> | File list for delta updates (when using multi-file downloads). | 6.1 |
2490
+ | **`missing`** | <code><a href="#getmissingbundlefilesresult">GetMissingBundleFilesResult</a></code> | Missing manifest entries for this device when {@link <a href="#getlatestoptions">GetLatestOptions.includeBundleSize</a>} is enabled. | 8.47.0 |
2491
+ | **`downloadSize`** | <code><a href="#getbundledownloadsizeresult">GetBundleDownloadSizeResult</a></code> | Estimated download size for missing manifest entries when {@link <a href="#getlatestoptions">GetLatestOptions.includeBundleSize</a>} is enabled. | 8.47.0 |
2492
+ | **`link`** | <code>string</code> | Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release). | 7.35.0 |
2493
+ | **`comment`** | <code>string</code> | Optional comment or description for this bundle version. | 7.35.0 |
2494
+
2495
+
2496
+ ##### GetMissingBundleFilesResult
2497
+
2498
+ | Prop | Type | Description | Since |
2499
+ | ------------------- | ---------------------------- | ----------------------------------------------------------------------- | ------ |
2500
+ | **`missing`** | <code>ManifestEntry[]</code> | Entries that are not available locally and need to be downloaded. | 8.47.0 |
2501
+ | **`total`** | <code>number</code> | Total entries in the provided manifest. | 8.47.0 |
2502
+ | **`missingCount`** | <code>number</code> | Number of entries that need to be downloaded. | 8.47.0 |
2503
+ | **`reusableCount`** | <code>number</code> | Number of entries that can be reused from builtin files or local cache. | 8.47.0 |
2504
+
2505
+
2506
+ ##### GetBundleDownloadSizeResult
2507
+
2508
+ | Prop | Type | Description | Since |
2509
+ | ------------------ | ----------------------------- | --------------------------------------------------- | ------ |
2510
+ | **`totalSize`** | <code>number</code> | Sum of all known file sizes in bytes. | 8.47.0 |
2511
+ | **`knownFiles`** | <code>number</code> | Number of files with a known size. | 8.47.0 |
2512
+ | **`unknownFiles`** | <code>number</code> | Number of files whose size could not be determined. | 8.47.0 |
2513
+ | **`files`** | <code>BundleFileSize[]</code> | Per-file size results. | 8.47.0 |
2514
+
2515
+
2516
+ ##### BundleFileSize
2517
+
2518
+ | Prop | Type | Description | Since |
2519
+ | ------------------ | --------------------------- | ----------------------------------------------------------- | ------ |
2520
+ | **`file_name`** | <code>string \| null</code> | File name from the manifest entry. | 8.47.0 |
2521
+ | **`file_hash`** | <code>string \| null</code> | File hash from the manifest entry. | 8.47.0 |
2522
+ | **`download_url`** | <code>string \| null</code> | Download URL from the manifest entry. | 8.47.0 |
2523
+ | **`size`** | <code>number</code> | Estimated bytes to download when the server exposes a size. | 8.47.0 |
2524
+ | **`error`** | <code>string</code> | Error for this entry when the size could not be determined. | 8.47.0 |
2061
2525
 
2062
2526
 
2063
2527
  ##### GetLatestOptions
2064
2528
 
2065
- | Prop | Type | Description | Default | Since |
2066
- | ------------- | ------------------- | ----------------------------------------------------------------------------------------------- | ---------------------- | ----- |
2067
- | **`channel`** | <code>string</code> | The channel to get the latest version for The channel must allow 'self_assign' for this to work | <code>undefined</code> | 6.8.0 |
2529
+ | Prop | Type | Description | Default | Since |
2530
+ | ----------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
2531
+ | **`channel`** | <code>string</code> | The channel to get the latest version for The channel must allow 'self_assign' for this to work | <code>undefined</code> | 6.8.0 |
2532
+ | **`appId`** | <code>string</code> | Temporarily use another app id for this update check while using a trusted preview container. This only changes the app id sent by this request; it does not persist a preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.47.0 |
2533
+ | **`includeBundleSize`** | <code>boolean</code> | When true, the native plugin computes which manifest files are missing on this device and asks the Capgo update endpoint for their stored sizes before resolving {@link getLatest}. This adds one backend request only when the update response contains a manifest. It does not perform per-file network checks. | <code>false</code> | 8.47.0 |
2534
+
2535
+
2536
+ ##### GetMissingBundleFilesOptions
2537
+
2538
+ | Prop | Type | Description | Since |
2539
+ | ---------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
2540
+ | **`manifest`** | <code>ManifestEntry[]</code> | Manifest returned by {@link getLatest}. Passing the full {@link <a href="#latestversion">LatestVersion</a>} response is supported because it contains this field. | 8.47.0 |
2541
+ | **`version`** | <code>string</code> | Target bundle version. Passing the full {@link <a href="#latestversion">LatestVersion</a>} response is supported because it contains this field. | 8.47.0 |
2542
+ | **`sessionKey`** | <code>string</code> | Session key returned by {@link getLatest}, required only when file hashes are encrypted. | 8.47.0 |
2543
+
2544
+
2545
+ ##### GetBundleDownloadSizeOptions
2546
+
2547
+ | Prop | Type | Description | Since |
2548
+ | -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
2549
+ | **`manifest`** | <code>ManifestEntry[]</code> | Manifest entries to estimate. Pass `missing.missing` from {@link getMissingBundleFiles} to estimate only the bytes this device still needs to download. | 8.47.0 |
2550
+ | **`version`** | <code>string</code> | Target bundle version. Pass `latest.version` when estimating files returned by {@link getLatest}. | 8.47.0 |
2068
2551
 
2069
2552
 
2070
2553
  ##### ChannelRes
@@ -2113,7 +2596,7 @@ If you don't use backend, you need to provide the URL and version of the bundle.
2113
2596
 
2114
2597
  | Prop | Type | Description | Since |
2115
2598
  | -------------------- | -------------------- | ----------------------------------------------- | ----- |
2116
- | **`id`** | <code>string</code> | The channel ID | 7.5.0 |
2599
+ | **`id`** | <code>number</code> | The channel ID | 7.5.0 |
2117
2600
  | **`name`** | <code>string</code> | The channel name | 7.5.0 |
2118
2601
  | **`public`** | <code>boolean</code> | Whether this is a public channel | 7.5.0 |
2119
2602
  | **`allow_self_set`** | <code>boolean</code> | Whether devices can self-assign to this channel | 7.5.0 |
@@ -2176,6 +2659,18 @@ If you don't use backend, you need to provide the URL and version of the bundle.
2176
2659
  | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Current status of download, between 0 and 100. | 4.0.0 |
2177
2660
 
2178
2661
 
2662
+ ##### UpdateCheckResultEvent
2663
+
2664
+ | Prop | Type | Description | Since |
2665
+ | ---------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------- |
2666
+ | **`kind`** | <code><a href="#updateresponsekind">UpdateResponseKind</a></code> | Classification for the update check result, provided by the backend. | 8.45.11 |
2667
+ | **`error`** | <code>string</code> | Backend error code, when provided. | 8.45.11 |
2668
+ | **`message`** | <code>string</code> | Backend message, when provided. | 8.45.11 |
2669
+ | **`statusCode`** | <code>number</code> | HTTP status code returned by the update endpoint. | 8.45.11 |
2670
+ | **`version`** | <code>string</code> | Version referenced by the update check result. | 8.45.11 |
2671
+ | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Current bundle on the device. | 8.45.11 |
2672
+
2673
+
2179
2674
  ##### UpdateAvailableEvent
2180
2675
 
2181
2676
  | Prop | Type | Description | Since |
@@ -2204,6 +2699,20 @@ If you don't use backend, you need to provide the URL and version of the bundle.
2204
2699
  | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a update failed to install. | 4.0.0 |
2205
2700
 
2206
2701
 
2702
+ ##### SetEvent
2703
+
2704
+ | Prop | Type | Description | Since |
2705
+ | ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------- |
2706
+ | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a bundle has been applied successfully. This event uses native `retainUntilConsumed` behavior. | 8.43.12 |
2707
+
2708
+
2709
+ ##### SetNextEvent
2710
+
2711
+ | Prop | Type | Description | Since |
2712
+ | ------------ | ------------------------------------------------- | ----------------------------------------------------------- | ------ |
2713
+ | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a bundle is queued as the next bundle to install. | 6.14.0 |
2714
+
2715
+
2207
2716
  ##### DownloadFailedEvent
2208
2717
 
2209
2718
  | Prop | Type | Description | Since |
@@ -2213,10 +2722,10 @@ If you don't use backend, you need to provide the URL and version of the bundle.
2213
2722
 
2214
2723
  ##### AppReadyEvent
2215
2724
 
2216
- | Prop | Type | Description | Since |
2217
- | ------------ | ------------------------------------------------- | ------------------------------------- | ----- |
2218
- | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emitted when the app is ready to use. | 5.2.0 |
2219
- | **`status`** | <code>string</code> | | |
2725
+ | Prop | Type | Description | Since |
2726
+ | ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----- |
2727
+ | **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emitted when the app is ready to use. This event uses native `retainUntilConsumed` behavior. | 5.2.0 |
2728
+ | **`status`** | <code>string</code> | | |
2220
2729
 
2221
2730
 
2222
2731
  ##### ChannelPrivateEvent
@@ -2254,9 +2763,10 @@ State information for flexible update progress (Android only).
2254
2763
 
2255
2764
  ##### ShakeMenuEnabled
2256
2765
 
2257
- | Prop | Type |
2258
- | ------------- | -------------------- |
2259
- | **`enabled`** | <code>boolean</code> |
2766
+ | Prop | Type | Description | Since |
2767
+ | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
2768
+ | **`enabled`** | <code>boolean</code> | | |
2769
+ | **`gesture`** | <code><a href="#shakemenugesture">ShakeMenuGesture</a></code> | The currently configured native gesture used to open the preview/channel menu. Undefined means consumers should treat the gesture as the default `shake` behavior. | 8.48.0 |
2260
2770
 
2261
2771
 
2262
2772
  ##### SetShakeChannelSelectorOptions
@@ -2353,6 +2863,15 @@ error: The bundle has failed to download.
2353
2863
  <code>'background' | 'kill' | 'nativeVersion' | 'date'</code>
2354
2864
 
2355
2865
 
2866
+ ##### UpdateResponseKind
2867
+
2868
+ Classification for update-check responses that do not provide a downloadable bundle.
2869
+ The update backend provides this field directly. Missing or unknown values are treated as
2870
+ failed by native clients.
2871
+
2872
+ <code>'up_to_date' | 'blocked' | 'failed'</code>
2873
+
2874
+
2356
2875
  ##### BreakingAvailableEvent
2357
2876
 
2358
2877
  Payload emitted by {@link CapacitorUpdaterPlugin.addListener} with `breakingAvailable`.
@@ -2360,6 +2879,15 @@ Payload emitted by {@link CapacitorUpdaterPlugin.addListener} with `breakingAvai
2360
2879
  <code><a href="#majoravailableevent">MajorAvailableEvent</a></code>
2361
2880
 
2362
2881
 
2882
+ ##### ShakeMenuGesture
2883
+
2884
+ Native gesture options that open the shake menu.
2885
+
2886
+ Supported values are `shake` and `threeFingerPinch`.
2887
+
2888
+ <code>'shake' | 'threeFingerPinch'</code>
2889
+
2890
+
2363
2891
  #### Enums
2364
2892
 
2365
2893