@capgo/capacitor-updater 7.45.10 → 7.50.2
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/Package.swift +1 -1
- package/README.md +510 -92
- package/android/src/main/java/ee/forgr/capacitor_updater/AndroidAppExitReporter.java +92 -0
- package/android/src/main/java/ee/forgr/capacitor_updater/CapacitorUpdaterPlugin.java +3192 -777
- package/android/src/main/java/ee/forgr/capacitor_updater/CapgoUpdater.java +798 -299
- package/android/src/main/java/ee/forgr/capacitor_updater/DeviceIdHelper.java +45 -30
- package/android/src/main/java/ee/forgr/capacitor_updater/DownloadService.java +46 -28
- package/android/src/main/java/ee/forgr/capacitor_updater/DownloadWorkerManager.java +2 -0
- package/android/src/main/java/ee/forgr/capacitor_updater/ShakeDetector.java +3 -3
- package/android/src/main/java/ee/forgr/capacitor_updater/ShakeMenu.java +359 -25
- package/android/src/main/java/ee/forgr/capacitor_updater/ThreeFingerPinchDetector.java +323 -0
- package/dist/docs.json +1283 -169
- package/dist/esm/definitions.d.ts +621 -44
- package/dist/esm/definitions.js.map +1 -1
- package/dist/esm/web.d.ts +11 -1
- package/dist/esm/web.js +59 -1
- package/dist/esm/web.js.map +1 -1
- package/dist/plugin.cjs.js +59 -1
- package/dist/plugin.cjs.js.map +1 -1
- package/dist/plugin.js +59 -1
- package/dist/plugin.js.map +1 -1
- package/ios/Sources/CapacitorUpdaterPlugin/AES.swift +0 -1
- package/ios/Sources/CapacitorUpdaterPlugin/AppHealthTracker.swift +82 -0
- package/ios/Sources/CapacitorUpdaterPlugin/BigInt.swift +0 -16
- package/ios/Sources/CapacitorUpdaterPlugin/BundleInfo.swift +2 -2
- package/ios/Sources/CapacitorUpdaterPlugin/BundleStatus.swift +78 -2
- package/ios/Sources/CapacitorUpdaterPlugin/CapacitorUpdaterPlugin.swift +2116 -223
- package/ios/Sources/CapacitorUpdaterPlugin/CapgoUpdater.swift +997 -332
- package/ios/Sources/CapacitorUpdaterPlugin/CryptoCipher.swift +0 -1
- package/ios/Sources/CapacitorUpdaterPlugin/InternalUtils.swift +78 -1
- package/ios/Sources/CapacitorUpdaterPlugin/ShakeMenu.swift +418 -36
- package/ios/Sources/CapacitorUpdaterPlugin/WebViewStatsReporter.swift +276 -0
- package/package.json +15 -3
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# Capacitor updater
|
|
2
|
-
|
|
2
|
+
<a href="https://capgo.app/"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-updater" alt="Capgo - Instant updates for Capacitor" /></a>
|
|
3
3
|
[](https://discord.com/invite/VnYRvBfgA6)
|
|
4
4
|
<a href="https://discord.com/invite/VnYRvBfgA6"><img src="https://img.shields.io/discord/912707985829163099?color=%237289DA&label=Discord" alt="Discord">
|
|
5
5
|
[](https://www.npmjs.com/package/@capgo/capacitor-updater)
|
|
@@ -79,7 +79,7 @@ First follow the migration guide of Capacitor:
|
|
|
79
79
|
- **Channel storage change**: `setChannel()` now stores channel assignments locally on the device instead of in the cloud. This provides better offline support and reduces backend load.
|
|
80
80
|
- Channel assignments persist between app restarts
|
|
81
81
|
- Use `unsetChannel()` to clear the local assignment and revert to `defaultChannel`
|
|
82
|
-
- Old devices (< v7.34.0)
|
|
82
|
+
- Old devices (< v7.34.0) use now a KV storage to prevent overload the primary DB of Capgo
|
|
83
83
|
- **New event**: Listen to the `channelPrivate` event to handle cases where a user tries to assign themselves to a private channel (one that doesn't allow self-assignment). See example in the `setChannel()` documentation above.
|
|
84
84
|
|
|
85
85
|
## Migration to v7
|
|
@@ -133,6 +133,20 @@ We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bun
|
|
|
133
133
|
|
|
134
134
|
## Installation
|
|
135
135
|
|
|
136
|
+
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Then use the following prompt:
|
|
143
|
+
|
|
144
|
+
```text
|
|
145
|
+
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-updater` plugin in my project.
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
|
|
149
|
+
|
|
136
150
|
Step by step here: [Getting started](https://capgo.app/docs/getting-started/add-an-app/)
|
|
137
151
|
|
|
138
152
|
Or
|
|
@@ -286,44 +300,46 @@ Downgrading to a previous version of the updater plugin is not supported.
|
|
|
286
300
|
|
|
287
301
|
CapacitorUpdater can be configured with these options:
|
|
288
302
|
|
|
289
|
-
| Prop | Type
|
|
290
|
-
| ------------------------------- |
|
|
291
|
-
| **`appReadyTimeout`** | <code>number</code>
|
|
292
|
-
| **`responseTimeout`** | <code>number</code>
|
|
293
|
-
| **`autoDeleteFailed`** | <code>boolean</code>
|
|
294
|
-
| **`autoDeletePrevious`** | <code>boolean</code>
|
|
295
|
-
| **`autoUpdate`** | <code>boolean</code>
|
|
296
|
-
| **`resetWhenUpdate`** | <code>boolean</code>
|
|
297
|
-
| **`updateUrl`** | <code>string</code>
|
|
298
|
-
| **`channelUrl`** | <code>string</code>
|
|
299
|
-
| **`statsUrl`** | <code>string</code>
|
|
300
|
-
| **`publicKey`** | <code>string</code>
|
|
301
|
-
| **`version`** | <code>string</code>
|
|
302
|
-
| **`directUpdate`** | <code>boolean \| 'always' \| 'atInstall' \| 'onLaunch'</code>
|
|
303
|
-
| **`autoSplashscreen`** | <code>boolean</code>
|
|
304
|
-
| **`autoSplashscreenLoader`** | <code>boolean</code>
|
|
305
|
-
| **`autoSplashscreenTimeout`** | <code>number</code>
|
|
306
|
-
| **`periodCheckDelay`** | <code>number</code>
|
|
307
|
-
| **`localS3`** | <code>boolean</code>
|
|
308
|
-
| **`localHost`** | <code>string</code>
|
|
309
|
-
| **`localWebHost`** | <code>string</code>
|
|
310
|
-
| **`localSupa`** | <code>string</code>
|
|
311
|
-
| **`localSupaAnon`** | <code>string</code>
|
|
312
|
-
| **`localApi`** | <code>string</code>
|
|
313
|
-
| **`localApiFiles`** | <code>string</code>
|
|
314
|
-
| **`allowModifyUrl`** | <code>boolean</code>
|
|
315
|
-
| **`allowModifyAppId`** | <code>boolean</code>
|
|
316
|
-
| **`allowManualBundleError`** | <code>boolean</code>
|
|
317
|
-
| **`
|
|
318
|
-
| **`
|
|
319
|
-
| **`
|
|
320
|
-
| **`
|
|
321
|
-
| **`
|
|
322
|
-
| **`
|
|
323
|
-
| **`
|
|
324
|
-
| **`
|
|
325
|
-
| **`
|
|
326
|
-
| **`
|
|
303
|
+
| Prop | Type | Description | Default | Since |
|
|
304
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------- |
|
|
305
|
+
| **`appReadyTimeout`** | <code>number</code> | Configure the number of milliseconds the native plugin should wait before considering an update 'failed'. Only available for Android and iOS. | <code>10000 // (10 seconds)</code> | |
|
|
306
|
+
| **`responseTimeout`** | <code>number</code> | Configure the number of seconds the native plugin should wait before considering API timeout. Only available for Android and iOS. | <code>20 // (20 second)</code> | |
|
|
307
|
+
| **`autoDeleteFailed`** | <code>boolean</code> | Configure whether the plugin should use automatically delete failed bundles. Only available for Android and iOS. | <code>true</code> | |
|
|
308
|
+
| **`autoDeletePrevious`** | <code>boolean</code> | Configure whether the plugin should use automatically delete previous bundles after a successful update. Only available for Android and iOS. | <code>true</code> | |
|
|
309
|
+
| **`autoUpdate`** | <code>boolean \| 'always' \| 'off' \| 'atBackground' \| 'atInstall' \| 'onLaunch' \| 'onlyDownload'</code> | Configure how the plugin checks for, downloads, and applies live updates. The plugin checks for updates when the app moves to the foreground and, if {@link periodCheckDelay} is set, on a repeating timer while the app stays open. Boolean values keep their existing behavior: - `true`: Same as `"atBackground"`. - `false`: Same as `"off"`. String values merge the previous Auto Update and Direct Update configuration: - `"off"`: Disable automatic update checks. - `"atBackground"`: Check and download automatically on each foreground check, then apply the update the next time the app moves to background. - `"atInstall"`: Apply immediately only after a fresh install or native app store update; otherwise use `"atBackground"` behavior. - `"onLaunch"`: Apply immediately only when the app is brought to the foreground from a killed state (cold start). After that first check, fall back to `"atBackground"` behavior. - `"always"`: Check on every foreground transition and apply immediately whenever an update is available. - `"onlyDownload"`: Check and download automatically, emit `updateAvailable`, and never set the next bundle or apply an update automatically. Only available for Android and iOS. | <code>true</code> | |
|
|
310
|
+
| **`resetWhenUpdate`** | <code>boolean</code> | Automatically delete previous downloaded bundles when a newer native app bundle is installed to the device. Setting this to false can broke the auto update flow if the user download from the store a native app bundle that is older than the current downloaded bundle. Upload will be prevented by channel setting downgrade_under_native. Only available for Android and iOS. | <code>true</code> | |
|
|
311
|
+
| **`updateUrl`** | <code>string</code> | Configure the URL / endpoint to which update checks are sent. Only available for Android and iOS. | <code>https://plugin.capgo.app/updates</code> | |
|
|
312
|
+
| **`channelUrl`** | <code>string</code> | Configure the URL / endpoint for channel operations. Only available for Android and iOS. | <code>https://plugin.capgo.app/channel_self</code> | |
|
|
313
|
+
| **`statsUrl`** | <code>string</code> | Configure the URL / endpoint to which update statistics are sent. Only available for Android and iOS. Set to "" to disable stats reporting. Native stats include update lifecycle events, app health signals such as crashes, Android ANRs, low-memory exits, iOS memory warnings, and WebView health signals such as JavaScript errors, unhandled promise rejections, resource load failures, WebView renderer exits, and unclean WebView restarts when available. | <code>https://plugin.capgo.app/stats</code> | |
|
|
314
|
+
| **`publicKey`** | <code>string</code> | Configure the public key for end to end live update encryption Version 2 Only available for Android and iOS. | <code>undefined</code> | 6.2.0 |
|
|
315
|
+
| **`version`** | <code>string</code> | Configure the current version of the app. This will be used for the first update request. If not set, the plugin will get the version from the native code. Only available for Android and iOS. | <code>undefined</code> | 4.17.48 |
|
|
316
|
+
| **`directUpdate`** | <code>boolean \| 'always' \| 'atInstall' \| 'onLaunch'</code> | Configure when the plugin should direct install updates. Only for autoUpdate mode. | <code>false</code> | 5.1.0 |
|
|
317
|
+
| **`autoSplashscreen`** | <code>boolean</code> | Automatically handle splashscreen hiding when using directUpdate. When enabled, the plugin will automatically hide the splashscreen after updates are applied or when no update is needed. This removes the need to manually listen for appReady events and call SplashScreen.hide(). Only works when autoUpdate is set to "atInstall", "always", or "onLaunch", or when the deprecated directUpdate option is set to "atInstall", "always", "onLaunch", or true. Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false. Requires Auto Update and Direct Update behavior to be enabled. Only available for Android and iOS. | <code>false</code> | 7.6.0 |
|
|
318
|
+
| **`autoSplashscreenLoader`** | <code>boolean</code> | Display a native loading indicator on top of the splashscreen while automatic direct updates are running. Only takes effect when {@link autoSplashscreen} is enabled. Requires the @capacitor/splash-screen plugin to be installed and configured with launchAutoHide: false. Only available for Android and iOS. | <code>false</code> | 7.19.0 |
|
|
319
|
+
| **`autoSplashscreenTimeout`** | <code>number</code> | Automatically hide the splashscreen after the specified number of milliseconds when using automatic direct updates. If the timeout elapses, the update continues to download in the background while the splashscreen is dismissed. Set to `0` (zero) to disable the timeout. When the timeout fires, the direct update flow is skipped and the downloaded bundle is installed on the next background/launch. Requires {@link autoSplashscreen} to be enabled. Only available for Android and iOS. | <code>10000 // (10 seconds)</code> | 7.19.0 |
|
|
320
|
+
| **`periodCheckDelay`** | <code>number</code> | Configure the delay period for period update check. the unit is in seconds. Only available for Android and iOS. Cannot be less than 600 seconds (10 minutes). | <code>0 (disabled)</code> | |
|
|
321
|
+
| **`localS3`** | <code>boolean</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
|
|
322
|
+
| **`localHost`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
|
|
323
|
+
| **`localWebHost`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
|
|
324
|
+
| **`localSupa`** | <code>string</code> | Configure the CLI to use a local server for testing or self-hosted update server. | <code>undefined</code> | 4.17.48 |
|
|
325
|
+
| **`localSupaAnon`** | <code>string</code> | Configure the CLI to use a local server for testing. | <code>undefined</code> | 4.17.48 |
|
|
326
|
+
| **`localApi`** | <code>string</code> | Configure the CLI to use a local api for testing. | <code>undefined</code> | 6.3.3 |
|
|
327
|
+
| **`localApiFiles`** | <code>string</code> | Configure the CLI to use a local file api for testing. | <code>undefined</code> | 6.3.3 |
|
|
328
|
+
| **`allowModifyUrl`** | <code>boolean</code> | Allow the plugin to modify the updateUrl, statsUrl and channelUrl dynamically from the JavaScript side. | <code>false</code> | 5.4.0 |
|
|
329
|
+
| **`allowModifyAppId`** | <code>boolean</code> | Allow the plugin to modify the appId dynamically from the JavaScript side. | <code>false</code> | 7.14.0 |
|
|
330
|
+
| **`allowManualBundleError`** | <code>boolean</code> | Allow marking bundles as errored from JavaScript while using manual update flows. When enabled, {@link CapacitorUpdaterPlugin.setBundleError} can change a bundle status to `error`. | <code>false</code> | 7.20.0 |
|
|
331
|
+
| **`allowPreview`** | <code>boolean</code> | Allow JavaScript to start a native preview session and temporarily request updates for another app id. This is intended for trusted container apps that implement Expo Go-style preview flows. Only available for Android and iOS. | <code>false</code> | 8.47.0 |
|
|
332
|
+
| **`persistCustomId`** | <code>boolean</code> | Persist the customId set through {@link CapacitorUpdaterPlugin.setCustomId} across app restarts. Only available for Android and iOS. | <code>false (will be true by default in a future major release v8.x.x)</code> | 7.17.3 |
|
|
333
|
+
| **`persistModifyUrl`** | <code>boolean</code> | Persist the updateUrl, statsUrl and channelUrl set through {@link CapacitorUpdaterPlugin.setUpdateUrl}, {@link CapacitorUpdaterPlugin.setStatsUrl} and {@link CapacitorUpdaterPlugin.setChannelUrl} across app restarts. Only available for Android and iOS. | <code>false</code> | 7.20.0 |
|
|
334
|
+
| **`allowSetDefaultChannel`** | <code>boolean</code> | Allow or disallow the {@link CapacitorUpdaterPlugin.setChannel} method to modify the defaultChannel. When set to `false`, calling `setChannel()` will return an error with code `disabled_by_config`. | <code>true</code> | 7.34.0 |
|
|
335
|
+
| **`defaultChannel`** | <code>string</code> | Set the default channel for the app in the config. Case sensitive. This will setting will override the default channel set in the cloud, but will still respect overrides made in the cloud. This requires the channel to allow devices to self dissociate/associate in the channel settings. https://capgo.app/docs/public-api/channels/#channel-configuration-options | <code>undefined</code> | 5.5.0 |
|
|
336
|
+
| **`appId`** | <code>string</code> | Configure the app id for the app in the config. | <code>undefined</code> | 6.0.0 |
|
|
337
|
+
| **`keepUrlPathAfterReload`** | <code>boolean</code> | Configure the plugin to keep the URL path after a reload. WARNING: When a reload is triggered, 'window.history' will be cleared. | <code>false</code> | 6.8.0 |
|
|
338
|
+
| **`disableJSLogging`** | <code>boolean</code> | Disable the JavaScript logging of the plugin. if true, the plugin will not log to the JavaScript console. only the native log will be done | <code>false</code> | 7.3.0 |
|
|
339
|
+
| **`osLogging`** | <code>boolean</code> | Enable OS-level logging. When enabled, logs are written to the system log which can be inspected in production builds. - **iOS**: Uses os_log instead of Swift.print, logs accessible via Console.app or Instruments - **Android**: Logs to Logcat (android.util.Log) When set to false, system logging is disabled on both platforms (only JavaScript console logging will occur if enabled). This is useful for debugging production apps (App Store/TestFlight builds on iOS, or production APKs on Android). | <code>true</code> | 8.42.0 |
|
|
340
|
+
| **`shakeMenu`** | <code>boolean</code> | Enable the native preview menu gesture while a preview session is active. Outside preview sessions this preview menu is ignored, unless {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled. | <code>false</code> | 7.5.0 |
|
|
341
|
+
| **`shakeMenuGesture`** | <code><a href="#shakemenugesture">ShakeMenuGesture</a></code> | Choose which native gesture opens the preview/channel menu. This applies to both {@link PluginsConfig.CapacitorUpdater.shakeMenu} and {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}. Only available for Android and iOS. | <code>'shake'</code> | 8.48.0 |
|
|
342
|
+
| **`allowShakeChannelSelector`** | <code>boolean</code> | Enable the native menu gesture to show a channel selector menu for switching between update channels. If {@link PluginsConfig.CapacitorUpdater.shakeMenu} is also enabled while a preview session is active, the shake menu includes both preview actions and channel switching. The native gesture can be changed with {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}. Only available for Android and iOS. | <code>false</code> | 8.43.0 |
|
|
327
343
|
|
|
328
344
|
### Examples
|
|
329
345
|
|
|
@@ -337,7 +353,7 @@ In `capacitor.config.json`:
|
|
|
337
353
|
"responseTimeout": 10 // (10 second),
|
|
338
354
|
"autoDeleteFailed": false,
|
|
339
355
|
"autoDeletePrevious": false,
|
|
340
|
-
"autoUpdate":
|
|
356
|
+
"autoUpdate": "onlyDownload",
|
|
341
357
|
"resetWhenUpdate": false,
|
|
342
358
|
"updateUrl": https://example.com/api/auto_update,
|
|
343
359
|
"channelUrl": https://example.com/api/channel,
|
|
@@ -359,6 +375,7 @@ In `capacitor.config.json`:
|
|
|
359
375
|
"allowModifyUrl": undefined,
|
|
360
376
|
"allowModifyAppId": undefined,
|
|
361
377
|
"allowManualBundleError": undefined,
|
|
378
|
+
"allowPreview": undefined,
|
|
362
379
|
"persistCustomId": undefined,
|
|
363
380
|
"persistModifyUrl": undefined,
|
|
364
381
|
"allowSetDefaultChannel": undefined,
|
|
@@ -368,6 +385,7 @@ In `capacitor.config.json`:
|
|
|
368
385
|
"disableJSLogging": undefined,
|
|
369
386
|
"osLogging": undefined,
|
|
370
387
|
"shakeMenu": undefined,
|
|
388
|
+
"shakeMenuGesture": undefined,
|
|
371
389
|
"allowShakeChannelSelector": undefined
|
|
372
390
|
}
|
|
373
391
|
}
|
|
@@ -388,7 +406,7 @@ const config: CapacitorConfig = {
|
|
|
388
406
|
responseTimeout: 10 // (10 second),
|
|
389
407
|
autoDeleteFailed: false,
|
|
390
408
|
autoDeletePrevious: false,
|
|
391
|
-
autoUpdate:
|
|
409
|
+
autoUpdate: "onlyDownload",
|
|
392
410
|
resetWhenUpdate: false,
|
|
393
411
|
updateUrl: https://example.com/api/auto_update,
|
|
394
412
|
channelUrl: https://example.com/api/channel,
|
|
@@ -410,6 +428,7 @@ const config: CapacitorConfig = {
|
|
|
410
428
|
allowModifyUrl: undefined,
|
|
411
429
|
allowModifyAppId: undefined,
|
|
412
430
|
allowManualBundleError: undefined,
|
|
431
|
+
allowPreview: undefined,
|
|
413
432
|
persistCustomId: undefined,
|
|
414
433
|
persistModifyUrl: undefined,
|
|
415
434
|
allowSetDefaultChannel: undefined,
|
|
@@ -419,6 +438,7 @@ const config: CapacitorConfig = {
|
|
|
419
438
|
disableJSLogging: undefined,
|
|
420
439
|
osLogging: undefined,
|
|
421
440
|
shakeMenu: undefined,
|
|
441
|
+
shakeMenuGesture: undefined,
|
|
422
442
|
allowShakeChannelSelector: undefined,
|
|
423
443
|
},
|
|
424
444
|
},
|
|
@@ -441,6 +461,13 @@ export default config;
|
|
|
441
461
|
* [`download(...)`](#download)
|
|
442
462
|
* [`next(...)`](#next)
|
|
443
463
|
* [`set(...)`](#set)
|
|
464
|
+
* [`startPreviewSession(...)`](#startpreviewsession)
|
|
465
|
+
* [`listPreviews()`](#listpreviews)
|
|
466
|
+
* [`setPreview(...)`](#setpreview)
|
|
467
|
+
* [`resetPreview()`](#resetpreview)
|
|
468
|
+
* [`deletePreview(...)`](#deletepreview)
|
|
469
|
+
* [`checkPreviewUpdate(...)`](#checkpreviewupdate)
|
|
470
|
+
* [`updatePreview(...)`](#updatepreview)
|
|
444
471
|
* [`delete(...)`](#delete)
|
|
445
472
|
* [`setBundleError(...)`](#setbundleerror)
|
|
446
473
|
* [`list(...)`](#list)
|
|
@@ -449,7 +476,10 @@ export default config;
|
|
|
449
476
|
* [`reload()`](#reload)
|
|
450
477
|
* [`setMultiDelay(...)`](#setmultidelay)
|
|
451
478
|
* [`cancelDelay()`](#canceldelay)
|
|
479
|
+
* [`triggerUpdateCheck()`](#triggerupdatecheck)
|
|
452
480
|
* [`getLatest(...)`](#getlatest)
|
|
481
|
+
* [`getMissingBundleFiles(...)`](#getmissingbundlefiles)
|
|
482
|
+
* [`getBundleDownloadSize(...)`](#getbundledownloadsize)
|
|
453
483
|
* [`setChannel(...)`](#setchannel)
|
|
454
484
|
* [`unsetChannel(...)`](#unsetchannel)
|
|
455
485
|
* [`getChannel()`](#getchannel)
|
|
@@ -626,6 +656,11 @@ The bundle must include an `index.html` file at the root level.
|
|
|
626
656
|
For encrypted bundles, provide the `sessionKey` and `checksum` parameters.
|
|
627
657
|
For multi-file delta updates, provide the `manifest` array.
|
|
628
658
|
|
|
659
|
+
**Android Background Runner note:** `@capacitor/background-runner` loads its
|
|
660
|
+
configured runner script from native APK assets. Live updates cannot replace
|
|
661
|
+
that runner script. Keep it stable across OTA updates and ship a native app
|
|
662
|
+
update when the runner code changes.
|
|
663
|
+
|
|
629
664
|
| Param | Type | Description |
|
|
630
665
|
| ------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
631
666
|
| **`options`** | <code><a href="#downloadoptions">DownloadOptions</a></code> | The {@link <a href="#downloadoptions">DownloadOptions</a>} for downloading a new bundle zip. |
|
|
@@ -694,6 +729,161 @@ For other state preservation needs, save your data before calling this method (e
|
|
|
694
729
|
--------------------
|
|
695
730
|
|
|
696
731
|
|
|
732
|
+
#### startPreviewSession(...)
|
|
733
|
+
|
|
734
|
+
```typescript
|
|
735
|
+
startPreviewSession(options?: StartPreviewSessionOptions | undefined) => Promise<void>
|
|
736
|
+
```
|
|
737
|
+
|
|
738
|
+
Start a temporary preview/testing session.
|
|
739
|
+
|
|
740
|
+
This stores the currently active bundle as the pending fallback, enables the
|
|
741
|
+
native shake menu, and makes the next applied bundle show a native notice
|
|
742
|
+
explaining that shaking the device can reload or leave the preview.
|
|
743
|
+
Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
|
|
744
|
+
When `appId` is provided, the preview session temporarily uses that app id
|
|
745
|
+
for update checks until the user leaves the preview. Native updater stats are
|
|
746
|
+
skipped while the preview session is active.
|
|
747
|
+
|
|
748
|
+
Use this before calling {@link set} for Expo Go-style preview flows.
|
|
749
|
+
Use {@link listPreviews}, {@link setPreview}, {@link resetPreview},
|
|
750
|
+
{@link deletePreview}, {@link checkPreviewUpdate}, and
|
|
751
|
+
{@link updatePreview} to manage saved local previews.
|
|
752
|
+
|
|
753
|
+
| Param | Type | Description |
|
|
754
|
+
| ------------- | --------------------------------------------------------------------------------- | --------------------------------- |
|
|
755
|
+
| **`options`** | <code><a href="#startpreviewsessionoptions">StartPreviewSessionOptions</a></code> | Optional preview session options. |
|
|
756
|
+
|
|
757
|
+
**Since:** 8.47.0
|
|
758
|
+
|
|
759
|
+
--------------------
|
|
760
|
+
|
|
761
|
+
|
|
762
|
+
#### listPreviews()
|
|
763
|
+
|
|
764
|
+
```typescript
|
|
765
|
+
listPreviews() => Promise<PreviewListResult>
|
|
766
|
+
```
|
|
767
|
+
|
|
768
|
+
Get every locally available preview bundle that was registered by
|
|
769
|
+
{@link startPreviewSession} and later applied with {@link set}.
|
|
770
|
+
|
|
771
|
+
This only returns previews whose bundles are still available locally. It is
|
|
772
|
+
safe to show this in a preview switcher or native debug menu.
|
|
773
|
+
|
|
774
|
+
**Returns:** <code>Promise<<a href="#previewlistresult">PreviewListResult</a>></code>
|
|
775
|
+
|
|
776
|
+
**Since:** 8.49.0
|
|
777
|
+
|
|
778
|
+
--------------------
|
|
779
|
+
|
|
780
|
+
|
|
781
|
+
#### setPreview(...)
|
|
782
|
+
|
|
783
|
+
```typescript
|
|
784
|
+
setPreview(options: BundleId) => Promise<void>
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
Switch to a locally available preview bundle and reload the WebView.
|
|
788
|
+
|
|
789
|
+
If the app is not already in a preview session, the current live bundle is
|
|
790
|
+
saved as the fallback so {@link resetPreview} or the native shake menu can
|
|
791
|
+
return to it later.
|
|
792
|
+
|
|
793
|
+
| Param | Type | Description |
|
|
794
|
+
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
795
|
+
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
|
|
796
|
+
|
|
797
|
+
**Since:** 8.49.0
|
|
798
|
+
|
|
799
|
+
--------------------
|
|
800
|
+
|
|
801
|
+
|
|
802
|
+
#### resetPreview()
|
|
803
|
+
|
|
804
|
+
```typescript
|
|
805
|
+
resetPreview() => Promise<void>
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
Leave the active preview session and reload the saved live bundle.
|
|
809
|
+
|
|
810
|
+
This does not delete any saved previews. Use {@link deletePreview} to remove
|
|
811
|
+
a preview from local storage.
|
|
812
|
+
|
|
813
|
+
**Since:** 8.49.0
|
|
814
|
+
|
|
815
|
+
--------------------
|
|
816
|
+
|
|
817
|
+
|
|
818
|
+
#### deletePreview(...)
|
|
819
|
+
|
|
820
|
+
```typescript
|
|
821
|
+
deletePreview(options: BundleId) => Promise<DeletePreviewResult>
|
|
822
|
+
```
|
|
823
|
+
|
|
824
|
+
Delete a locally saved preview and its bundle when possible.
|
|
825
|
+
|
|
826
|
+
Active previews cannot be deleted until you switch away from them or call
|
|
827
|
+
{@link resetPreview}. If only the preview metadata can be removed, the
|
|
828
|
+
method still resolves with `deleted: false`.
|
|
829
|
+
|
|
830
|
+
| Param | Type | Description |
|
|
831
|
+
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
832
|
+
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
|
|
833
|
+
|
|
834
|
+
**Returns:** <code>Promise<<a href="#deletepreviewresult">DeletePreviewResult</a>></code>
|
|
835
|
+
|
|
836
|
+
**Since:** 8.49.0
|
|
837
|
+
|
|
838
|
+
--------------------
|
|
839
|
+
|
|
840
|
+
|
|
841
|
+
#### checkPreviewUpdate(...)
|
|
842
|
+
|
|
843
|
+
```typescript
|
|
844
|
+
checkPreviewUpdate(options: BundleId) => Promise<PreviewUpdateResult>
|
|
845
|
+
```
|
|
846
|
+
|
|
847
|
+
Check whether a saved preview's payload URL points to a newer preview bundle.
|
|
848
|
+
|
|
849
|
+
Only previews started with a `payloadUrl` can be checked natively. Direct URL
|
|
850
|
+
previews can still be switched or deleted locally, but the updater does not
|
|
851
|
+
know where to check for newer versions.
|
|
852
|
+
|
|
853
|
+
| Param | Type | Description |
|
|
854
|
+
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
855
|
+
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
|
|
856
|
+
|
|
857
|
+
**Returns:** <code>Promise<<a href="#previewupdateresult">PreviewUpdateResult</a>></code>
|
|
858
|
+
|
|
859
|
+
**Since:** 8.49.0
|
|
860
|
+
|
|
861
|
+
--------------------
|
|
862
|
+
|
|
863
|
+
|
|
864
|
+
#### updatePreview(...)
|
|
865
|
+
|
|
866
|
+
```typescript
|
|
867
|
+
updatePreview(options: BundleId) => Promise<PreviewUpdateResult>
|
|
868
|
+
```
|
|
869
|
+
|
|
870
|
+
Download the newest bundle for a saved preview payload URL.
|
|
871
|
+
|
|
872
|
+
If the preview being updated is active, the new bundle is applied and the
|
|
873
|
+
WebView reloads. Otherwise, the saved preview entry is moved to the newly
|
|
874
|
+
downloaded bundle and can be selected later with {@link setPreview}.
|
|
875
|
+
|
|
876
|
+
| Param | Type | Description |
|
|
877
|
+
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
878
|
+
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |
|
|
879
|
+
|
|
880
|
+
**Returns:** <code>Promise<<a href="#previewupdateresult">PreviewUpdateResult</a>></code>
|
|
881
|
+
|
|
882
|
+
**Since:** 8.49.0
|
|
883
|
+
|
|
884
|
+
--------------------
|
|
885
|
+
|
|
886
|
+
|
|
697
887
|
#### delete(...)
|
|
698
888
|
|
|
699
889
|
```typescript
|
|
@@ -907,6 +1097,33 @@ This is useful when:
|
|
|
907
1097
|
--------------------
|
|
908
1098
|
|
|
909
1099
|
|
|
1100
|
+
#### triggerUpdateCheck()
|
|
1101
|
+
|
|
1102
|
+
```typescript
|
|
1103
|
+
triggerUpdateCheck() => Promise<TriggerUpdateCheckResult>
|
|
1104
|
+
```
|
|
1105
|
+
|
|
1106
|
+
Trigger the native auto-update check/download pipeline immediately.
|
|
1107
|
+
|
|
1108
|
+
This starts the same background update flow used when the app moves to the
|
|
1109
|
+
foreground with auto-update enabled. It is useful for native integrations
|
|
1110
|
+
such as a silent push notification asking the app to check for a Capgo
|
|
1111
|
+
bundle without reimplementing the update protocol in JavaScript.
|
|
1112
|
+
|
|
1113
|
+
The promise resolves after the native background work has been queued, not
|
|
1114
|
+
after the update has been downloaded or installed. Listen to updater events
|
|
1115
|
+
such as `updateAvailable`, `downloadComplete`, `downloadFailed`, and
|
|
1116
|
+
`noNeedUpdate` for the final result.
|
|
1117
|
+
|
|
1118
|
+
Native support is available on iOS and Android. On Web, this method returns
|
|
1119
|
+
a result with `status: 'unavailable'`. Native platforms also return
|
|
1120
|
+
`unavailable` when the native auto-update system is disabled.
|
|
1121
|
+
|
|
1122
|
+
**Returns:** <code>Promise<<a href="#triggerupdatecheckresult">TriggerUpdateCheckResult</a>></code>
|
|
1123
|
+
|
|
1124
|
+
--------------------
|
|
1125
|
+
|
|
1126
|
+
|
|
910
1127
|
#### getLatest(...)
|
|
911
1128
|
|
|
912
1129
|
```typescript
|
|
@@ -965,6 +1182,73 @@ In this scenario, the server:
|
|
|
965
1182
|
--------------------
|
|
966
1183
|
|
|
967
1184
|
|
|
1185
|
+
#### getMissingBundleFiles(...)
|
|
1186
|
+
|
|
1187
|
+
```typescript
|
|
1188
|
+
getMissingBundleFiles(options: GetMissingBundleFilesOptions) => Promise<GetMissingBundleFilesResult>
|
|
1189
|
+
```
|
|
1190
|
+
|
|
1191
|
+
Return the manifest entries that still need to be downloaded for a partial update.
|
|
1192
|
+
|
|
1193
|
+
Pass the result from {@link getLatest} directly when it includes a `manifest`.
|
|
1194
|
+
The native plugin compares each manifest entry with the files already available
|
|
1195
|
+
in the builtin bundle and the local delta cache. Entries that can be reused are
|
|
1196
|
+
omitted from the returned `missing` list.
|
|
1197
|
+
|
|
1198
|
+
For encrypted manifests, pass the `sessionKey` returned by {@link getLatest} so
|
|
1199
|
+
encrypted file hashes can be checked against local files.
|
|
1200
|
+
|
|
1201
|
+
```typescript
|
|
1202
|
+
const latest = await CapacitorUpdater.getLatest();
|
|
1203
|
+
const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
|
|
1204
|
+
```
|
|
1205
|
+
|
|
1206
|
+
| Param | Type | Description |
|
|
1207
|
+
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1208
|
+
| **`options`** | <code><a href="#getmissingbundlefilesoptions">GetMissingBundleFilesOptions</a></code> | A {@link <a href="#getmissingbundlefilesoptions">GetMissingBundleFilesOptions</a>} object, or a {@link <a href="#latestversion">LatestVersion</a>} response containing `manifest`. |
|
|
1209
|
+
|
|
1210
|
+
**Returns:** <code>Promise<<a href="#getmissingbundlefilesresult">GetMissingBundleFilesResult</a>></code>
|
|
1211
|
+
|
|
1212
|
+
**Since:** 8.47.0
|
|
1213
|
+
|
|
1214
|
+
--------------------
|
|
1215
|
+
|
|
1216
|
+
|
|
1217
|
+
#### getBundleDownloadSize(...)
|
|
1218
|
+
|
|
1219
|
+
```typescript
|
|
1220
|
+
getBundleDownloadSize(options: GetBundleDownloadSizeOptions) => Promise<GetBundleDownloadSizeResult>
|
|
1221
|
+
```
|
|
1222
|
+
|
|
1223
|
+
Estimate the download size for manifest entries before downloading them.
|
|
1224
|
+
|
|
1225
|
+
This method sends the provided manifest entries to the Capgo update endpoint
|
|
1226
|
+
once and reads the stored manifest `file_size` metadata. It does not perform
|
|
1227
|
+
per-file `HEAD` requests from the app.
|
|
1228
|
+
|
|
1229
|
+
Use this after {@link getMissingBundleFiles} to estimate only the files this
|
|
1230
|
+
device still needs:
|
|
1231
|
+
|
|
1232
|
+
```typescript
|
|
1233
|
+
const latest = await CapacitorUpdater.getLatest();
|
|
1234
|
+
const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
|
|
1235
|
+
const size = await CapacitorUpdater.getBundleDownloadSize({
|
|
1236
|
+
version: latest.version,
|
|
1237
|
+
manifest: missing.missing,
|
|
1238
|
+
});
|
|
1239
|
+
```
|
|
1240
|
+
|
|
1241
|
+
| Param | Type | Description |
|
|
1242
|
+
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
1243
|
+
| **`options`** | <code><a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a></code> | A {@link <a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a>} object containing manifest entries. |
|
|
1244
|
+
|
|
1245
|
+
**Returns:** <code>Promise<<a href="#getbundledownloadsizeresult">GetBundleDownloadSizeResult</a>></code>
|
|
1246
|
+
|
|
1247
|
+
**Since:** 8.47.0
|
|
1248
|
+
|
|
1249
|
+
--------------------
|
|
1250
|
+
|
|
1251
|
+
|
|
968
1252
|
#### setChannel(...)
|
|
969
1253
|
|
|
970
1254
|
```typescript
|
|
@@ -976,6 +1260,11 @@ Assign this device to a specific update channel at runtime.
|
|
|
976
1260
|
Channels allow you to distribute different bundle versions to different groups of users
|
|
977
1261
|
(e.g., "production", "beta", "staging"). This method switches the device to a new channel.
|
|
978
1262
|
|
|
1263
|
+
**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the
|
|
1264
|
+
selected channel locally on the device. It does not create or update a backend Device Override,
|
|
1265
|
+
so the device will not appear as overridden in the Capgo dashboard. Only assignments created
|
|
1266
|
+
from the dashboard or the Public API are shown in the Device Override UI.
|
|
1267
|
+
|
|
979
1268
|
**Requirements:**
|
|
980
1269
|
- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
|
|
981
1270
|
- The backend may accept or reject the request based on channel settings
|
|
@@ -1002,7 +1291,8 @@ CapacitorUpdater.addListener('channelPrivate', (data) => {
|
|
|
1002
1291
|
});
|
|
1003
1292
|
```
|
|
1004
1293
|
|
|
1005
|
-
This sends a request to the Capgo backend
|
|
1294
|
+
This sends a request to the Capgo backend to validate the specified channel, then stores the
|
|
1295
|
+
channel locally on the device.
|
|
1006
1296
|
|
|
1007
1297
|
| Param | Type | Description |
|
|
1008
1298
|
| ------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -1021,11 +1311,12 @@ This sends a request to the Capgo backend linking your device ID to the specifie
|
|
|
1021
1311
|
unsetChannel(options: UnsetChannelOptions) => Promise<void>
|
|
1022
1312
|
```
|
|
1023
1313
|
|
|
1024
|
-
Remove the
|
|
1314
|
+
Remove the plugin-managed local channel assignment and return to the default channel.
|
|
1025
1315
|
|
|
1026
|
-
This
|
|
1316
|
+
This clears only the channel stored locally by {@link setChannel}; it does not delete Dashboard or Public API Device Override records. After the local assignment is cleared, normal channel precedence applies:
|
|
1317
|
+
- An existing Dashboard or Public API Device Override, if one exists
|
|
1027
1318
|
- The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
|
|
1028
|
-
- Your backend
|
|
1319
|
+
- Your backend default channel for this app
|
|
1029
1320
|
|
|
1030
1321
|
Use this when:
|
|
1031
1322
|
- Users opt out of beta/testing programs
|
|
@@ -1060,6 +1351,9 @@ Use this to:
|
|
|
1060
1351
|
- Check if a device is on a specific channel before showing features
|
|
1061
1352
|
- Verify channel assignment after calling {@link setChannel}
|
|
1062
1353
|
|
|
1354
|
+
On native platforms, a successful response also refreshes the locally persisted
|
|
1355
|
+
default channel used by update checks.
|
|
1356
|
+
|
|
1063
1357
|
**Returns:** <code>Promise<<a href="#getchannelres">GetChannelRes</a>></code>
|
|
1064
1358
|
|
|
1065
1359
|
**Since:** 4.8.0
|
|
@@ -1171,7 +1465,7 @@ It's automatically generated and stored securely by the plugin.
|
|
|
1171
1465
|
**Privacy & Security characteristics:**
|
|
1172
1466
|
- Generated as a UUID (not based on hardware identifiers)
|
|
1173
1467
|
- Stored securely in platform-specific secure storage
|
|
1174
|
-
- Android:
|
|
1468
|
+
- Android: mirrored into backup-restorable app preferences for reinstall restore
|
|
1175
1469
|
- iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
|
|
1176
1470
|
- Not synced to cloud (iOS)
|
|
1177
1471
|
- Follows Apple and Google privacy best practices
|
|
@@ -1179,7 +1473,9 @@ It's automatically generated and stored securely by the plugin.
|
|
|
1179
1473
|
|
|
1180
1474
|
**Persistence:**
|
|
1181
1475
|
The device ID persists across app reinstalls to maintain consistent device identity
|
|
1182
|
-
for update tracking and analytics.
|
|
1476
|
+
for update tracking and analytics when platform storage is preserved. On Android,
|
|
1477
|
+
apps with custom backup rules must keep the plugin app preferences eligible for
|
|
1478
|
+
backup/restore; disabling Android backup or clearing app data creates a new ID.
|
|
1183
1479
|
|
|
1184
1480
|
Use this to:
|
|
1185
1481
|
- Debug update delivery issues (check what ID the server sees)
|
|
@@ -1690,23 +1986,20 @@ Use this to:
|
|
|
1690
1986
|
setShakeMenu(options: SetShakeMenuOptions) => Promise<void>
|
|
1691
1987
|
```
|
|
1692
1988
|
|
|
1693
|
-
Enable or disable the
|
|
1989
|
+
Enable or disable the native preview menu gesture.
|
|
1694
1990
|
|
|
1695
|
-
|
|
1696
|
-
-
|
|
1697
|
-
-
|
|
1698
|
-
-
|
|
1699
|
-
- Update status
|
|
1991
|
+
During preview sessions, users can use the configured native gesture to:
|
|
1992
|
+
- Reload the current preview
|
|
1993
|
+
- Leave the test app and return to the fallback bundle
|
|
1994
|
+
- Switch update channel, when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is also enabled
|
|
1700
1995
|
|
|
1701
|
-
|
|
1702
|
-
|
|
1703
|
-
- Debug update flows
|
|
1704
|
-
- Switch between production and test bundles
|
|
1705
|
-
- Verify bundle installations
|
|
1996
|
+
Outside preview sessions, this preview menu is ignored. The channel selector can still be
|
|
1997
|
+
shown outside preview sessions when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled.
|
|
1706
1998
|
|
|
1707
1999
|
**Important:** Disable this in production builds or only enable for internal testers.
|
|
1708
2000
|
|
|
1709
|
-
|
|
2001
|
+
This can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
|
|
2002
|
+
The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.
|
|
1710
2003
|
|
|
1711
2004
|
| Param | Type |
|
|
1712
2005
|
| ------------- | ------------------------------------------------------------------- |
|
|
@@ -1723,7 +2016,7 @@ Can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
|
|
|
1723
2016
|
isShakeMenuEnabled() => Promise<ShakeMenuEnabled>
|
|
1724
2017
|
```
|
|
1725
2018
|
|
|
1726
|
-
Check if the
|
|
2019
|
+
Check if the native preview menu gesture is currently enabled.
|
|
1727
2020
|
|
|
1728
2021
|
Returns the current state of the shake menu feature that can be toggled via
|
|
1729
2022
|
{@link setShakeMenu} or configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
|
|
@@ -1746,16 +2039,14 @@ Use this to:
|
|
|
1746
2039
|
setShakeChannelSelector(options: SetShakeChannelSelectorOptions) => Promise<void>
|
|
1747
2040
|
```
|
|
1748
2041
|
|
|
1749
|
-
Enable or disable the
|
|
2042
|
+
Enable or disable the channel selector menu gesture at runtime.
|
|
1750
2043
|
|
|
1751
|
-
When enabled
|
|
1752
|
-
|
|
1753
|
-
|
|
2044
|
+
When enabled, the configured native gesture can show a channel selector, including outside preview sessions.
|
|
2045
|
+
If {@link setShakeMenu} is also enabled while a preview session is active, the shake menu includes
|
|
2046
|
+
both preview actions and channel switching.
|
|
1754
2047
|
|
|
1755
|
-
|
|
1756
|
-
|
|
1757
|
-
|
|
1758
|
-
Can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
|
|
2048
|
+
This can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
|
|
2049
|
+
The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.
|
|
1759
2050
|
|
|
1760
2051
|
| Param | Type |
|
|
1761
2052
|
| ------------- | ----------------------------------------------------------------------------------------- |
|
|
@@ -2070,6 +2361,61 @@ If you don't use backend, you need to provide the URL and version of the bundle.
|
|
|
2070
2361
|
| **`id`** | <code>string</code> |
|
|
2071
2362
|
|
|
2072
2363
|
|
|
2364
|
+
##### StartPreviewSessionOptions
|
|
2365
|
+
|
|
2366
|
+
| Prop | Type | Description | Default | Since |
|
|
2367
|
+
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
|
|
2368
|
+
| **`appId`** | <code>string</code> | App id to use while the preview session is active. The previous app id is restored when leaving the preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.47.0 |
|
|
2369
|
+
| **`payloadUrl`** | <code>string</code> | HTTP(S) URL returning a preview download payload. When provided, the native shake reload action fetches this payload again before reloading so channel previews can move to the latest bundle. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.48.0 |
|
|
2370
|
+
| **`name`** | <code>string</code> | Human-readable preview name stored with the next preview bundle applied by {@link set}. Native preview menus and {@link listPreviews} can display it. | <code>undefined</code> | 8.49.0 |
|
|
2371
|
+
| **`source`** | <code>string</code> | Optional source label for the preview, such as `channel`, `bundle`, `url`, or `payload`. This is stored as metadata only. | <code>undefined</code> | 8.49.0 |
|
|
2372
|
+
|
|
2373
|
+
|
|
2374
|
+
##### PreviewListResult
|
|
2375
|
+
|
|
2376
|
+
| Prop | Type | Description | Since |
|
|
2377
|
+
| ------------------- | --------------------------------------------------- | ------------------------------------------------------- | ------ |
|
|
2378
|
+
| **`previews`** | <code>PreviewInfo[]</code> | Locally available preview bundles. | 8.49.0 |
|
|
2379
|
+
| **`current`** | <code><a href="#previewinfo">PreviewInfo</a></code> | Current preview when a preview session is active. | 8.49.0 |
|
|
2380
|
+
| **`currentBundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Bundle currently loaded by the WebView. | 8.49.0 |
|
|
2381
|
+
| **`liveBundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Bundle that will be restored when leaving preview mode. | 8.49.0 |
|
|
2382
|
+
|
|
2383
|
+
|
|
2384
|
+
##### PreviewInfo
|
|
2385
|
+
|
|
2386
|
+
| Prop | Type | Description | Since |
|
|
2387
|
+
| ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------ |
|
|
2388
|
+
| **`id`** | <code>string</code> | Preview bundle id. | 8.49.0 |
|
|
2389
|
+
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Locally downloaded bundle backing this preview. | 8.49.0 |
|
|
2390
|
+
| **`name`** | <code>string</code> | Human-readable name supplied when the preview was started. | 8.49.0 |
|
|
2391
|
+
| **`source`** | <code>string</code> | Metadata source label supplied when the preview was started. | 8.49.0 |
|
|
2392
|
+
| **`appId`** | <code>string</code> | Preview app id, when the session uses an app id override. | 8.49.0 |
|
|
2393
|
+
| **`payloadUrl`** | <code>string</code> | Payload URL used to refresh this preview. | 8.49.0 |
|
|
2394
|
+
| **`createdAt`** | <code>string</code> | ISO timestamp for when this preview was first saved. | 8.49.0 |
|
|
2395
|
+
| **`updatedAt`** | <code>string</code> | ISO timestamp for the last metadata or bundle update. | 8.49.0 |
|
|
2396
|
+
| **`lastUsedAt`** | <code>string</code> | ISO timestamp for the last time this preview was activated. | 8.49.0 |
|
|
2397
|
+
| **`isActive`** | <code>boolean</code> | Whether this preview is the currently active bundle in a preview session. | 8.49.0 |
|
|
2398
|
+
|
|
2399
|
+
|
|
2400
|
+
##### DeletePreviewResult
|
|
2401
|
+
|
|
2402
|
+
| Prop | Type | Description | Since |
|
|
2403
|
+
| ------------- | -------------------- | ------------------------------------------------ | ------ |
|
|
2404
|
+
| **`removed`** | <code>boolean</code> | Whether preview metadata was removed. | 8.49.0 |
|
|
2405
|
+
| **`deleted`** | <code>boolean</code> | Whether the underlying local bundle was deleted. | 8.49.0 |
|
|
2406
|
+
|
|
2407
|
+
|
|
2408
|
+
##### PreviewUpdateResult
|
|
2409
|
+
|
|
2410
|
+
| Prop | Type | Description | Since |
|
|
2411
|
+
| ------------------- | --------------------------------------------------- | --------------------------------------------------------------------- | ------ |
|
|
2412
|
+
| **`preview`** | <code><a href="#previewinfo">PreviewInfo</a></code> | Saved preview metadata after the check or update. | 8.49.0 |
|
|
2413
|
+
| **`latestVersion`** | <code>string</code> | Latest version returned by the preview payload endpoint. | 8.49.0 |
|
|
2414
|
+
| **`upToDate`** | <code>boolean</code> | Whether the saved preview already matches the latest payload version. | 8.49.0 |
|
|
2415
|
+
| **`updated`** | <code>boolean</code> | Whether a newer bundle was downloaded and saved. | 8.49.0 |
|
|
2416
|
+
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | New bundle when {@link updatePreview} downloaded one. | 8.49.0 |
|
|
2417
|
+
|
|
2418
|
+
|
|
2073
2419
|
##### BundleListResult
|
|
2074
2420
|
|
|
2075
2421
|
| Prop | Type |
|
|
@@ -2115,31 +2461,93 @@ If you don't use backend, you need to provide the URL and version of the bundle.
|
|
|
2115
2461
|
| **`value`** | <code>string</code> | |
|
|
2116
2462
|
|
|
2117
2463
|
|
|
2464
|
+
##### TriggerUpdateCheckResult
|
|
2465
|
+
|
|
2466
|
+
Result returned after requesting an immediate native auto-update check.
|
|
2467
|
+
|
|
2468
|
+
| Prop | Type | Description |
|
|
2469
|
+
| ------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
2470
|
+
| **`status`** | <code>'queued' \| 'already_running' \| 'unavailable'</code> | Native trigger state: `queued` when a check was queued, `already_running` when the native update pipeline is already active, or `unavailable` on Web or when native auto-update is disabled. |
|
|
2471
|
+
| **`queued`** | <code>boolean</code> | Whether a new native update check was queued. This is `true` only when `status` is `queued`; otherwise it is `false`. |
|
|
2472
|
+
|
|
2473
|
+
|
|
2118
2474
|
##### LatestVersion
|
|
2119
2475
|
|
|
2120
|
-
| Prop
|
|
2121
|
-
|
|
|
2122
|
-
| **`version`**
|
|
2123
|
-
| **`checksum`**
|
|
2124
|
-
| **`breaking`**
|
|
2125
|
-
| **`major`**
|
|
2126
|
-
| **`message`**
|
|
2127
|
-
| **`sessionKey`**
|
|
2128
|
-
| **`error`**
|
|
2129
|
-
| **`kind`**
|
|
2130
|
-
| **`statusCode`**
|
|
2131
|
-
| **`old`**
|
|
2132
|
-
| **`url`**
|
|
2133
|
-
| **`manifest`**
|
|
2134
|
-
| **`
|
|
2135
|
-
| **`
|
|
2476
|
+
| Prop | Type | Description | Since |
|
|
2477
|
+
| ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
|
|
2478
|
+
| **`version`** | <code>string</code> | Result of getLatest method | 4.0.0 |
|
|
2479
|
+
| **`checksum`** | <code>string</code> | | 6 |
|
|
2480
|
+
| **`breaking`** | <code>boolean</code> | Indicates whether the update was flagged as breaking by the backend. | 7.22.0 |
|
|
2481
|
+
| **`major`** | <code>boolean</code> | | |
|
|
2482
|
+
| **`message`** | <code>string</code> | Optional message from the server. When no new version is available, this will be "No new version available". | |
|
|
2483
|
+
| **`sessionKey`** | <code>string</code> | | |
|
|
2484
|
+
| **`error`** | <code>string</code> | Error code from the server, if any. Use `kind` for classification instead of parsing this value. | |
|
|
2485
|
+
| **`kind`** | <code><a href="#updateresponsekind">UpdateResponseKind</a></code> | Classification for this response, provided by the backend. | 8.45.11 |
|
|
2486
|
+
| **`statusCode`** | <code>number</code> | HTTP status code returned by the update server for classified update-check responses. | 8.45.11 |
|
|
2487
|
+
| **`old`** | <code>string</code> | The previous/current version name (provided for reference). | |
|
|
2488
|
+
| **`url`** | <code>string</code> | Download URL for the bundle (when a new version is available). | |
|
|
2489
|
+
| **`manifest`** | <code>ManifestEntry[]</code> | File list for delta updates (when using multi-file downloads). | 6.1 |
|
|
2490
|
+
| **`missing`** | <code><a href="#getmissingbundlefilesresult">GetMissingBundleFilesResult</a></code> | Missing manifest entries for this device when {@link <a href="#getlatestoptions">GetLatestOptions.includeBundleSize</a>} is enabled. | 8.47.0 |
|
|
2491
|
+
| **`downloadSize`** | <code><a href="#getbundledownloadsizeresult">GetBundleDownloadSizeResult</a></code> | Estimated download size for missing manifest entries when {@link <a href="#getlatestoptions">GetLatestOptions.includeBundleSize</a>} is enabled. | 8.47.0 |
|
|
2492
|
+
| **`link`** | <code>string</code> | Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release). | 7.35.0 |
|
|
2493
|
+
| **`comment`** | <code>string</code> | Optional comment or description for this bundle version. | 7.35.0 |
|
|
2494
|
+
|
|
2495
|
+
|
|
2496
|
+
##### GetMissingBundleFilesResult
|
|
2497
|
+
|
|
2498
|
+
| Prop | Type | Description | Since |
|
|
2499
|
+
| ------------------- | ---------------------------- | ----------------------------------------------------------------------- | ------ |
|
|
2500
|
+
| **`missing`** | <code>ManifestEntry[]</code> | Entries that are not available locally and need to be downloaded. | 8.47.0 |
|
|
2501
|
+
| **`total`** | <code>number</code> | Total entries in the provided manifest. | 8.47.0 |
|
|
2502
|
+
| **`missingCount`** | <code>number</code> | Number of entries that need to be downloaded. | 8.47.0 |
|
|
2503
|
+
| **`reusableCount`** | <code>number</code> | Number of entries that can be reused from builtin files or local cache. | 8.47.0 |
|
|
2504
|
+
|
|
2505
|
+
|
|
2506
|
+
##### GetBundleDownloadSizeResult
|
|
2507
|
+
|
|
2508
|
+
| Prop | Type | Description | Since |
|
|
2509
|
+
| ------------------ | ----------------------------- | --------------------------------------------------- | ------ |
|
|
2510
|
+
| **`totalSize`** | <code>number</code> | Sum of all known file sizes in bytes. | 8.47.0 |
|
|
2511
|
+
| **`knownFiles`** | <code>number</code> | Number of files with a known size. | 8.47.0 |
|
|
2512
|
+
| **`unknownFiles`** | <code>number</code> | Number of files whose size could not be determined. | 8.47.0 |
|
|
2513
|
+
| **`files`** | <code>BundleFileSize[]</code> | Per-file size results. | 8.47.0 |
|
|
2514
|
+
|
|
2515
|
+
|
|
2516
|
+
##### BundleFileSize
|
|
2517
|
+
|
|
2518
|
+
| Prop | Type | Description | Since |
|
|
2519
|
+
| ------------------ | --------------------------- | ----------------------------------------------------------- | ------ |
|
|
2520
|
+
| **`file_name`** | <code>string \| null</code> | File name from the manifest entry. | 8.47.0 |
|
|
2521
|
+
| **`file_hash`** | <code>string \| null</code> | File hash from the manifest entry. | 8.47.0 |
|
|
2522
|
+
| **`download_url`** | <code>string \| null</code> | Download URL from the manifest entry. | 8.47.0 |
|
|
2523
|
+
| **`size`** | <code>number</code> | Estimated bytes to download when the server exposes a size. | 8.47.0 |
|
|
2524
|
+
| **`error`** | <code>string</code> | Error for this entry when the size could not be determined. | 8.47.0 |
|
|
2136
2525
|
|
|
2137
2526
|
|
|
2138
2527
|
##### GetLatestOptions
|
|
2139
2528
|
|
|
2140
|
-
| Prop
|
|
2141
|
-
|
|
|
2142
|
-
| **`channel`**
|
|
2529
|
+
| Prop | Type | Description | Default | Since |
|
|
2530
|
+
| ----------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
|
|
2531
|
+
| **`channel`** | <code>string</code> | The channel to get the latest version for The channel must allow 'self_assign' for this to work | <code>undefined</code> | 6.8.0 |
|
|
2532
|
+
| **`appId`** | <code>string</code> | Temporarily use another app id for this update check while using a trusted preview container. This only changes the app id sent by this request; it does not persist a preview session. Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`. | <code>undefined</code> | 8.47.0 |
|
|
2533
|
+
| **`includeBundleSize`** | <code>boolean</code> | When true, the native plugin computes which manifest files are missing on this device and asks the Capgo update endpoint for their stored sizes before resolving {@link getLatest}. This adds one backend request only when the update response contains a manifest. It does not perform per-file network checks. | <code>false</code> | 8.47.0 |
|
|
2534
|
+
|
|
2535
|
+
|
|
2536
|
+
##### GetMissingBundleFilesOptions
|
|
2537
|
+
|
|
2538
|
+
| Prop | Type | Description | Since |
|
|
2539
|
+
| ---------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
|
|
2540
|
+
| **`manifest`** | <code>ManifestEntry[]</code> | Manifest returned by {@link getLatest}. Passing the full {@link <a href="#latestversion">LatestVersion</a>} response is supported because it contains this field. | 8.47.0 |
|
|
2541
|
+
| **`version`** | <code>string</code> | Target bundle version. Passing the full {@link <a href="#latestversion">LatestVersion</a>} response is supported because it contains this field. | 8.47.0 |
|
|
2542
|
+
| **`sessionKey`** | <code>string</code> | Session key returned by {@link getLatest}, required only when file hashes are encrypted. | 8.47.0 |
|
|
2543
|
+
|
|
2544
|
+
|
|
2545
|
+
##### GetBundleDownloadSizeOptions
|
|
2546
|
+
|
|
2547
|
+
| Prop | Type | Description | Since |
|
|
2548
|
+
| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
|
|
2549
|
+
| **`manifest`** | <code>ManifestEntry[]</code> | Manifest entries to estimate. Pass `missing.missing` from {@link getMissingBundleFiles} to estimate only the bytes this device still needs to download. | 8.47.0 |
|
|
2550
|
+
| **`version`** | <code>string</code> | Target bundle version. Pass `latest.version` when estimating files returned by {@link getLatest}. | 8.47.0 |
|
|
2143
2551
|
|
|
2144
2552
|
|
|
2145
2553
|
##### ChannelRes
|
|
@@ -2188,7 +2596,7 @@ If you don't use backend, you need to provide the URL and version of the bundle.
|
|
|
2188
2596
|
|
|
2189
2597
|
| Prop | Type | Description | Since |
|
|
2190
2598
|
| -------------------- | -------------------- | ----------------------------------------------- | ----- |
|
|
2191
|
-
| **`id`** | <code>
|
|
2599
|
+
| **`id`** | <code>number</code> | The channel ID | 7.5.0 |
|
|
2192
2600
|
| **`name`** | <code>string</code> | The channel name | 7.5.0 |
|
|
2193
2601
|
| **`public`** | <code>boolean</code> | Whether this is a public channel | 7.5.0 |
|
|
2194
2602
|
| **`allow_self_set`** | <code>boolean</code> | Whether devices can self-assign to this channel | 7.5.0 |
|
|
@@ -2355,9 +2763,10 @@ State information for flexible update progress (Android only).
|
|
|
2355
2763
|
|
|
2356
2764
|
##### ShakeMenuEnabled
|
|
2357
2765
|
|
|
2358
|
-
| Prop | Type
|
|
2359
|
-
| ------------- |
|
|
2360
|
-
| **`enabled`** | <code>boolean</code>
|
|
2766
|
+
| Prop | Type | Description | Since |
|
|
2767
|
+
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
|
|
2768
|
+
| **`enabled`** | <code>boolean</code> | | |
|
|
2769
|
+
| **`gesture`** | <code><a href="#shakemenugesture">ShakeMenuGesture</a></code> | The currently configured native gesture used to open the preview/channel menu. Undefined means consumers should treat the gesture as the default `shake` behavior. | 8.48.0 |
|
|
2361
2770
|
|
|
2362
2771
|
|
|
2363
2772
|
##### SetShakeChannelSelectorOptions
|
|
@@ -2470,6 +2879,15 @@ Payload emitted by {@link CapacitorUpdaterPlugin.addListener} with `breakingAvai
|
|
|
2470
2879
|
<code><a href="#majoravailableevent">MajorAvailableEvent</a></code>
|
|
2471
2880
|
|
|
2472
2881
|
|
|
2882
|
+
##### ShakeMenuGesture
|
|
2883
|
+
|
|
2884
|
+
Native gesture options that open the shake menu.
|
|
2885
|
+
|
|
2886
|
+
Supported values are `shake` and `threeFingerPinch`.
|
|
2887
|
+
|
|
2888
|
+
<code>'shake' | 'threeFingerPinch'</code>
|
|
2889
|
+
|
|
2890
|
+
|
|
2473
2891
|
#### Enums
|
|
2474
2892
|
|
|
2475
2893
|
|