Skip to main content

App Update — Methods

Every public method on the App Update interface. Signatures are copied verbatim from src/definitions.ts in the plugin repo.

import { NativeUpdate } from 'native-update';

All methods return Promise<T> and throw a typed UpdateError for failure cases. The most relevant codes for App Update are listed in the common errors section at the bottom.

getAppUpdateInfo()​

getAppUpdateInfo(): Promise<AppUpdateInfo>

The single read-only call. Returns whether an update is available, what flows are allowed for it, and store-managed download progress (when a flexible update is mid-flight).

Returns AppUpdateInfo — updateAvailable, currentVersion, availableVersion, updatePriority, immediateUpdateAllowed, flexibleUpdateAllowed, clientVersionStalenessDays, installStatus, bytesDownloaded, totalBytesToDownload.

Throws NETWORK_ERROR (no connectivity to the lookup endpoint), PLATFORM_NOT_SUPPORTED (e.g. Android device without Play Services).

const info = await NativeUpdate.getAppUpdateInfo();

if (!info.updateAvailable) return;

console.log(`Update: ${info.currentVersion} → ${info.availableVersion}`);
console.log(`Priority: ${info.updatePriority ?? 'n/a'}`);
console.log(`Stale for ${info.clientVersionStalenessDays ?? 0} days`);

Cheap to call. Safe to call at every cold start, on resume, or on a timer. Idempotent.

performImmediateUpdate()​

performImmediateUpdate(): Promise<void>

Triggers Google Play's full-screen blocking update flow. The user sees a Play-branded dialog with "Update" / "Cancel" buttons; choosing "Cancel" exits your app. After successful update, your app relaunches on the new binary.

Throws PLATFORM_NOT_SUPPORTED on iOS / web, UPDATE_NOT_AVAILABLE if no update is staged, UPDATE_IN_PROGRESS if a flexible update is already running.

Best for: security patches, breaking server contract changes, data-integrity fixes (priority 5).

const info = await NativeUpdate.getAppUpdateInfo();
if (info.updateAvailable && info.immediateUpdateAllowed && info.updatePriority >= 5) {
  await NativeUpdate.performImmediateUpdate();
}
Cancellation kills the app

If the user taps "Cancel", Play exits your app process. Do not save state in the activity that hosts this call without persisting it first.

startFlexibleUpdate()​

startFlexibleUpdate(): Promise<void>

Triggers Google Play's background download flow. The user accepts a small Play dialog, then the download proceeds in the background while the user keeps using your app. When the download finishes, the SDK fires the appUpdateReady event — that is your cue to call completeFlexibleUpdate().

Subscribe to appUpdateProgress for a download progress UI.

Throws PLATFORM_NOT_SUPPORTED on iOS / web, UPDATE_NOT_AVAILABLE, UPDATE_IN_PROGRESS.

Best for: non-critical improvements, bug fixes (priority 1–4).

await NativeUpdate.startFlexibleUpdate();

const handle = await NativeUpdate.addListener('appUpdateProgress', ({ percent }) => {
  setUpdatePercent(percent);
});

const ready = await NativeUpdate.addListener('appUpdateReady', () => {
  showSnackbar('Update ready — restart to apply', {
    action: { label: 'Restart', onClick: () => NativeUpdate.completeFlexibleUpdate() },
  });
});

completeFlexibleUpdate()​

completeFlexibleUpdate(): Promise<void>

Finishes a flexible update — applies the downloaded APK and relaunches the app. Call this only after the appUpdateReady event fires.

Throws PLATFORM_NOT_SUPPORTED on iOS / web, UPDATE_NOT_AVAILABLE if no flexible update is staged, INSTALL_ERROR on platform-side install failure.

// In response to a user tapping "Restart now":
await NativeUpdate.completeFlexibleUpdate();
// Process exits and relaunches.

openAppStore(options?)​

openAppStore(options?: OpenAppStoreOptions): Promise<void>

Cross-platform fallback — opens the store page for your app. Uses appStoreId (iOS) or packageName (Android) from your config by default; pass options.appId to override.

ParameterTypeRequiredDescription
options.appIdstringnoOverride the configured app ID. iOS expects the numeric App Store ID; Android expects the Java package name.

Throws INVALID_CONFIG (no appStoreId / packageName configured and no override passed).

// Use configured IDs:
await NativeUpdate.openAppStore();

// Override (e.g. opening a sister app's store page):
await NativeUpdate.openAppStore({ appId: '1234567890' });

On iOS this opens itms-apps://itunes.apple.com/app/id<appId>. On Android it opens market://details?id=<packageName> (falling back to the web Play URL if the Play Store app is unavailable). On web it opens https://apps.apple.com/... or https://play.google.com/... based on Capacitor.getPlatform() heuristics — typically web should treat both as outbound links.

Common errors​

CodeWhen you see itWhat to do
NETWORK_ERRORNo connectivity for the lookup callCache the last AppUpdateInfo; retry on next foreground.
PLATFORM_NOT_SUPPORTEDCalling performImmediateUpdate / startFlexibleUpdate / completeFlexibleUpdate on iOS or webBranch on Capacitor.getPlatform(); fall back to openAppStore().
UPDATE_NOT_AVAILABLECalling complete / immediate before a download existsAlways gate behind getAppUpdateInfo() + appUpdateReady event.
UPDATE_IN_PROGRESSTriggering a second flow before the first completesInspect info.installStatus; wait for INSTALLED / FAILED.
UPDATE_CANCELLEDUser declined the Play promptSurface a non-blocking banner; respect their choice for the session.
INSTALL_ERRORPlay install step failedLog to your monitoring; retry after a short delay or fall back to openAppStore().
INVALID_CONFIGopenAppStore() called without an IDConfigure appStoreId and packageName in config.

Full code list ships in Batch 4 alongside the security reference.

Method reference verified against src/definitions.ts in the plugin repo as of 2026-05-10. Documented by Ahsan Mahmood.