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:
Configuration
Add an updateUrl
to your capacitor.config.json
.
{ "plugins": { "CapacitorUpdater": { "updateUrl": "https://myserver.com/app/updates/updates.json", } }}
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:
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:
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.