cordova-plugin-store-update-check

A Cordova plugin that checks Google Play and App Store for updates. The application controls when to check, show a prompt, and open the store listing.

GitHub · npm

The only method is check, with Cordova callbacks or a Promise. It never starts an update download, installs an update, restarts the app, shows dialogs, opens a store, or checks automatically at startup/resume. It does not disable the stores' own automatic updates.

Platforms

• Android: Cordova Android 12+, Google Play Store, Play App Update SDK 2.1.0 by default. Uses AppUpdateManager.getAppUpdateInfo().
• iOS: Cordova iOS 7+, Swift 5 language mode. Uses native URLSession to query Apple Lookup by the installed application's bundle ID and the explicitly selected store country. No Siren, CocoaPods dependencies, API key, backend, or WKWebView CORS configuration is required.
• Browser / other platforms: rejects with UNSUPPORTED_PLATFORM.

Install

From npm:

cordova plugin add cordova-plugin-store-update-check

For local development from a Cordova application root:

cordova plugin add /path/to/cordova-plugin-store-update-check

The Android SDK dependency can be overridden with --variable PLAY_APP_UPDATE_SDK_VERSION=2.1.0.

If the host app has not configured Swift yet, add <preference name="SwiftVersion" value="5.0" /> to its iOS configuration. The plugin does not overwrite the host application's compiler settings.

Usage

Call after deviceready or Ionic's platform.ready(). Use the Cordova global at runtime; do not bundle the plugin's CommonJS module into Angular.

The callback API is compatible with Awesome Cordova Plugins' default @Cordova() wrapper:

cordova.plugins.storeUpdate.check(
  { country: 'IE' },
  (info) => {
    if (info.available) {
      // Show your own dialog; open info.storeUrl only after acceptance.
    }
  },
  (error) => {
    console.warn(error.code, error.message);
  },
);

Both callbacks are required in callback mode. Android also supports check(success, error) without options. With no callbacks, the existing Promise API remains available:

import type { StoreUpdateInfo } from 'cordova-plugin-store-update-check';

const info: StoreUpdateInfo = await cordova.plugins.storeUpdate.check({
  country: 'IE',
});

if (info.available) {
  // Show your own dialog when the user's work has been saved.
  // Open info.storeUrl through your external-links service on acceptance.
}

country is a two-letter ISO 3166-1 alpha-2 App Store country, such as IE, GB, PL, or US. It is required on iOS and ignored on Android, where check() without arguments remains supported. Lowercase codes are accepted. There is no silent US fallback, and this plugin does not infer the Apple account's storefront from the phone's language/locale. Pass the storefront appropriate to your application/user; results describe the selected country's public listing.

The bundle identifier/package name is always read natively from the running application. JavaScript cannot substitute another application.

Awesome Cordova Plugins

Use the following metadata for the future upstream wrapper:

| Setting | Value | | ------------ | ----------------------------------- | | pluginName | StoreUpdateCheck | | plugin | cordova-plugin-store-update-check | | pluginRef | cordova.plugins.storeUpdate | | platforms | ['Android', 'iOS'] |

The wrapper method can use the standard decorator and return type:

@Cordova()
check(options?: StoreUpdateOptions): Promise<StoreUpdateInfo> {
  return; // Source stub for the Awesome Cordova Plugins build pipeline.
}

No otherPromise, custom callback indexes, or observable: true setting is needed. ACP appends success/error callbacks to the supplied arguments and builds its own Promise. This plugin supports both (options, success, error) and (success, error) so omitting optional Android options works correctly. The callback form returns void and does not create an extra Promise.

On both native platforms, the asynchronous request starts with NO_RESULT and keepCallback: true. This preserves the callback without emitting a success value. Its terminal OK or ERROR result uses keepCallback: false, releasing the callback. keepCallback controls native callback lifetime; ACP compatibility itself comes from the success/error API. Leaving keepCallback: true on the final result is unnecessary for a single check. JavaScript delivers at most one terminal callback, including when a timeout is followed by a late native response.

Compatibility tests exercise the actual distributed @awesome-cordova-plugins/[email protected] runtime. The upstream wrapper has not been submitted or published. Follow the ACP developer guide when adding it to that repository.

Releasing

The publish workflow publishes to npm through trusted publishing. It uses GitHub's short-lived OIDC identity and stores no npm token.

1. Update version in package.json and plugin.xml together, then merge the tested change to main.
2. Create a GitHub release whose tag is exactly v<package version>, for example v1.2.0.
3. The workflow verifies JavaScript, types and Swift tests before publishing. A tag/version mismatch stops the release.

Before the first automated release, configure the npm package's trusted publisher for owner MaximBelov, repository cordova-plugin-store-update-check, workflow publish.yml, and GitHub environment npm, with direct publishing enabled. The package must first exist on npm; its initial publication requires an authenticated maintainer. See npm trusted publishing.

Android result

{
  "platform": "android",
  "status": "available",
  "available": true,
  "availableVersionCode": 123,
  "packageName": "com.example.app",
  "storeUrl": "https://play.google.com/store/apps/details?id=com.example.app"
}

| Status | available | availableVersionCode | Meaning | | ------------- | ----------- | ---------------------- | ------------------------------------------------------------------------------------------------ | | available | true | Number | Google Play reports an available update. | | unavailable | false | null | Google Play reports no available update. | | in-progress | true | Number | A previously started developer-triggered update exists. This plugin does not start or resume it. |

The version code is an Android integer build code, not a display version such as 9.9.0. When no update is available, Google Play returns an arbitrary version code; this plugin returns null instead.

iOS result

{
  "platform": "ios",
  "status": "available",
  "available": true,
  "availableVersionCode": null,
  "packageName": "com.example.app",
  "storeUrl": "https://apps.apple.com/ie/app/id123456789",
  "country": "IE",
  "installedVersion": "9.9.0",
  "storeVersion": "9.10.0",
  "minimumOsVersion": "15.0",
  "compatible": true
}

• Compares Apple Lookup's version with the native CFBundleShortVersionString, not the CodePush version.
• Compares numeric components: 1.10 > 1.9, 1.2 == 1.2.0.
• available is true only when the store version is newer and its minimum iOS version is satisfied.
• compatible specifically describes minimum iOS compatibility. A newer release requiring a newer OS returns available: false, status: 'unavailable', compatible: false, and preserves the store version for the application's UI.
• No downgrade prompt when the installed version is newer than the public listing.
• Empty results, missing/malformed fields, or a mismatched bundle ID are errors, not proof that the app is up to date.
• Apple Lookup describes public store metadata; it does not check TestFlight builds, compare CFBundleVersion build numbers, or guarantee immediate propagation of a release. It is not an account-specific eligibility API. The App Store makes the final installation decision.

Opening the store

After the user accepts your Angular dialog, pass the returned storeUrl to your application's external-links service. For example, if the host app provides an ExternalLinksService:

await this.externalLinksService.launchWebsite(info.storeUrl, {
  externalBrowser: true,
  thirdPartyWarning: false,
});

These HTTPS URLs point to the relevant store listings. On Android, a host app that specifically needs to launch the Play Store application can use an external market://details?id=<packageName> intent with an HTTPS fallback. The plugin opens neither URL itself.

Errors

Failures call the error callback, or reject the Promise when callbacks are omitted, with an Error named StoreUpdateCheckError. Its code is:

| Code | Meaning | | ---------------------- | ---------------------------------------------------------- | | UNSUPPORTED_PLATFORM | Neither Android nor iOS. | | INVALID_ARGUMENT | Invalid options or missing/invalid two-letter iOS country. | | CHECK_FAILED | Native bridge, store request, or HTTP failure. | | AVAILABILITY_UNKNOWN | Google Play cannot determine update availability. | | APP_NOT_FOUND | No matching application in the selected App Store country. | | INVALID_RESPONSE | Malformed Apple Lookup response/version metadata. | | TIMEOUT | The request exceeded its timeout. |

The nullable nativeCode preserves a Google Play InstallException code or an iOS network error code when available.

JavaScript stops waiting after 15 seconds; a late response cannot change a settled promise. iOS additionally bounds network requests to 12 seconds and cancels pending requests on WebView reset/plugin disposal. The JavaScript timeout does not cancel an Android Play request.

Catch errors in the application without blocking normal use. Throttle checks and remember deferrals in your Angular service. Persist drafts independently: opening a store listing does not protect in-memory work from installation or process termination.

Migration from update-notifier

This package is not automatically connected to the host app. To migrate:

1. Remove the old update-notifier plugin and its dependencies/patches. Otherwise its startup hooks can still initiate updates or show prompts.
2. Remove UpdateNotifier.onUpdateReady() / completeUpdate() integration and obsolete Siren preferences.
3. Add this plugin and call check({ country }) from Angular at appropriate moments.
4. Show your own dialog and open the store only after acceptance.

The iOS check is now included in the package; a separate Angular Apple Lookup adapter is not needed.

Verification

From this plugin's repository root:

npm ci
npm run format:check

# JavaScript bridge and ACP compatibility tests; Node.js 22+.
npm test

# Only the real Awesome Cordova Plugins runtime integration tests.
npm run test:compat

# Native Swift lookup tests; macOS and Xcode command-line tools required.
npm run test:ios

# Type declarations.
npm run test:types

The Swift tests exercise the actual request builder and response/version handling with fixtures. They do not contact Apple or prove on-device store behavior.

Before release, install the plugin into an Android/iOS Cordova app and check:

• Android: follow Google's Play testing process with matching application ID, signing identity and tester account. A higher eligible version should return available; checking alone must not start an update. After updating through Play, check again. A sideloaded debug APK is not a reliable positive-update test.
• iOS: use the real bundle ID and a country where the app is published. Check older, equal and newer native versions; an incompatible minimum OS; missing listings; network failures; and WebView reset during a request. Confirm the returned listing is correct and no dialog/navigation occurs automatically.
• On both platforms, verify draft recovery after leaving the application and installing an update through the store.

References: Google Play checks, AppUpdateInfo, Play testing, Apple Lookup, Siren's Lookup implementation, Cordova iOS plugins.