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	All updates	Default; full auto-update
major	0.0.0 → 1.0.0	Same major (e.g. 1.x → 1.y)	Prevent breaking changes from reaching old native
minor	0.0.0 → 1.1.0, 1.1.0 → 1.2.0	Same minor (e.g. 1.2.x → 1.2.y)	Stricter control within major
patch	Any change except patch bump	Only 0.0.311 → 0.0.314	Very strict; patch-only updates
metadata	Updates without min_update_version	Updates with explicit compatibility metadata	Custom compatibility rules per bundle

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.