capacitor-updater

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #golang #go #rust #deep-learning #docker #java #awesome #vue #mcp #ios #open-source

capacitor-updater

(★ 829)

Capacitor plugin for Instant updates: Ship updates, fixes, changes, and features within minutes

File Explorer

Download Latest Version (.zip)

- worktrees.json
- - bug-report.md
  - feature-request.md
- - android-preview-menu-buttons.webp
  - buffer-256kb-vs-ladder.webp
  - cpu-scaled-concurrency.webp
  - manifest-range-and-hash.webp
- - verify-packed-example.sh
- - build.yml
  - bump_version.yml
  - deploy_example_app.yml
  - github-releases-to-discord.yml
  - pr_beta_prompt.yml
  - pr_beta_publish.yml
  - test.yml
- FUNDING.yml
- - example-app-smoke-config-guards.yaml
  - example-app-smoke-no-persist.yaml
  - example-app-smoke.yaml
- - cold-launch-app.yaml
  - relaunch-app.yaml
- - assert-live-update-core.yaml
  - assert-live-update-download.yaml
  - example-app-smoke-config-guards.yaml
  - example-app-smoke-no-persist.yaml
  - example-app-smoke.yaml
  - live-update-deferred.yaml
  - manual-manifest-flow.yaml
  - manual-zip-config-guards-flow.yaml
  - manual-zip-flow.yaml
  - native-reset-live.yaml
- assert-state.yaml
- deferred-download.yaml
- example-app-api-smoke-android.yaml
- example-app-api-smoke-config-guards-android.yaml
- example-app-api-smoke-config-guards.yaml
- example-app-api-smoke-ios.yaml
- example-app-api-smoke-no-persist-ios.yaml
- example-app-api-smoke-no-persist.yaml
- example-app-api-smoke-runtime-ios.yaml
- example-app-api-smoke-sequence-config-guards-ios.yaml
- example-app-api-smoke-sequence-ios.yaml
- example-app-api-smoke-sequence-manual-zip-ios.yaml
- example-app-api-smoke.yaml
- initial-direct-update.yaml
- kill-then-direct-update.yaml
- manual-manifest-flow.yaml
- manual-manifest-v1-flow.yaml
- manual-manifest-v2-flow.yaml
- manual-zip-cleanup-flow.yaml
- manual-zip-config-guards-flow.yaml
- manual-zip-flow.yaml
- manual-zip-v1-flow.yaml
- manual-zip-v2-queue-flow.yaml
- manual-zip-v2-reload-and-failed-flow.yaml
- settings.json
- .gitignore
- .project
- build.gradle
- gradle.properties
- gradlew
- gradlew.bat
- proguard-rules.pro
- settings.gradle
- github-social-preview.png
- github-social-template.svg
- - .gitignore
  - build.gradle
  - capacitor.settings.gradle
  - gradle.properties
  - gradlew
  - gradlew.bat
  - settings.gradle
  - variables.gradle
- - capgo-icon.png
  - capgo-icon.svg
- - .gitignore
  - debug.xcconfig
- - icon.png
- - main.js
  - style.css
- .gitignore
- bun.lock
- bunfig.toml
- capacitor.config.ts
- index.html
- package.json
- README.md
- vite.config.ts
- .gitignore
- core.json
- crypto-rsa.json
- README.md
- - install-bun.sh
  - install-maestro.sh
- - build-bundles.mjs
  - command.mjs
  - fake-capgo-server.mjs
  - prepare-android-scenario.mjs
  - prepare-ios-scenario.mjs
  - run-android-live-update-ci.sh
  - run-android-live-update.sh
  - run-android-native-update-reset.sh
  - run-ios-live-update.sh
  - run-ios-native-update-reset.sh
  - scenarios.mjs
  - select-ios-simulator.sh
- check-capacitor-plugin-wiring.mjs
- generate-ai-changelog.mjs
- generate-docs.js
- generate-rsa-contract-fixtures.mjs
- native-platform.sh
- test-ios.sh
- test-maestro-android.sh
- test-maestro-ios.sh
- definitions.ts
- history.ts
- index.ts
- web.ts
.eslintignore
.gitignore
.prettierignore
AGENTS.md
api.md
bun.lock
CapgoCapacitorUpdater.podspec
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
jsr.json
LICENSE
package.json
Package.swift
README.md
renovate.json
rollup.config.mjs
tsconfig.json

# Installation Guide

1. Get the code

git clone https://github.com/Cap-go/capacitor-updater

Downloads the entire project code from GitHub to your computer.

cd capacitor-updater

Moves into the project folder you just downloaded.

2. Gradle (Java/Kotlin)

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
JDK (Java) Required to build and run Java/Kotlin projects.
Gradle If the repo includes gradlew (Gradle Wrapper), you don't need to install Gradle separately.

cd android

This project's files live in a subfolder, so move into it first.

./gradlew build

Builds the project using Gradle.

✅ A BUILD SUCCESSFUL message means it worked. The output is created under build/.

3. Node.js

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install @capgo/capacitor-updater

Downloads and installs the libraries listed in package.json.

npm install @capgo/capacitor-updater@latest

Downloads and installs the libraries listed in package.json.

npm install @capgo/capacitor-updater@lts-v7

Downloads and installs the libraries listed in package.json.

npm install @capgo/capacitor-updater@lts-v6

Downloads and installs the libraries listed in package.json.

npm install @capgo/capacitor-updater@lts-v5

Downloads and installs the libraries listed in package.json.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Capacitor updater
<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>
[![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.com/invite/VnYRvBfgA6)
<a href="https://discord.com/invite/VnYRvBfgA6"><img src="https://img.shields.io/discord/912707985829163099?color=%237289DA&label=Discord" alt="Discord">
[![npm](https://img.shields.io/npm/dm/@capgo/capacitor-updater)](https://www.npmjs.com/package/@capgo/capacitor-updater)
[![GitHub latest commit](https://badgen.net/github/last-commit/Cap-go/capacitor-updater/main)](https://GitHub.com/Cap-go/capacitor-updater/commit/)
[![https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg](https://good-labs.github.io/greater-good-affirmation/assets/images/badge.svg)](https://good-labs.github.io/greater-good-affirmation)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=Cap-go_capacitor-updater&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=Cap-go_capacitor-updater)
[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=Cap-go_capacitor-updater&metric=bugs)](https://sonarcloud.io/summary/new_code?id=Cap-go_capacitor-updater)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Cap-go_capacitor-updater&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Cap-go_capacitor-updater)
[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=Cap-go_capacitor-updater&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=Cap-go_capacitor-updater)
[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Cap-go_capacitor-updater&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Cap-go_capacitor-updater)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Cap-go_capacitor-updater&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Cap-go_capacitor-updater)
[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=Cap-go_capacitor-updater&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=Cap-go_capacitor-updater)
[![Open Bounties](https://img.shields.io/endpoint?url=https%3A%2F%2Fconsole.algora.io%2Fapi%2Fshields%2FCapgo%2Fbounties%3Fstatus%3Dopen)](https://console.algora.io/org/Capgo/bounties?status=open)
[![Rewarded Bounties](https://img.shields.io/endpoint?url=https%3A%2F%2Fconsole.algora.io%2Fapi%2Fshields%2FCapgo%2Fbounties%3Fstatus%3Dcompleted)](https://console.algora.io/org/Capgo/bounties?status=completed)

<div align="center">
  <h2><a href="https://capgo.app/?ref=plugin_updater_v7"> ➡️ Get Instant updates for your App with Capgo</a></h2>
  <h2><a href="https://capgo.app/consulting/?ref=plugin_updater_v7"> Missing a feature? We’ll build the plugin for you 💪</a></h2>
</div>

Capacitor plugin to update your app remotely in real-time.

Open-source Alternative to Appflow, Codepush or Capawesome

## Why Capacitor Updater?

App store review processes can take days or weeks, blocking critical bug fixes and updates from reaching your users. Capacitor Updater solves this by:

- **Instant updates** - Push JavaScript/HTML/CSS updates directly to users without app store review
- **Delta updates** - Only download changed files, making updates ultra-fast
- **Rollback protection** - Automatically revert broken updates to keep your app stable
- **Open source** - Self-host or use Capgo Cloud, with full control over your update infrastructure
- **Battle-tested** - Used by 3000+ production apps with proven reliability
- **Most stared** - Capacitor updater is the most stared Capacitor plugin on GitHub

Perfect for fixing bugs immediately, A/B testing features, and maintaining control over your release schedule.

## Features

- ☁️ Cloud / Self hosted Support: Use our [Cloud](https://capgo.app/) to manage your app updates or yours.
- 📦 Bundle Management: Download, assign to channel, rollback.
- 📺 Channel Support: Use channels to manage different environments.
- 🎯 Set Channel to specific device to do QA or debug one user.
- 🔄 Auto Update: Automatically download and set the latest bundle for the app.
- 🛟 Rollback: Reset the app to last working bundle if an incompatible bundle has been set.
- 🔁 **Delta Updates**: Make instant updates by only downloading changed files.
- 🔒 **Security**: Encrypt and sign each updates with best in class security standards.
- ⚔️ **Battle-Tested**: Used in more than 3000 projects.
- 📊 View your deployment statistics
- 🔋 Supports Android and iOS
- ⚡️ Capacitor 4/5/6/7/8 support
- 🌐 **Open Source**: Licensed under the Mozilla Public License 2.0
- 🌐 **Open Source Backend**: Self install [our backend](https://github.com/Cap-go/capgo) in your infra

You have 3 ways possible :
- Use [capgo.app](https://capgo.app) a full featured auto-update system in 5 min Setup, to manage version, update, revert and see stats.
- Use your own server update with auto-update system
- Use manual methods to zip, upload, download, from JS to do it when you want.

## Documentation
The most complete [documentation here](https://capgo.app/docs/).

## Community
Join the [discord](https://discord.gg/VnYRvBfgA6) to get help.

## Migration to v8

This major version is here to follow Capacitor major version 8

First follow the migration guide of Capacitor:

[https://capacitorjs.com/docs/updating/8-0](https://capacitorjs.com/docs/updating/8-0/)

## Migration to v7.34

- **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.
  - Channel assignments persist between app restarts
  - Use `unsetChannel()` to clear the local assignment and revert to `defaultChannel`
  - Old devices (< v7.34.0) use now a KV storage to prevent overload the primary DB of Capgo
- **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.

## Migration to v7

The minimum iOS version is now **15.0** to match Capacitor 7/8 requirements.

Starting from v8, the plugin uses [ZIPFoundation](https://github.com/weichsel/ZIPFoundation) instead of SSZipArchive/ZipArchive for ZIP extraction. ZIPFoundation uses Apple's native `libcompression` framework, which removes the previous zlib dependency and its associated security constraints.

## Compatibility

| Plugin version | Capacitor compatibility | Maintained        |
| -------------- | ----------------------- | ----------------- |
| v8.\*.\*       | v8.\*.\*                | ✅                 |
| v7.\*.\*       | v7.\*.\*                | ✅                 |
| v6.\*.\*       | v6.\*.\*                | ✅                 |
| v5.\*.\*       | v5.\*.\*                | ✅ |
| v4.\*.\*       | v4.\*.\*                | ✅                 |
| v3.\*.\*       | v3.\*.\*                | ⚠️ Deprecated     |
| > 7            | v4.\*.\*                | ⚠️ Deprecated, our CI got crazy and bumped too much version     |

> **Note:** Versions 4, 5, 6, 7, and 8 all share the same features. The major version simply follows your Capacitor version. You can safely use any of these versions that matches your Capacitor installation.

### iOS

#### Privacy manifest

Add the `NSPrivacyAccessedAPICategoryUserDefaults` dictionary key to your [Privacy Manifest](https://capacitorjs.com/docs/ios/privacy-manifest) (usually `ios/App/PrivacyInfo.xcprivacy`):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
      
      <dict>
        <key>NSPrivacyAccessedAPIType</key>
        <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
        <key>NSPrivacyAccessedAPITypeReasons</key>
        <array>
          <string>CA92.1</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>
```

We recommend to declare [`CA92.1`](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api#4278401) as the reason for accessing the [`UserDefaults`](https://developer.apple.com/documentation/foundation/userdefaults) API.

## Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

Then use the following prompt:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-updater` plugin in my project.
```

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

Step by step here: [Getting started](https://capgo.app/docs/getting-started/add-an-app/)

```bash
npm install @capgo/capacitor-updater
npx cap sync
```

### Install a specific version

Use npm tags to install the version matching your Capacitor version:

```bash
# For Capacitor 8 (latest)
npm install @capgo/capacitor-updater@latest

# For Capacitor 7
npm install @capgo/capacitor-updater@lts-v7

# For Capacitor 6
npm install @capgo/capacitor-updater@lts-v6

# For Capacitor 5
npm install @capgo/capacitor-updater@lts-v5

# For Capacitor 4
npm install @capgo/capacitor-updater@lts-v4
```

## Auto-update setup

Create your account in [capgo.app](https://capgo.app) and get your [API key](https://console.capgo.app/dashboard/apikeys)
- Login to CLI `npx @capgo/cli@latest init API_KEY`
And follow the steps by step to setup your app.

For detailed instructions on the auto-update setup, refer to the [Auto update documentation](https://capgo.app/docs/plugin/cloud-mode/getting-started/).

## No Cloud setup

Download update distribution zipfiles from a custom URL. Manually control the entire update process.

- Edit your `capacitor.config.json` like below, set `autoUpdate` to false.
```json
// capacitor.config.json
{
	"appId": "**.***.**",
	"appName": "Name",
	"plugins": {
		"CapacitorUpdater": {
			"autoUpdate": false,
		}
	}
}
```
- Add to your main code
```javascript
  import { CapacitorUpdater } from '@capgo/capacitor-updater'
  CapacitorUpdater.notifyAppReady()
```
This informs Capacitor Updater that the current update bundle has loaded successfully. Failing to call this method will cause your application to be rolled back to the previously successful version (or built-in bundle).
- Add this to your application.
```javascript
  const version = await CapacitorUpdater.download({
    version: '0.0.4',
    url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
  })
  await CapacitorUpdater.set(version); // sets the new version, and reloads the app
```
- Failed updates will automatically roll back to the last successful version.
- Example: Using App-state to control updates, with SplashScreen:
You might also consider performing auto-update when application state changes, and using the Splash Screen to improve user experience.
```javascript
  import { CapacitorUpdater, VersionInfo } from '@capgo/capacitor-updater'
  import { SplashScreen } from '@capacitor/splash-screen'
  import { App } from '@capacitor/app'

let version: VersionInfo;
  App.addListener('appStateChange', async (state) => {
      if (state.isActive) {
        // Ensure download occurs while the app is active, or download may fail
        version = await CapacitorUpdater.download({
          version: '0.0.4',
          url: 'https://github.com/Cap-go/demo-app/releases/download/0.0.4/dist.zip',
        })
      }

if (!state.isActive && version) {
        // Activate the update when the application is sent to background
        SplashScreen.show()
        try {
          await CapacitorUpdater.set(version);
          // At this point, the new version should be active, and will need to hide the splash screen
        } catch () {
          SplashScreen.hide() // Hide the splash screen again if something went wrong
        }
      }
  })

```

TIP: If you prefer a secure and automated way to update your app, you can use [capgo.app](https://capgo.app) - a full-featured, auto-update system.

### Store Guideline Compliance

Android Google Play and iOS App Store have corresponding guidelines that have rules you should be aware of before integrating the Capacitor-updater solution within your application.

#### Google play

Third paragraph of [Device and Network Abuse](https://support.google.com/googleplay/android-developer/answer/9888379?hl=en) topic describe that updating source code by any method besides Google Play's update mechanism is restricted. But this restriction does not apply to updating JavaScript bundles.
> This restriction does not apply to code that runs in a virtual machine and has limited access to Android APIs (such as JavaScript in a web view or browser).

That fully allow Capacitor-updater as it updates just JS bundles and can't update native code part.

#### App Store

Paragraph **3.3.2**, since back in 2015's [Apple Developer Program License Agreement](https://developer.apple.com/programs/ios/information/) fully allowed performing over-the-air updates of JavaScript and assets.

And in its latest version (20170605) [downloadable here](https://developer.apple.com/terms/) this ruling is even broader:

> Interpreted code may be downloaded to an Application, but only so long as such code:
- (a) does not change the primary purpose of the Application by providing features or functionality that are inconsistent with the intended and advertised purpose of the Application as submitted to the App Store
- (b) does not create a store or storefront for other code or applications
- (c) does not bypass signing, sandbox, or other security features of the OS.

Capacitor-updater allows you to respect these rules in full compliance, so long as the update you push does not significantly deviate your product from its original App Store approved intent.

To further remain in compliance with Apple's guidelines, we suggest that App Store-distributed apps don't enable the `Force update` scenario, since in the [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/) it is written that:

> Apps must not force users to rate the app, review the app, download other apps, or other similar actions to access functionality, content, or use of the app.

This is not a problem for the default behavior of background update, since it won't force the user to apply the new version until the next app close, but at least you should be aware of that ruling if you decide to show it.

### Packaging `dist.zip` update bundles

Capacitor Updater works by unzipping a compiled app bundle to the native device filesystem. Whatever you choose to name the file you upload/download from your release/update server URL (via either manual or automatic updating), this `.zip` bundle must meet the following requirements:

- The zip file should contain the full contents of your production Capacitor build output folder, usually `{project directory}/dist/` or `{project directory}/www/`. This is where `index.html` will be located, and it should also contain all bundled JavaScript, CSS, and web resources necessary for your app to run.
- Do not password encrypt the bundle zip file, or it will fail to unpack.
- Make sure the bundle does not contain any extra hidden files or folders, or it may fail to unpack.

### Downgrading to a previous version of the updater plugin

Downgrading to a previous version of the updater plugin is not supported.

## Updater Plugin Config

<docgen-config>

CapacitorUpdater can be configured with these options:

| Prop                                   | Type                                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Default                                                                       | Since   |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------- |
| **`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>                                            |         |
| **`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>                                                |         |
| **`autoDeleteFailed`**                 | <code>boolean</code>                                                                                       | Configure whether the plugin should use automatically delete failed bundles. Only available for Android and iOS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | <code>true</code>                                                             |         |
| **`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>                                                             |         |
| **`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. When {@link periodCheckDelay} is greater than 0, it also checks 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>                                                             |         |
| **`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>                                                             |         |
| **`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>                                 |         |
| **`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>                            |         |
| **`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, unclean WebView restarts, app launch readiness timing, and WebView load milestones when available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | <code>https://plugin.capgo.app/stats</code>                                   |         |
| **`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   |
| **`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 |
| **`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   |
| **`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   |
| **`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  |
| **`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  |
| **`periodCheckDelay`**                 | <code>number</code>                                                                                        | Configure the interval in seconds for repeating update checks while the app stays open. Foreground checks still run when this is 0. Values below 600 are normalized to 600. Only available for Android and iOS. Cannot be less than 600 seconds (10 minutes).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | <code>0 (disabled)</code>                                                     |         |
| **`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 |
| **`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 |
| **`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 |
| **`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 |
| **`localSupaAnon`**                    | <code>string</code>                                                                                        | Configure the CLI to use a local server for testing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | <code>undefined</code>                                                        | 4.17.48 |
| **`localApi`**                         | <code>string</code>                                                                                        | Configure the CLI to use a local api for testing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <code>undefined</code>                                                        | 6.3.3   |
| **`localApiFiles`**                    | <code>string</code>                                                                                        | Configure the CLI to use a local file api for testing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | <code>undefined</code>                                                        | 6.3.3   |
| **`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   |
| **`allowModifyAppId`**                 | <code>boolean</code>                                                                                       | Allow the plugin to modify the appId dynamically from the JavaScript side.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | <code>false</code>                                                            | 7.14.0  |
| **`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  |
| **`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  |
| **`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  |
| **`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  |
| **`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  |
| **`persistDefaultChannelOnReinstall`** | <code>boolean</code>                                                                                       | Keep the default channel stored by {@link CapacitorUpdaterPlugin.setChannel} or refreshed by {@link CapacitorUpdaterPlugin.getChannel} when app data is restored into a new app install. `setChannel()` and a successful `getChannel()` still persist the selected channel across app restarts. When this option is `false`, native startup clears that persisted channel when it detects app data restored into a new installation. Native build cleanup clears the persisted channel only when `persistDefaultChannelOnReinstall` is `false`, `resetWhenUpdate` is `true`, and the native build version has changed. Only available for Android and iOS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | <code>true</code>                                                             | 8.51.0  |
| **`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   |
| **`appId`**                            | <code>string</code>                                                                                        | Configure the app id for the app in the config.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | <code>undefined</code>                                                        | 6.0.0   |
| **`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   |
| **`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   |
| **`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  |
| **`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   |
| **`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  |
| **`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  |

### Examples

In `capacitor.config.json`:

```json
{
  "plugins": {
    "CapacitorUpdater": {
      "appReadyTimeout": 1000 // (1 second, minimum 1000),
      "responseTimeout": 10 // (10 second),
      "autoDeleteFailed": false,
      "autoDeletePrevious": false,
      "autoUpdate": "onlyDownload",
      "resetWhenUpdate": false,
      "updateUrl": https://example.com/api/auto_update,
      "channelUrl": https://example.com/api/channel,
      "statsUrl": https://example.com/api/stats,
      "publicKey": undefined,
      "version": undefined,
      "directUpdate": undefined,
      "autoSplashscreen": undefined,
      "autoSplashscreenLoader": undefined,
      "autoSplashscreenTimeout": undefined,
      "periodCheckDelay": 3600 (1 hour),
      "localS3": undefined,
      "localHost": undefined,
      "localWebHost": undefined,
      "localSupa": undefined,
      "localSupaAnon": undefined,
      "localApi": undefined,
      "localApiFiles": undefined,
      "allowModifyUrl": undefined,
      "allowModifyAppId": undefined,
      "allowManualBundleError": undefined,
      "allowPreview": undefined,
      "persistCustomId": undefined,
      "persistModifyUrl": undefined,
      "allowSetDefaultChannel": undefined,
      "persistDefaultChannelOnReinstall": undefined,
      "defaultChannel": undefined,
      "appId": undefined,
      "keepUrlPathAfterReload": undefined,
      "disableJSLogging": undefined,
      "osLogging": undefined,
      "shakeMenu": undefined,
      "shakeMenuGesture": undefined,
      "allowShakeChannelSelector": undefined
    }
  }
}
```

In `capacitor.config.ts`:

```ts
/// <reference types="@capgo/capacitor-updater" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      appReadyTimeout: 1000 // (1 second, minimum 1000),
      responseTimeout: 10 // (10 second),
      autoDeleteFailed: false,
      autoDeletePrevious: false,
      autoUpdate: "onlyDownload",
      resetWhenUpdate: false,
      updateUrl: https://example.com/api/auto_update,
      channelUrl: https://example.com/api/channel,
      statsUrl: https://example.com/api/stats,
      publicKey: undefined,
      version: undefined,
      directUpdate: undefined,
      autoSplashscreen: undefined,
      autoSplashscreenLoader: undefined,
      autoSplashscreenTimeout: undefined,
      periodCheckDelay: 3600 (1 hour),
      localS3: undefined,
      localHost: undefined,
      localWebHost: undefined,
      localSupa: undefined,
      localSupaAnon: undefined,
      localApi: undefined,
      localApiFiles: undefined,
      allowModifyUrl: undefined,
      allowModifyAppId: undefined,
      allowManualBundleError: undefined,
      allowPreview: undefined,
      persistCustomId: undefined,
      persistModifyUrl: undefined,
      allowSetDefaultChannel: undefined,
      persistDefaultChannelOnReinstall: undefined,
      defaultChannel: undefined,
      appId: undefined,
      keepUrlPathAfterReload: undefined,
      disableJSLogging: undefined,
      osLogging: undefined,
      shakeMenu: undefined,
      shakeMenuGesture: undefined,
      allowShakeChannelSelector: undefined,
    },
  },
};

export default config;
```

</docgen-config>

## API

<docgen-index>

* [`notifyAppReady()`](#notifyappready)
* [`setUpdateUrl(...)`](#setupdateurl)
* [`setStatsUrl(...)`](#setstatsurl)
* [`setChannelUrl(...)`](#setchannelurl)
* [`download(...)`](#download)
* [`next(...)`](#next)
* [`set(...)`](#set)
* [`startPreviewSession(...)`](#startpreviewsession)
* [`listPreviews()`](#listpreviews)
* [`setPreview(...)`](#setpreview)
* [`resetPreview()`](#resetpreview)
* [`deletePreview(...)`](#deletepreview)
* [`checkPreviewUpdate(...)`](#checkpreviewupdate)
* [`updatePreview(...)`](#updatepreview)
* [`delete(...)`](#delete)
* [`setBundleError(...)`](#setbundleerror)
* [`list(...)`](#list)
* [`reset(...)`](#reset)
* [`current()`](#current)
* [`reload()`](#reload)
* [`setMultiDelay(...)`](#setmultidelay)
* [`cancelDelay()`](#canceldelay)
* [`triggerUpdateCheck()`](#triggerupdatecheck)
* [`getLatest(...)`](#getlatest)
* [`getMissingBundleFiles(...)`](#getmissingbundlefiles)
* [`getBundleDownloadSize(...)`](#getbundledownloadsize)
* [`setChannel(...)`](#setchannel)
* [`unsetChannel(...)`](#unsetchannel)
* [`getChannel()`](#getchannel)
* [`listChannels()`](#listchannels)
* [`setCustomId(...)`](#setcustomid)
* [`getBuiltinVersion()`](#getbuiltinversion)
* [`getDeviceId()`](#getdeviceid)
* [`getPluginVersion()`](#getpluginversion)
* [`isAutoUpdateEnabled()`](#isautoupdateenabled)
* [`removeAllListeners()`](#removealllisteners)
* [`addListener('download', ...)`](#addlistenerdownload-)
* [`addListener('noNeedUpdate', ...)`](#addlistenernoneedupdate-)
* [`addListener('updateCheckResult', ...)`](#addlistenerupdatecheckresult-)
* [`addListener('updateAvailable', ...)`](#addlistenerupdateavailable-)
* [`addListener('downloadComplete', ...)`](#addlistenerdownloadcomplete-)
* [`addListener('breakingAvailable', ...)`](#addlistenerbreakingavailable-)
* [`addListener('majorAvailable', ...)`](#addlistenermajoravailable-)
* [`addListener('updateFailed', ...)`](#addlistenerupdatefailed-)
* [`addListener('set', ...)`](#addlistenerset-)
* [`addListener('setNext', ...)`](#addlistenersetnext-)
* [`addListener('downloadFailed', ...)`](#addlistenerdownloadfailed-)
* [`addListener('appReloaded', ...)`](#addlistenerappreloaded-)
* [`addListener('appReady', ...)`](#addlistenerappready-)
* [`addListener('channelPrivate', ...)`](#addlistenerchannelprivate-)
* [`addListener('onFlexibleUpdateStateChange', ...)`](#addlisteneronflexibleupdatestatechange-)
* [`isAutoUpdateAvailable()`](#isautoupdateavailable)
* [`getNextBundle()`](#getnextbundle)
* [`getFailedUpdate()`](#getfailedupdate)
* [`setShakeMenu(...)`](#setshakemenu)
* [`isShakeMenuEnabled()`](#isshakemenuenabled)
* [`setShakeChannelSelector(...)`](#setshakechannelselector)
* [`isShakeChannelSelectorEnabled()`](#isshakechannelselectorenabled)
* [`getAppId()`](#getappid)
* [`setAppId(...)`](#setappid)
* [`getAppUpdateInfo(...)`](#getappupdateinfo)
* [`openAppStore(...)`](#openappstore)
* [`performImmediateUpdate()`](#performimmediateupdate)
* [`startFlexibleUpdate()`](#startflexibleupdate)
* [`completeFlexibleUpdate()`](#completeflexibleupdate)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
* [Enums](#enums)

</docgen-index>

<docgen-api>

#### notifyAppReady()

```typescript
notifyAppReady() => Promise<AppReadyResult>
```

Notify the native layer that JavaScript initialized successfully.

**CRITICAL: You must call this method on every app launch to prevent automatic rollback.**

This is a simple notification to confirm that your bundle's JavaScript loaded and executed.
The native web server successfully served the bundle files and your JS runtime started.
That's all it checks - nothing more complex.

**What triggers rollback:**
- NOT calling this method within the timeout (default: 10 seconds)
- Complete JavaScript failure (bundle won't load at all)

**What does NOT trigger rollback:**
- Runtime errors after initialization (API failures, crashes, etc.)
- Network request failures
- Application logic errors

**IMPORTANT: Call this BEFORE any network requests.**
Don't wait for APIs, data loading, or async operations. Call it as soon as your
JavaScript bundle starts executing to confirm the bundle itself is valid.

Best practices:
- Call immediately in your app entry point (main.js, app component mount, etc.)
- Don't put it after network calls or heavy initialization
- Don't wrap it in try/catch with conditions
- Adjust {@link PluginsConfig.CapacitorUpdater.appReadyTimeout} if you need more time

**Returns:** <code>Promise&lt;<a href="#appreadyresult">AppReadyResult</a>&gt;</code>

--------------------

#### setUpdateUrl(...)

```typescript
setUpdateUrl(options: UpdateUrl) => Promise<void>
```

Set the update URL for the app dynamically at runtime.

This overrides the {@link PluginsConfig.CapacitorUpdater.updateUrl} config value.
Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.

Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
Otherwise, the URL will reset to the config value on next app launch.

| Param         | Type                                            | Description                                       |
| ------------- | ----------------------------------------------- | ------------------------------------------------- |
| **`options`** | <code><a href="#updateurl">UpdateUrl</a></code> | Contains the URL to use for checking for updates. |

**Since:** 5.4.0

--------------------

#### setStatsUrl(...)

```typescript
setStatsUrl(options: StatsUrl) => Promise<void>
```

Set the statistics URL for the app dynamically at runtime.

This overrides the {@link PluginsConfig.CapacitorUpdater.statsUrl} config value.
Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.

Pass an empty string to disable statistics gathering entirely.
Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.

| Param         | Type                                          | Description                                                                    |
| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
| **`options`** | <code><a href="#statsurl">StatsUrl</a></code> | Contains the URL to use for sending statistics, or an empty string to disable. |

**Since:** 5.4.0

--------------------

#### setChannelUrl(...)

```typescript
setChannelUrl(options: ChannelUrl) => Promise<void>
```

Set the channel URL for the app dynamically at runtime.

This overrides the {@link PluginsConfig.CapacitorUpdater.channelUrl} config value.
Requires {@link PluginsConfig.CapacitorUpdater.allowModifyUrl} to be set to `true`.

Use {@link PluginsConfig.CapacitorUpdater.persistModifyUrl} to persist this value across app restarts.
Otherwise, the URL will reset to the config value on next app launch.

| Param         | Type                                              | Description                                     |
| ------------- | ------------------------------------------------- | ----------------------------------------------- |
| **`options`** | <code><a href="#channelurl">ChannelUrl</a></code> | Contains the URL to use for channel operations. |

**Since:** 5.4.0

--------------------

#### download(...)

```typescript
download(options: DownloadOptions) => Promise<BundleInfo>
```

Download a new bundle from the provided URL for later installation.

The downloaded bundle is stored locally but not activated. To use it:
- Call {@link next} to set it for installation on next app backgrounding/restart
- Call {@link set} to activate it immediately (destroys current JavaScript context)

The URL should point to a zip file containing either:
- Your app files directly in the zip root, or
- A single folder containing all your app files

The bundle must include an `index.html` file at the root level.

For encrypted bundles, provide the `sessionKey` and `checksum` parameters.
For multi-file delta updates, provide the `manifest` array.

**Android Background Runner note:** `@capacitor/background-runner` loads its
configured runner script from native APK assets. Live updates cannot replace
that runner script. Keep it stable across OTA updates and ship a native app
update when the runner code changes. When a bundle switch happens, Capacitor
Updater cancels and reschedules configured Background Runner WorkManager jobs
and syncs the bundled runner script into native `public/` storage when present.

| Param         | Type                                                        | Description                                                                                  |
| ------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#downloadoptions">DownloadOptions</a></code> | The {@link <a href="#downloadoptions">DownloadOptions</a>} for downloading a new bundle zip. |

**Returns:** <code>Promise&lt;<a href="#bundleinfo">BundleInfo</a>&gt;</code>

--------------------

#### next(...)

```typescript
next(options: BundleId) => Promise<BundleInfo>
```

Set the next bundle to be activated when the app backgrounds or restarts.

This is the recommended way to apply updates as it doesn't interrupt the user's current session.
The bundle will be activated when:
- The app is backgrounded (user switches away), or
- The app is killed and relaunched, or
- {@link reload} is called manually

Unlike {@link set}, this method does NOT destroy the current JavaScript context immediately.
Your app continues running normally until one of the above events occurs.

Use {@link setMultiDelay} to add additional conditions before the update is applied.

| Param         | Type                                          | Description                                                                                                                 |
| ------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | Contains the ID of the bundle to set as next. Use {@link <a href="#bundleinfo">BundleInfo.id</a>} from a downloaded bundle. |

**Returns:** <code>Promise&lt;<a href="#bundleinfo">BundleInfo</a>&gt;</code>

--------------------

#### set(...)

```typescript
set(options: BundleId) => Promise<void>
```

Set the current bundle and immediately reloads the app.

**IMPORTANT: This is a terminal operation that destroys the current JavaScript context.**

When you call this method:
- The entire JavaScript context is immediately destroyed
- The app reloads from a different folder with different files
- NO code after this call will execute
- NO promises will resolve
- NO callbacks will fire
- Event listeners registered after this call are unreliable and may never fire

The reload happens automatically - you don't need to do anything else.
If you need to preserve state like the current URL path, use the {@link PluginsConfig.CapacitorUpdater.keepUrlPathAfterReload} config option.
For other state preservation needs, save your data before calling this method (e.g., to localStorage).

**Do not** try to execute additional logic after calling `set()` - it won't work as expected.

| Param         | Type                                          | Description                                                                                       |
| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the new bundle id to set as current. |

--------------------

#### startPreviewSession(...)

```typescript
startPreviewSession(options?: StartPreviewSessionOptions | undefined) => Promise<void>
```

Start a temporary preview/testing session.

This stores the currently active bundle as the pending fallback, enables the
native shake menu, and makes the next applied bundle show a native notice
explaining that shaking the device can reload or leave the preview.
Requires {@link PluginsConfig.CapacitorUpdater.allowPreview} to be `true`.
When `appId` is provided, the preview session temporarily uses that app id
for update checks until the user leaves the preview. Native updater stats are
skipped while the preview session is active.

Use this before calling {@link set} for Expo Go-style preview flows.
Use {@link listPreviews}, {@link setPreview}, {@link resetPreview},
{@link deletePreview}, {@link checkPreviewUpdate}, and
{@link updatePreview} to manage saved local previews.

| Param         | Type                                                                              | Description                       |
| ------------- | --------------------------------------------------------------------------------- | --------------------------------- |
| **`options`** | <code><a href="#startpreviewsessionoptions">StartPreviewSessionOptions</a></code> | Optional preview session options. |

**Since:** 8.47.0

--------------------

#### listPreviews()

```typescript
listPreviews() => Promise<PreviewListResult>
```

Get every locally available preview bundle that was registered by
{@link startPreviewSession} and later applied with {@link set}.

This only returns previews whose bundles are still available locally. It is
safe to show this in a preview switcher or native debug menu.

**Returns:** <code>Promise&lt;<a href="#previewlistresult">PreviewListResult</a>&gt;</code>

**Since:** 8.49.0

--------------------

#### setPreview(...)

```typescript
setPreview(options: BundleId) => Promise<void>
```

Switch to a locally available preview bundle and reload the WebView.

If the app is not already in a preview session, the current live bundle is
saved as the fallback so {@link resetPreview} or the native shake menu can
return to it later.

| Param         | Type                                          | Description                                                                         |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |

**Since:** 8.49.0

--------------------

#### resetPreview()

```typescript
resetPreview() => Promise<void>
```

Leave the active preview session and reload the saved live bundle.

This does not delete any saved previews. Use {@link deletePreview} to remove
a preview from local storage.

**Since:** 8.49.0

--------------------

#### deletePreview(...)

```typescript
deletePreview(options: BundleId) => Promise<DeletePreviewResult>
```

Delete a locally saved preview and its bundle when possible.

Active previews cannot be deleted until you switch away from them or call
{@link resetPreview}. If only the preview metadata can be removed, the
method still resolves with `deleted: false`.

| Param         | Type                                          | Description                                                                         |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |

**Returns:** <code>Promise&lt;<a href="#deletepreviewresult">DeletePreviewResult</a>&gt;</code>

**Since:** 8.49.0

--------------------

#### checkPreviewUpdate(...)

```typescript
checkPreviewUpdate(options: BundleId) => Promise<PreviewUpdateResult>
```

Check whether a saved preview's payload URL points to a newer preview bundle.

Only previews started with a `payloadUrl` can be checked natively. Direct URL
previews can still be switched or deleted locally, but the updater does not
know where to check for newer versions.

| Param         | Type                                          | Description                                                                         |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |

**Returns:** <code>Promise&lt;<a href="#previewupdateresult">PreviewUpdateResult</a>&gt;</code>

**Since:** 8.49.0

--------------------

#### updatePreview(...)

```typescript
updatePreview(options: BundleId) => Promise<PreviewUpdateResult>
```

Download the newest bundle for a saved preview payload URL.

If the preview being updated is active, the new bundle is applied and the
WebView reloads. Otherwise, the saved preview entry is moved to the newly
downloaded bundle and can be selected later with {@link setPreview}.

| Param         | Type                                          | Description                                                                         |
| ------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the preview bundle ID. |

**Returns:** <code>Promise&lt;<a href="#previewupdateresult">PreviewUpdateResult</a>&gt;</code>

**Since:** 8.49.0

--------------------

#### delete(...)

```typescript
delete(options: BundleId) => Promise<void>
```

Delete a bundle from local storage to free up disk space.

You cannot delete:
- The currently active bundle
- The `builtin` bundle (the version shipped with your app)
- The bundle set as `next` (call {@link next} with a different bundle first)

Use {@link list} to get all available bundle IDs.

**Note:** The bundle ID is NOT the same as the version name.
Use the `id` field from {@link <a href="#bundleinfo">BundleInfo</a>}, not the `version` field.

| Param         | Type                                          | Description                                                                           |
| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the bundle ID to delete. |

--------------------

#### setBundleError(...)

```typescript
setBundleError(options: BundleId) => Promise<BundleInfo>
```

Manually mark a bundle as failed/errored in manual update mode.

This is useful when you detect that a bundle has critical issues and want to prevent
it from being used again. The bundle status will be changed to `error` and the plugin
will avoid using this bundle in the future.

**Requirements:**
- {@link PluginsConfig.CapacitorUpdater.allowManualBundleError} must be set to `true`
- Only works in manual update mode (when autoUpdate is disabled)

Common use case: After downloading and testing a bundle, you discover it has critical
bugs and want to mark it as failed so it won't be retried.

| Param         | Type                                          | Description                                                                                    |
| ------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#bundleid">BundleId</a></code> | A {@link <a href="#bundleid">BundleId</a>} object containing the bundle ID to mark as errored. |

**Returns:** <code>Promise&lt;<a href="#bundleinfo">BundleInfo</a>&gt;</code>

**Since:** 7.20.0

--------------------

#### list(...)

```typescript
list(options?: ListOptions | undefined) => Promise<BundleListResult>
```

Get all locally downloaded bundles stored in your app.

This returns all bundles that have been downloaded and are available locally, including:
- The currently active bundle
- The `builtin` bundle (shipped with your app)
- Any downloaded bundles waiting to be activated
- Failed bundles (with `error` status)

Use this to:
- Check available disk space by counting bundles
- Delete old bundles with {@link delete}
- Monitor bundle download status

| Param         | Type                                                | Description                                                                                |
| ------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **`options`** | <code><a href="#listoptions">ListOptions</a></code> | The {@link <a href="#listoptions">ListOptions</a>} for customizing the bundle list output. |

**Returns:** <code>Promise&lt;<a href="#bundlelistresult">BundleListResult</a>&gt;</code>

--------------------

#### reset(...)

```typescript
reset(options?: ResetOptions | undefined) => Promise<void>
```

Reset the app to a known good bundle.

This method helps recover from problematic updates by reverting to either:
- The `builtin` bundle (the original version shipped with your app to App Store/Play Store)
- The last successfully loaded bundle (most recent bundle that worked correctly)

**IMPORTANT: This triggers an immediate app reload, destroying the current JavaScript context.**
See {@link set} for details on the implications of this operation.

Use cases:
- Emergency recovery when an update causes critical issues
- Testing rollback functionality
- Providing users a "reset to factory" option

| Param         | Type                                                  |
| ------------- | ----------------------------------------------------- |
| **`options`** | <code><a href="#resetoptions">ResetOptions</a></code> |

--------------------

#### current()

```typescript
current() => Promise<CurrentBundleResult>
```

Get information about the currently active bundle.

Returns:
- `bundle`: The currently active bundle information
- `native`: The version of the builtin bundle (the original app version from App/Play Store)

If no updates have been applied, `bundle.id` will be `"builtin"`, indicating the app
is running the original version shipped with the native app.

Use this to:
- Display the current version to users
- Check if an update is currently active
- Compare against available updates
- Log the active bundle for debugging

**Returns:** <code>Promise&lt;<a href="#currentbundleresult">CurrentBundleResult</a>&gt;</code>

--------------------

#### reload()

```typescript
reload() => Promise<void>
```

Manually reload the app to apply a pending update.

This triggers the same reload behavior that happens automatically when the app backgrounds.
If you've called {@link next} to queue an update, calling `reload()` will apply it immediately.

**IMPORTANT: This destroys the current JavaScript context immediately.**
See {@link set} for details on the implications of this operation.

Common use cases:
- Applying an update immediately after download instead of waiting for backgrounding
- Providing a "Restart now" button to users after an update is ready
- Testing update flows during development

If no update is pending (no call to {@link next}), this simply reloads the current bundle.

--------------------

#### setMultiDelay(...)

```typescript
setMultiDelay(options: MultiDelayConditions) => Promise<void>
```

Configure conditions that must be met before a pending update is applied.

After calling {@link next} to queue an update, use this method to control when it gets applied.
The update will only be installed after ALL specified conditions are satisfied.

Available condition types:
- `background`: Wait for the app to be backgrounded. Optionally specify duration in milliseconds.
- `kill`: Wait for the app to be killed and relaunched (**Note:** Current behavior triggers update immediately on kill, not on next background. This will be fixed in v8.)
- `date`: Wait until a specific date/time (ISO 8601 format)
- `nativeVersion`: Wait until the native app is updated to a specific version

Condition value formats:
- `background`: Number in milliseconds (e.g., `"300000"` for 5 minutes), or omit for immediate
- `kill`: No value needed
- `date`: ISO 8601 date string (e.g., `"2025-12-31T23:59:59Z"`)
- `nativeVersion`: Version string (e.g., `"2.0.0"`)

| Param         | Type                                                                  | Description                                                                                        |
| ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#multidelayconditions">MultiDelayConditions</a></code> | Contains the {@link <a href="#multidelayconditions">MultiDelayConditions</a>} array of conditions. |

**Since:** 4.3.0

--------------------

#### cancelDelay()

```typescript
cancelDelay() => Promise<void>
```

Cancel all delay conditions and apply the pending update immediately.

If you've set delay conditions with {@link setMultiDelay}, this method clears them
and triggers the pending update to be applied on the next app background or restart.

This is useful when:
- User manually requests to update now (e.g., clicks "Update now" button)
- Your app detects it's a good time to update (e.g., user finished critical task)
- You want to override a time-based delay early

**Since:** 4.0.0

--------------------

#### triggerUpdateCheck()

```typescript
triggerUpdateCheck() => Promise<TriggerUpdateCheckResult>
```

Trigger the native auto-update check/download pipeline immediately.

This starts the same background update flow used when the app moves to the
foreground with auto-update enabled. It is useful for native integrations
such as a silent push notification asking the app to check for a Capgo
bundle without reimplementing the update protocol in JavaScript.

The promise resolves after the native background work has been queued, not
after the update has been downloaded or installed. Listen to updater events
such as `updateAvailable`, `downloadComplete`, `downloadFailed`, and
`noNeedUpdate` for the final result.

Native support is available on iOS and Android. On Web, this method returns
a result with `status: 'unavailable'`. Native platforms also return
`unavailable` when the native auto-update system is disabled.

**Returns:** <code>Promise&lt;<a href="#triggerupdatecheckresult">TriggerUpdateCheckResult</a>&gt;</code>

--------------------

#### getLatest(...)

```typescript
getLatest(options?: GetLatestOptions | undefined) => Promise<LatestVersion>
```

Check the update server for the latest available bundle version.

This queries your configured update URL (or Capgo backend) to see if a newer bundle
is available for download. It does NOT download the bundle automatically.

The response includes:
- `version`: The latest available version identifier
- `url`: Download URL for the bundle (if available)
- `breaking`: Whether this update is marked as incompatible (requires native app update)
- `message`: Optional message from the server
- `manifest`: File list for delta updates (if using multi-file downloads)

After receiving the latest version info, you can:
1. Compare it with your current version
2. Download it using {@link download}
3. Apply it using {@link next} or {@link set}

**Important: Handling "no new version available"**

When the device's current version matches the latest version on the server (i.e., the device is already
up-to-date), the server returns a 200 response with `error: "no_new_version_available"` and
`message: "No new version available"`. This is a normal, expected condition and resolves with
`kind: "up_to_date"` when the backend provides that classification.

You should check `kind` and `error` before attempting to download:

```typescript
const latest = await CapacitorUpdater.getLatest();
if (latest.kind === 'up_to_date') {
  console.log('Already up to date');
} else if (latest.kind === 'blocked') {
  console.log('Update is blocked:', latest.error);
} else if (latest.url) {
  // New version is available, proceed with download
}
```

In this scenario, the server:
- Logs the request with a "No new version available" message
- Sends a "noNew" stat action to track that the device checked for updates but was already current (done on the backend)

| Param         | Type                                                          | Description                                                                                          |
| ------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#getlatestoptions">GetLatestOptions</a></code> | Optional {@link <a href="#getlatestoptions">GetLatestOptions</a>} to specify which channel to check. |

**Returns:** <code>Promise&lt;<a href="#latestversion">LatestVersion</a>&gt;</code>

**Since:** 4.0.0

--------------------

#### getMissingBundleFiles(...)

```typescript
getMissingBundleFiles(options: GetMissingBundleFilesOptions) => Promise<GetMissingBundleFilesResult>
```

Return the manifest entries that still need to be downloaded for a partial update.

Pass the result from {@link getLatest} directly when it includes a `manifest`.
The native plugin compares each manifest entry with the files already available
in the builtin bundle and the local delta cache. Entries that can be reused are
omitted from the returned `missing` list.

For encrypted manifests, pass the `sessionKey` returned by {@link getLatest} so
encrypted file hashes can be checked against local files.

```typescript
const latest = await CapacitorUpdater.getLatest();
const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
```

| Param         | Type                                                                                  | Description                                                                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`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`. |

**Returns:** <code>Promise&lt;<a href="#getmissingbundlefilesresult">GetMissingBundleFilesResult</a>&gt;</code>

**Since:** 8.47.0

--------------------

#### getBundleDownloadSize(...)

```typescript
getBundleDownloadSize(options: GetBundleDownloadSizeOptions) => Promise<GetBundleDownloadSizeResult>
```

Estimate the download size for manifest entries before downloading them.

This method sends the provided manifest entries to the Capgo update endpoint
once and reads the stored manifest `file_size` metadata. It does not perform
per-file `HEAD` requests from the app.

Use this after {@link getMissingBundleFiles} to estimate only the files this
device still needs:

```typescript
const latest = await CapacitorUpdater.getLatest();
const missing = await CapacitorUpdater.getMissingBundleFiles(latest);
const size = await CapacitorUpdater.getBundleDownloadSize({
  version: latest.version,
  manifest: missing.missing,
});
```

| Param         | Type                                                                                  | Description                                                                                                            |
| ------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a></code> | A {@link <a href="#getbundledownloadsizeoptions">GetBundleDownloadSizeOptions</a>} object containing manifest entries. |

**Returns:** <code>Promise&lt;<a href="#getbundledownloadsizeresult">GetBundleDownloadSizeResult</a>&gt;</code>

**Since:** 8.47.0

--------------------

#### setChannel(...)

```typescript
setChannel(options: SetChannelOptions) => Promise<ChannelRes>
```

Assign this device to a specific update channel at runtime.

Channels allow you to distribute different bundle versions to different groups of users
(e.g., "production", "beta", "staging"). This method switches the device to a new channel.

**Device Override UI:** `setChannel()` validates the channel with the backend, then stores the
selected channel locally on the device for future app restarts. It does not create or update
a backend Device Override, so the device will not appear as overridden in the Capgo dashboard.
Only assignments created from the dashboard or the Public API are shown in the Device Override UI.

**Requirements:**
- The target channel must allow self-assignment (configured in your Capgo dashboard or backend)
- The backend may accept or reject the request based on channel settings

**When to use:**
- After the app is ready and the user has interacted (e.g., opted into beta program)
- To implement in-app channel switching (beta toggle, tester access, etc.)
- For user-driven channel changes

**When NOT to use:**
- At app boot/initialization - use {@link PluginsConfig.CapacitorUpdater.defaultChannel} config instead
- Before user interaction

**Important: Listen for the `channelPrivate` event**

When a user attempts to set a channel that doesn't allow device self-assignment, the method will
throw an error AND fire a {@link addListener}('channelPrivate') event. You should listen to this event
to provide appropriate feedback to users:

```typescript
CapacitorUpdater.addListener('channelPrivate', (data) =&gt; {
  console.warn(`Cannot access channel "${data.channel}": ${data.message}`);
  // Show user-friendly message
});
```

This sends a request to the Capgo backend to validate the specified channel, then stores the
channel locally on the device for future app restarts.

| Param         | Type                                                            | Description                                                                                                                  |
| ------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#setchanneloptions">SetChannelOptions</a></code> | The {@link <a href="#setchanneloptions">SetChannelOptions</a>} containing the channel name and optional auto-update trigger. |

**Returns:** <code>Promise&lt;<a href="#channelres">ChannelRes</a>&gt;</code>

**Since:** 4.7.0

--------------------

#### unsetChannel(...)

```typescript
unsetChannel(options: UnsetChannelOptions) => Promise<void>
```

Remove the plugin-managed local channel assignment and return to the default channel.

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:
- An existing Dashboard or Public API Device Override, if one exists
- The {@link PluginsConfig.CapacitorUpdater.defaultChannel} if configured, or
- Your backend default channel for this app

Use this when:
- Users opt out of beta/testing programs
- You want to reset a device to standard update distribution
- Testing channel switching behavior

| Param         | Type                                                                |
| ------------- | ------------------------------------------------------------------- |
| **`options`** | <code><a href="#unsetchanneloptions">UnsetChannelOptions</a></code> |

**Since:** 4.7.0

--------------------

#### getChannel()

```typescript
getChannel() => Promise<GetChannelRes>
```

Get the current channel assigned to this device.

Returns information about:
- `channel`: The currently assigned channel name (if any)
- `allowSet`: Whether the channel allows self-assignment
- `status`: Operation status
- `error`/`message`: Additional information (if applicable)

Use this to:
- Display current channel to users (e.g., "You're on the Beta channel")
- Check if a device is on a specific channel before showing features
- Verify channel assignment after calling {@link setChannel}

On native platforms, a successful response also refreshes the default channel used by update checks.
This refresh is persisted across app restarts.

**Returns:** <code>Promise&lt;<a href="#getchannelres">GetChannelRes</a>&gt;</code>

**Since:** 4.8.0

--------------------

#### listChannels()

```typescript
listChannels() => Promise<ListChannelsResult>
```

Get a list of all channels available for this device to self-assign to.

Only returns channels where `allow_self_set` is `true`. These are channels that
users can switch to using {@link setChannel} without backend administrator intervention.

Each channel includes:
- `id`: Unique channel identifier
- `name`: Human-readable channel name
- `public`: Whether the channel is publicly visible
- `allow_self_set`: Always `true` in results (filtered to only self-assignable channels)

Use this to:
- Build a channel selector UI for users (e.g., "Join Beta" button)
- Show available testing/preview channels
- Implement channel discovery features

**Returns:** <code>Promise&lt;<a href="#listchannelsresult">ListChannelsResult</a>&gt;</code>

**Since:** 7.5.0

--------------------

#### setCustomId(...)

```typescript
setCustomId(options: SetCustomIdOptions) => Promise<void>
```

Set a custom identifier for this device.

This allows you to identify devices by your own custom ID (user ID, account ID, etc.)
instead of or in addition to the device's unique hardware ID. The custom ID is sent
to your update server and can be used for:
- Targeting specific users for updates
- Analytics and user tracking
- Debugging and support (correlating devices with users)
- A/B testing or feature flagging

**Persistence:**
- When {@link PluginsConfig.CapacitorUpdater.persistCustomId} is `true`, the ID persists across app restarts
- When `false`, the ID is only kept for the current session

**Clearing the custom ID:**
- Pass an empty string `""` to remove any stored custom ID

| Param         | Type                                                              | Description                                                                                               |
| ------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#setcustomidoptions">SetCustomIdOptions</a></code> | The {@link <a href="#setcustomidoptions">SetCustomIdOptions</a>} containing the custom identifier string. |

**Since:** 4.9.0

--------------------

#### getBuiltinVersion()

```typescript
getBuiltinVersion() => Promise<BuiltinVersion>
```

Get the builtin bundle version (the original version shipped with your native app).

This returns the version of the bundle that was included when the app was installed
from the App Store or Play Store. This is NOT the currently active bundle version -
use {@link current} for that.

Returns:
- The {@link PluginsConfig.CapacitorUpdater.version} config value if set, or
- The native app version from platform configs (package.json, Info.plist, build.gradle)

Use this to:
- Display the "factory" version to users
- Compare against downloaded bundle versions
- Determine if any updates have been applied
- Debugging version mismatches

**Returns:** <code>Promise&lt;<a href="#builtinversion">BuiltinVersion</a>&gt;</code>

**Since:** 5.2.0

--------------------

#### getDeviceId()

```typescript
getDeviceId() => Promise<DeviceId>
```

Get the unique, privacy-friendly identifier for this device.

This ID is used to identify the device when communicating with update servers.
It's automatically generated and stored securely by the plugin.

**Privacy & Security characteristics:**
- Generated as a UUID (not based on hardware identifiers)
- Stored securely in platform-specific secure storage
- Android: mirrored into backup-restorable app preferences for reinstall restore
- iOS: Keychain with `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`
- Not synced to cloud (iOS)
- Follows Apple and Google privacy best practices
- Users can clear it via system settings (Android) or keychain access (iOS)

**Persistence:**
The device ID persists across app reinstalls to maintain consistent device identity
for update tracking and analytics when platform storage is preserved. On Android,
apps with custom backup rules must keep the plugin app preferences eligible for
backup/restore; disabling Android backup or clearing app data creates a new ID.

Use this to:
- Debug update delivery issues (check what ID the server sees)
- Implement device-specific features
- Correlate server logs with specific devices

**Returns:** <code>Promise&lt;<a href="#deviceid">DeviceId</a>&gt;</code>

--------------------

#### getPluginVersion()

```typescript
getPluginVersion() => Promise<PluginVersion>
```

Get the version of the Capacitor Updater plugin installed in your app.

This returns the version of the native plugin code (Android/iOS), which is sent
to the update server with each request. This is NOT your app version or bundle version.

Use this to:
- Debug plugin-specific issues (when reporting bugs)
- Verify plugin installation and version
- Check compatibility with backend features
- Display in debug/about screens

**Returns:** <code>Promise&lt;<a href="#pluginversion">PluginVersion</a>&gt;</code>

--------------------

#### isAutoUpdateEnabled()

```typescript
isAutoUpdateEnabled() => Promise<AutoUpdateEnabled>
```

Check if automatic updates are currently enabled.

Returns `true` if {@link PluginsConfig.CapacitorUpdater.autoUpdate} is enabled,
meaning the plugin will automatically check for, download, and apply updates.

Returns `false` if in manual mode, where you control the update flow using
{@link getLatest}, {@link download}, {@link next}, and {@link set}.

Use this to:
- Determine which update flow your app is using
- Show/hide manual update UI based on mode
- Debug update behavior

**Returns:** <code>Promise&lt;<a href="#autoupdateenabled">AutoUpdateEnabled</a>&gt;</code>

--------------------

#### removeAllListeners()

```typescript
removeAllListeners() => Promise<void>
```

Remove all event listeners registered for this plugin.

This unregisters all listeners added via {@link addListener} for all event types:
- `download`
- `noNeedUpdate`
- `updateCheckResult`
- `updateAvailable`
- `downloadComplete`
- `downloadFailed`
- `breakingAvailable` / `majorAvailable`
- `updateFailed`
- `appReloaded`
- `appReady`

Use this during cleanup (e.g., when unmounting components or closing screens)
to prevent memory leaks from lingering event listeners.

**Since:** 1.0.0

--------------------

#### addListener('download', ...)

```typescript
addListener(eventName: 'download', listenerFunc: (state: DownloadEvent) => void) => Promise<PluginListenerHandle>
```

Listen for bundle download event in the App. Fires once a download has started, during downloading and when finished.
This will return you all download percent during the download

| Param              | Type                                                                        |
| ------------------ | --------------------------------------------------------------------------- |
| **`eventName`**    | <code>'download'</code>                                                     |
| **`listenerFunc`** | <code>(state: <a href="#downloadevent">DownloadEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 2.0.11

--------------------

#### addListener('noNeedUpdate', ...)

```typescript
addListener(eventName: 'noNeedUpdate', listenerFunc: (state: NoNeedEvent) => void) => Promise<PluginListenerHandle>
```

Listen for no need to update event, useful when you want force check every time the app is launched

| Param              | Type                                                                    |
| ------------------ | ----------------------------------------------------------------------- |
| **`eventName`**    | <code>'noNeedUpdate'</code>                                             |
| **`listenerFunc`** | <code>(state: <a href="#noneedevent">NoNeedEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 4.0.0

--------------------

#### addListener('updateCheckResult', ...)

```typescript
addListener(eventName: 'updateCheckResult', listenerFunc: (state: UpdateCheckResultEvent) => void) => Promise<PluginListenerHandle>
```

Listen for update check results before the updater decides whether to download.
The backend can classify the <a href="#updatecheckresultevent">UpdateCheckResultEvent</a> payload as `up_to_date`, `blocked`, or `failed`.

This event is emitted alongside legacy events. For `up_to_date` and `blocked`, it is emitted before
`noNeedUpdate` and does not emit `downloadFailed`. For `failed`, it is emitted before the legacy
`downloadFailed` event and keeps the existing failure stats behavior.

| Param              | Type                                                                                          |
| ------------------ | --------------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'updateCheckResult'</code>                                                              |
| **`listenerFunc`** | <code>(state: <a href="#updatecheckresultevent">UpdateCheckResultEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 8.45.11

--------------------

#### addListener('updateAvailable', ...)

```typescript
addListener(eventName: 'updateAvailable', listenerFunc: (state: UpdateAvailableEvent) => void) => Promise<PluginListenerHandle>
```

Listen for available update event, useful when you want to force check every time the app is launched

| Param              | Type                                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'updateAvailable'</code>                                                            |
| **`listenerFunc`** | <code>(state: <a href="#updateavailableevent">UpdateAvailableEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 4.0.0

--------------------

#### addListener('downloadComplete', ...)

```typescript
addListener(eventName: 'downloadComplete', listenerFunc: (state: DownloadCompleteEvent) => void) => Promise<PluginListenerHandle>
```

Listen for downloadComplete events.

| Param              | Type                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'downloadComplete'</code>                                                             |
| **`listenerFunc`** | <code>(state: <a href="#downloadcompleteevent">DownloadCompleteEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 4.0.0

--------------------

#### addListener('breakingAvailable', ...)

```typescript
addListener(eventName: 'breakingAvailable', listenerFunc: (state: BreakingAvailableEvent) => void) => Promise<PluginListenerHandle>
```

Listen for breaking update events when the backend flags an update as incompatible with the current app.
Emits the same payload as the legacy `majorAvailable` listener.

| Param              | Type                                                                                    |
| ------------------ | --------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'breakingAvailable'</code>                                                        |
| **`listenerFunc`** | <code>(state: <a href="#majoravailableevent">MajorAvailableEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 7.22.0

--------------------

#### addListener('majorAvailable', ...)

```typescript
addListener(eventName: 'majorAvailable', listenerFunc: (state: MajorAvailableEvent) => void) => Promise<PluginListenerHandle>
```

Listen for Major update event in the App, let you know when major update is blocked by setting disableAutoUpdateBreaking

| Param              | Type                                                                                    |
| ------------------ | --------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'majorAvailable'</code>                                                           |
| **`listenerFunc`** | <code>(state: <a href="#majoravailableevent">MajorAvailableEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 2.3.0

--------------------

#### addListener('updateFailed', ...)

```typescript
addListener(eventName: 'updateFailed', listenerFunc: (state: UpdateFailedEvent) => void) => Promise<PluginListenerHandle>
```

Listen for update fail event in the App, let you know when update has fail to install at next app start

| Param              | Type                                                                                |
| ------------------ | ----------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'updateFailed'</code>                                                         |
| **`listenerFunc`** | <code>(state: <a href="#updatefailedevent">UpdateFailedEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 2.3.0

--------------------

#### addListener('set', ...)

```typescript
addListener(eventName: 'set', listenerFunc: (state: SetEvent) => void) => Promise<PluginListenerHandle>
```

Listen for set event in the App, let you know when a bundle has been applied successfully.
This event is retained natively until JavaScript consumes it, so if the app reloads before your
listener is attached, the last pending `set` event is delivered once the listener subscribes.

| Param              | Type                                                              |
| ------------------ | ----------------------------------------------------------------- |
| **`eventName`**    | <code>'set'</code>                                                |
| **`listenerFunc`** | <code>(state: <a href="#setevent">SetEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 8.43.12

--------------------

#### addListener('setNext', ...)

```typescript
addListener(eventName: 'setNext', listenerFunc: (state: SetNextEvent) => void) => Promise<PluginListenerHandle>
```

Listen for set next event in the App, let you know when a bundle is queued as the next bundle to install.

| Param              | Type                                                                      |
| ------------------ | ------------------------------------------------------------------------- |
| **`eventName`**    | <code>'setNext'</code>                                                    |
| **`listenerFunc`** | <code>(state: <a href="#setnextevent">SetNextEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 6.14.0

--------------------

#### addListener('downloadFailed', ...)

```typescript
addListener(eventName: 'downloadFailed', listenerFunc: (state: DownloadFailedEvent) => void) => Promise<PluginListenerHandle>
```

Listen for download fail event in the App, let you know when a bundle download has failed

| Param              | Type                                                                                    |
| ------------------ | --------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'downloadFailed'</code>                                                           |
| **`listenerFunc`** | <code>(state: <a href="#downloadfailedevent">DownloadFailedEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 4.0.0

--------------------

#### addListener('appReloaded', ...)

```typescript
addListener(eventName: 'appReloaded', listenerFunc: () => void) => Promise<PluginListenerHandle>
```

Listen for reload event in the App, let you know when reload has happened

| Param              | Type                       |
| ------------------ | -------------------------- |
| **`eventName`**    | <code>'appReloaded'</code> |
| **`listenerFunc`** | <code>() =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 4.3.0

--------------------

#### addListener('appReady', ...)

```typescript
addListener(eventName: 'appReady', listenerFunc: (state: AppReadyEvent) => void) => Promise<PluginListenerHandle>
```

Listen for app ready event in the App, let you know when app is ready to use.
This event is retained natively until JavaScript consumes it, so it can still be delivered after
a reload even if the listener is attached later in app startup.

| Param              | Type                                                                        |
| ------------------ | --------------------------------------------------------------------------- |
| **`eventName`**    | <code>'appReady'</code>                                                     |
| **`listenerFunc`** | <code>(state: <a href="#appreadyevent">AppReadyEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 5.1.0

--------------------

#### addListener('channelPrivate', ...)

```typescript
addListener(eventName: 'channelPrivate', listenerFunc: (state: ChannelPrivateEvent) => void) => Promise<PluginListenerHandle>
```

Listen for channel private event, fired when attempting to set a channel that doesn't allow device self-assignment.

This event is useful for:
- Informing users they don't have permission to switch to a specific channel
- Implementing custom error handling for channel restrictions
- Logging unauthorized channel access attempts

| Param              | Type                                                                                    |
| ------------------ | --------------------------------------------------------------------------------------- |
| **`eventName`**    | <code>'channelPrivate'</code>                                                           |
| **`listenerFunc`** | <code>(state: <a href="#channelprivateevent">ChannelPrivateEvent</a>) =&gt; void</code> |

**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>

**Since:** 7.34.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

--------------------

#### isAutoUpdateAvailable()

```typescript
isAutoUpdateAvailable() => Promise<AutoUpdateAvailable>
```

Check if the auto-update feature is available (not disabled by custom server configuration).

Returns `false` when a custom `updateUrl` is configured, as this typically indicates
you're using a self-hosted update server that may not support all auto-update features.

Returns `true` when using the default Capgo backend or when the feature is available.

This is different from {@link isAutoUpdateEnabled}:
- `isAutoUpdateEnabled()`: Checks if auto-update MODE is turned on/off
- `isAutoUpdateAvailable()`: Checks if auto-update is SUPPORTED with your current configuration

**Returns:** <code>Promise&lt;<a href="#autoupdateavailable">AutoUpdateAvailable</a>&gt;</code>

--------------------

#### getNextBundle()

```typescript
getNextBundle() => Promise<BundleInfo | null>
```

Get information about the bundle queued to be activated on next reload.

Returns:
- {@link <a href="#bundleinfo">BundleInfo</a>} object if a bundle has been queued via {@link next}
- `null` if no update is pending

This is useful to:
- Check if an update is waiting to be applied
- Display "Update pending" status to users
- Show version info of the queued update
- Decide whether to show a "Restart to update" prompt

The queued bundle will be activated when:
- The app is backgrounded (default behavior)
- The app is killed and restarted
- {@link reload} is called manually
- Delay conditions set by {@link setMultiDelay} are met

**Returns:** <code>Promise&lt;<a href="#bundleinfo">BundleInfo</a> | null&gt;</code>

**Since:** 6.8.0

--------------------

#### getFailedUpdate()

```typescript
getFailedUpdate() => Promise<UpdateFailedEvent | null>
```

Retrieve information about the most recent bundle that failed to load.

When a bundle fails to load (e.g., JavaScript errors prevent initialization, missing files),
the plugin automatically rolls back and stores information about the failure. This method
retrieves that failure information.

**IMPORTANT: The stored value is cleared after being retrieved once.**
Calling this method multiple times will only return the failure info on the first call,
then `null` on subsequent calls until another failure occurs.

Returns:
- {@link <a href="#updatefailedevent">UpdateFailedEvent</a>} with bundle info if a failure was recorded
- `null` if no failure has occurred or if it was already retrieved

Use this to:
- Show users why an update failed
- Log failure information for debugging
- Implement custom error handling/reporting
- Display rollback notifications

**Returns:** <code>Promise&lt;<a href="#updatefailedevent">UpdateFailedEvent</a> | null&gt;</code>

**Since:** 7.22.0

--------------------

#### setShakeMenu(...)

```typescript
setShakeMenu(options: SetShakeMenuOptions) => Promise<void>
```

Enable or disable the native preview menu gesture.

During preview sessions, users can use the configured native gesture to:
- Reload the current preview
- Leave the test app and return to the fallback bundle
- Switch update channel, when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is also enabled

Outside preview sessions, this preview menu is ignored. The channel selector can still be
shown outside preview sessions when {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector} is enabled.

**Important:** Disable this in production builds or only enable for internal testers.

This can also be configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.
The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.

| Param         | Type                                                                |
| ------------- | ------------------------------------------------------------------- |
| **`options`** | <code><a href="#setshakemenuoptions">SetShakeMenuOptions</a></code> |

**Since:** 7.5.0

--------------------

#### isShakeMenuEnabled()

```typescript
isShakeMenuEnabled() => Promise<ShakeMenuEnabled>
```

Check if the native preview menu gesture is currently enabled.

Returns the current state of the shake menu feature that can be toggled via
{@link setShakeMenu} or configured via {@link PluginsConfig.CapacitorUpdater.shakeMenu}.

Use this to:
- Check if debug features are enabled
- Show/hide debug settings UI
- Verify configuration during testing

**Returns:** <code>Promise&lt;<a href="#shakemenuenabled">ShakeMenuEnabled</a>&gt;</code>

**Since:** 7.5.0

--------------------

#### setShakeChannelSelector(...)

```typescript
setShakeChannelSelector(options: SetShakeChannelSelectorOptions) => Promise<void>
```

Enable or disable the channel selector menu gesture at runtime.

When enabled, the configured native gesture can show a channel selector, including outside preview sessions.
If {@link setShakeMenu} is also enabled while a preview session is active, the shake menu includes
both preview actions and channel switching.

This can also be configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.
The native gesture is configured via {@link PluginsConfig.CapacitorUpdater.shakeMenuGesture}.

| Param         | Type                                                                                      |
| ------------- | ----------------------------------------------------------------------------------------- |
| **`options`** | <code><a href="#setshakechannelselectoroptions">SetShakeChannelSelectorOptions</a></code> |

**Since:** 8.43.0

--------------------

#### isShakeChannelSelectorEnabled()

```typescript
isShakeChannelSelectorEnabled() => Promise<ShakeChannelSelectorEnabled>
```

Check if the shake channel selector is currently enabled.

Returns the current state of the shake channel selector feature that can be toggled via
{@link setShakeChannelSelector} or configured via {@link PluginsConfig.CapacitorUpdater.allowShakeChannelSelector}.

**Returns:** <code>Promise&lt;<a href="#shakechannelselectorenabled">ShakeChannelSelectorEnabled</a>&gt;</code>

**Since:** 8.43.0

--------------------

#### getAppId()

```typescript
getAppId() => Promise<GetAppIdRes>
```

Get the currently configured App ID used for update server communication.

Returns the App ID that identifies this app to the update server. This can be:
- The value set via {@link setAppId}, or
- The {@link PluginsConfig.CapacitorUpdater.appId} config value, or
- The default app identifier from your native app configuration

Use this to:
- Verify which App ID is being used for updates
- Debug update delivery issues
- Display app configuration in debug screens
- Confirm App ID after calling {@link setAppId}

**Returns:** <code>Promise&lt;<a href="#getappidres">GetAppIdRes</a>&gt;</code>

**Since:** 7.14.0

--------------------

#### setAppId(...)

```typescript
setAppId(options: SetAppIdOptions) => Promise<void>
```

Dynamically change the App ID used for update server communication.

This overrides the App ID used to identify your app to the update server, allowing you
to switch between different app configurations at runtime (e.g., production vs staging
app IDs, or multi-tenant configurations).

**Requirements:**
- {@link PluginsConfig.CapacitorUpdater.allowModifyAppId} must be set to `true`

**Important considerations:**
- Changing the App ID will affect which updates this device receives
- The new App ID must exist on your update server
- This is primarily for advanced use cases (multi-tenancy, environment switching)
- Most apps should use the config-based {@link PluginsConfig.CapacitorUpdater.appId} instead

| Param         | Type                                                        |
| ------------- | ----------------------------------------------------------- |
| **`options`** | <code><a href="#setappidoptions">SetAppIdOptions</a></code> |

**Since:** 7.14.0

--------------------

#### 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

--------------------

#### Interfaces

##### AppReadyResult

| Prop         | Type                                              |
| ------------ | ------------------------------------------------- |
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> |

##### BundleInfo

| Prop             | Type                                                  |
| ---------------- | ----------------------------------------------------- |
| **`id`**         | <code>string</code>                                   |
| **`version`**    | <code>string</code>                                   |
| **`downloaded`** | <code>string</code>                                   |
| **`checksum`**   | <code>string</code>                                   |
| **`status`**     | <code><a href="#bundlestatus">BundleStatus</a></code> |

##### UpdateUrl

| Prop      | Type                |
| --------- | ------------------- |
| **`url`** | <code>string</code> |

##### StatsUrl

| Prop      | Type                |
| --------- | ------------------- |
| **`url`** | <code>string</code> |

##### ChannelUrl

| Prop      | Type                |
| --------- | ------------------- |
| **`url`** | <code>string</code> |

##### DownloadOptions

This URL and versions are used to download the bundle from the server, If you use backend all information will be given by the method getLatest.
If you don't use backend, you need to provide the URL and version of the bundle. Checksum and sessionKey are required if you encrypted the bundle with the CLI command encrypt, you should receive them as result of the command.

| Prop             | Type                         | Description                                                                                                                                                      | Default                | Since |
| ---------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- |
| **`url`**        | <code>string</code>          | The URL of the bundle zip file (e.g: dist.zip) to be downloaded. (This can be any URL. E.g: Amazon S3, a GitHub tag, any other place you've hosted your bundle.) |                        |       |
| **`version`**    | <code>string</code>          | The version code/name of this bundle/version                                                                                                                     |                        |       |
| **`sessionKey`** | <code>string</code>          | The session key for the update, when the bundle is encrypted with a session key                                                                                  | <code>undefined</code> | 4.0.0 |
| **`checksum`**   | <code>string</code>          | The checksum for the update, it should be in sha256 and encrypted with private key if the bundle is encrypted                                                    | <code>undefined</code> | 4.0.0 |
| **`manifest`**   | <code>ManifestEntry[]</code> | The manifest for multi-file downloads                                                                                                                            | <code>undefined</code> | 6.1.0 |

##### ManifestEntry

| Prop               | Type                        |
| ------------------ | --------------------------- |
| **`file_name`**    | <code>string \| null</code> |
| **`file_hash`**    | <code>string \| null</code> |
| **`download_url`** | <code>string \| null</code> |

##### BundleId

| Prop     | Type                |
| -------- | ------------------- |
| **`id`** | <code>string</code> |

##### StartPreviewSessionOptions

| Prop             | Type                | Description                                                                                                                                                                                                                                                               | Default                | Since  |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
| **`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 |
| **`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 |
| **`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 |
| **`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 |

##### PreviewListResult

| Prop                | Type                                                | Description                                             | Since  |
| ------------------- | --------------------------------------------------- | ------------------------------------------------------- | ------ |
| **`previews`**      | <code>PreviewInfo[]</code>                          | Locally available preview bundles.                      | 8.49.0 |
| **`current`**       | <code><a href="#previewinfo">PreviewInfo</a></code> | Current preview when a preview session is active.       | 8.49.0 |
| **`currentBundle`** | <code><a href="#bundleinfo">BundleInfo</a></code>   | Bundle currently loaded by the WebView.                 | 8.49.0 |
| **`liveBundle`**    | <code><a href="#bundleinfo">BundleInfo</a></code>   | Bundle that will be restored when leaving preview mode. | 8.49.0 |

##### PreviewInfo

| Prop             | Type                                              | Description                                                               | Since  |
| ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------ |
| **`id`**         | <code>string</code>                               | Preview bundle id.                                                        | 8.49.0 |
| **`bundle`**     | <code><a href="#bundleinfo">BundleInfo</a></code> | Locally downloaded bundle backing this preview.                           | 8.49.0 |
| **`name`**       | <code>string</code>                               | Human-readable name supplied when the preview was started.                | 8.49.0 |
| **`source`**     | <code>string</code>                               | Metadata source label supplied when the preview was started.              | 8.49.0 |
| **`appId`**      | <code>string</code>                               | Preview app id, when the session uses an app id override.                 | 8.49.0 |
| **`payloadUrl`** | <code>string</code>                               | Payload URL used to refresh this preview.                                 | 8.49.0 |
| **`createdAt`**  | <code>string</code>                               | ISO timestamp for when this preview was first saved.                      | 8.49.0 |
| **`updatedAt`**  | <code>string</code>                               | ISO timestamp for the last metadata or bundle update.                     | 8.49.0 |
| **`lastUsedAt`** | <code>string</code>                               | ISO timestamp for the last time this preview was activated.               | 8.49.0 |
| **`isActive`**   | <code>boolean</code>                              | Whether this preview is the currently active bundle in a preview session. | 8.49.0 |

##### DeletePreviewResult

| Prop          | Type                 | Description                                      | Since  |
| ------------- | -------------------- | ------------------------------------------------ | ------ |
| **`removed`** | <code>boolean</code> | Whether preview metadata was removed.            | 8.49.0 |
| **`deleted`** | <code>boolean</code> | Whether the underlying local bundle was deleted. | 8.49.0 |

##### PreviewUpdateResult

| Prop                | Type                                                | Description                                                           | Since  |
| ------------------- | --------------------------------------------------- | --------------------------------------------------------------------- | ------ |
| **`preview`**       | <code><a href="#previewinfo">PreviewInfo</a></code> | Saved preview metadata after the check or update.                     | 8.49.0 |
| **`latestVersion`** | <code>string</code>                                 | Latest version returned by the preview payload endpoint.              | 8.49.0 |
| **`upToDate`**      | <code>boolean</code>                                | Whether the saved preview already matches the latest payload version. | 8.49.0 |
| **`updated`**       | <code>boolean</code>                                | Whether a newer bundle was downloaded and saved.                      | 8.49.0 |
| **`bundle`**        | <code><a href="#bundleinfo">BundleInfo</a></code>   | New bundle when {@link updatePreview} downloaded one.                 | 8.49.0 |

##### BundleListResult

| Prop          | Type                      |
| ------------- | ------------------------- |
| **`bundles`** | <code>BundleInfo[]</code> |

##### ListOptions

| Prop      | Type                 | Description                                                                                                                                   | Default            | Since  |
| --------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------ |
| **`raw`** | <code>boolean</code> | Whether to return the raw bundle list or the manifest. If true, the list will attempt to read the internal database instead of files on disk. | <code>false</code> | 6.14.0 |

##### ResetOptions

| Prop                   | Type                 | Description                                                                                                                                                                                                        | Default            |
| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
| **`toLastSuccessful`** | <code>boolean</code> | Reset to the last successfully loaded bundle instead of the builtin one.                                                                                                                                           | <code>false</code> |
| **`usePendingBundle`** | <code>boolean</code> | Apply the pending bundle set via {@link next} while resetting. When `true`, the plugin will switch to the pending bundle immediately and clear the pending flag. If no pending bundle exists, the reset will fail. | <code>false</code> |

##### CurrentBundleResult

| Prop         | Type                                              |
| ------------ | ------------------------------------------------- |
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> |
| **`native`** | <code>string</code>                               |

##### MultiDelayConditions

| Prop                  | Type                          |
| --------------------- | ----------------------------- |
| **`delayConditions`** | <code>DelayCondition[]</code> |

##### DelayCondition

| Prop        | Type                                                      | Description                              |
| ----------- | --------------------------------------------------------- | ---------------------------------------- |
| **`kind`**  | <code><a href="#delayuntilnext">DelayUntilNext</a></code> | Set up delay conditions in setMultiDelay |
| **`value`** | <code>string</code>                                       |                                          |

##### TriggerUpdateCheckResult

Result returned after requesting an immediate native auto-update check.

| Prop         | Type                                                        | Description                                                                                                                                                                                  |
| ------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`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. |
| **`queued`** | <code>boolean</code>                                        | Whether a new native update check was queued. This is `true` only when `status` is `queued`; otherwise it is `false`.                                                                        |

##### LatestVersion

| Prop               | Type                                                                                | Description                                                                                                                                      | Since   |
| ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| **`version`**      | <code>string</code>                                                                 | Result of getLatest method                                                                                                                       | 4.0.0   |
| **`checksum`**     | <code>string</code>                                                                 |                                                                                                                                                  | 6       |
| **`breaking`**     | <code>boolean</code>                                                                | Indicates whether the update was flagged as breaking by the backend.                                                                             | 7.22.0  |
| **`major`**        | <code>boolean</code>                                                                |                                                                                                                                                  |         |
| **`message`**      | <code>string</code>                                                                 | Optional message from the server. When no new version is available, this will be "No new version available".                                     |         |
| **`sessionKey`**   | <code>string</code>                                                                 |                                                                                                                                                  |         |
| **`error`**        | <code>string</code>                                                                 | Error code from the server, if any. Use `kind` for classification instead of parsing this value.                                                 |         |
| **`kind`**         | <code><a href="#updateresponsekind">UpdateResponseKind</a></code>                   | Classification for this response, provided by the backend.                                                                                       | 8.45.11 |
| **`statusCode`**   | <code>number</code>                                                                 | HTTP status code returned by the update server for classified update-check responses.                                                            | 8.45.11 |
| **`old`**          | <code>string</code>                                                                 | The previous/current version name (provided for reference).                                                                                      |         |
| **`url`**          | <code>string</code>                                                                 | Download URL for the bundle (when a new version is available).                                                                                   |         |
| **`manifest`**     | <code>ManifestEntry[]</code>                                                        | File list for delta updates (when using multi-file downloads).                                                                                   | 6.1     |
| **`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  |
| **`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  |
| **`link`**         | <code>string</code>                                                                 | Optional link associated with this bundle version (e.g., release notes URL, changelog, GitHub release).                                          | 7.35.0  |
| **`comment`**      | <code>string</code>                                                                 | Optional comment or description for this bundle version.                                                                                         | 7.35.0  |

##### GetMissingBundleFilesResult

| Prop                | Type                         | Description                                                             | Since  |
| ------------------- | ---------------------------- | ----------------------------------------------------------------------- | ------ |
| **`missing`**       | <code>ManifestEntry[]</code> | Entries that are not available locally and need to be downloaded.       | 8.47.0 |
| **`total`**         | <code>number</code>          | Total entries in the provided manifest.                                 | 8.47.0 |
| **`missingCount`**  | <code>number</code>          | Number of entries that need to be downloaded.                           | 8.47.0 |
| **`reusableCount`** | <code>number</code>          | Number of entries that can be reused from builtin files or local cache. | 8.47.0 |

##### GetBundleDownloadSizeResult

| Prop               | Type                          | Description                                         | Since  |
| ------------------ | ----------------------------- | --------------------------------------------------- | ------ |
| **`totalSize`**    | <code>number</code>           | Sum of all known file sizes in bytes.               | 8.47.0 |
| **`knownFiles`**   | <code>number</code>           | Number of files with a known size.                  | 8.47.0 |
| **`unknownFiles`** | <code>number</code>           | Number of files whose size could not be determined. | 8.47.0 |
| **`files`**        | <code>BundleFileSize[]</code> | Per-file size results.                              | 8.47.0 |

##### BundleFileSize

| Prop               | Type                        | Description                                                 | Since  |
| ------------------ | --------------------------- | ----------------------------------------------------------- | ------ |
| **`file_name`**    | <code>string \| null</code> | File name from the manifest entry.                          | 8.47.0 |
| **`file_hash`**    | <code>string \| null</code> | File hash from the manifest entry.                          | 8.47.0 |
| **`download_url`** | <code>string \| null</code> | Download URL from the manifest entry.                       | 8.47.0 |
| **`size`**         | <code>number</code>         | Estimated bytes to download when the server exposes a size. | 8.47.0 |
| **`error`**        | <code>string</code>         | Error for this entry when the size could not be determined. | 8.47.0 |

##### GetLatestOptions

| Prop                    | Type                 | Description                                                                                                                                                                                                                                                                                                       | Default                | Since  |
| ----------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------ |
| **`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  |
| **`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 |
| **`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 |

##### GetMissingBundleFilesOptions

| Prop             | Type                         | Description                                                                                                                                                       | Since  |
| ---------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| **`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 |
| **`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 |
| **`sessionKey`** | <code>string</code>          | Session key returned by {@link getLatest}, required only when file hashes are encrypted.                                                                          | 8.47.0 |

##### GetBundleDownloadSizeOptions

| Prop           | Type                         | Description                                                                                                                                             | Since  |
| -------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| **`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 |
| **`version`**  | <code>string</code>          | Target bundle version. Pass `latest.version` when estimating files returned by {@link getLatest}.                                                       | 8.47.0 |

##### ChannelRes

| Prop          | Type                | Description                   | Since |
| ------------- | ------------------- | ----------------------------- | ----- |
| **`status`**  | <code>string</code> | Current status of set channel | 4.7.0 |
| **`error`**   | <code>string</code> |                               |       |
| **`message`** | <code>string</code> |                               |       |

##### SetChannelOptions

| Prop                    | Type                 |
| ----------------------- | -------------------- |
| **`channel`**           | <code>string</code>  |
| **`triggerAutoUpdate`** | <code>boolean</code> |

##### UnsetChannelOptions

| Prop                    | Type                 |
| ----------------------- | -------------------- |
| **`triggerAutoUpdate`** | <code>boolean</code> |

##### GetChannelRes

| Prop           | Type                 | Description                   | Since |
| -------------- | -------------------- | ----------------------------- | ----- |
| **`channel`**  | <code>string</code>  | Current status of get channel | 4.8.0 |
| **`error`**    | <code>string</code>  |                               |       |
| **`message`**  | <code>string</code>  |                               |       |
| **`status`**   | <code>string</code>  |                               |       |
| **`allowSet`** | <code>boolean</code> |                               |       |

##### ListChannelsResult

| Prop           | Type                       | Description                | Since |
| -------------- | -------------------------- | -------------------------- | ----- |
| **`channels`** | <code>ChannelInfo[]</code> | List of available channels | 7.5.0 |

##### ChannelInfo

| Prop                 | Type                 | Description                                     | Since |
| -------------------- | -------------------- | ----------------------------------------------- | ----- |
| **`id`**             | <code>number</code>  | The channel ID                                  | 7.5.0 |
| **`name`**           | <code>string</code>  | The channel name                                | 7.5.0 |
| **`public`**         | <code>boolean</code> | Whether this is a public channel                | 7.5.0 |
| **`allow_self_set`** | <code>boolean</code> | Whether devices can self-assign to this channel | 7.5.0 |

##### SetCustomIdOptions

| Prop           | Type                | Description                                                                                   |
| -------------- | ------------------- | --------------------------------------------------------------------------------------------- |
| **`customId`** | <code>string</code> | Custom identifier to associate with the device. Use an empty string to clear any saved value. |

##### BuiltinVersion

| Prop          | Type                |
| ------------- | ------------------- |
| **`version`** | <code>string</code> |

##### DeviceId

| Prop           | Type                |
| -------------- | ------------------- |
| **`deviceId`** | <code>string</code> |

##### PluginVersion

| Prop          | Type                |
| ------------- | ------------------- |
| **`version`** | <code>string</code> |

##### AutoUpdateEnabled

| Prop          | Type                 |
| ------------- | -------------------- |
| **`enabled`** | <code>boolean</code> |

##### PluginListenerHandle

| Prop         | Type                                      |
| ------------ | ----------------------------------------- |
| **`remove`** | <code>() =&gt; Promise&lt;void&gt;</code> |

##### DownloadEvent

| Prop          | Type                                              | Description                                    | Since |
| ------------- | ------------------------------------------------- | ---------------------------------------------- | ----- |
| **`percent`** | <code>number</code>                               | Current status of download, between 0 and 100. | 4.0.0 |
| **`bundle`**  | <code><a href="#bundleinfo">BundleInfo</a></code> |                                                |       |

##### NoNeedEvent

| Prop         | Type                                              | Description                                    | Since |
| ------------ | ------------------------------------------------- | ---------------------------------------------- | ----- |
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Current status of download, between 0 and 100. | 4.0.0 |

##### UpdateCheckResultEvent

| Prop             | Type                                                              | Description                                                          | Since   |
| ---------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ------- |
| **`kind`**       | <code><a href="#updateresponsekind">UpdateResponseKind</a></code> | Classification for the update check result, provided by the backend. | 8.45.11 |
| **`error`**      | <code>string</code>                                               | Backend error code, when provided.                                   | 8.45.11 |
| **`message`**    | <code>string</code>                                               | Backend message, when provided.                                      | 8.45.11 |
| **`statusCode`** | <code>number</code>                                               | HTTP status code returned by the update endpoint.                    | 8.45.11 |
| **`version`**    | <code>string</code>                                               | Version referenced by the update check result.                       | 8.45.11 |
| **`bundle`**     | <code><a href="#bundleinfo">BundleInfo</a></code>                 | Current bundle on the device.                                        | 8.45.11 |

##### UpdateAvailableEvent

##### DownloadCompleteEvent

| Prop         | Type                                              | Description                          | Since |
| ------------ | ------------------------------------------------- | ------------------------------------ | ----- |
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a new update is available. | 4.0.0 |

##### MajorAvailableEvent

| Prop          | Type                | Description                               | Since |
| ------------- | ------------------- | ----------------------------------------- | ----- |
| **`version`** | <code>string</code> | Emit when a breaking update is available. | 4.0.0 |

##### UpdateFailedEvent

| Prop         | Type                                              | Description                           | Since |
| ------------ | ------------------------------------------------- | ------------------------------------- | ----- |
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a update failed to install. | 4.0.0 |

##### SetEvent

| Prop         | Type                                              | Description                                                                                              | Since   |
| ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------- |
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emit when a bundle has been applied successfully. This event uses native `retainUntilConsumed` behavior. | 8.43.12 |

##### SetNextEvent

##### DownloadFailedEvent

| Prop          | Type                | Description                | Since |
| ------------- | ------------------- | -------------------------- | ----- |
| **`version`** | <code>string</code> | Emit when a download fail. | 4.0.0 |

##### AppReadyEvent

| Prop         | Type                                              | Description                                                                                  | Since |
| ------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----- |
| **`bundle`** | <code><a href="#bundleinfo">BundleInfo</a></code> | Emitted when the app is ready to use. This event uses native `retainUntilConsumed` behavior. | 5.2.0 |
| **`status`** | <code>string</code>                               |                                                                                              |       |

##### ChannelPrivateEvent

| Prop          | Type                | Description                                                                         | Since  |
| ------------- | ------------------- | ----------------------------------------------------------------------------------- | ------ |
| **`channel`** | <code>string</code> | Emitted when attempting to set a channel that doesn't allow device self-assignment. | 7.34.0 |
| **`message`** | <code>string</code> |                                                                                     |        |

##### 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 |

##### AutoUpdateAvailable

| Prop            | Type                 |
| --------------- | -------------------- |
| **`available`** | <code>boolean</code> |

##### SetShakeMenuOptions

| Prop          | Type                 |
| ------------- | -------------------- |
| **`enabled`** | <code>boolean</code> |

##### ShakeMenuEnabled

| Prop          | Type                                                          | Description                                                                                                                                                        | Since  |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ |
| **`enabled`** | <code>boolean</code>                                          |                                                                                                                                                                    |        |
| **`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 |

##### SetShakeChannelSelectorOptions

| Prop          | Type                 |
| ------------- | -------------------- |
| **`enabled`** | <code>boolean</code> |

##### ShakeChannelSelectorEnabled

| Prop          | Type                 |
| ------------- | -------------------- |
| **`enabled`** | <code>boolean</code> |

##### GetAppIdRes

| Prop        | Type                |
| ----------- | ------------------- |
| **`appId`** | <code>string</code> |

##### SetAppIdOptions

| Prop        | Type                |
| ----------- | ------------------- |
| **`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 |

#### Type Aliases

##### BundleStatus

pending: The bundle is pending to be **SET** as the next bundle.
downloading: The bundle is being downloaded.
success: The bundle has been downloaded and is ready to be **SET** as the next bundle.
error: The bundle has failed to download.

##### DelayUntilNext

<code>'background' | 'kill' | 'nativeVersion' | 'date'</code>

##### UpdateResponseKind

Classification for update-check responses that do not provide a downloadable bundle.
The update backend provides this field directly. Missing or unknown values are treated as
failed by native clients.

<code>'up_to_date' | 'blocked' | 'failed'</code>

##### BreakingAvailableEvent

Payload emitted by {@link CapacitorUpdaterPlugin.addListener} with `breakingAvailable`.

<code><a href="#majoravailableevent">MajorAvailableEvent</a></code>

##### ShakeMenuGesture

Native gesture options that open the shake menu.

Supported values are `shake` and `threeFingerPinch`.

<code>'shake' | 'threeFingerPinch'</code>

#### Enums

##### 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. |

##### 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.                                      |

##### 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

```javascript
  import { CapacitorUpdater } from '@capgo/capacitor-updater';

CapacitorUpdater.addListener('download', (info: any) => {
  console.log('download was fired', info.percent);
});
```

On iOS, Apple don't allow you to show a message when the app is updated, so you can't show a progress bar.

### Inspiration

- [cordova-plugin-ionic](https://github.com/ionic-team/cordova-plugin-ionic)
- [capacitor-codepush](https://github.dev/mapiacompany/capacitor-codepush)

### Contributors

[jamesyoung1337](https://github.com/jamesyoung1337) Thank you so much for your guidance and support, it was impossible to make this plugin work without you.

capacitor-updater

File Explorer

# Installation Guide

2. Gradle (Java/Kotlin)

3. Node.js

Today's picks

Was this content helpful?

Recent Feedback

capacitor-updater

File Explorer

# Installation Guide

2. Gradle (Java/Kotlin)

3. Node.js

Today's picks

Was this content helpful?

Recent Feedback

Download README