@capgo/capacitor-updater 8.46.3 → 8.47.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +178 -19
- package/android/src/main/java/ee/forgr/capacitor_updater/CapacitorUpdaterPlugin.java +466 -30
- package/android/src/main/java/ee/forgr/capacitor_updater/CapgoUpdater.java +239 -22
- package/android/src/main/java/ee/forgr/capacitor_updater/ShakeMenu.java +95 -3
- package/dist/docs.json +473 -0
- package/dist/esm/definitions.d.ts +241 -0
- package/dist/esm/definitions.js.map +1 -1
- package/dist/esm/web.d.ts +4 -1
- package/dist/esm/web.js +30 -0
- package/dist/esm/web.js.map +1 -1
- package/dist/plugin.cjs.js +30 -0
- package/dist/plugin.cjs.js.map +1 -1
- package/dist/plugin.js +30 -0
- package/dist/plugin.js.map +1 -1
- package/ios/Sources/CapacitorUpdaterPlugin/CapacitorUpdaterPlugin.swift +354 -15
- package/ios/Sources/CapacitorUpdaterPlugin/CapgoUpdater.swift +194 -8
- package/ios/Sources/CapacitorUpdaterPlugin/InternalUtils.swift +2 -0
- package/ios/Sources/CapacitorUpdaterPlugin/ShakeMenu.swift +47 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -314,6 +314,7 @@ CapacitorUpdater can be configured with these options:
|
|
|
314
314
|
| **`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 |
|
|
315
315
|
| **`allowModifyAppId`** | <code>boolean</code> | Allow the plugin to modify the appId dynamically from the JavaScript side. | <code>false</code> | 7.14.0 |
|
|
316
316
|
| **`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 |
|
|
317
|
+
| **`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 |
|
|
317
318
|
| **`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 |
|
|
318
319
|
| **`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 |
|
|
319
320
|
| **`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 |
|
|
@@ -359,6 +360,7 @@ In `capacitor.config.json`:
|
|
|
359
360
|
"allowModifyUrl": undefined,
|
|
360
361
|
"allowModifyAppId": undefined,
|
|
361
362
|
"allowManualBundleError": undefined,
|
|
363
|
+
"allowPreview": undefined,
|
|
362
364
|
"persistCustomId": undefined,
|
|
363
365
|
"persistModifyUrl": undefined,
|
|
364
366
|
"allowSetDefaultChannel": undefined,
|
|
@@ -410,6 +412,7 @@ const config: CapacitorConfig = {
|
|
|
410
412
|
allowModifyUrl: undefined,
|
|
411
413
|
allowModifyAppId: undefined,
|
|
412
414
|
allowManualBundleError: undefined,
|
|
415
|
+
allowPreview: undefined,
|
|
413
416
|
persistCustomId: undefined,
|
|
414
417
|
persistModifyUrl: undefined,
|
|
415
418
|
allowSetDefaultChannel: undefined,
|
|
@@ -441,6 +444,7 @@ export default config;
|
|
|
441
444
|
* [`download(...)`](#download)
|
|
442
445
|
* [`next(...)`](#next)
|
|
443
446
|
* [`set(...)`](#set)
|
|
447
|
+
* [`startPreviewSession(...)`](#startpreviewsession)
|
|
444
448
|
* [`delete(...)`](#delete)
|
|
445
449
|
* [`setBundleError(...)`](#setbundleerror)
|
|
446
450
|
* [`list(...)`](#list)
|
|
@@ -451,6 +455,8 @@ export default config;
|
|
|
451
455
|
* [`cancelDelay()`](#canceldelay)
|
|
452
456
|
* [`triggerUpdateCheck()`](#triggerupdatecheck)
|
|
453
457
|
* [`getLatest(...)`](#getlatest)
|
|
458
|
+
* [`getMissingBundleFiles(...)`](#getmissingbundlefiles)
|
|
459
|
+
* [`getBundleDownloadSize(...)`](#getbundledownloadsize)
|
|
454
460
|
* [`setChannel(...)`](#setchannel)
|
|
455
461
|
* [`unsetChannel(...)`](#unsetchannel)
|
|
456
462
|
* [`getChannel()`](#getchannel)
|
|
@@ -695,6 +701,33 @@ For other state preservation needs, save your data before calling this method (e
|
|
|
695
701
|
--------------------
|
|
696
702
|
|
|
697
703
|
|
|
704
|
+
#### startPreviewSession(...)
|
|
705
|
+
|
|
706
|
+
```typescript
|
|
707
|
+
startPreviewSession(options?: StartPreviewSessionOptions | undefined) => Promise<void>
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
Start a temporary preview/testing session.
|
|
711
|
+
|
|
712
|
+
This stores the currently active bundle as the pending fallback, enables the
|
|
713
|
+
native shake menu, and makes the next applied bundle show a native notice
|
|
714
|
+
explaining that shaking the device can reload or leave the preview.
|
|
715
|
+
Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
|
|
716
|
+
When `appId` is provided, the preview session temporarily uses that app id
|
|
717
|
+
for update checks until the user leaves the preview. Native updater stats are
|
|
718
|
+
skipped while the preview session is active.
|
|
719
|
+
|
|
720
|
+
Use this before calling {@link set} for Expo Go-style preview flows.
|
|
721
|
+
|
|
722
|
+
| Param | Type | Description |
|
|
723
|
+
| ------------- | --------------------------------------------------------------------------------- | --------------------------------- |
|
|
724
|
+
| **`options`** | <code><a href="#startpreviewsessionoptions">StartPreviewSessionOptions</a></code> | Optional preview session options. |
|
|
725
|
+
|
|
726
|
+
**Since:** 8.47.0
|
|
727
|
+
|
|
728
|
+
--------------------
|
|
729
|
+
|
|
730
|
+
|
|
698
731
|
#### delete(...)
|
|
699
732
|
|
|
700
733
|
```typescript
|
|
@@ -993,6 +1026,73 @@ In this scenario, the server:
|
|
|
993
1026
|
--------------------
|
|
994
1027
|
|
|
995
1028
|
|
|
1029
|
+
#### getMissingBundleFiles(...)
|
|
1030
|
+
|
|
1031
|
+
```typescript
|
|
1032
|
+
getMissingBundleFiles(options: GetMissingBundleFilesOptions) => Promise<GetMissingBundleFilesResult>
|
|
1033
|
+
```
|
|
1034
|
+
|
|
1035
|
+
Return the manifest entries that still need to be downloaded for a partial update.
|
|
1036
|
+
|
|
1037
|
+
Pass the result from {@link getLatest} directly when it includes a `manifest`.
|
|
1038
|
+
The native plugin compares each manifest entry with the files already available
|
|
1039
|
+
in the builtin bundle and the local delta cache. Entries that can be reused are
|
|
1040
|
+
omitted from the returned `missing` list.
|
|
1041
|
+
|
|
1042
|
+
For encrypted manifests, pass the `sessionKey` returned by {@link getLatest} so
|
|
1043
|
+
encrypted file hashes can be checked against local files.
|
|
1044
|
+
|
|
1045
|
+
```typescript
|
|
1046
|
+
const latest = await CapacitorUpdater.getLatest();
|
|
1047
|
+
const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
|
|
1048
|
+
```
|
|
1049
|
+
|
|
1050
|
+
| Param | Type | Description |
|
|
1051
|
+
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1052
|
+
| **`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`. |
|
|
1053
|
+
|
|
1054
|
+
**Returns:** <code>Promise<<a href="#getmissingbundlefilesresult">GetMissingBundleFilesResult</a>></code>
|
|
1055
|
+
|
|
1056
|
+
**Since:** 8.47.0
|
|
1057
|
+
|
|
1058
|
+
--------------------
|
|
1059
|
+
|
|
1060
|
+
|
|
1061
|
+
#### getBundleDownloadSize(...)
|
|
1062
|
+
|
|
1063
|
+
```typescript
|
|
1064
|
+
getBundleDownloadSize(options: GetBundleDownloadSizeOptions) => Promise<GetBundleDownloadSizeResult>
|
|
1065
|
+
```
|
|
1066
|
+
|
|
1067
|
+
Estimate the download size for manifest entries before downloading them.
|
|
1068
|
+
|
|
1069
|
+
This method sends the provided manifest entries to the Capgo update endpoint
|
|
1070
|
+
once and reads the stored manifest `file_size` metadata. It does not perform
|
|
1071
|
+
per-file `HEAD` requests from the app.
|
|
1072
|
+
|
|
1073
|
+
Use this after {@link getMissingBundleFiles} to estimate only the files this
|
|
1074
|
+
device still needs:
|
|
1075
|
+
|
|
1076
|
+
```typescript
|
|
1077
|
+
const latest = await CapacitorUpdater.getLatest();
|
|
1078
|
+
const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
|
|
1079
|
+
const size = await CapacitorUpdater.getBundleDownloadSize({
|
|
1080
|
+
version: latest.version,
|
|
1081
|
+
manifest: missing.missing,
|
|
1082
|
+
});
|
|
1083
|
+
```
|
|
1084
|
+
|
|
1085
|
+
| Param | Type | Description |
|
|
1086
|
+
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
1087
|
+
| **`options`** | <code><a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a></code> | A {@link <a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a>} object containing manifest entries. |
|
|
1088
|
+
|
|
1089
|
+
**Returns:** <code>Promise<<a href="#getbundledownloadsizeresult">GetBundleDownloadSizeResult</a>></code>
|
|
1090
|
+
|
|
1091
|
+
**Since:** 8.47.0
|
|
1092
|
+
|
|
1093
|
+
--------------------
|
|
1094
|
+
|
|
1095
|
+
|
|
996
1096
|
#### setChannel(...)
|
|
997
1097
|
|
|
998
1098
|
```typescript
|
|
@@ -2098,6 +2198,13 @@ If you don't use backend, you need to provide the URL and version of the bundle.
|
|
|
2098
2198
|
| **`id`** | <code>string</code> |
|
|
2099
2199
|
|
|
2100
2200
|
|
|
2201
|
+
##### StartPreviewSessionOptions
|
|
2202
|
+
|
|
2203
|
+
| Prop | Type | Description | Default | Since |
|
|
2204
|
+
| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
|
|
2205
|
+
| **`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 |
|
|
2206
|
+
|
|
2207
|
+
|
|
2101
2208
|
##### BundleListResult
|
|
2102
2209
|
|
|
2103
2210
|
| Prop | Type |
|
|
@@ -2155,29 +2262,81 @@ Result returned after requesting an immediate native auto-update check.
|
|
|
2155
2262
|
|
|
2156
2263
|
##### LatestVersion
|
|
2157
2264
|
|
|
2158
|
-
| Prop
|
|
2159
|
-
|
|
|
2160
|
-
| **`version`**
|
|
2161
|
-
| **`checksum`**
|
|
2162
|
-
| **`breaking`**
|
|
2163
|
-
| **`major`**
|
|
2164
|
-
| **`message`**
|
|
2165
|
-
| **`sessionKey`**
|
|
2166
|
-
| **`error`**
|
|
2167
|
-
| **`kind`**
|
|
2168
|
-
| **`statusCode`**
|
|
2169
|
-
| **`old`**
|
|
2170
|
-
| **`url`**
|
|
2171
|
-
| **`manifest`**
|
|
2172
|
-
| **`
|
|
2173
|
-
| **`
|
|
2265
|
+
| Prop | Type | Description | Since |
|
|
2266
|
+
| ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
|
|
2267
|
+
| **`version`** | <code>string</code> | Result of getLatest method | 4.0.0 |
|
|
2268
|
+
| **`checksum`** | <code>string</code> | | 6 |
|
|
2269
|
+
| **`breaking`** | <code>boolean</code> | Indicates whether the update was flagged as breaking by the backend. | 7.22.0 |
|
|
2270
|
+
| **`major`** | <code>boolean</code> | | |
|
|
2271
|
+
| **`message`** | <code>string</code> | Optional message from the server. When no new version is available, this will be "No new version available". | |
|
|
2272
|
+
| **`sessionKey`** | <code>string</code> | | |
|
|
2273
|
+
| **`error`** | <code>string</code> | Error code from the server, if any. Use `kind` for classification instead of parsing this value. | |
|
|
2274
|
+
| **`kind`** | <code><a href="#updateresponsekind">UpdateResponseKind</a></code> | Classification for this response, provided by the backend. | 8.45.11 |
|
|
2275
|
+
| **`statusCode`** | <code>number</code> | HTTP status code returned by the update server for classified update-check responses. | 8.45.11 |
|
|
2276
|
+
| **`old`** | <code>string</code> | The previous/current version name (provided for reference). | |
|
|
2277
|
+
| **`url`** | <code>string</code> | Download URL for the bundle (when a new version is available). | |
|
|
2278
|
+
| **`manifest`** | <code>ManifestEntry[]</code> | File list for delta updates (when using multi-file downloads). | 6.1 |
|
|
2279
|
+
| **`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 |
|
|
2280
|
+
| **`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 |
|
|
2281
|
+
| **`link`** | <code>string</code> | Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release). | 7.35.0 |
|
|
2282
|
+
| **`comment`** | <code>string</code> | Optional comment or description for this bundle version. | 7.35.0 |
|
|
2283
|
+
|
|
2284
|
+
|
|
2285
|
+
##### GetMissingBundleFilesResult
|
|
2286
|
+
|
|
2287
|
+
| Prop | Type | Description | Since |
|
|
2288
|
+
| ------------------- | ---------------------------- | ----------------------------------------------------------------------- | ------ |
|
|
2289
|
+
| **`missing`** | <code>ManifestEntry[]</code> | Entries that are not available locally and need to be downloaded. | 8.47.0 |
|
|
2290
|
+
| **`total`** | <code>number</code> | Total entries in the provided manifest. | 8.47.0 |
|
|
2291
|
+
| **`missingCount`** | <code>number</code> | Number of entries that need to be downloaded. | 8.47.0 |
|
|
2292
|
+
| **`reusableCount`** | <code>number</code> | Number of entries that can be reused from builtin files or local cache. | 8.47.0 |
|
|
2293
|
+
|
|
2294
|
+
|
|
2295
|
+
##### GetBundleDownloadSizeResult
|
|
2296
|
+
|
|
2297
|
+
| Prop | Type | Description | Since |
|
|
2298
|
+
| ------------------ | ----------------------------- | --------------------------------------------------- | ------ |
|
|
2299
|
+
| **`totalSize`** | <code>number</code> | Sum of all known file sizes in bytes. | 8.47.0 |
|
|
2300
|
+
| **`knownFiles`** | <code>number</code> | Number of files with a known size. | 8.47.0 |
|
|
2301
|
+
| **`unknownFiles`** | <code>number</code> | Number of files whose size could not be determined. | 8.47.0 |
|
|
2302
|
+
| **`files`** | <code>BundleFileSize[]</code> | Per-file size results. | 8.47.0 |
|
|
2303
|
+
|
|
2304
|
+
|
|
2305
|
+
##### BundleFileSize
|
|
2306
|
+
|
|
2307
|
+
| Prop | Type | Description | Since |
|
|
2308
|
+
| ------------------ | --------------------------- | ----------------------------------------------------------- | ------ |
|
|
2309
|
+
| **`file_name`** | <code>string \| null</code> | File name from the manifest entry. | 8.47.0 |
|
|
2310
|
+
| **`file_hash`** | <code>string \| null</code> | File hash from the manifest entry. | 8.47.0 |
|
|
2311
|
+
| **`download_url`** | <code>string \| null</code> | Download URL from the manifest entry. | 8.47.0 |
|
|
2312
|
+
| **`size`** | <code>number</code> | Estimated bytes to download when the server exposes a size. | 8.47.0 |
|
|
2313
|
+
| **`error`** | <code>string</code> | Error for this entry when the size could not be determined. | 8.47.0 |
|
|
2174
2314
|
|
|
2175
2315
|
|
|
2176
2316
|
##### GetLatestOptions
|
|
2177
2317
|
|
|
2178
|
-
| Prop
|
|
2179
|
-
|
|
|
2180
|
-
| **`channel`**
|
|
2318
|
+
| Prop | Type | Description | Default | Since |
|
|
2319
|
+
| ----------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
|
|
2320
|
+
| **`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 |
|
|
2321
|
+
| **`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 |
|
|
2322
|
+
| **`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 |
|
|
2323
|
+
|
|
2324
|
+
|
|
2325
|
+
##### GetMissingBundleFilesOptions
|
|
2326
|
+
|
|
2327
|
+
| Prop | Type | Description | Since |
|
|
2328
|
+
| ---------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
|
|
2329
|
+
| **`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 |
|
|
2330
|
+
| **`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 |
|
|
2331
|
+
| **`sessionKey`** | <code>string</code> | Session key returned by {@link getLatest}, required only when file hashes are encrypted. | 8.47.0 |
|
|
2332
|
+
|
|
2333
|
+
|
|
2334
|
+
##### GetBundleDownloadSizeOptions
|
|
2335
|
+
|
|
2336
|
+
| Prop | Type | Description | Since |
|
|
2337
|
+
| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
|
|
2338
|
+
| **`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 |
|
|
2339
|
+
| **`version`** | <code>string</code> | Target bundle version. Pass `latest.version` when estimating files returned by {@link getLatest}. | 8.47.0 |
|
|
2181
2340
|
|
|
2182
2341
|
|
|
2183
2342
|
##### ChannelRes
|