@capgo/capacitor-updater 7.37.0 → 7.39.0

package/README.md

@@ -439,8 +439,15 @@ export default config;
 * [`isShakeMenuEnabled()`](#isshakemenuenabled)
 * [`getAppId()`](#getappid)
 * [`setAppId(...)`](#setappid)
+* [`getAppUpdateInfo(...)`](#getappupdateinfo)
+* [`openAppStore(...)`](#openappstore)
+* [`performImmediateUpdate()`](#performimmediateupdate)
+* [`startFlexibleUpdate()`](#startflexibleupdate)
+* [`completeFlexibleUpdate()`](#completeflexibleupdate)
+* [`addListener('onFlexibleUpdateStateChange', ...)`](#addlisteneronflexibleupdatestatechange-)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
+* [Enums](#enums)
 
 </docgen-index>
 
@@ -1642,6 +1649,201 @@ app IDs, or multi-tenant configurations).
 --------------------
 
 
+#### getAppUpdateInfo(...)
+
+```typescript
+getAppUpdateInfo(options?: GetAppUpdateInfoOptions | undefined) => Promise<AppUpdateInfo>
+```
+
+Get information about the app's availability in the App Store or Play Store.
+
+This method checks the native app stores to see if a newer version of the app
+is available for download. This is different from Capgo's OTA updates - this
+checks for native app updates that require going through the app stores.
+
+**Platform differences:**
+- **Android**: Uses Play Store's In-App Updates API for accurate update information
+- **iOS**: Queries the App Store lookup API (requires country code for accurate results)
+
+**Returns information about:**
+- Current installed version
+- Available version in the store (if any)
+- Whether an update is available
+- Update priority (Android only)
+- Whether immediate/flexible updates are allowed (Android only)
+
+Use this to:
+- Check if users need to update from the app store
+- Show "Update Available" prompts for native updates
+- Implement version gating (require minimum native version)
+- Combine with Capgo OTA updates for a complete update strategy
+
+| Param         | Type                                                                        | Description                                                                                                |
+| ------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| **`options`** | <code><a href="#getappupdateinfooptions">GetAppUpdateInfoOptions</a></code> | Optional {@link <a href="#getappupdateinfooptions">GetAppUpdateInfoOptions</a>} with country code for iOS. |
+
+**Returns:** <code>Promise&lt;<a href="#appupdateinfo">AppUpdateInfo</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+#### openAppStore(...)
+
+```typescript
+openAppStore(options?: OpenAppStoreOptions | undefined) => Promise<void>
+```
+
+Open the app's page in the App Store or Play Store.
+
+This navigates the user to your app's store listing where they can manually
+update the app. Use this as a fallback when in-app updates are not available
+or when the user needs to update on iOS.
+
+**Platform behavior:**
+- **Android**: Opens Play Store to the app's page
+- **iOS**: Opens App Store to the app's page
+
+**Customization options:**
+- `appId`: Specify a custom App Store ID (iOS) - useful for opening a different app's page
+- `packageName`: Specify a custom package name (Android) - useful for opening a different app's page
+
+| Param         | Type                                                                | Description                                                                                                          |
+| ------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **`options`** | <code><a href="#openappstoreoptions">OpenAppStoreOptions</a></code> | Optional {@link <a href="#openappstoreoptions">OpenAppStoreOptions</a>} to customize which app's store page to open. |
+
+**Since:** 8.0.0
+
+--------------------
+
+
+#### performImmediateUpdate()
+
+```typescript
+performImmediateUpdate() => Promise<AppUpdateResult>
+```
+
+Perform an immediate in-app update on Android.
+
+This triggers Google Play's immediate update flow, which:
+1. Shows a full-screen update UI
+2. Downloads and installs the update
+3. Restarts the app automatically
+
+The user cannot continue using the app until the update is complete.
+This is ideal for critical updates that must be installed immediately.
+
+**Requirements:**
+- Android only (throws error on iOS)
+- An update must be available (check with {@link getAppUpdateInfo} first)
+- The update must allow immediate updates (`immediateUpdateAllowed: true`)
+
+**User experience:**
+- Full-screen blocking UI
+- Progress shown during download
+- App automatically restarts after installation
+
+**Returns:** <code>Promise&lt;<a href="#appupdateresult">AppUpdateResult</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+#### startFlexibleUpdate()
+
+```typescript
+startFlexibleUpdate() => Promise<AppUpdateResult>
+```
+
+Start a flexible in-app update on Android.
+
+This triggers Google Play's flexible update flow, which:
+1. Downloads the update in the background
+2. Allows the user to continue using the app
+3. Notifies when download is complete
+4. Requires calling {@link completeFlexibleUpdate} to install
+
+Monitor the download progress using the `onFlexibleUpdateStateChange` listener.
+
+**Requirements:**
+- Android only (throws error on iOS)
+- An update must be available (check with {@link getAppUpdateInfo} first)
+- The update must allow flexible updates (`flexibleUpdateAllowed: true`)
+
+**Typical flow:**
+1. Call `startFlexibleUpdate()` to begin download
+2. Listen to `onFlexibleUpdateStateChange` for progress
+3. When status is `DOWNLOADED`, prompt user to restart
+4. Call `completeFlexibleUpdate()` to install and restart
+
+**Returns:** <code>Promise&lt;<a href="#appupdateresult">AppUpdateResult</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
+#### completeFlexibleUpdate()
+
+```typescript
+completeFlexibleUpdate() => Promise<void>
+```
+
+Complete a flexible in-app update on Android.
+
+After a flexible update has been downloaded (status `DOWNLOADED` in
+`onFlexibleUpdateStateChange`), call this method to install the update
+and restart the app.
+
+**Important:** This will immediately restart the app. Make sure to:
+- Save any user data before calling
+- Prompt the user before restarting
+- Only call when the download status is `DOWNLOADED`
+
+**Since:** 8.0.0
+
+--------------------
+
+
+#### addListener('onFlexibleUpdateStateChange', ...)
+
+```typescript
+addListener(eventName: 'onFlexibleUpdateStateChange', listenerFunc: (state: FlexibleUpdateState) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for flexible update state changes on Android.
+
+This event fires during the flexible update download process, providing:
+- Download progress (bytes downloaded / total bytes)
+- Installation status changes
+
+**Install status values:**
+- `UNKNOWN` (0): Unknown status
+- `PENDING` (1): Download pending
+- `DOWNLOADING` (2): Download in progress
+- `INSTALLING` (3): Installing the update
+- `INSTALLED` (4): Update installed (app restart needed)
+- `FAILED` (5): Update failed
+- `CANCELED` (6): Update was canceled
+- `DOWNLOADED` (11): Download complete, ready to install
+
+When status is `DOWNLOADED`, you should prompt the user and call
+{@link completeFlexibleUpdate} to finish the installation.
+
+| Param              | Type                                                                                    |
+| ------------------ | --------------------------------------------------------------------------------------- |
+| **`eventName`**    | <code>'onFlexibleUpdateStateChange'</code>                                              |
+| **`listenerFunc`** | <code>(state: <a href="#flexibleupdatestate">FlexibleUpdateState</a>) =&gt; void</code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.0.0
+
+--------------------
+
+
 #### Interfaces
 
 
@@ -1978,6 +2180,65 @@ If you don't use backend, you need to provide the URL and version of the bundle.
 | **`appId`** | <code>string</code> |
 
 
+##### AppUpdateInfo
+
+Information about app updates available in the App Store or Play Store.
+
+| Prop                              | Type                                                                                | Description                                                                                                                                                                                                              | Since |
+| --------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`currentVersionName`**          | <code>string</code>                                                                 | The currently installed version name (e.g., "1.2.3").                                                                                                                                                                    | 8.0.0 |
+| **`availableVersionName`**        | <code>string</code>                                                                 | The version name available in the store, if an update is available. May be undefined if no update information is available.                                                                                              | 8.0.0 |
+| **`currentVersionCode`**          | <code>string</code>                                                                 | The currently installed version code (Android) or build number (iOS).                                                                                                                                                    | 8.0.0 |
+| **`availableVersionCode`**        | <code>string</code>                                                                 | The version code available in the store (Android only). On iOS, this will be the same as `availableVersionName`.                                                                                                         | 8.0.0 |
+| **`availableVersionReleaseDate`** | <code>string</code>                                                                 | The release date of the available version (iOS only). Format: ISO 8601 date string.                                                                                                                                      | 8.0.0 |
+| **`updateAvailability`**          | <code><a href="#appupdateavailability">AppUpdateAvailability</a></code>             | The current update availability status.                                                                                                                                                                                  | 8.0.0 |
+| **`updatePriority`**              | <code>number</code>                                                                 | The priority of the update as set by the developer in Play Console (Android only). Values range from 0 (default/lowest) to 5 (highest priority). Use this to decide whether to show an update prompt or force an update. | 8.0.0 |
+| **`immediateUpdateAllowed`**      | <code>boolean</code>                                                                | Whether an immediate update is allowed (Android only). If `true`, you can call {@link CapacitorUpdaterPlugin.performImmediateUpdate}.                                                                                    | 8.0.0 |
+| **`flexibleUpdateAllowed`**       | <code>boolean</code>                                                                | Whether a flexible update is allowed (Android only). If `true`, you can call {@link CapacitorUpdaterPlugin.startFlexibleUpdate}.                                                                                         | 8.0.0 |
+| **`clientVersionStalenessDays`**  | <code>number</code>                                                                 | Number of days since the update became available (Android only). Use this to implement "update nagging" - remind users more frequently as the update ages.                                                               | 8.0.0 |
+| **`installStatus`**               | <code><a href="#flexibleupdateinstallstatus">FlexibleUpdateInstallStatus</a></code> | The current install status of a flexible update (Android only).                                                                                                                                                          | 8.0.0 |
+| **`minimumOsVersion`**            | <code>string</code>                                                                 | The minimum OS version required for the available update (iOS only).                                                                                                                                                     | 8.0.0 |
+
+
+##### GetAppUpdateInfoOptions
+
+Options for {@link CapacitorUpdaterPlugin.getAppUpdateInfo}.
+
+| Prop          | Type                | Description                                                                                                                                                                                                                                                                                                                     | Since |
+| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`country`** | <code>string</code> | Two-letter country code (ISO 3166-1 alpha-2) for the App Store lookup. This is required on iOS to get accurate App Store information, as app availability and versions can vary by country. Examples: "US", "GB", "DE", "JP", "FR" On Android, this option is ignored as the Play Store handles region detection automatically. | 8.0.0 |
+
+
+##### OpenAppStoreOptions
+
+Options for {@link CapacitorUpdaterPlugin.openAppStore}.
+
+| Prop              | Type                | Description                                                                                                                                                                                                  | Since |
+| ----------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
+| **`packageName`** | <code>string</code> | The Android package name to open in the Play Store. If not specified, uses the current app's package name. Use this to open a different app's store page. Only used on Android.                              | 8.0.0 |
+| **`appId`**       | <code>string</code> | The iOS App Store ID to open. If not specified, uses the current app's bundle identifier to look up the app. Use this to open a different app's store page or when automatic lookup fails. Only used on iOS. | 8.0.0 |
+
+
+##### AppUpdateResult
+
+Result of an app update operation.
+
+| Prop       | Type                                                                | Description                              | Since |
+| ---------- | ------------------------------------------------------------------- | ---------------------------------------- | ----- |
+| **`code`** | <code><a href="#appupdateresultcode">AppUpdateResultCode</a></code> | The result code of the update operation. | 8.0.0 |
+
+
+##### FlexibleUpdateState
+
+State information for flexible update progress (Android only).
+
+| Prop                       | Type                                                                                | Description                                                                        | Since |
+| -------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ----- |
+| **`installStatus`**        | <code><a href="#flexibleupdateinstallstatus">FlexibleUpdateInstallStatus</a></code> | The current installation status.                                                   | 8.0.0 |
+| **`bytesDownloaded`**      | <code>number</code>                                                                 | Number of bytes downloaded so far. Only available during the `DOWNLOADING` status. | 8.0.0 |
+| **`totalBytesToDownload`** | <code>number</code>                                                                 | Total number of bytes to download. Only available during the `DOWNLOADING` status. | 8.0.0 |
+
+
 #### Type Aliases
 
 
@@ -2002,6 +2263,45 @@ Payload emitted by {@link CapacitorUpdaterPlugin.addListener} with `breakingAvai
 
 <code><a href="#majoravailableevent">MajorAvailableEvent</a></code>
 
+
+#### Enums
+
+
+##### AppUpdateAvailability
+
+| Members                    | Value          | Description                                                                                |
+| -------------------------- | -------------- | ------------------------------------------------------------------------------------------ |
+| **`UNKNOWN`**              | <code>0</code> | Update availability is unknown. This typically means the check hasn't completed or failed. |
+| **`UPDATE_NOT_AVAILABLE`** | <code>1</code> | No update is available. The installed version is the latest.                               |
+| **`UPDATE_AVAILABLE`**     | <code>2</code> | An update is available for download.                                                       |
+| **`UPDATE_IN_PROGRESS`**   | <code>3</code> | An update is currently being downloaded or installed.                                      |
+
+
+##### FlexibleUpdateInstallStatus
+
+| Members           | Value           | Description                                                                                                                    |
+| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| **`UNKNOWN`**     | <code>0</code>  | Unknown install status.                                                                                                        |
+| **`PENDING`**     | <code>1</code>  | Download is pending and will start soon.                                                                                       |
+| **`DOWNLOADING`** | <code>2</code>  | Download is in progress. Check `bytesDownloaded` and `totalBytesToDownload` for progress.                                      |
+| **`INSTALLING`**  | <code>3</code>  | The update is being installed.                                                                                                 |
+| **`INSTALLED`**   | <code>4</code>  | The update has been installed. The app needs to be restarted to use the new version.                                           |
+| **`FAILED`**      | <code>5</code>  | The update failed to download or install.                                                                                      |
+| **`CANCELED`**    | <code>6</code>  | The update was canceled by the user.                                                                                           |
+| **`DOWNLOADED`**  | <code>11</code> | The update has been downloaded and is ready to install. Call {@link CapacitorUpdaterPlugin.completeFlexibleUpdate} to install. |
+
+
+##### AppUpdateResultCode
+
+| Members             | Value          | Description                                                                                                                 |
+| ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **`OK`**            | <code>0</code> | The update completed successfully.                                                                                          |
+| **`CANCELED`**      | <code>1</code> | The user canceled the update.                                                                                               |
+| **`FAILED`**        | <code>2</code> | The update failed.                                                                                                          |
+| **`NOT_AVAILABLE`** | <code>3</code> | No update is available.                                                                                                     |
+| **`NOT_ALLOWED`**   | <code>4</code> | The requested update type is not allowed. For example, trying to perform an immediate update when only flexible is allowed. |
+| **`INFO_MISSING`**  | <code>5</code> | Required information is missing. This can happen if {@link CapacitorUpdaterPlugin.getAppUpdateInfo} wasn't called first.    |
+
 </docgen-api>
 
 ### Listen to download events

package/android/build.gradle

@@ -57,6 +57,9 @@ dependencies {
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation 'io.github.g00fy2:versioncompare:1.5.0'
+    // Play Core library for in-app updates
+    implementation 'com.google.android.play:app-update:2.1.0'
+    implementation 'com.google.android.play:app-update-ktx:2.1.0'
     testImplementation "junit:junit:$junitVersion"
     testImplementation 'org.mockito:mockito-core:5.20.0'
     testImplementation 'org.json:json:20250517'