Update Types

Capgo supports several types of over-the-air (OTA) updates. This page lists and explains all of them so you can choose the right combination for your app.

Apply Timing

Controls when an update is applied after it is downloaded.

Type	Description	Use Case
autoUpdate: atBackground	Download in background, apply when user backgrounds or kills the app	Most apps; minimal disruption
autoUpdate: atInstall	Apply immediately only on fresh install or app store update	New users get latest; existing users use default flow
autoUpdate: onLaunch	Apply immediately on install, store update, or after app kill	Balance between freshness and session stability
autoUpdate: always	Apply immediately whenever an update is downloaded (including on resume)	Critical fixes, apps with simple state
autoUpdate: onlyDownload	Download automatically and emit updateAvailable, but never apply or set the next bundle automatically	Apps that show their own update prompt or control exactly when to call set()

Configure in capacitor.config.ts:

plugins: {
  CapacitorUpdater: {
    autoUpdate: 'atBackground', // default; true is still accepted
    // or: 'off' | 'atInstall' | 'onLaunch' | 'always' | 'onlyDownload'
  }
}

Tip

For full details and splashscreen handling, see Update Behavior.

Delay Conditions

Conditions that must be met before an update is installed. Use setMultiDelay to combine them (all conditions must be satisfied).

Condition	Description	Example
date	Wait until after a specific date/time	Coordinate with server-side release
background	Wait a minimum duration (ms) after app is backgrounded	Avoid applying during quick app switches
nativeVersion	Require a minimum native binary version	Block updates on incompatible native code
kill	Wait until the next app kill event	Apply only on full restart

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

await CapacitorUpdater.setMultiDelay({
  delayConditions: [
    { kind: 'date', value: '2023-06-01T00:00:00.000Z' },
    { kind: 'background', value: '60000' },
  ],
});

Danger

The kill condition triggers after the first kill event, not the next background like the others. This will be fixed in a future release.

Version Blocking (Channel Policy)

Controls which semver updates a channel will auto-deliver. Set via --disable-auto-update on channels.

Strategy	Blocks	Allows	Use Case
none	Nothing	Any target bundle version	Default; full auto-update
major	Higher major than version_build, for example 1.2.3 -> 2.0.0	Same major, for example 1.2.3 -> 1.9.0 or 1.2.3 -> 1.2.4	Prevent breaking changes from reaching old native code
minor	Different major or minor than version_build, for example 1.2.3 -> 1.3.0	Same major and minor, for example 1.2.3 -> 1.2.4	Keep updates inside one native minor line
patch	Any major, minor, or patch number change, for example 1.0.0 -> 1.0.1	Only suffix changes while MAJOR.MINOR.PATCH stays identical, for example 1.0.0-beta.1 -> 1.0.0-beta.2 or 1.0.0+build.1 -> 1.0.0+build.2	Strictest mode: no core version movement
metadata	Missing min_update_version, or version_build below it	Target bundle whose min_update_version is less than or equal to version_build	Custom compatibility rules per bundle

These checks compare the target bundle against the native baseline sent as version_build, not the currently installed downloaded bundle sent as version_name.

npx @capgo/cli channel set production --disable-auto-update major

Caution

patch and metadata require careful setup. See CLI commands and Version Targeting for details.

Delivery Types

How the bundle is transferred to the device.

Type	Description	When to Use
Full bundle	Entire JS bundle is downloaded	First install, large changes, or when delta is unavailable
Delta (manifest)	Only changed files are downloaded	Most updates; faster and bandwidth-friendly

# Full bundle (default)
npx @capgo/cli bundle upload --channel production

# Delta updates
npx @capgo/cli bundle upload --channel production --delta

Tip

When using instant apply modes (atInstall, onLaunch, or always), enable Delta updates to minimize download time and improve UX.

Quick Reference

Category	Types
Apply timing	off, atBackground, atInstall, onLaunch, always, onlyDownload
Delay conditions	date, background, nativeVersion, kill
Version blocking	none, major, minor, patch, metadata
Delivery	Full bundle, Delta (manifest)

Related

• Update Behavior — Configure apply timing and delays
• Version Targeting — Channel-based version routing
• Delta (manifest) Updates — Enable partial downloads
• Channels — Channel configuration and precedence

Keep going from Update Types

If you are using Update Types to plan live update delivery, connect it with Capgo Live Updates for the product workflow in Capgo Live Updates, Overview for the implementation detail in Overview, Features for the implementation detail in Features, Update Behavior for the implementation detail in Update Behavior, and Getting Started for the implementation detail in Getting Started.