Auto Update

This documentation will explain how to run your auto-update server.

Serve your bundle

Make sure your bundle is served over HTTPS, and the server has the right CORS headers to allow the app to download the update. e.g. https://myserver.com/app/updates/updates.json

If you’re unfamiliar with serving a bundle, we recommend you try Capgo Cloud or see an example here:

Serving a Bundle

Configuration

Add an updateUrl to your capacitor.config.json.

{
  "plugins": {
    "CapacitorUpdater": {
      "updateUrl": "https://myserver.com/app/updates/updates.json",
    }
  }
}

Caution

When you are pushing a self-hosted update, be mindful you cannot use “HTTP” endpoint as it’s against the security policies of Android apps, for testing purposes you can allow it.

Update API

The plugin will do a POST call to your API each time the app is open, with this body:

interface AppInfos {
    "platform": "ios" | "android",
    "device_id": "UUID_of_device_unique_by_install",
    "app_id": "APPID_FROM_CAPACITOR_CONFIG",
    "custom_id": "your_custom_id_set_on_runtime",
    "plugin_version": "PLUGIN_VERSION",
    "version_build": "VERSION_NUMBER_FROM_NATIVE_CODE",
    "version_code": "VERSION_CODE_FROM_NATIVE_CODE",
    "version_name": "LAST_DOWNLOADER_VERSION" | "builtin"
    "version_os": "VERSION_OF_SYSYEM_OS",
    "is_emulator": boolean,
    "is_prod": boolean,
}

The server API should respond, in JSON, to the capacitor-updater plugin. With this data if an update is necessary:

{
"version": "1.2.3",
"url": "https://myserver.com/app/updates/my-new-app-2.0.0.zip",
"checksum": "sha256_checksum_of_bundle"
}

In Auto-update mode the server should compare the versions and return the right one, if the URL key is present, the plugin starts the download process.

If you add “message” and “error” key, the version will not be set, and the message will be displayed in logs instead.

version key should be in semver format.

The zip should have index.html as a file at the root, or only one folder at the root with index.html inside.

You can use the command of the CLI to zip your bundle:

Create a bundle with your files to serve from your server

npx @capgo/cli bundle zip --path [/path/to/my/bundle]

Generating Bundle Checksum

Important: You must use the Capgo CLI to create your bundle zip file. The Capgo plugin requires a specific zip format and structure that is only guaranteed when using the official CLI tool. Standard zip utilities may create incompatible archives.

To generate the checksum for your bundle, use the Capgo CLI zip command with the --json flag:

Create bundle with checksum information

npx @capgo/cli bundle zip [appId] --json

This command will:

• Create a properly formatted zip file compatible with the Capgo plugin
• Generate the SHA256 checksum for integrity verification
• Output bundle information in JSON format

Example output:

{
  "version": "1.2.3",
  "checksum": "a1b2c3d4e5f6789...",
  "size": 1234567
}

Use the checksum value from this output in your API response to ensure the plugin can verify the bundle integrity before installation.