@capgo/capacitor-updater 8.0.1 → 8.2.0
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.
- package/CapgoCapacitorUpdater.podspec +7 -5
- package/Package.swift +9 -7
- package/README.md +984 -215
- package/android/build.gradle +24 -12
- package/android/proguard-rules.pro +22 -5
- package/android/src/main/java/ee/forgr/capacitor_updater/BundleInfo.java +110 -22
- package/android/src/main/java/ee/forgr/capacitor_updater/Callback.java +2 -2
- package/android/src/main/java/ee/forgr/capacitor_updater/CapacitorUpdaterPlugin.java +1316 -489
- package/android/src/main/java/ee/forgr/capacitor_updater/{CapacitorUpdater.java → CapgoUpdater.java} +662 -203
- package/android/src/main/java/ee/forgr/capacitor_updater/{CryptoCipherV2.java → CryptoCipher.java} +138 -33
- package/android/src/main/java/ee/forgr/capacitor_updater/DelayCondition.java +0 -3
- package/android/src/main/java/ee/forgr/capacitor_updater/DelayUpdateUtils.java +260 -0
- package/android/src/main/java/ee/forgr/capacitor_updater/DeviceIdHelper.java +221 -0
- package/android/src/main/java/ee/forgr/capacitor_updater/DownloadService.java +497 -133
- package/android/src/main/java/ee/forgr/capacitor_updater/DownloadWorkerManager.java +80 -25
- package/android/src/main/java/ee/forgr/capacitor_updater/Logger.java +338 -0
- package/android/src/main/java/ee/forgr/capacitor_updater/ShakeDetector.java +72 -0
- package/android/src/main/java/ee/forgr/capacitor_updater/ShakeMenu.java +169 -0
- package/dist/docs.json +873 -154
- package/dist/esm/definitions.d.ts +881 -114
- package/dist/esm/definitions.js.map +1 -1
- package/dist/esm/history.d.ts +1 -0
- package/dist/esm/history.js +283 -0
- package/dist/esm/history.js.map +1 -0
- package/dist/esm/index.d.ts +1 -0
- package/dist/esm/index.js +1 -0
- package/dist/esm/index.js.map +1 -1
- package/dist/esm/web.d.ts +12 -1
- package/dist/esm/web.js +29 -2
- package/dist/esm/web.js.map +1 -1
- package/dist/plugin.cjs.js +311 -2
- package/dist/plugin.cjs.js.map +1 -1
- package/dist/plugin.js +311 -2
- package/dist/plugin.js.map +1 -1
- package/ios/Sources/CapacitorUpdaterPlugin/AES.swift +69 -0
- package/ios/Sources/CapacitorUpdaterPlugin/BigInt.swift +55 -0
- package/ios/{Plugin → Sources/CapacitorUpdaterPlugin}/BundleInfo.swift +37 -10
- package/ios/{Plugin → Sources/CapacitorUpdaterPlugin}/BundleStatus.swift +1 -1
- package/ios/Sources/CapacitorUpdaterPlugin/CapacitorUpdaterPlugin.swift +1610 -0
- package/ios/{Plugin/CapacitorUpdater.swift → Sources/CapacitorUpdaterPlugin/CapgoUpdater.swift} +541 -231
- package/ios/Sources/CapacitorUpdaterPlugin/CryptoCipher.swift +286 -0
- package/ios/Sources/CapacitorUpdaterPlugin/DelayUpdateUtils.swift +220 -0
- package/ios/Sources/CapacitorUpdaterPlugin/DeviceIdHelper.swift +120 -0
- package/ios/{Plugin → Sources/CapacitorUpdaterPlugin}/InternalUtils.swift +54 -0
- package/ios/Sources/CapacitorUpdaterPlugin/Logger.swift +310 -0
- package/ios/Sources/CapacitorUpdaterPlugin/RSA.swift +274 -0
- package/ios/Sources/CapacitorUpdaterPlugin/ShakeMenu.swift +112 -0
- package/ios/{Plugin → Sources/CapacitorUpdaterPlugin}/UserDefaultsExtension.swift +0 -2
- package/package.json +21 -19
- package/ios/Plugin/CapacitorUpdaterPlugin.swift +0 -975
- package/ios/Plugin/CryptoCipherV2.swift +0 -310
- /package/{LICENCE → LICENSE} +0 -0
- /package/ios/{Plugin → Sources/CapacitorUpdaterPlugin}/DelayCondition.swift +0 -0
- /package/ios/{Plugin → Sources/CapacitorUpdaterPlugin}/DelayUntilNext.swift +0 -0
- /package/ios/{Plugin → Sources/CapacitorUpdaterPlugin}/Info.plist +0 -0
package/README.md
CHANGED
|
@@ -16,36 +16,80 @@
|
|
|
16
16
|
[](https://console.algora.io/org/Capgo/bounties?status=completed)
|
|
17
17
|
|
|
18
18
|
<div align="center">
|
|
19
|
-
<h2><a href="https://capgo.app/?ref=
|
|
20
|
-
<h2><a href="https://capgo.app/consulting/?ref=
|
|
19
|
+
<h2><a href="https://capgo.app/?ref=plugin_updater_v7"> ➡️ Get Instant updates for your App with Capgo</a></h2>
|
|
20
|
+
<h2><a href="https://capgo.app/consulting/?ref=plugin_updater_v7"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
|
|
21
21
|
</div>
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
Capacitor plugin to update your app remotely in real-time.
|
|
24
|
+
|
|
25
|
+
Open-source Alternative to Appflow, Codepush or Capawesome
|
|
26
|
+
|
|
27
|
+
## Why Capacitor Updater?
|
|
28
|
+
|
|
29
|
+
App store review processes can take days or weeks, blocking critical bug fixes and updates from reaching your users. Capacitor Updater solves this by:
|
|
30
|
+
|
|
31
|
+
- **Instant updates** - Push JavaScript/HTML/CSS updates directly to users without app store review
|
|
32
|
+
- **Delta updates** - Only download changed files, making updates ultra-fast
|
|
33
|
+
- **Rollback protection** - Automatically revert broken updates to keep your app stable
|
|
34
|
+
- **Open source** - Self-host or use Capgo Cloud, with full control over your update infrastructure
|
|
35
|
+
- **Battle-tested** - Used by 3000+ production apps with proven reliability
|
|
36
|
+
- **Most stared** - Capacitor updater is the most stared Capacitor plugin on GitHub
|
|
37
|
+
|
|
38
|
+
Perfect for fixing bugs immediately, A/B testing features, and maintaining control over your release schedule.
|
|
39
|
+
|
|
40
|
+
## Features
|
|
41
|
+
|
|
42
|
+
- ☁️ Cloud / Self hosted Support: Use our [Cloud](https://capgo.app/) to manage your app updates or yours.
|
|
43
|
+
- 📦 Bundle Management: Download, assign to channel, rollback.
|
|
44
|
+
- 📺 Channel Support: Use channels to manage different environments.
|
|
45
|
+
- 🎯 Set Channel to specific device to do QA or debug one user.
|
|
46
|
+
- 🔄 Auto Update: Automatically download and set the latest bundle for the app.
|
|
47
|
+
- 🛟 Rollback: Reset the app to last working bundle if an incompatible bundle has been set.
|
|
48
|
+
- 🔁 **Delta Updates**: Make instant updates by only downloading changed files.
|
|
49
|
+
- 🔒 **Security**: Encrypt and sign each updates with best in class security standards.
|
|
50
|
+
- ⚔️ **Battle-Tested**: Used in more than 3000 projects.
|
|
51
|
+
- 📊 View your deployment statistics
|
|
52
|
+
- 🔋 Supports Android and iOS
|
|
53
|
+
- ⚡️ Capacitor 6/7 support
|
|
54
|
+
- 🌐 **Open Source**: Licensed under the Mozilla Public License 2.0
|
|
55
|
+
- 🌐 **Open Source Backend**: Self install [our backend](https://github.com/Cap-go/capgo) in your infra
|
|
56
|
+
|
|
24
57
|
|
|
25
58
|
You have 3 ways possible :
|
|
26
59
|
- Use [capgo.app](https://capgo.app) a full featured auto-update system in 5 min Setup, to manage version, update, revert and see stats.
|
|
27
60
|
- Use your own server update with auto-update system
|
|
28
61
|
- Use manual methods to zip, upload, download, from JS to do it when you want.
|
|
29
62
|
|
|
63
|
+
## Documentation
|
|
64
|
+
The most complete [documentation here](https://capgo.app/docs/).
|
|
30
65
|
|
|
31
66
|
## Community
|
|
32
67
|
Join the [discord](https://discord.gg/VnYRvBfgA6) to get help.
|
|
33
68
|
|
|
34
|
-
##
|
|
35
|
-
|
|
69
|
+
## Migration to v8
|
|
70
|
+
|
|
71
|
+
## Migration to v7.34
|
|
72
|
+
|
|
73
|
+
- **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.
|
|
74
|
+
- Channel assignments persist between app restarts
|
|
75
|
+
- Use `unsetChannel()` to clear the local assignment and revert to `defaultChannel`
|
|
76
|
+
- Old devices (< v7.34.0) will continue using cloud-based storage
|
|
77
|
+
- **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.
|
|
36
78
|
|
|
37
79
|
## Migration to v7
|
|
38
80
|
|
|
39
|
-
|
|
40
|
-
|
|
81
|
+
The min version of IOS is now 15.5 instead of 15 as Capacitor 8 requirement.
|
|
82
|
+
This is due to bump of ZipArchive to latest, a key dependency of this project is the zlib library. zlib before version 1.2.12 allows memory corruption when deflating (i.e., when compressing) if the input has many distant matches according to [CVE-2018-25032](https://nvd.nist.gov/vuln/detail/cve-2018-25032).
|
|
83
|
+
zlib is a native library so we need to bump the minimum iOS version to 15.5 as ZipArchive did the same in their latest versions.
|
|
41
84
|
|
|
42
85
|
## Compatibility
|
|
43
86
|
|
|
44
87
|
| Plugin version | Capacitor compatibility | Maintained |
|
|
45
88
|
| -------------- | ----------------------- | ----------------- |
|
|
89
|
+
| v8.\*.\* | v8.\*.\* | Beta |
|
|
46
90
|
| v7.\*.\* | v7.\*.\* | ✅ |
|
|
47
|
-
| v6.\*.\* | v6.\*.\* |
|
|
48
|
-
| v5.\*.\* | v5.\*.\* |
|
|
91
|
+
| v6.\*.\* | v6.\*.\* | ✅ |
|
|
92
|
+
| v5.\*.\* | v5.\*.\* | ⚠️ Deprecated |
|
|
49
93
|
| v4.\*.\* | v4.\*.\* | ⚠️ Deprecated |
|
|
50
94
|
| v3.\*.\* | v3.\*.\* | ⚠️ Deprecated |
|
|
51
95
|
| > 7 | v4.\*.\* | ⚠️ Deprecated, our CI got crazy and bumped too much version |
|
|
@@ -81,6 +125,10 @@ We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bun
|
|
|
81
125
|
|
|
82
126
|
## Installation
|
|
83
127
|
|
|
128
|
+
Step by step here: [Getting started](https://capgo.app/docs/getting-started/add-an-app/)
|
|
129
|
+
|
|
130
|
+
Or
|
|
131
|
+
|
|
84
132
|
```bash
|
|
85
133
|
npm install @capgo/capacitor-updater
|
|
86
134
|
npx cap sync
|
|
@@ -88,14 +136,14 @@ npx cap sync
|
|
|
88
136
|
|
|
89
137
|
## Auto-update setup
|
|
90
138
|
|
|
91
|
-
Create your account in [capgo.app](https://capgo.app) and get your [API key](https://
|
|
139
|
+
Create your account in [capgo.app](https://capgo.app) and get your [API key](https://console.capgo.app/dashboard/apikeys)
|
|
92
140
|
- Login to CLI `npx @capgo/cli@latest init API_KEY`
|
|
93
141
|
And follow the steps by step to setup your app.
|
|
94
142
|
|
|
95
143
|
For detailed instructions on the auto-update setup, refer to the [Auto update documentation](https://capgo.app/docs/plugin/cloud-mode/getting-started/).
|
|
96
144
|
|
|
97
145
|
|
|
98
|
-
##
|
|
146
|
+
## No Cloud setup
|
|
99
147
|
|
|
100
148
|
Download update distribution zipfiles from a custom URL. Manually control the entire update process.
|
|
101
149
|
|
|
@@ -117,10 +165,11 @@ Download update distribution zipfiles from a custom URL. Manually control the en
|
|
|
117
165
|
import { CapacitorUpdater } from '@capgo/capacitor-updater'
|
|
118
166
|
CapacitorUpdater.notifyAppReady()
|
|
119
167
|
```
|
|
120
|
-
This informs Capacitor Updater that the current update bundle has loaded
|
|
168
|
+
This informs Capacitor Updater that the current update bundle has loaded successfully. Failing to call this method will cause your application to be rolled back to the previously successful version (or built-in bundle).
|
|
121
169
|
- Add this to your application.
|
|
122
170
|
```javascript
|
|
123
171
|
const version = await CapacitorUpdater.download({
|
|
172
|
+
version: '0.0.4',
|
|
124
173
|
url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
|
|
125
174
|
})
|
|
126
175
|
await CapacitorUpdater.set(version); // sets the new version, and reloads the app
|
|
@@ -138,6 +187,7 @@ You might also consider performing auto-update when application state changes, a
|
|
|
138
187
|
if (state.isActive) {
|
|
139
188
|
// Ensure download occurs while the app is active, or download may fail
|
|
140
189
|
version = await CapacitorUpdater.download({
|
|
190
|
+
version: '0.0.4',
|
|
141
191
|
url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
|
|
142
192
|
})
|
|
143
193
|
}
|
|
@@ -203,32 +253,42 @@ Capacitor Updater works by unzipping a compiled app bundle to the native device
|
|
|
203
253
|
|
|
204
254
|
CapacitorUpdater can be configured with these options:
|
|
205
255
|
|
|
206
|
-
| Prop
|
|
207
|
-
|
|
|
208
|
-
| **`appReadyTimeout`**
|
|
209
|
-
| **`responseTimeout`**
|
|
210
|
-
| **`autoDeleteFailed`**
|
|
211
|
-
| **`autoDeletePrevious`**
|
|
212
|
-
| **`autoUpdate`**
|
|
213
|
-
| **`resetWhenUpdate`**
|
|
214
|
-
| **`updateUrl`**
|
|
215
|
-
| **`channelUrl`**
|
|
216
|
-
| **`statsUrl`**
|
|
217
|
-
| **`publicKey`**
|
|
218
|
-
| **`version`**
|
|
219
|
-
| **`directUpdate`**
|
|
220
|
-
| **`
|
|
221
|
-
| **`
|
|
222
|
-
| **`
|
|
223
|
-
| **`
|
|
224
|
-
| **`
|
|
225
|
-
| **`
|
|
226
|
-
| **`
|
|
227
|
-
| **`
|
|
228
|
-
| **`
|
|
229
|
-
| **`
|
|
230
|
-
| **`
|
|
231
|
-
| **`
|
|
256
|
+
| Prop | Type | Description | Default | Since |
|
|
257
|
+
| ----------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------- |
|
|
258
|
+
| **`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> | |
|
|
259
|
+
| **`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> | |
|
|
260
|
+
| **`autoDeleteFailed`** | <code>boolean</code> | Configure whether the plugin should use automatically delete failed bundles. Only available for Android and iOS. | <code>true</code> | |
|
|
261
|
+
| **`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> | |
|
|
262
|
+
| **`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> | |
|
|
263
|
+
| **`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> | |
|
|
264
|
+
| **`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> | |
|
|
265
|
+
| **`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> | |
|
|
266
|
+
| **`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> | |
|
|
267
|
+
| **`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 |
|
|
268
|
+
| **`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 |
|
|
269
|
+
| **`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 --partial 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 Only available for Android and iOS. | <code>false</code> | 5.1.0 |
|
|
270
|
+
| **`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 |
|
|
271
|
+
| **`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 |
|
|
272
|
+
| **`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 |
|
|
273
|
+
| **`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> | |
|
|
274
|
+
| **`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 |
|
|
275
|
+
| **`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 |
|
|
276
|
+
| **`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 |
|
|
277
|
+
| **`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 |
|
|
278
|
+
| **`localSupaAnon`** | <code>string</code> | Configure the CLI to use a local server for testing. | <code>undefined</code> | 4.17.48 |
|
|
279
|
+
| **`localApi`** | <code>string</code> | Configure the CLI to use a local api for testing. | <code>undefined</code> | 6.3.3 |
|
|
280
|
+
| **`localApiFiles`** | <code>string</code> | Configure the CLI to use a local file api for testing. | <code>undefined</code> | 6.3.3 |
|
|
281
|
+
| **`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 |
|
|
282
|
+
| **`allowModifyAppId`** | <code>boolean</code> | Allow the plugin to modify the appId dynamically from the JavaScript side. | <code>false</code> | 7.14.0 |
|
|
283
|
+
| **`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 |
|
|
284
|
+
| **`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 |
|
|
285
|
+
| **`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 |
|
|
286
|
+
| **`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 |
|
|
287
|
+
| **`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 |
|
|
288
|
+
| **`appId`** | <code>string</code> | Configure the app id for the app in the config. | <code>undefined</code> | 6.0.0 |
|
|
289
|
+
| **`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 |
|
|
290
|
+
| **`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 |
|
|
291
|
+
| **`shakeMenu`** | <code>boolean</code> | Enable shake gesture to show update menu for debugging/testing purposes | <code>false</code> | 7.5.0 |
|
|
232
292
|
|
|
233
293
|
### Examples
|
|
234
294
|
|
|
@@ -250,7 +310,10 @@ In `capacitor.config.json`:
|
|
|
250
310
|
"publicKey": undefined,
|
|
251
311
|
"version": undefined,
|
|
252
312
|
"directUpdate": undefined,
|
|
253
|
-
"
|
|
313
|
+
"autoSplashscreen": undefined,
|
|
314
|
+
"autoSplashscreenLoader": undefined,
|
|
315
|
+
"autoSplashscreenTimeout": undefined,
|
|
316
|
+
"periodCheckDelay": 3600 (1 hour),
|
|
254
317
|
"localS3": undefined,
|
|
255
318
|
"localHost": undefined,
|
|
256
319
|
"localWebHost": undefined,
|
|
@@ -259,9 +322,16 @@ In `capacitor.config.json`:
|
|
|
259
322
|
"localApi": undefined,
|
|
260
323
|
"localApiFiles": undefined,
|
|
261
324
|
"allowModifyUrl": undefined,
|
|
325
|
+
"allowModifyAppId": undefined,
|
|
326
|
+
"allowManualBundleError": undefined,
|
|
327
|
+
"persistCustomId": undefined,
|
|
328
|
+
"persistModifyUrl": undefined,
|
|
329
|
+
"allowSetDefaultChannel": undefined,
|
|
262
330
|
"defaultChannel": undefined,
|
|
263
331
|
"appId": undefined,
|
|
264
|
-
"keepUrlPathAfterReload": undefined
|
|
332
|
+
"keepUrlPathAfterReload": undefined,
|
|
333
|
+
"disableJSLogging": undefined,
|
|
334
|
+
"shakeMenu": undefined
|
|
265
335
|
}
|
|
266
336
|
}
|
|
267
337
|
}
|
|
@@ -289,7 +359,10 @@ const config: CapacitorConfig = {
|
|
|
289
359
|
publicKey: undefined,
|
|
290
360
|
version: undefined,
|
|
291
361
|
directUpdate: undefined,
|
|
292
|
-
|
|
362
|
+
autoSplashscreen: undefined,
|
|
363
|
+
autoSplashscreenLoader: undefined,
|
|
364
|
+
autoSplashscreenTimeout: undefined,
|
|
365
|
+
periodCheckDelay: 3600 (1 hour),
|
|
293
366
|
localS3: undefined,
|
|
294
367
|
localHost: undefined,
|
|
295
368
|
localWebHost: undefined,
|
|
@@ -298,9 +371,16 @@ const config: CapacitorConfig = {
|
|
|
298
371
|
localApi: undefined,
|
|
299
372
|
localApiFiles: undefined,
|
|
300
373
|
allowModifyUrl: undefined,
|
|
374
|
+
allowModifyAppId: undefined,
|
|
375
|
+
allowManualBundleError: undefined,
|
|
376
|
+
persistCustomId: undefined,
|
|
377
|
+
persistModifyUrl: undefined,
|
|
378
|
+
allowSetDefaultChannel: undefined,
|
|
301
379
|
defaultChannel: undefined,
|
|
302
380
|
appId: undefined,
|
|
303
381
|
keepUrlPathAfterReload: undefined,
|
|
382
|
+
disableJSLogging: undefined,
|
|
383
|
+
shakeMenu: undefined,
|
|
304
384
|
},
|
|
305
385
|
},
|
|
306
386
|
};
|
|
@@ -313,6 +393,7 @@ export default config;
|
|
|
313
393
|
## API
|
|
314
394
|
|
|
315
395
|
<docgen-index>
|
|
396
|
+
<!--Auto-generated, compact index-->
|
|
316
397
|
|
|
317
398
|
* [`notifyAppReady()`](#notifyappready)
|
|
318
399
|
* [`setUpdateUrl(...)`](#setupdateurl)
|
|
@@ -322,6 +403,7 @@ export default config;
|
|
|
322
403
|
* [`next(...)`](#next)
|
|
323
404
|
* [`set(...)`](#set)
|
|
324
405
|
* [`delete(...)`](#delete)
|
|
406
|
+
* [`setBundleError(...)`](#setbundleerror)
|
|
325
407
|
* [`list(...)`](#list)
|
|
326
408
|
* [`reset(...)`](#reset)
|
|
327
409
|
* [`current()`](#current)
|
|
@@ -332,6 +414,7 @@ export default config;
|
|
|
332
414
|
* [`setChannel(...)`](#setchannel)
|
|
333
415
|
* [`unsetChannel(...)`](#unsetchannel)
|
|
334
416
|
* [`getChannel()`](#getchannel)
|
|
417
|
+
* [`listChannels()`](#listchannels)
|
|
335
418
|
* [`setCustomId(...)`](#setcustomid)
|
|
336
419
|
* [`getBuiltinVersion()`](#getbuiltinversion)
|
|
337
420
|
* [`getDeviceId()`](#getdeviceid)
|
|
@@ -342,13 +425,20 @@ export default config;
|
|
|
342
425
|
* [`addListener('noNeedUpdate', ...)`](#addlistenernoneedupdate-)
|
|
343
426
|
* [`addListener('updateAvailable', ...)`](#addlistenerupdateavailable-)
|
|
344
427
|
* [`addListener('downloadComplete', ...)`](#addlistenerdownloadcomplete-)
|
|
428
|
+
* [`addListener('breakingAvailable', ...)`](#addlistenerbreakingavailable-)
|
|
345
429
|
* [`addListener('majorAvailable', ...)`](#addlistenermajoravailable-)
|
|
346
430
|
* [`addListener('updateFailed', ...)`](#addlistenerupdatefailed-)
|
|
347
431
|
* [`addListener('downloadFailed', ...)`](#addlistenerdownloadfailed-)
|
|
348
432
|
* [`addListener('appReloaded', ...)`](#addlistenerappreloaded-)
|
|
349
433
|
* [`addListener('appReady', ...)`](#addlistenerappready-)
|
|
434
|
+
* [`addListener('channelPrivate', ...)`](#addlistenerchannelprivate-)
|
|
350
435
|
* [`isAutoUpdateAvailable()`](#isautoupdateavailable)
|
|
351
436
|
* [`getNextBundle()`](#getnextbundle)
|
|
437
|
+
* [`getFailedUpdate()`](#getfailedupdate)
|
|
438
|
+
* [`setShakeMenu(...)`](#setshakemenu)
|
|
439
|
+
* [`isShakeMenuEnabled()`](#isshakemenuenabled)
|
|
440
|
+
* [`getAppId()`](#getappid)
|
|
441
|
+
* [`setAppId(...)`](#setappid)
|
|
352
442
|
* [Interfaces](#interfaces)
|
|
353
443
|
* [Type Aliases](#type-aliases)
|
|
354
444
|
|
|
@@ -357,79 +447,133 @@ export default config;
|
|
|
357
447
|
<docgen-api>
|
|
358
448
|
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
|
|
359
449
|
|
|
360
|
-
|
|
450
|
+
#### notifyAppReady()
|
|
361
451
|
|
|
362
452
|
```typescript
|
|
363
453
|
notifyAppReady() => Promise<AppReadyResult>
|
|
364
454
|
```
|
|
365
455
|
|
|
366
|
-
Notify
|
|
367
|
-
|
|
368
|
-
|
|
456
|
+
Notify the native layer that JavaScript initialized successfully.
|
|
457
|
+
|
|
458
|
+
**CRITICAL: You must call this method on every app launch to prevent automatic rollback.**
|
|
459
|
+
|
|
460
|
+
This is a simple notification to confirm that your bundle's JavaScript loaded and executed.
|
|
461
|
+
The native web server successfully served the bundle files and your JS runtime started.
|
|
462
|
+
That's all it checks - nothing more complex.
|
|
463
|
+
|
|
464
|
+
**What triggers rollback:**
|
|
465
|
+
- NOT calling this method within the timeout (default: 10 seconds)
|
|
466
|
+
- Complete JavaScript failure (bundle won't load at all)
|
|
467
|
+
|
|
468
|
+
**What does NOT trigger rollback:**
|
|
469
|
+
- Runtime errors after initialization (API failures, crashes, etc.)
|
|
470
|
+
- Network request failures
|
|
471
|
+
- Application logic errors
|
|
472
|
+
|
|
473
|
+
**IMPORTANT: Call this BEFORE any network requests.**
|
|
474
|
+
Don't wait for APIs, data loading, or async operations. Call it as soon as your
|
|
475
|
+
JavaScript bundle starts executing to confirm the bundle itself is valid.
|
|
476
|
+
|
|
477
|
+
Best practices:
|
|
478
|
+
- Call immediately in your app entry point (main.js, app component mount, etc.)
|
|
479
|
+
- Don't put it after network calls or heavy initialization
|
|
480
|
+
- Don't wrap it in try/catch with conditions
|
|
481
|
+
- Adjust {@link PluginsConfig.CapacitorUpdater.appReadyTimeout} if you need more time
|
|
369
482
|
|
|
370
483
|
**Returns:** <code>Promise<<a href="#appreadyresult">AppReadyResult</a>></code>
|
|
371
484
|
|
|
372
485
|
--------------------
|
|
373
486
|
|
|
374
487
|
|
|
375
|
-
|
|
488
|
+
#### setUpdateUrl(...)
|
|
376
489
|
|
|
377
490
|
```typescript
|
|
378
491
|
setUpdateUrl(options: UpdateUrl) => Promise<void>
|
|
379
492
|
```
|
|
380
493
|
|
|
381
|
-
Set the
|
|
494
|
+
Set the update URL for the app dynamically at runtime.
|
|
495
|
+
|
|
496
|
+
This overrides the {@link PluginsConfig.CapacitorUpdater.updateUrl} config value.
|
|
497
|
+
Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.
|
|
498
|
+
|
|
499
|
+
Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
|
|
500
|
+
Otherwise, the URL will reset to the config value on next app launch.
|
|
382
501
|
|
|
383
502
|
| Param | Type | Description |
|
|
384
503
|
| ------------- | ----------------------------------------------- | ------------------------------------------------- |
|
|
385
|
-
| **`options`** | <code><a href="#updateurl">UpdateUrl</a></code> |
|
|
504
|
+
| **`options`** | <code><a href="#updateurl">UpdateUrl</a></code> | Contains the URL to use for checking for updates. |
|
|
386
505
|
|
|
387
506
|
**Since:** 5.4.0
|
|
388
507
|
|
|
389
508
|
--------------------
|
|
390
509
|
|
|
391
510
|
|
|
392
|
-
|
|
511
|
+
#### setStatsUrl(...)
|
|
393
512
|
|
|
394
513
|
```typescript
|
|
395
514
|
setStatsUrl(options: StatsUrl) => Promise<void>
|
|
396
515
|
```
|
|
397
516
|
|
|
398
|
-
Set the
|
|
517
|
+
Set the statistics URL for the app dynamically at runtime.
|
|
518
|
+
|
|
519
|
+
This overrides the {@link PluginsConfig.CapacitorUpdater.statsUrl} config value.
|
|
520
|
+
Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.
|
|
399
521
|
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
522
|
+
Pass an empty string to disable statistics gathering entirely.
|
|
523
|
+
Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
|
|
524
|
+
|
|
525
|
+
| Param | Type | Description |
|
|
526
|
+
| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
527
|
+
| **`options`** | <code><a href="#statsurl">StatsUrl</a></code> | Contains the URL to use for sending statistics, or an empty string to disable. |
|
|
403
528
|
|
|
404
529
|
**Since:** 5.4.0
|
|
405
530
|
|
|
406
531
|
--------------------
|
|
407
532
|
|
|
408
533
|
|
|
409
|
-
|
|
534
|
+
#### setChannelUrl(...)
|
|
410
535
|
|
|
411
536
|
```typescript
|
|
412
537
|
setChannelUrl(options: ChannelUrl) => Promise<void>
|
|
413
538
|
```
|
|
414
539
|
|
|
415
|
-
Set the
|
|
540
|
+
Set the channel URL for the app dynamically at runtime.
|
|
541
|
+
|
|
542
|
+
This overrides the {@link PluginsConfig.CapacitorUpdater.channelUrl} config value.
|
|
543
|
+
Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.
|
|
416
544
|
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
545
|
+
Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
|
|
546
|
+
Otherwise, the URL will reset to the config value on next app launch.
|
|
547
|
+
|
|
548
|
+
| Param | Type | Description |
|
|
549
|
+
| ------------- | ------------------------------------------------- | ----------------------------------------------- |
|
|
550
|
+
| **`options`** | <code><a href="#channelurl">ChannelUrl</a></code> | Contains the URL to use for channel operations. |
|
|
420
551
|
|
|
421
552
|
**Since:** 5.4.0
|
|
422
553
|
|
|
423
554
|
--------------------
|
|
424
555
|
|
|
425
556
|
|
|
426
|
-
|
|
557
|
+
#### download(...)
|
|
427
558
|
|
|
428
559
|
```typescript
|
|
429
560
|
download(options: DownloadOptions) => Promise<BundleInfo>
|
|
430
561
|
```
|
|
431
562
|
|
|
432
|
-
Download a new bundle from the provided URL
|
|
563
|
+
Download a new bundle from the provided URL for later installation.
|
|
564
|
+
|
|
565
|
+
The downloaded bundle is stored locally but not activated. To use it:
|
|
566
|
+
- Call {@link next} to set it for installation on next app backgrounding/restart
|
|
567
|
+
- Call {@link set} to activate it immediately (destroys current JavaScript context)
|
|
568
|
+
|
|
569
|
+
The URL should point to a zip file containing either:
|
|
570
|
+
- Your app files directly in the zip root, or
|
|
571
|
+
- A single folder containing all your app files
|
|
572
|
+
|
|
573
|
+
The bundle must include an `index.html` file at the root level.
|
|
574
|
+
|
|
575
|
+
For encrypted bundles, provide the `sessionKey` and `checksum` parameters.
|
|
576
|
+
For multi-file partial updates, provide the `manifest` array.
|
|
433
577
|
|
|
434
578
|
| Param | Type | Description |
|
|
435
579
|
| ------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
@@ -440,24 +584,35 @@ Download a new bundle from the provided URL, it should be a zip file, with files
|
|
|
440
584
|
--------------------
|
|
441
585
|
|
|
442
586
|
|
|
443
|
-
|
|
587
|
+
#### next(...)
|
|
444
588
|
|
|
445
589
|
```typescript
|
|
446
590
|
next(options: BundleId) => Promise<BundleInfo>
|
|
447
591
|
```
|
|
448
592
|
|
|
449
|
-
Set the next bundle to be
|
|
593
|
+
Set the next bundle to be activated when the app backgrounds or restarts.
|
|
594
|
+
|
|
595
|
+
This is the recommended way to apply updates as it doesn't interrupt the user's current session.
|
|
596
|
+
The bundle will be activated when:
|
|
597
|
+
- The app is backgrounded (user switches away), or
|
|
598
|
+
- The app is killed and relaunched, or
|
|
599
|
+
- {@link reload} is called manually
|
|
600
|
+
|
|
601
|
+
Unlike {@link set}, this method does NOT destroy the current JavaScript context immediately.
|
|
602
|
+
Your app continues running normally until one of the above events occurs.
|
|
450
603
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
|
604
|
+
Use {@link setMultiDelay} to add additional conditions before the update is applied.
|
|
605
|
+
|
|
606
|
+
| Param | Type | Description |
|
|
607
|
+
| ------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
608
|
+
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | Contains the ID of the bundle to set as next. Use {@link <a href="#bundleinfo">BundleInfo.id</a>} from a downloaded bundle. |
|
|
454
609
|
|
|
455
610
|
**Returns:** <code>Promise<<a href="#bundleinfo">BundleInfo</a>></code>
|
|
456
611
|
|
|
457
612
|
--------------------
|
|
458
613
|
|
|
459
614
|
|
|
460
|
-
|
|
615
|
+
#### set(...)
|
|
461
616
|
|
|
462
617
|
```typescript
|
|
463
618
|
set(options: BundleId) => Promise<void>
|
|
@@ -465,6 +620,22 @@ set(options: BundleId) => Promise<void>
|
|
|
465
620
|
|
|
466
621
|
Set the current bundle and immediately reloads the app.
|
|
467
622
|
|
|
623
|
+
**IMPORTANT: This is a terminal operation that destroys the current JavaScript context.**
|
|
624
|
+
|
|
625
|
+
When you call this method:
|
|
626
|
+
- The entire JavaScript context is immediately destroyed
|
|
627
|
+
- The app reloads from a different folder with different files
|
|
628
|
+
- NO code after this call will execute
|
|
629
|
+
- NO promises will resolve
|
|
630
|
+
- NO callbacks will fire
|
|
631
|
+
- Event listeners registered after this call are unreliable and may never fire
|
|
632
|
+
|
|
633
|
+
The reload happens automatically - you don't need to do anything else.
|
|
634
|
+
If you need to preserve state like the current URL path, use the {@link PluginsConfig.CapacitorUpdater.keepUrlPathAfterReload} config option.
|
|
635
|
+
For other state preservation needs, save your data before calling this method (e.g., to localStorage).
|
|
636
|
+
|
|
637
|
+
**Do not** try to execute additional logic after calling `set()` - it won't work as expected.
|
|
638
|
+
|
|
468
639
|
| Param | Type | Description |
|
|
469
640
|
| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
470
641
|
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the new bundle id to set as current. |
|
|
@@ -472,124 +643,273 @@ Set the current bundle and immediately reloads the app.
|
|
|
472
643
|
--------------------
|
|
473
644
|
|
|
474
645
|
|
|
475
|
-
|
|
646
|
+
#### delete(...)
|
|
476
647
|
|
|
477
648
|
```typescript
|
|
478
649
|
delete(options: BundleId) => Promise<void>
|
|
479
650
|
```
|
|
480
651
|
|
|
481
|
-
|
|
652
|
+
Delete a bundle from local storage to free up disk space.
|
|
653
|
+
|
|
654
|
+
You cannot delete:
|
|
655
|
+
- The currently active bundle
|
|
656
|
+
- The `builtin` bundle (the version shipped with your app)
|
|
657
|
+
- The bundle set as `next` (call {@link next} with a different bundle first)
|
|
658
|
+
|
|
659
|
+
Use {@link list} to get all available bundle IDs.
|
|
482
660
|
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
661
|
+
**Note:** The bundle ID is NOT the same as the version name.
|
|
662
|
+
Use the `id` field from {@link <a href="#bundleinfo">BundleInfo</a>}, not the `version` field.
|
|
663
|
+
|
|
664
|
+
| Param | Type | Description |
|
|
665
|
+
| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
666
|
+
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the bundle ID to delete. |
|
|
486
667
|
|
|
487
668
|
--------------------
|
|
488
669
|
|
|
489
670
|
|
|
490
|
-
|
|
671
|
+
#### setBundleError(...)
|
|
672
|
+
|
|
673
|
+
```typescript
|
|
674
|
+
setBundleError(options: BundleId) => Promise<BundleInfo>
|
|
675
|
+
```
|
|
676
|
+
|
|
677
|
+
Manually mark a bundle as failed/errored in manual update mode.
|
|
678
|
+
|
|
679
|
+
This is useful when you detect that a bundle has critical issues and want to prevent
|
|
680
|
+
it from being used again. The bundle status will be changed to `error` and the plugin
|
|
681
|
+
will avoid using this bundle in the future.
|
|
682
|
+
|
|
683
|
+
**Requirements:**
|
|
684
|
+
- {@link PluginsConfig.CapacitorUpdater.allowManualBundleError} must be set to `true`
|
|
685
|
+
- Only works in manual update mode (when autoUpdate is disabled)
|
|
686
|
+
|
|
687
|
+
Common use case: After downloading and testing a bundle, you discover it has critical
|
|
688
|
+
bugs and want to mark it as failed so it won't be retried.
|
|
689
|
+
|
|
690
|
+
| Param | Type | Description |
|
|
691
|
+
| ------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
692
|
+
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the bundle ID to mark as errored. |
|
|
693
|
+
|
|
694
|
+
**Returns:** <code>Promise<<a href="#bundleinfo">BundleInfo</a>></code>
|
|
695
|
+
|
|
696
|
+
**Since:** 7.20.0
|
|
697
|
+
|
|
698
|
+
--------------------
|
|
699
|
+
|
|
700
|
+
|
|
701
|
+
#### list(...)
|
|
491
702
|
|
|
492
703
|
```typescript
|
|
493
704
|
list(options?: ListOptions | undefined) => Promise<BundleListResult>
|
|
494
705
|
```
|
|
495
706
|
|
|
496
|
-
Get all locally downloaded bundles in your app
|
|
707
|
+
Get all locally downloaded bundles stored in your app.
|
|
708
|
+
|
|
709
|
+
This returns all bundles that have been downloaded and are available locally, including:
|
|
710
|
+
- The currently active bundle
|
|
711
|
+
- The `builtin` bundle (shipped with your app)
|
|
712
|
+
- Any downloaded bundles waiting to be activated
|
|
713
|
+
- Failed bundles (with `error` status)
|
|
714
|
+
|
|
715
|
+
Use this to:
|
|
716
|
+
- Check available disk space by counting bundles
|
|
717
|
+
- Delete old bundles with {@link delete}
|
|
718
|
+
- Monitor bundle download status
|
|
497
719
|
|
|
498
|
-
| Param | Type | Description
|
|
499
|
-
| ------------- | --------------------------------------------------- |
|
|
500
|
-
| **`options`** | <code><a href="#listoptions">ListOptions</a></code> | The {@link <a href="#listoptions">ListOptions</a>} for
|
|
720
|
+
| Param | Type | Description |
|
|
721
|
+
| ------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
722
|
+
| **`options`** | <code><a href="#listoptions">ListOptions</a></code> | The {@link <a href="#listoptions">ListOptions</a>} for customizing the bundle list output. |
|
|
501
723
|
|
|
502
724
|
**Returns:** <code>Promise<<a href="#bundlelistresult">BundleListResult</a>></code>
|
|
503
725
|
|
|
504
726
|
--------------------
|
|
505
727
|
|
|
506
728
|
|
|
507
|
-
|
|
729
|
+
#### reset(...)
|
|
508
730
|
|
|
509
731
|
```typescript
|
|
510
732
|
reset(options?: ResetOptions | undefined) => Promise<void>
|
|
511
733
|
```
|
|
512
734
|
|
|
513
|
-
Reset the app to
|
|
735
|
+
Reset the app to a known good bundle.
|
|
736
|
+
|
|
737
|
+
This method helps recover from problematic updates by reverting to either:
|
|
738
|
+
- The `builtin` bundle (the original version shipped with your app to App Store/Play Store)
|
|
739
|
+
- The last successfully loaded bundle (most recent bundle that worked correctly)
|
|
740
|
+
|
|
741
|
+
**IMPORTANT: This triggers an immediate app reload, destroying the current JavaScript context.**
|
|
742
|
+
See {@link set} for details on the implications of this operation.
|
|
514
743
|
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
744
|
+
Use cases:
|
|
745
|
+
- Emergency recovery when an update causes critical issues
|
|
746
|
+
- Testing rollback functionality
|
|
747
|
+
- Providing users a "reset to factory" option
|
|
748
|
+
|
|
749
|
+
| Param | Type |
|
|
750
|
+
| ------------- | ----------------------------------------------------- |
|
|
751
|
+
| **`options`** | <code><a href="#resetoptions">ResetOptions</a></code> |
|
|
518
752
|
|
|
519
753
|
--------------------
|
|
520
754
|
|
|
521
755
|
|
|
522
|
-
|
|
756
|
+
#### current()
|
|
523
757
|
|
|
524
758
|
```typescript
|
|
525
759
|
current() => Promise<CurrentBundleResult>
|
|
526
760
|
```
|
|
527
761
|
|
|
528
|
-
Get
|
|
762
|
+
Get information about the currently active bundle.
|
|
763
|
+
|
|
764
|
+
Returns:
|
|
765
|
+
- `bundle`: The currently active bundle information
|
|
766
|
+
- `native`: The version of the builtin bundle (the original app version from App/Play Store)
|
|
767
|
+
|
|
768
|
+
If no updates have been applied, `bundle.id` will be `"builtin"`, indicating the app
|
|
769
|
+
is running the original version shipped with the native app.
|
|
770
|
+
|
|
771
|
+
Use this to:
|
|
772
|
+
- Display the current version to users
|
|
773
|
+
- Check if an update is currently active
|
|
774
|
+
- Compare against available updates
|
|
775
|
+
- Log the active bundle for debugging
|
|
529
776
|
|
|
530
777
|
**Returns:** <code>Promise<<a href="#currentbundleresult">CurrentBundleResult</a>></code>
|
|
531
778
|
|
|
532
779
|
--------------------
|
|
533
780
|
|
|
534
781
|
|
|
535
|
-
|
|
782
|
+
#### reload()
|
|
536
783
|
|
|
537
784
|
```typescript
|
|
538
785
|
reload() => Promise<void>
|
|
539
786
|
```
|
|
540
787
|
|
|
541
|
-
|
|
788
|
+
Manually reload the app to apply a pending update.
|
|
789
|
+
|
|
790
|
+
This triggers the same reload behavior that happens automatically when the app backgrounds.
|
|
791
|
+
If you've called {@link next} to queue an update, calling `reload()` will apply it immediately.
|
|
792
|
+
|
|
793
|
+
**IMPORTANT: This destroys the current JavaScript context immediately.**
|
|
794
|
+
See {@link set} for details on the implications of this operation.
|
|
795
|
+
|
|
796
|
+
Common use cases:
|
|
797
|
+
- Applying an update immediately after download instead of waiting for backgrounding
|
|
798
|
+
- Providing a "Restart now" button to users after an update is ready
|
|
799
|
+
- Testing update flows during development
|
|
800
|
+
|
|
801
|
+
If no update is pending (no call to {@link next}), this simply reloads the current bundle.
|
|
542
802
|
|
|
543
803
|
--------------------
|
|
544
804
|
|
|
545
805
|
|
|
546
|
-
|
|
806
|
+
#### setMultiDelay(...)
|
|
547
807
|
|
|
548
808
|
```typescript
|
|
549
809
|
setMultiDelay(options: MultiDelayConditions) => Promise<void>
|
|
550
810
|
```
|
|
551
811
|
|
|
552
|
-
|
|
553
|
-
After all conditions are met, the update process will run start again as usual, so update will be installed after a backgrounding or killing the app.
|
|
554
|
-
For the `date` kind, the value should be an iso8601 date string.
|
|
555
|
-
For the `background` kind, the value should be a number in milliseconds.
|
|
556
|
-
For the `nativeVersion` kind, the value should be the version number.
|
|
557
|
-
For the `kill` kind, the value is not used.
|
|
558
|
-
The function has unconsistent behavior the option kill do trigger the update after the first kill and not after the next background like other options. This will be fixed in a future major release.
|
|
812
|
+
Configure conditions that must be met before a pending update is applied.
|
|
559
813
|
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
814
|
+
After calling {@link next} to queue an update, use this method to control when it gets applied.
|
|
815
|
+
The update will only be installed after ALL specified conditions are satisfied.
|
|
816
|
+
|
|
817
|
+
Available condition types:
|
|
818
|
+
- `background`: Wait for the app to be backgrounded. Optionally specify duration in milliseconds.
|
|
819
|
+
- `kill`: Wait for the app to be killed and relaunched (**Note:** Current behavior triggers update immediately on kill, not on next background. This will be fixed in v8.)
|
|
820
|
+
- `date`: Wait until a specific date/time (ISO 8601 format)
|
|
821
|
+
- `nativeVersion`: Wait until the native app is updated to a specific version
|
|
822
|
+
|
|
823
|
+
Condition value formats:
|
|
824
|
+
- `background`: Number in milliseconds (e.g., `"300000"` for 5 minutes), or omit for immediate
|
|
825
|
+
- `kill`: No value needed
|
|
826
|
+
- `date`: ISO 8601 date string (e.g., `"2025-12-31T23:59:59Z"`)
|
|
827
|
+
- `nativeVersion`: Version string (e.g., `"2.0.0"`)
|
|
828
|
+
|
|
829
|
+
| Param | Type | Description |
|
|
830
|
+
| ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
831
|
+
| **`options`** | <code><a href="#multidelayconditions">MultiDelayConditions</a></code> | Contains the {@link <a href="#multidelayconditions">MultiDelayConditions</a>} array of conditions. |
|
|
563
832
|
|
|
564
833
|
**Since:** 4.3.0
|
|
565
834
|
|
|
566
835
|
--------------------
|
|
567
836
|
|
|
568
837
|
|
|
569
|
-
|
|
838
|
+
#### cancelDelay()
|
|
570
839
|
|
|
571
840
|
```typescript
|
|
572
841
|
cancelDelay() => Promise<void>
|
|
573
842
|
```
|
|
574
843
|
|
|
575
|
-
|
|
844
|
+
Cancel all delay conditions and apply the pending update immediately.
|
|
845
|
+
|
|
846
|
+
If you've set delay conditions with {@link setMultiDelay}, this method clears them
|
|
847
|
+
and triggers the pending update to be applied on the next app background or restart.
|
|
848
|
+
|
|
849
|
+
This is useful when:
|
|
850
|
+
- User manually requests to update now (e.g., clicks "Update now" button)
|
|
851
|
+
- Your app detects it's a good time to update (e.g., user finished critical task)
|
|
852
|
+
- You want to override a time-based delay early
|
|
576
853
|
|
|
577
854
|
**Since:** 4.0.0
|
|
578
855
|
|
|
579
856
|
--------------------
|
|
580
857
|
|
|
581
858
|
|
|
582
|
-
|
|
859
|
+
#### getLatest(...)
|
|
583
860
|
|
|
584
861
|
```typescript
|
|
585
862
|
getLatest(options?: GetLatestOptions | undefined) => Promise<LatestVersion>
|
|
586
863
|
```
|
|
587
864
|
|
|
588
|
-
|
|
865
|
+
Check the update server for the latest available bundle version.
|
|
866
|
+
|
|
867
|
+
This queries your configured update URL (or Capgo backend) to see if a newer bundle
|
|
868
|
+
is available for download. It does NOT download the bundle automatically.
|
|
869
|
+
|
|
870
|
+
The response includes:
|
|
871
|
+
- `version`: The latest available version identifier
|
|
872
|
+
- `url`: Download URL for the bundle (if available)
|
|
873
|
+
- `breaking`: Whether this update is marked as incompatible (requires native app update)
|
|
874
|
+
- `message`: Optional message from the server
|
|
875
|
+
- `manifest`: File list for partial updates (if using multi-file downloads)
|
|
876
|
+
|
|
877
|
+
After receiving the latest version info, you can:
|
|
878
|
+
1. Compare it with your current version
|
|
879
|
+
2. Download it using {@link download}
|
|
880
|
+
3. Apply it using {@link next} or {@link set}
|
|
881
|
+
|
|
882
|
+
**Important: Error handling for "no new version available"**
|
|
883
|
+
|
|
884
|
+
When the device's current version matches the latest version on the server (i.e., the device is already
|
|
885
|
+
up-to-date), the server returns a 200 response with `error: "no_new_version_available"` and
|
|
886
|
+
`message: "No new version available"`. **This causes `getLatest()` to throw an error**, even though
|
|
887
|
+
this is a normal, expected condition.
|
|
888
|
+
|
|
889
|
+
You should catch this specific error to handle it gracefully:
|
|
890
|
+
|
|
891
|
+
```typescript
|
|
892
|
+
try {
|
|
893
|
+
const latest = await CapacitorUpdater.getLatest();
|
|
894
|
+
// New version is available, proceed with download
|
|
895
|
+
} catch (error) {
|
|
896
|
+
if (error.message === 'No new version available') {
|
|
897
|
+
// Device is already on the latest version - this is normal
|
|
898
|
+
console.log('Already up to date');
|
|
899
|
+
} else {
|
|
900
|
+
// Actual error occurred
|
|
901
|
+
console.error('Failed to check for updates:', error);
|
|
902
|
+
}
|
|
903
|
+
}
|
|
904
|
+
```
|
|
905
|
+
|
|
906
|
+
In this scenario, the server:
|
|
907
|
+
- Logs the request with a "No new version available" message
|
|
908
|
+
- Sends a "noNew" stat action to track that the device checked for updates but was already current (done on the backend)
|
|
589
909
|
|
|
590
|
-
| Param | Type |
|
|
591
|
-
| ------------- | ------------------------------------------------------------- |
|
|
592
|
-
| **`options`** | <code><a href="#getlatestoptions">GetLatestOptions</a></code> |
|
|
910
|
+
| Param | Type | Description |
|
|
911
|
+
| ------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
912
|
+
| **`options`** | <code><a href="#getlatestoptions">GetLatestOptions</a></code> | Optional {@link <a href="#getlatestoptions">GetLatestOptions</a>} to specify which channel to check. |
|
|
593
913
|
|
|
594
914
|
**Returns:** <code>Promise<<a href="#latestversion">LatestVersion</a>></code>
|
|
595
915
|
|
|
@@ -598,20 +918,48 @@ Get Latest bundle available from update Url
|
|
|
598
918
|
--------------------
|
|
599
919
|
|
|
600
920
|
|
|
601
|
-
|
|
921
|
+
#### setChannel(...)
|
|
602
922
|
|
|
603
923
|
```typescript
|
|
604
924
|
setChannel(options: SetChannelOptions) => Promise<ChannelRes>
|
|
605
925
|
```
|
|
606
926
|
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
927
|
+
Assign this device to a specific update channel at runtime.
|
|
928
|
+
|
|
929
|
+
Channels allow you to distribute different bundle versions to different groups of users
|
|
930
|
+
(e.g., "production", "beta", "staging"). This method switches the device to a new channel.
|
|
931
|
+
|
|
932
|
+
**Requirements:**
|
|
933
|
+
- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
|
|
934
|
+
- The backend may accept or reject the request based on channel settings
|
|
935
|
+
|
|
936
|
+
**When to use:**
|
|
937
|
+
- After the app is ready and the user has interacted (e.g., opted into beta program)
|
|
938
|
+
- To implement in-app channel switching (beta toggle, tester access, etc.)
|
|
939
|
+
- For user-driven channel changes
|
|
940
|
+
|
|
941
|
+
**When NOT to use:**
|
|
942
|
+
- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead
|
|
943
|
+
- Before user interaction
|
|
944
|
+
|
|
945
|
+
**Important: Listen for the `channelPrivate` event**
|
|
946
|
+
|
|
947
|
+
When a user attempts to set a channel that doesn't allow device self-assignment, the method will
|
|
948
|
+
throw an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event
|
|
949
|
+
to provide appropriate feedback to users:
|
|
950
|
+
|
|
951
|
+
```typescript
|
|
952
|
+
CapacitorUpdater.addListener('channelPrivate', (data) => {
|
|
953
|
+
console.warn(`Cannot access channel "${data.channel}": ${data.message}`);
|
|
954
|
+
// Show user-friendly message
|
|
955
|
+
});
|
|
956
|
+
```
|
|
957
|
+
|
|
958
|
+
This sends a request to the Capgo backend linking your device ID to the specified channel.
|
|
611
959
|
|
|
612
|
-
| Param | Type | Description
|
|
613
|
-
| ------------- | --------------------------------------------------------------- |
|
|
614
|
-
| **`options`** | <code><a href="#setchanneloptions">SetChannelOptions</a></code> |
|
|
960
|
+
| Param | Type | Description |
|
|
961
|
+
| ------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
962
|
+
| **`options`** | <code><a href="#setchanneloptions">SetChannelOptions</a></code> | The {@link <a href="#setchanneloptions">SetChannelOptions</a>} containing the channel name and optional auto-update trigger. |
|
|
615
963
|
|
|
616
964
|
**Returns:** <code>Promise<<a href="#channelres">ChannelRes</a>></code>
|
|
617
965
|
|
|
@@ -620,13 +968,22 @@ This methods send to Capgo backend a request to link the device ID to the channe
|
|
|
620
968
|
--------------------
|
|
621
969
|
|
|
622
970
|
|
|
623
|
-
|
|
971
|
+
#### unsetChannel(...)
|
|
624
972
|
|
|
625
973
|
```typescript
|
|
626
974
|
unsetChannel(options: UnsetChannelOptions) => Promise<void>
|
|
627
975
|
```
|
|
628
976
|
|
|
629
|
-
|
|
977
|
+
Remove the device's channel assignment and return to the default channel.
|
|
978
|
+
|
|
979
|
+
This unlinks the device from any specifically assigned channel, causing it to fall back to:
|
|
980
|
+
- The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
|
|
981
|
+
- Your backend's default channel for this app
|
|
982
|
+
|
|
983
|
+
Use this when:
|
|
984
|
+
- Users opt out of beta/testing programs
|
|
985
|
+
- You want to reset a device to standard update distribution
|
|
986
|
+
- Testing channel switching behavior
|
|
630
987
|
|
|
631
988
|
| Param | Type |
|
|
632
989
|
| ------------- | ------------------------------------------------------------------- |
|
|
@@ -637,13 +994,24 @@ Unset the channel for this device. The device will then return to the default ch
|
|
|
637
994
|
--------------------
|
|
638
995
|
|
|
639
996
|
|
|
640
|
-
|
|
997
|
+
#### getChannel()
|
|
641
998
|
|
|
642
999
|
```typescript
|
|
643
1000
|
getChannel() => Promise<GetChannelRes>
|
|
644
1001
|
```
|
|
645
1002
|
|
|
646
|
-
Get the channel
|
|
1003
|
+
Get the current channel assigned to this device.
|
|
1004
|
+
|
|
1005
|
+
Returns information about:
|
|
1006
|
+
- `channel`: The currently assigned channel name (if any)
|
|
1007
|
+
- `allowSet`: Whether the channel allows self-assignment
|
|
1008
|
+
- `status`: Operation status
|
|
1009
|
+
- `error`/`message`: Additional information (if applicable)
|
|
1010
|
+
|
|
1011
|
+
Use this to:
|
|
1012
|
+
- Display current channel to users (e.g., "You're on the Beta channel")
|
|
1013
|
+
- Check if a device is on a specific channel before showing features
|
|
1014
|
+
- Verify channel assignment after calling {@link setChannel}
|
|
647
1015
|
|
|
648
1016
|
**Returns:** <code>Promise<<a href="#getchannelres">GetChannelRes</a>></code>
|
|
649
1017
|
|
|
@@ -652,30 +1020,88 @@ Get the channel for this device
|
|
|
652
1020
|
--------------------
|
|
653
1021
|
|
|
654
1022
|
|
|
655
|
-
|
|
1023
|
+
#### listChannels()
|
|
1024
|
+
|
|
1025
|
+
```typescript
|
|
1026
|
+
listChannels() => Promise<ListChannelsResult>
|
|
1027
|
+
```
|
|
1028
|
+
|
|
1029
|
+
Get a list of all channels available for this device to self-assign to.
|
|
1030
|
+
|
|
1031
|
+
Only returns channels where `allow_self_set` is `true`. These are channels that
|
|
1032
|
+
users can switch to using {@link setChannel} without backend administrator intervention.
|
|
1033
|
+
|
|
1034
|
+
Each channel includes:
|
|
1035
|
+
- `id`: Unique channel identifier
|
|
1036
|
+
- `name`: Human-readable channel name
|
|
1037
|
+
- `public`: Whether the channel is publicly visible
|
|
1038
|
+
- `allow_self_set`: Always `true` in results (filtered to only self-assignable channels)
|
|
1039
|
+
|
|
1040
|
+
Use this to:
|
|
1041
|
+
- Build a channel selector UI for users (e.g., "Join Beta" button)
|
|
1042
|
+
- Show available testing/preview channels
|
|
1043
|
+
- Implement channel discovery features
|
|
1044
|
+
|
|
1045
|
+
**Returns:** <code>Promise<<a href="#listchannelsresult">ListChannelsResult</a>></code>
|
|
1046
|
+
|
|
1047
|
+
**Since:** 7.5.0
|
|
1048
|
+
|
|
1049
|
+
--------------------
|
|
1050
|
+
|
|
1051
|
+
|
|
1052
|
+
#### setCustomId(...)
|
|
656
1053
|
|
|
657
1054
|
```typescript
|
|
658
1055
|
setCustomId(options: SetCustomIdOptions) => Promise<void>
|
|
659
1056
|
```
|
|
660
1057
|
|
|
661
|
-
Set a custom
|
|
1058
|
+
Set a custom identifier for this device.
|
|
662
1059
|
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
1060
|
+
This allows you to identify devices by your own custom ID (user ID, account ID, etc.)
|
|
1061
|
+
instead of or in addition to the device's unique hardware ID. The custom ID is sent
|
|
1062
|
+
to your update server and can be used for:
|
|
1063
|
+
- Targeting specific users for updates
|
|
1064
|
+
- Analytics and user tracking
|
|
1065
|
+
- Debugging and support (correlating devices with users)
|
|
1066
|
+
- A/B testing or feature flagging
|
|
1067
|
+
|
|
1068
|
+
**Persistence:**
|
|
1069
|
+
- When {@link PluginsConfig.CapacitorUpdater.persistCustomId} is `true`, the ID persists across app restarts
|
|
1070
|
+
- When `false`, the ID is only kept for the current session
|
|
1071
|
+
|
|
1072
|
+
**Clearing the custom ID:**
|
|
1073
|
+
- Pass an empty string `""` to remove any stored custom ID
|
|
1074
|
+
|
|
1075
|
+
| Param | Type | Description |
|
|
1076
|
+
| ------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
1077
|
+
| **`options`** | <code><a href="#setcustomidoptions">SetCustomIdOptions</a></code> | The {@link <a href="#setcustomidoptions">SetCustomIdOptions</a>} containing the custom identifier string. |
|
|
666
1078
|
|
|
667
1079
|
**Since:** 4.9.0
|
|
668
1080
|
|
|
669
1081
|
--------------------
|
|
670
1082
|
|
|
671
1083
|
|
|
672
|
-
|
|
1084
|
+
#### getBuiltinVersion()
|
|
673
1085
|
|
|
674
1086
|
```typescript
|
|
675
1087
|
getBuiltinVersion() => Promise<BuiltinVersion>
|
|
676
1088
|
```
|
|
677
1089
|
|
|
678
|
-
Get the
|
|
1090
|
+
Get the builtin bundle version (the original version shipped with your native app).
|
|
1091
|
+
|
|
1092
|
+
This returns the version of the bundle that was included when the app was installed
|
|
1093
|
+
from the App Store or Play Store. This is NOT the currently active bundle version -
|
|
1094
|
+
use {@link current} for that.
|
|
1095
|
+
|
|
1096
|
+
Returns:
|
|
1097
|
+
- The {@link PluginsConfig.CapacitorUpdater.version} config value if set, or
|
|
1098
|
+
- The native app version from platform configs (package.json, Info.plist, build.gradle)
|
|
1099
|
+
|
|
1100
|
+
Use this to:
|
|
1101
|
+
- Display the "factory" version to users
|
|
1102
|
+
- Compare against downloaded bundle versions
|
|
1103
|
+
- Determine if any updates have been applied
|
|
1104
|
+
- Debugging version mismatches
|
|
679
1105
|
|
|
680
1106
|
**Returns:** <code>Promise<<a href="#builtinversion">BuiltinVersion</a>></code>
|
|
681
1107
|
|
|
@@ -684,65 +1110,121 @@ Get the native app version or the builtin version if set in config
|
|
|
684
1110
|
--------------------
|
|
685
1111
|
|
|
686
1112
|
|
|
687
|
-
|
|
1113
|
+
#### getDeviceId()
|
|
688
1114
|
|
|
689
1115
|
```typescript
|
|
690
1116
|
getDeviceId() => Promise<DeviceId>
|
|
691
1117
|
```
|
|
692
1118
|
|
|
693
|
-
Get unique
|
|
1119
|
+
Get the unique, privacy-friendly identifier for this device.
|
|
1120
|
+
|
|
1121
|
+
This ID is used to identify the device when communicating with update servers.
|
|
1122
|
+
It's automatically generated and stored securely by the plugin.
|
|
1123
|
+
|
|
1124
|
+
**Privacy & Security characteristics:**
|
|
1125
|
+
- Generated as a UUID (not based on hardware identifiers)
|
|
1126
|
+
- Stored securely in platform-specific secure storage
|
|
1127
|
+
- Android: Android Keystore (persists across app reinstalls on API 23+)
|
|
1128
|
+
- iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
|
|
1129
|
+
- Not synced to cloud (iOS)
|
|
1130
|
+
- Follows Apple and Google privacy best practices
|
|
1131
|
+
- Users can clear it via system settings (Android) or keychain access (iOS)
|
|
1132
|
+
|
|
1133
|
+
**Persistence:**
|
|
1134
|
+
The device ID persists across app reinstalls to maintain consistent device identity
|
|
1135
|
+
for update tracking and analytics.
|
|
1136
|
+
|
|
1137
|
+
Use this to:
|
|
1138
|
+
- Debug update delivery issues (check what ID the server sees)
|
|
1139
|
+
- Implement device-specific features
|
|
1140
|
+
- Correlate server logs with specific devices
|
|
694
1141
|
|
|
695
1142
|
**Returns:** <code>Promise<<a href="#deviceid">DeviceId</a>></code>
|
|
696
1143
|
|
|
697
1144
|
--------------------
|
|
698
1145
|
|
|
699
1146
|
|
|
700
|
-
|
|
1147
|
+
#### getPluginVersion()
|
|
701
1148
|
|
|
702
1149
|
```typescript
|
|
703
1150
|
getPluginVersion() => Promise<PluginVersion>
|
|
704
1151
|
```
|
|
705
1152
|
|
|
706
|
-
Get the
|
|
1153
|
+
Get the version of the Capacitor Updater plugin installed in your app.
|
|
1154
|
+
|
|
1155
|
+
This returns the version of the native plugin code (Android/iOS), which is sent
|
|
1156
|
+
to the update server with each request. This is NOT your app version or bundle version.
|
|
1157
|
+
|
|
1158
|
+
Use this to:
|
|
1159
|
+
- Debug plugin-specific issues (when reporting bugs)
|
|
1160
|
+
- Verify plugin installation and version
|
|
1161
|
+
- Check compatibility with backend features
|
|
1162
|
+
- Display in debug/about screens
|
|
707
1163
|
|
|
708
1164
|
**Returns:** <code>Promise<<a href="#pluginversion">PluginVersion</a>></code>
|
|
709
1165
|
|
|
710
1166
|
--------------------
|
|
711
1167
|
|
|
712
1168
|
|
|
713
|
-
|
|
1169
|
+
#### isAutoUpdateEnabled()
|
|
714
1170
|
|
|
715
1171
|
```typescript
|
|
716
1172
|
isAutoUpdateEnabled() => Promise<AutoUpdateEnabled>
|
|
717
1173
|
```
|
|
718
1174
|
|
|
719
|
-
|
|
1175
|
+
Check if automatic updates are currently enabled.
|
|
1176
|
+
|
|
1177
|
+
Returns `true` if {@link PluginsConfig.CapacitorUpdater.autoUpdate} is enabled,
|
|
1178
|
+
meaning the plugin will automatically check for, download, and apply updates.
|
|
1179
|
+
|
|
1180
|
+
Returns `false` if in manual mode, where you control the update flow using
|
|
1181
|
+
{@link getLatest}, {@link download}, {@link next}, and {@link set}.
|
|
1182
|
+
|
|
1183
|
+
Use this to:
|
|
1184
|
+
- Determine which update flow your app is using
|
|
1185
|
+
- Show/hide manual update UI based on mode
|
|
1186
|
+
- Debug update behavior
|
|
720
1187
|
|
|
721
1188
|
**Returns:** <code>Promise<<a href="#autoupdateenabled">AutoUpdateEnabled</a>></code>
|
|
722
1189
|
|
|
723
1190
|
--------------------
|
|
724
1191
|
|
|
725
1192
|
|
|
726
|
-
|
|
1193
|
+
#### removeAllListeners()
|
|
727
1194
|
|
|
728
1195
|
```typescript
|
|
729
1196
|
removeAllListeners() => Promise<void>
|
|
730
1197
|
```
|
|
731
1198
|
|
|
732
|
-
Remove all listeners for this plugin.
|
|
1199
|
+
Remove all event listeners registered for this plugin.
|
|
1200
|
+
|
|
1201
|
+
This unregisters all listeners added via {@link addListener} for all event types:
|
|
1202
|
+
- `download`
|
|
1203
|
+
- `noNeedUpdate`
|
|
1204
|
+
- `updateAvailable`
|
|
1205
|
+
- `downloadComplete`
|
|
1206
|
+
- `downloadFailed`
|
|
1207
|
+
- `breakingAvailable` / `majorAvailable`
|
|
1208
|
+
- `updateFailed`
|
|
1209
|
+
- `appReloaded`
|
|
1210
|
+
- `appReady`
|
|
1211
|
+
|
|
1212
|
+
Use this during cleanup (e.g., when unmounting components or closing screens)
|
|
1213
|
+
to prevent memory leaks from lingering event listeners.
|
|
733
1214
|
|
|
734
1215
|
**Since:** 1.0.0
|
|
735
1216
|
|
|
736
1217
|
--------------------
|
|
737
1218
|
|
|
738
1219
|
|
|
739
|
-
|
|
1220
|
+
#### addListener('download', ...)
|
|
740
1221
|
|
|
741
1222
|
```typescript
|
|
742
1223
|
addListener(eventName: 'download', listenerFunc: (state: DownloadEvent) => void) => Promise<PluginListenerHandle>
|
|
743
1224
|
```
|
|
744
1225
|
|
|
745
1226
|
Listen for bundle download event in the App. Fires once a download has started, during downloading and when finished.
|
|
1227
|
+
This will return you all download percent during the download
|
|
746
1228
|
|
|
747
1229
|
| Param | Type |
|
|
748
1230
|
| ------------------ | --------------------------------------------------------------------------- |
|
|
@@ -756,7 +1238,7 @@ Listen for bundle download event in the App. Fires once a download has started,
|
|
|
756
1238
|
--------------------
|
|
757
1239
|
|
|
758
1240
|
|
|
759
|
-
|
|
1241
|
+
#### addListener('noNeedUpdate', ...)
|
|
760
1242
|
|
|
761
1243
|
```typescript
|
|
762
1244
|
addListener(eventName: 'noNeedUpdate', listenerFunc: (state: NoNeedEvent) => void) => Promise<PluginListenerHandle>
|
|
@@ -776,7 +1258,7 @@ Listen for no need to update event, useful when you want force check every time
|
|
|
776
1258
|
--------------------
|
|
777
1259
|
|
|
778
1260
|
|
|
779
|
-
|
|
1261
|
+
#### addListener('updateAvailable', ...)
|
|
780
1262
|
|
|
781
1263
|
```typescript
|
|
782
1264
|
addListener(eventName: 'updateAvailable', listenerFunc: (state: UpdateAvailableEvent) => void) => Promise<PluginListenerHandle>
|
|
@@ -796,7 +1278,7 @@ Listen for available update event, useful when you want to force check every tim
|
|
|
796
1278
|
--------------------
|
|
797
1279
|
|
|
798
1280
|
|
|
799
|
-
|
|
1281
|
+
#### addListener('downloadComplete', ...)
|
|
800
1282
|
|
|
801
1283
|
```typescript
|
|
802
1284
|
addListener(eventName: 'downloadComplete', listenerFunc: (state: DownloadCompleteEvent) => void) => Promise<PluginListenerHandle>
|
|
@@ -816,7 +1298,28 @@ Listen for downloadComplete events.
|
|
|
816
1298
|
--------------------
|
|
817
1299
|
|
|
818
1300
|
|
|
819
|
-
|
|
1301
|
+
#### addListener('breakingAvailable', ...)
|
|
1302
|
+
|
|
1303
|
+
```typescript
|
|
1304
|
+
addListener(eventName: 'breakingAvailable', listenerFunc: (state: BreakingAvailableEvent) => void) => Promise<PluginListenerHandle>
|
|
1305
|
+
```
|
|
1306
|
+
|
|
1307
|
+
Listen for breaking update events when the backend flags an update as incompatible with the current app.
|
|
1308
|
+
Emits the same payload as the legacy `majorAvailable` listener.
|
|
1309
|
+
|
|
1310
|
+
| Param | Type |
|
|
1311
|
+
| ------------------ | --------------------------------------------------------------------------------------- |
|
|
1312
|
+
| **`eventName`** | <code>'breakingAvailable'</code> |
|
|
1313
|
+
| **`listenerFunc`** | <code>(state: <a href="#majoravailableevent">MajorAvailableEvent</a>) => void</code> |
|
|
1314
|
+
|
|
1315
|
+
**Returns:** <code>Promise<<a href="#pluginlistenerhandle">PluginListenerHandle</a>></code>
|
|
1316
|
+
|
|
1317
|
+
**Since:** 7.22.0
|
|
1318
|
+
|
|
1319
|
+
--------------------
|
|
1320
|
+
|
|
1321
|
+
|
|
1322
|
+
#### addListener('majorAvailable', ...)
|
|
820
1323
|
|
|
821
1324
|
```typescript
|
|
822
1325
|
addListener(eventName: 'majorAvailable', listenerFunc: (state: MajorAvailableEvent) => void) => Promise<PluginListenerHandle>
|
|
@@ -836,7 +1339,7 @@ Listen for Major update event in the App, let you know when major update is bloc
|
|
|
836
1339
|
--------------------
|
|
837
1340
|
|
|
838
1341
|
|
|
839
|
-
|
|
1342
|
+
#### addListener('updateFailed', ...)
|
|
840
1343
|
|
|
841
1344
|
```typescript
|
|
842
1345
|
addListener(eventName: 'updateFailed', listenerFunc: (state: UpdateFailedEvent) => void) => Promise<PluginListenerHandle>
|
|
@@ -856,7 +1359,7 @@ Listen for update fail event in the App, let you know when update has fail to in
|
|
|
856
1359
|
--------------------
|
|
857
1360
|
|
|
858
1361
|
|
|
859
|
-
|
|
1362
|
+
#### addListener('downloadFailed', ...)
|
|
860
1363
|
|
|
861
1364
|
```typescript
|
|
862
1365
|
addListener(eventName: 'downloadFailed', listenerFunc: (state: DownloadFailedEvent) => void) => Promise<PluginListenerHandle>
|
|
@@ -876,7 +1379,7 @@ Listen for download fail event in the App, let you know when a bundle download h
|
|
|
876
1379
|
--------------------
|
|
877
1380
|
|
|
878
1381
|
|
|
879
|
-
|
|
1382
|
+
#### addListener('appReloaded', ...)
|
|
880
1383
|
|
|
881
1384
|
```typescript
|
|
882
1385
|
addListener(eventName: 'appReloaded', listenerFunc: () => void) => Promise<PluginListenerHandle>
|
|
@@ -896,13 +1399,13 @@ Listen for reload event in the App, let you know when reload has happened
|
|
|
896
1399
|
--------------------
|
|
897
1400
|
|
|
898
1401
|
|
|
899
|
-
|
|
1402
|
+
#### addListener('appReady', ...)
|
|
900
1403
|
|
|
901
1404
|
```typescript
|
|
902
1405
|
addListener(eventName: 'appReady', listenerFunc: (state: AppReadyEvent) => void) => Promise<PluginListenerHandle>
|
|
903
1406
|
```
|
|
904
1407
|
|
|
905
|
-
Listen for app ready event in the App, let you know when app is ready to use
|
|
1408
|
+
Listen for app ready event in the App, let you know when app is ready to use, this event is retain till consumed.
|
|
906
1409
|
|
|
907
1410
|
| Param | Type |
|
|
908
1411
|
| ------------------ | --------------------------------------------------------------------------- |
|
|
@@ -916,27 +1419,76 @@ Listen for app ready event in the App, let you know when app is ready to use
|
|
|
916
1419
|
--------------------
|
|
917
1420
|
|
|
918
1421
|
|
|
919
|
-
|
|
1422
|
+
#### addListener('channelPrivate', ...)
|
|
1423
|
+
|
|
1424
|
+
```typescript
|
|
1425
|
+
addListener(eventName: 'channelPrivate', listenerFunc: (state: ChannelPrivateEvent) => void) => Promise<PluginListenerHandle>
|
|
1426
|
+
```
|
|
1427
|
+
|
|
1428
|
+
Listen for channel private event, fired when attempting to set a channel that doesn't allow device self-assignment.
|
|
1429
|
+
|
|
1430
|
+
This event is useful for:
|
|
1431
|
+
- Informing users they don't have permission to switch to a specific channel
|
|
1432
|
+
- Implementing custom error handling for channel restrictions
|
|
1433
|
+
- Logging unauthorized channel access attempts
|
|
1434
|
+
|
|
1435
|
+
| Param | Type |
|
|
1436
|
+
| ------------------ | --------------------------------------------------------------------------------------- |
|
|
1437
|
+
| **`eventName`** | <code>'channelPrivate'</code> |
|
|
1438
|
+
| **`listenerFunc`** | <code>(state: <a href="#channelprivateevent">ChannelPrivateEvent</a>) => void</code> |
|
|
1439
|
+
|
|
1440
|
+
**Returns:** <code>Promise<<a href="#pluginlistenerhandle">PluginListenerHandle</a>></code>
|
|
1441
|
+
|
|
1442
|
+
**Since:** 7.34.0
|
|
1443
|
+
|
|
1444
|
+
--------------------
|
|
1445
|
+
|
|
1446
|
+
|
|
1447
|
+
#### isAutoUpdateAvailable()
|
|
920
1448
|
|
|
921
1449
|
```typescript
|
|
922
1450
|
isAutoUpdateAvailable() => Promise<AutoUpdateAvailable>
|
|
923
1451
|
```
|
|
924
1452
|
|
|
925
|
-
|
|
1453
|
+
Check if the auto-update feature is available (not disabled by custom server configuration).
|
|
1454
|
+
|
|
1455
|
+
Returns `false` when a custom `updateUrl` is configured, as this typically indicates
|
|
1456
|
+
you're using a self-hosted update server that may not support all auto-update features.
|
|
1457
|
+
|
|
1458
|
+
Returns `true` when using the default Capgo backend or when the feature is available.
|
|
1459
|
+
|
|
1460
|
+
This is different from {@link isAutoUpdateEnabled}:
|
|
1461
|
+
- `isAutoUpdateEnabled()`: Checks if auto-update MODE is turned on/off
|
|
1462
|
+
- `isAutoUpdateAvailable()`: Checks if auto-update is SUPPORTED with your current configuration
|
|
926
1463
|
|
|
927
1464
|
**Returns:** <code>Promise<<a href="#autoupdateavailable">AutoUpdateAvailable</a>></code>
|
|
928
1465
|
|
|
929
1466
|
--------------------
|
|
930
1467
|
|
|
931
1468
|
|
|
932
|
-
|
|
1469
|
+
#### getNextBundle()
|
|
933
1470
|
|
|
934
1471
|
```typescript
|
|
935
1472
|
getNextBundle() => Promise<BundleInfo | null>
|
|
936
1473
|
```
|
|
937
1474
|
|
|
938
|
-
Get the
|
|
939
|
-
|
|
1475
|
+
Get information about the bundle queued to be activated on next reload.
|
|
1476
|
+
|
|
1477
|
+
Returns:
|
|
1478
|
+
- {@link <a href="#bundleinfo">BundleInfo</a>} object if a bundle has been queued via {@link next}
|
|
1479
|
+
- `null` if no update is pending
|
|
1480
|
+
|
|
1481
|
+
This is useful to:
|
|
1482
|
+
- Check if an update is waiting to be applied
|
|
1483
|
+
- Display "Update pending" status to users
|
|
1484
|
+
- Show version info of the queued update
|
|
1485
|
+
- Decide whether to show a "Restart to update" prompt
|
|
1486
|
+
|
|
1487
|
+
The queued bundle will be activated when:
|
|
1488
|
+
- The app is backgrounded (default behavior)
|
|
1489
|
+
- The app is killed and restarted
|
|
1490
|
+
- {@link reload} is called manually
|
|
1491
|
+
- Delay conditions set by {@link setMultiDelay} are met
|
|
940
1492
|
|
|
941
1493
|
**Returns:** <code>Promise<<a href="#bundleinfo">BundleInfo</a> | null></code>
|
|
942
1494
|
|
|
@@ -945,17 +1497,162 @@ Returns null if no next bundle is set.
|
|
|
945
1497
|
--------------------
|
|
946
1498
|
|
|
947
1499
|
|
|
948
|
-
|
|
1500
|
+
#### getFailedUpdate()
|
|
1501
|
+
|
|
1502
|
+
```typescript
|
|
1503
|
+
getFailedUpdate() => Promise<UpdateFailedEvent | null>
|
|
1504
|
+
```
|
|
1505
|
+
|
|
1506
|
+
Retrieve information about the most recent bundle that failed to load.
|
|
1507
|
+
|
|
1508
|
+
When a bundle fails to load (e.g., JavaScript errors prevent initialization, missing files),
|
|
1509
|
+
the plugin automatically rolls back and stores information about the failure. This method
|
|
1510
|
+
retrieves that failure information.
|
|
1511
|
+
|
|
1512
|
+
**IMPORTANT: The stored value is cleared after being retrieved once.**
|
|
1513
|
+
Calling this method multiple times will only return the failure info on the first call,
|
|
1514
|
+
then `null` on subsequent calls until another failure occurs.
|
|
1515
|
+
|
|
1516
|
+
Returns:
|
|
1517
|
+
- {@link <a href="#updatefailedevent">UpdateFailedEvent</a>} with bundle info if a failure was recorded
|
|
1518
|
+
- `null` if no failure has occurred or if it was already retrieved
|
|
1519
|
+
|
|
1520
|
+
Use this to:
|
|
1521
|
+
- Show users why an update failed
|
|
1522
|
+
- Log failure information for debugging
|
|
1523
|
+
- Implement custom error handling/reporting
|
|
1524
|
+
- Display rollback notifications
|
|
1525
|
+
|
|
1526
|
+
**Returns:** <code>Promise<<a href="#updatefailedevent">UpdateFailedEvent</a> | null></code>
|
|
1527
|
+
|
|
1528
|
+
**Since:** 7.22.0
|
|
1529
|
+
|
|
1530
|
+
--------------------
|
|
1531
|
+
|
|
1532
|
+
|
|
1533
|
+
#### setShakeMenu(...)
|
|
1534
|
+
|
|
1535
|
+
```typescript
|
|
1536
|
+
setShakeMenu(options: SetShakeMenuOptions) => Promise<void>
|
|
1537
|
+
```
|
|
1538
|
+
|
|
1539
|
+
Enable or disable the shake gesture menu for debugging and testing.
|
|
1540
|
+
|
|
1541
|
+
When enabled, users can shake their device to open a debug menu that shows:
|
|
1542
|
+
- Current bundle information
|
|
1543
|
+
- Available bundles
|
|
1544
|
+
- Options to switch bundles manually
|
|
1545
|
+
- Update status
|
|
1546
|
+
|
|
1547
|
+
This is useful during development and testing to:
|
|
1548
|
+
- Quickly test different bundle versions
|
|
1549
|
+
- Debug update flows
|
|
1550
|
+
- Switch between production and test bundles
|
|
1551
|
+
- Verify bundle installations
|
|
1552
|
+
|
|
1553
|
+
**Important:** Disable this in production builds or only enable for internal testers.
|
|
1554
|
+
|
|
1555
|
+
Can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
|
|
1556
|
+
|
|
1557
|
+
| Param | Type |
|
|
1558
|
+
| ------------- | ------------------------------------------------------------------- |
|
|
1559
|
+
| **`options`** | <code><a href="#setshakemenuoptions">SetShakeMenuOptions</a></code> |
|
|
1560
|
+
|
|
1561
|
+
**Since:** 7.5.0
|
|
1562
|
+
|
|
1563
|
+
--------------------
|
|
1564
|
+
|
|
1565
|
+
|
|
1566
|
+
#### isShakeMenuEnabled()
|
|
1567
|
+
|
|
1568
|
+
```typescript
|
|
1569
|
+
isShakeMenuEnabled() => Promise<ShakeMenuEnabled>
|
|
1570
|
+
```
|
|
1571
|
+
|
|
1572
|
+
Check if the shake gesture debug menu is currently enabled.
|
|
1573
|
+
|
|
1574
|
+
Returns the current state of the shake menu feature that can be toggled via
|
|
1575
|
+
{@link setShakeMenu} or configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
|
|
1576
|
+
|
|
1577
|
+
Use this to:
|
|
1578
|
+
- Check if debug features are enabled
|
|
1579
|
+
- Show/hide debug settings UI
|
|
1580
|
+
- Verify configuration during testing
|
|
1581
|
+
|
|
1582
|
+
**Returns:** <code>Promise<<a href="#shakemenuenabled">ShakeMenuEnabled</a>></code>
|
|
1583
|
+
|
|
1584
|
+
**Since:** 7.5.0
|
|
1585
|
+
|
|
1586
|
+
--------------------
|
|
1587
|
+
|
|
1588
|
+
|
|
1589
|
+
#### getAppId()
|
|
1590
|
+
|
|
1591
|
+
```typescript
|
|
1592
|
+
getAppId() => Promise<GetAppIdRes>
|
|
1593
|
+
```
|
|
1594
|
+
|
|
1595
|
+
Get the currently configured App ID used for update server communication.
|
|
1596
|
+
|
|
1597
|
+
Returns the App ID that identifies this app to the update server. This can be:
|
|
1598
|
+
- The value set via {@link setAppId}, or
|
|
1599
|
+
- The {@link PluginsConfig.CapacitorUpdater.appId} config value, or
|
|
1600
|
+
- The default app identifier from your native app configuration
|
|
1601
|
+
|
|
1602
|
+
Use this to:
|
|
1603
|
+
- Verify which App ID is being used for updates
|
|
1604
|
+
- Debug update delivery issues
|
|
1605
|
+
- Display app configuration in debug screens
|
|
1606
|
+
- Confirm App ID after calling {@link setAppId}
|
|
949
1607
|
|
|
1608
|
+
**Returns:** <code>Promise<<a href="#getappidres">GetAppIdRes</a>></code>
|
|
950
1609
|
|
|
951
|
-
|
|
1610
|
+
**Since:** 7.14.0
|
|
1611
|
+
|
|
1612
|
+
--------------------
|
|
1613
|
+
|
|
1614
|
+
|
|
1615
|
+
#### setAppId(...)
|
|
1616
|
+
|
|
1617
|
+
```typescript
|
|
1618
|
+
setAppId(options: SetAppIdOptions) => Promise<void>
|
|
1619
|
+
```
|
|
1620
|
+
|
|
1621
|
+
Dynamically change the App ID used for update server communication.
|
|
1622
|
+
|
|
1623
|
+
This overrides the App ID used to identify your app to the update server, allowing you
|
|
1624
|
+
to switch between different app configurations at runtime (e.g., production vs staging
|
|
1625
|
+
app IDs, or multi-tenant configurations).
|
|
1626
|
+
|
|
1627
|
+
**Requirements:**
|
|
1628
|
+
- {@link PluginsConfig.CapacitorUpdater.allowModifyAppId} must be set to `true`
|
|
1629
|
+
|
|
1630
|
+
**Important considerations:**
|
|
1631
|
+
- Changing the App ID will affect which updates this device receives
|
|
1632
|
+
- The new App ID must exist on your update server
|
|
1633
|
+
- This is primarily for advanced use cases (multi-tenancy, environment switching)
|
|
1634
|
+
- Most apps should use the config-based {@link PluginsConfig.CapacitorUpdater.appId} instead
|
|
1635
|
+
|
|
1636
|
+
| Param | Type |
|
|
1637
|
+
| ------------- | ----------------------------------------------------------- |
|
|
1638
|
+
| **`options`** | <code><a href="#setappidoptions">SetAppIdOptions</a></code> |
|
|
1639
|
+
|
|
1640
|
+
**Since:** 7.14.0
|
|
1641
|
+
|
|
1642
|
+
--------------------
|
|
1643
|
+
|
|
1644
|
+
|
|
1645
|
+
#### Interfaces
|
|
1646
|
+
|
|
1647
|
+
|
|
1648
|
+
##### AppReadyResult
|
|
952
1649
|
|
|
953
1650
|
| Prop | Type |
|
|
954
1651
|
| ------------ | ------------------------------------------------- |
|
|
955
1652
|
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> |
|
|
956
1653
|
|
|
957
1654
|
|
|
958
|
-
|
|
1655
|
+
##### BundleInfo
|
|
959
1656
|
|
|
960
1657
|
| Prop | Type |
|
|
961
1658
|
| ---------------- | ----------------------------------------------------- |
|
|
@@ -966,66 +1663,79 @@ Returns null if no next bundle is set.
|
|
|
966
1663
|
| **`status`** | <code><a href="#bundlestatus">BundleStatus</a></code> |
|
|
967
1664
|
|
|
968
1665
|
|
|
969
|
-
|
|
1666
|
+
##### UpdateUrl
|
|
970
1667
|
|
|
971
1668
|
| Prop | Type |
|
|
972
1669
|
| --------- | ------------------- |
|
|
973
1670
|
| **`url`** | <code>string</code> |
|
|
974
1671
|
|
|
975
1672
|
|
|
976
|
-
|
|
1673
|
+
##### StatsUrl
|
|
977
1674
|
|
|
978
1675
|
| Prop | Type |
|
|
979
1676
|
| --------- | ------------------- |
|
|
980
1677
|
| **`url`** | <code>string</code> |
|
|
981
1678
|
|
|
982
1679
|
|
|
983
|
-
|
|
1680
|
+
##### ChannelUrl
|
|
984
1681
|
|
|
985
1682
|
| Prop | Type |
|
|
986
1683
|
| --------- | ------------------- |
|
|
987
1684
|
| **`url`** | <code>string</code> |
|
|
988
1685
|
|
|
989
1686
|
|
|
990
|
-
|
|
1687
|
+
##### DownloadOptions
|
|
1688
|
+
|
|
1689
|
+
This URL and versions are used to download the bundle from the server, If you use backend all information will be given by the method getLatest.
|
|
1690
|
+
If you don't use backend, you need to provide the URL and version of the bundle. Checksum and sessionKey are required if you encrypted the bundle with the CLI command encrypt, you should receive them as result of the command.
|
|
1691
|
+
|
|
1692
|
+
| Prop | Type | Description | Default | Since |
|
|
1693
|
+
| ---------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- |
|
|
1694
|
+
| **`url`** | <code>string</code> | The URL of the bundle zip file (e.g: dist.zip) to be downloaded. (This can be any URL. E.g: Amazon S3, a GitHub tag, any other place you've hosted your bundle.) | | |
|
|
1695
|
+
| **`version`** | <code>string</code> | The version code/name of this bundle/version | | |
|
|
1696
|
+
| **`sessionKey`** | <code>string</code> | The session key for the update, when the bundle is encrypted with a session key | <code>undefined</code> | 4.0.0 |
|
|
1697
|
+
| **`checksum`** | <code>string</code> | The checksum for the update, it should be in sha256 and encrypted with private key if the bundle is encrypted | <code>undefined</code> | 4.0.0 |
|
|
1698
|
+
| **`manifest`** | <code>ManifestEntry[]</code> | The manifest for multi-file downloads | <code>undefined</code> | 6.1.0 |
|
|
991
1699
|
|
|
992
|
-
| Prop | Type | Description | Default | Since |
|
|
993
|
-
| ---------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- |
|
|
994
|
-
| **`url`** | <code>string</code> | The URL of the bundle zip file (e.g: dist.zip) to be downloaded. (This can be any URL. E.g: Amazon S3, a GitHub tag, any other place you've hosted your bundle.) | | |
|
|
995
|
-
| **`version`** | <code>string</code> | The version code/name of this bundle/version | | |
|
|
996
|
-
| **`sessionKey`** | <code>string</code> | The session key for the update | <code>undefined</code> | 4.0.0 |
|
|
997
|
-
| **`checksum`** | <code>string</code> | The checksum for the update | <code>undefined</code> | 4.0.0 |
|
|
998
1700
|
|
|
1701
|
+
##### ManifestEntry
|
|
1702
|
+
|
|
1703
|
+
| Prop | Type |
|
|
1704
|
+
| ------------------ | --------------------------- |
|
|
1705
|
+
| **`file_name`** | <code>string \| null</code> |
|
|
1706
|
+
| **`file_hash`** | <code>string \| null</code> |
|
|
1707
|
+
| **`download_url`** | <code>string \| null</code> |
|
|
999
1708
|
|
|
1000
|
-
|
|
1709
|
+
|
|
1710
|
+
##### BundleId
|
|
1001
1711
|
|
|
1002
1712
|
| Prop | Type |
|
|
1003
1713
|
| -------- | ------------------- |
|
|
1004
1714
|
| **`id`** | <code>string</code> |
|
|
1005
1715
|
|
|
1006
1716
|
|
|
1007
|
-
|
|
1717
|
+
##### BundleListResult
|
|
1008
1718
|
|
|
1009
1719
|
| Prop | Type |
|
|
1010
1720
|
| ------------- | ------------------------- |
|
|
1011
1721
|
| **`bundles`** | <code>BundleInfo[]</code> |
|
|
1012
1722
|
|
|
1013
1723
|
|
|
1014
|
-
|
|
1724
|
+
##### ListOptions
|
|
1015
1725
|
|
|
1016
1726
|
| Prop | Type | Description | Default | Since |
|
|
1017
1727
|
| --------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------ |
|
|
1018
1728
|
| **`raw`** | <code>boolean</code> | Whether to return the raw bundle list or the manifest. If true, the list will attempt to read the internal database instead of files on disk. | <code>false</code> | 6.14.0 |
|
|
1019
1729
|
|
|
1020
1730
|
|
|
1021
|
-
|
|
1731
|
+
##### ResetOptions
|
|
1022
1732
|
|
|
1023
1733
|
| Prop | Type |
|
|
1024
1734
|
| ---------------------- | -------------------- |
|
|
1025
1735
|
| **`toLastSuccessful`** | <code>boolean</code> |
|
|
1026
1736
|
|
|
1027
1737
|
|
|
1028
|
-
|
|
1738
|
+
##### CurrentBundleResult
|
|
1029
1739
|
|
|
1030
1740
|
| Prop | Type |
|
|
1031
1741
|
| ------------ | ------------------------------------------------- |
|
|
@@ -1033,14 +1743,14 @@ Returns null if no next bundle is set.
|
|
|
1033
1743
|
| **`native`** | <code>string</code> |
|
|
1034
1744
|
|
|
1035
1745
|
|
|
1036
|
-
|
|
1746
|
+
##### MultiDelayConditions
|
|
1037
1747
|
|
|
1038
1748
|
| Prop | Type |
|
|
1039
1749
|
| --------------------- | ----------------------------- |
|
|
1040
1750
|
| **`delayConditions`** | <code>DelayCondition[]</code> |
|
|
1041
1751
|
|
|
1042
1752
|
|
|
1043
|
-
|
|
1753
|
+
##### DelayCondition
|
|
1044
1754
|
|
|
1045
1755
|
| Prop | Type | Description |
|
|
1046
1756
|
| ----------- | --------------------------------------------------------- | ---------------------------------------- |
|
|
@@ -1048,38 +1758,32 @@ Returns null if no next bundle is set.
|
|
|
1048
1758
|
| **`value`** | <code>string</code> | |
|
|
1049
1759
|
|
|
1050
1760
|
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
| Prop | Type | Description | Since |
|
|
1054
|
-
| ---------------- | ---------------------------- | -------------------------- | ----- |
|
|
1055
|
-
| **`version`** | <code>string</code> | Result of getLatest method | 4.0.0 |
|
|
1056
|
-
| **`checksum`** | <code>string</code> | | 6 |
|
|
1057
|
-
| **`major`** | <code>boolean</code> | | |
|
|
1058
|
-
| **`message`** | <code>string</code> | | |
|
|
1059
|
-
| **`sessionKey`** | <code>string</code> | | |
|
|
1060
|
-
| **`error`** | <code>string</code> | | |
|
|
1061
|
-
| **`old`** | <code>string</code> | | |
|
|
1062
|
-
| **`url`** | <code>string</code> | | |
|
|
1063
|
-
| **`manifest`** | <code>ManifestEntry[]</code> | | 6.1 |
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
#### ManifestEntry
|
|
1761
|
+
##### LatestVersion
|
|
1067
1762
|
|
|
1068
|
-
| Prop
|
|
1069
|
-
|
|
|
1070
|
-
| **`
|
|
1071
|
-
| **`
|
|
1072
|
-
| **`
|
|
1763
|
+
| Prop | Type | Description | Since |
|
|
1764
|
+
| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
|
|
1765
|
+
| **`version`** | <code>string</code> | Result of getLatest method | 4.0.0 |
|
|
1766
|
+
| **`checksum`** | <code>string</code> | | 6 |
|
|
1767
|
+
| **`breaking`** | <code>boolean</code> | Indicates whether the update was flagged as breaking by the backend. | 7.22.0 |
|
|
1768
|
+
| **`major`** | <code>boolean</code> | | |
|
|
1769
|
+
| **`message`** | <code>string</code> | Optional message from the server. When no new version is available, this will be "No new version available". | |
|
|
1770
|
+
| **`sessionKey`** | <code>string</code> | | |
|
|
1771
|
+
| **`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 | |
|
|
1772
|
+
| **`old`** | <code>string</code> | The previous/current version name (provided for reference). | |
|
|
1773
|
+
| **`url`** | <code>string</code> | Download URL for the bundle (when a new version is available). | |
|
|
1774
|
+
| **`manifest`** | <code>ManifestEntry[]</code> | File list for partial updates (when using multi-file downloads). | 6.1 |
|
|
1775
|
+
| **`link`** | <code>string</code> | Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release). | 7.35.0 |
|
|
1776
|
+
| **`comment`** | <code>string</code> | Optional comment or description for this bundle version. | 7.35.0 |
|
|
1073
1777
|
|
|
1074
1778
|
|
|
1075
|
-
|
|
1779
|
+
##### GetLatestOptions
|
|
1076
1780
|
|
|
1077
1781
|
| Prop | Type | Description | Default | Since |
|
|
1078
1782
|
| ------------- | ------------------- | ----------------------------------------------------------------------------------------------- | ---------------------- | ----- |
|
|
1079
1783
|
| **`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 |
|
|
1080
1784
|
|
|
1081
1785
|
|
|
1082
|
-
|
|
1786
|
+
##### ChannelRes
|
|
1083
1787
|
|
|
1084
1788
|
| Prop | Type | Description | Since |
|
|
1085
1789
|
| ------------- | ------------------- | ----------------------------- | ----- |
|
|
@@ -1088,7 +1792,7 @@ Returns null if no next bundle is set.
|
|
|
1088
1792
|
| **`message`** | <code>string</code> | | |
|
|
1089
1793
|
|
|
1090
1794
|
|
|
1091
|
-
|
|
1795
|
+
##### SetChannelOptions
|
|
1092
1796
|
|
|
1093
1797
|
| Prop | Type |
|
|
1094
1798
|
| ----------------------- | -------------------- |
|
|
@@ -1096,14 +1800,14 @@ Returns null if no next bundle is set.
|
|
|
1096
1800
|
| **`triggerAutoUpdate`** | <code>boolean</code> |
|
|
1097
1801
|
|
|
1098
1802
|
|
|
1099
|
-
|
|
1803
|
+
##### UnsetChannelOptions
|
|
1100
1804
|
|
|
1101
1805
|
| Prop | Type |
|
|
1102
1806
|
| ----------------------- | -------------------- |
|
|
1103
1807
|
| **`triggerAutoUpdate`** | <code>boolean</code> |
|
|
1104
1808
|
|
|
1105
1809
|
|
|
1106
|
-
|
|
1810
|
+
##### GetChannelRes
|
|
1107
1811
|
|
|
1108
1812
|
| Prop | Type | Description | Since |
|
|
1109
1813
|
| -------------- | -------------------- | ----------------------------- | ----- |
|
|
@@ -1114,49 +1818,66 @@ Returns null if no next bundle is set.
|
|
|
1114
1818
|
| **`allowSet`** | <code>boolean</code> | | |
|
|
1115
1819
|
|
|
1116
1820
|
|
|
1117
|
-
|
|
1821
|
+
##### ListChannelsResult
|
|
1118
1822
|
|
|
1119
|
-
| Prop | Type |
|
|
1120
|
-
| -------------- |
|
|
1121
|
-
| **`
|
|
1823
|
+
| Prop | Type | Description | Since |
|
|
1824
|
+
| -------------- | -------------------------- | -------------------------- | ----- |
|
|
1825
|
+
| **`channels`** | <code>ChannelInfo[]</code> | List of available channels | 7.5.0 |
|
|
1826
|
+
|
|
1827
|
+
|
|
1828
|
+
##### ChannelInfo
|
|
1829
|
+
|
|
1830
|
+
| Prop | Type | Description | Since |
|
|
1831
|
+
| -------------------- | -------------------- | ----------------------------------------------- | ----- |
|
|
1832
|
+
| **`id`** | <code>string</code> | The channel ID | 7.5.0 |
|
|
1833
|
+
| **`name`** | <code>string</code> | The channel name | 7.5.0 |
|
|
1834
|
+
| **`public`** | <code>boolean</code> | Whether this is a public channel | 7.5.0 |
|
|
1835
|
+
| **`allow_self_set`** | <code>boolean</code> | Whether devices can self-assign to this channel | 7.5.0 |
|
|
1836
|
+
|
|
1837
|
+
|
|
1838
|
+
##### SetCustomIdOptions
|
|
1839
|
+
|
|
1840
|
+
| Prop | Type | Description |
|
|
1841
|
+
| -------------- | ------------------- | --------------------------------------------------------------------------------------------- |
|
|
1842
|
+
| **`customId`** | <code>string</code> | Custom identifier to associate with the device. Use an empty string to clear any saved value. |
|
|
1122
1843
|
|
|
1123
1844
|
|
|
1124
|
-
|
|
1845
|
+
##### BuiltinVersion
|
|
1125
1846
|
|
|
1126
1847
|
| Prop | Type |
|
|
1127
1848
|
| ------------- | ------------------- |
|
|
1128
1849
|
| **`version`** | <code>string</code> |
|
|
1129
1850
|
|
|
1130
1851
|
|
|
1131
|
-
|
|
1852
|
+
##### DeviceId
|
|
1132
1853
|
|
|
1133
1854
|
| Prop | Type |
|
|
1134
1855
|
| -------------- | ------------------- |
|
|
1135
1856
|
| **`deviceId`** | <code>string</code> |
|
|
1136
1857
|
|
|
1137
1858
|
|
|
1138
|
-
|
|
1859
|
+
##### PluginVersion
|
|
1139
1860
|
|
|
1140
1861
|
| Prop | Type |
|
|
1141
1862
|
| ------------- | ------------------- |
|
|
1142
1863
|
| **`version`** | <code>string</code> |
|
|
1143
1864
|
|
|
1144
1865
|
|
|
1145
|
-
|
|
1866
|
+
##### AutoUpdateEnabled
|
|
1146
1867
|
|
|
1147
1868
|
| Prop | Type |
|
|
1148
1869
|
| ------------- | -------------------- |
|
|
1149
1870
|
| **`enabled`** | <code>boolean</code> |
|
|
1150
1871
|
|
|
1151
1872
|
|
|
1152
|
-
|
|
1873
|
+
##### PluginListenerHandle
|
|
1153
1874
|
|
|
1154
1875
|
| Prop | Type |
|
|
1155
1876
|
| ------------ | ----------------------------------------- |
|
|
1156
1877
|
| **`remove`** | <code>() => Promise<void></code> |
|
|
1157
1878
|
|
|
1158
1879
|
|
|
1159
|
-
|
|
1880
|
+
##### DownloadEvent
|
|
1160
1881
|
|
|
1161
1882
|
| Prop | Type | Description | Since |
|
|
1162
1883
|
| ------------- | ------------------------------------------------- | ---------------------------------------------- | ----- |
|
|
@@ -1164,49 +1885,49 @@ Returns null if no next bundle is set.
|
|
|
1164
1885
|
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | | |
|
|
1165
1886
|
|
|
1166
1887
|
|
|
1167
|
-
|
|
1888
|
+
##### NoNeedEvent
|
|
1168
1889
|
|
|
1169
1890
|
| Prop | Type | Description | Since |
|
|
1170
1891
|
| ------------ | ------------------------------------------------- | ---------------------------------------------- | ----- |
|
|
1171
1892
|
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Current status of download, between 0 and 100. | 4.0.0 |
|
|
1172
1893
|
|
|
1173
1894
|
|
|
1174
|
-
|
|
1895
|
+
##### UpdateAvailableEvent
|
|
1175
1896
|
|
|
1176
1897
|
| Prop | Type | Description | Since |
|
|
1177
1898
|
| ------------ | ------------------------------------------------- | ---------------------------------------------- | ----- |
|
|
1178
1899
|
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Current status of download, between 0 and 100. | 4.0.0 |
|
|
1179
1900
|
|
|
1180
1901
|
|
|
1181
|
-
|
|
1902
|
+
##### DownloadCompleteEvent
|
|
1182
1903
|
|
|
1183
1904
|
| Prop | Type | Description | Since |
|
|
1184
1905
|
| ------------ | ------------------------------------------------- | ------------------------------------ | ----- |
|
|
1185
1906
|
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a new update is available. | 4.0.0 |
|
|
1186
1907
|
|
|
1187
1908
|
|
|
1188
|
-
|
|
1909
|
+
##### MajorAvailableEvent
|
|
1189
1910
|
|
|
1190
|
-
| Prop | Type | Description
|
|
1191
|
-
| ------------- | ------------------- |
|
|
1192
|
-
| **`version`** | <code>string</code> | Emit when a
|
|
1911
|
+
| Prop | Type | Description | Since |
|
|
1912
|
+
| ------------- | ------------------- | ----------------------------------------- | ----- |
|
|
1913
|
+
| **`version`** | <code>string</code> | Emit when a breaking update is available. | 4.0.0 |
|
|
1193
1914
|
|
|
1194
1915
|
|
|
1195
|
-
|
|
1916
|
+
##### UpdateFailedEvent
|
|
1196
1917
|
|
|
1197
1918
|
| Prop | Type | Description | Since |
|
|
1198
1919
|
| ------------ | ------------------------------------------------- | ------------------------------------- | ----- |
|
|
1199
1920
|
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a update failed to install. | 4.0.0 |
|
|
1200
1921
|
|
|
1201
1922
|
|
|
1202
|
-
|
|
1923
|
+
##### DownloadFailedEvent
|
|
1203
1924
|
|
|
1204
1925
|
| Prop | Type | Description | Since |
|
|
1205
1926
|
| ------------- | ------------------- | -------------------------- | ----- |
|
|
1206
1927
|
| **`version`** | <code>string</code> | Emit when a download fail. | 4.0.0 |
|
|
1207
1928
|
|
|
1208
1929
|
|
|
1209
|
-
|
|
1930
|
+
##### AppReadyEvent
|
|
1210
1931
|
|
|
1211
1932
|
| Prop | Type | Description | Since |
|
|
1212
1933
|
| ------------ | ------------------------------------------------- | ------------------------------------- | ----- |
|
|
@@ -1214,25 +1935,73 @@ Returns null if no next bundle is set.
|
|
|
1214
1935
|
| **`status`** | <code>string</code> | | |
|
|
1215
1936
|
|
|
1216
1937
|
|
|
1217
|
-
|
|
1938
|
+
##### ChannelPrivateEvent
|
|
1939
|
+
|
|
1940
|
+
| Prop | Type | Description | Since |
|
|
1941
|
+
| ------------- | ------------------- | ----------------------------------------------------------------------------------- | ------ |
|
|
1942
|
+
| **`channel`** | <code>string</code> | Emitted when attempting to set a channel that doesn't allow device self-assignment. | 7.34.0 |
|
|
1943
|
+
| **`message`** | <code>string</code> | | |
|
|
1944
|
+
|
|
1945
|
+
|
|
1946
|
+
##### AutoUpdateAvailable
|
|
1218
1947
|
|
|
1219
1948
|
| Prop | Type |
|
|
1220
1949
|
| --------------- | -------------------- |
|
|
1221
1950
|
| **`available`** | <code>boolean</code> |
|
|
1222
1951
|
|
|
1223
1952
|
|
|
1224
|
-
|
|
1953
|
+
##### SetShakeMenuOptions
|
|
1954
|
+
|
|
1955
|
+
| Prop | Type |
|
|
1956
|
+
| ------------- | -------------------- |
|
|
1957
|
+
| **`enabled`** | <code>boolean</code> |
|
|
1225
1958
|
|
|
1226
1959
|
|
|
1227
|
-
|
|
1960
|
+
##### ShakeMenuEnabled
|
|
1961
|
+
|
|
1962
|
+
| Prop | Type |
|
|
1963
|
+
| ------------- | -------------------- |
|
|
1964
|
+
| **`enabled`** | <code>boolean</code> |
|
|
1965
|
+
|
|
1966
|
+
|
|
1967
|
+
##### GetAppIdRes
|
|
1968
|
+
|
|
1969
|
+
| Prop | Type |
|
|
1970
|
+
| ----------- | ------------------- |
|
|
1971
|
+
| **`appId`** | <code>string</code> |
|
|
1972
|
+
|
|
1973
|
+
|
|
1974
|
+
##### SetAppIdOptions
|
|
1975
|
+
|
|
1976
|
+
| Prop | Type |
|
|
1977
|
+
| ----------- | ------------------- |
|
|
1978
|
+
| **`appId`** | <code>string</code> |
|
|
1979
|
+
|
|
1980
|
+
|
|
1981
|
+
#### Type Aliases
|
|
1982
|
+
|
|
1983
|
+
|
|
1984
|
+
##### BundleStatus
|
|
1985
|
+
|
|
1986
|
+
pending: The bundle is pending to be **SET** as the next bundle.
|
|
1987
|
+
downloading: The bundle is being downloaded.
|
|
1988
|
+
success: The bundle has been downloaded and is ready to be **SET** as the next bundle.
|
|
1989
|
+
error: The bundle has failed to download.
|
|
1228
1990
|
|
|
1229
1991
|
<code>'success' | 'error' | 'pending' | 'downloading'</code>
|
|
1230
1992
|
|
|
1231
1993
|
|
|
1232
|
-
|
|
1994
|
+
##### DelayUntilNext
|
|
1233
1995
|
|
|
1234
1996
|
<code>'background' | 'kill' | 'nativeVersion' | 'date'</code>
|
|
1235
1997
|
|
|
1998
|
+
|
|
1999
|
+
##### BreakingAvailableEvent
|
|
2000
|
+
|
|
2001
|
+
Payload emitted by {@link CapacitorUpdaterPlugin.addListener} with `breakingAvailable`.
|
|
2002
|
+
|
|
2003
|
+
<code><a href="#majoravailableevent">MajorAvailableEvent</a></code>
|
|
2004
|
+
|
|
1236
2005
|
</docgen-api>
|
|
1237
2006
|
|
|
1238
2007
|
### Listen to download events
|