Skip to main content
Direct Updates

Show the latest version when users open your app

By default, a live update runs one session after it downloads. Direct update modes apply it at launch instead, behind your splash screen, so the first screen users see is already the new version.

autoUpdate: atInstall, onLaunch, or always
Splash screen held until the update is ready
Delta downloads keep the wait short

The Problem

Background updates arrive one session late

What happens in the default mode

1

The user opens the app

The app starts on the bundle it already has. The updater checks for a new one and downloads it in the background.

2

The session runs the current version

For the rest of that session, the user runs the code that was installed before your fix.

3

The update applies on the next resume

When the user leaves the app, the updater installs the new bundle. They see it the next time they open the app.

For most releases, that is the right trade-off. When the session that starts after your upload must run the new code, use a direct update mode.

When the first session matters

A broken payment or login flow

Users who open the app should not go through the broken screen once more before the fix applies.

A web-layer security fix

You want the patched JavaScript running from launch, not from the next session.

A dated change

Terms, notices, or event content that must be current on the first screen users see.

The Solution

What changes with a direct update mode

The updater checks at launch while your splash screen stays up. If a new bundle is available, it downloads and applies it before the splash screen hides.

Default mode (atBackground)

1
The user opens the app
2
The app shows the current version
3
The update downloads in the background
4
The update applies on the next resume

No wait at launch. Users see the update one session later.

Direct mode (onLaunch)

1
The user opens the app and the splash screen stays up
2
The updater checks and downloads the changed files
3
The update applies, the splash hides, the new version shows

Users see the new version on the first screen. They wait on the splash screen while it downloads.

Update behavior docs

How it works

How to set up direct updates

A direct mode is native configuration, so it ships in a store build first. After that, every live update follows it. Commands are from the Capgo docs.

  1. Add the splash screen plugin and pick a mode

    Install @capacitor/splash-screen, then set autoUpdate, autoSplashscreen, and launchAutoHide in capacitor.config.ts.

    npm install @capacitor/splash-screen
npx cap sync

// capacitor.config.ts
plugins: {
  CapacitorUpdater: {
    autoUpdate: 'onLaunch', // or 'atInstall' / 'always'
    autoSplashscreen: true,
    keepUrlPathAfterReload: true,
  },
  SplashScreen: { launchAutoHide: false },
}
    Splash screen handling

  2. Ship the config in a store build

    capacitor.config is compiled into the native app, so the new mode reaches users with your next store release. Capgo Build can produce it in the cloud.

    npx @capgo/cli@latest build request --platform ios
npx @capgo/cli@latest build request --platform android
    Capgo Build docs

  3. Upload bundles as deltas

    Users wait for the download at launch, so send only the changed files. The CLI detects instant apply modes and prompts for a delta upload.

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

  4. Keep automatic rollback on

    Call notifyAppReady() once your app has started. If a new bundle fails to start, the device goes back to the last working one.

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

await CapacitorUpdater.notifyAppReady()
    notifyAppReady() docs

Choose the mode that fits your app

Direct updates are a trade: a short wait at launch in exchange for the new version on the first screen.

Three instant apply modes

Set autoUpdate in capacitor.config.ts. Each mode decides when an update may apply while the user waits.

  • atInstall: only right after a fresh install or a store update of the native app
  • onLaunch: when the app starts from a killed state (cold start)
  • always: on every foreground check, even while the app is open
Updater settings

3

Instant apply modes in autoUpdate

Splash screen handling

Direct modes need @capacitor/splash-screen with launchAutoHide set to false, and autoSplashscreen set to true. The updater hides the splash screen once the update is applied, or once it knows no update is needed.

  • No manual SplashScreen.hide() call needed
  • keepUrlPathAfterReload keeps the user on the same route after the reload
  • Listen for appReady if you need extra work after the splash hides
Splash screen handling

autoSplashscreen

Required for every direct mode

Trade-offs to plan for

Users wait for the download at launch, and with always an update can reload the app while it is in use. Plan for both.

  • Upload with --delta so only changed files download
  • Save and restore app state so a reload does not lose user progress
  • Keep the default mode when one session of delay is fine
Delta updates docs

--delta

Recommended for every direct update upload

When to use direct updates

Use a direct mode when the current session must run the new code. Keep the default for everything else.

Critical bug fixes

Payment, login, or data bugs where running the old code for one more session is too much.

First-run onboarding

atInstall applies the latest bundle right after a fresh install or store update, so new users start on your current onboarding.

Dated content

Event pages, notices, or terms that must be current when users open the app.

Security patches

Web-layer security fixes that should run from launch. Fixes in native code still need a store release.

Routine releases

Styling tweaks and small features rarely justify a wait at launch. The default mode applies them one session later.

Apps that stay open for hours

With always, periodic checks (every 10 minutes by default) can apply an update while the app is open. Save state before relying on it.

Keeping the launch wait short

The wait at launch is the update check plus the download. Delta updates keep the download to the files that changed.

~50ms

Typical API latency

Delta

Only changed files are downloaded

1B+

Updates delivered per month

Solutions by Team Type

Find the solution that matches your team's needs

Enterprise

Multi-app, multi-team deployments

Startups

Ship fast without the overhead

Solo Developers

14-day free trial, CLI upload

Agencies

Manage multiple client apps

Apps built with Capacitor

Public information apps need urgent content fixes

Emergency, health, and civic apps cannot wait days to correct a broken checklist, resource link, or location-specific notice. Direct updates let the web layer move as soon as the fix is approved.

FEMA app icon WEATHER

FEMA

Emergency guidance where small content mistakes can become urgent.

Google Play installs
1.6M
Store rating
4.0
Conecte SUS app icon MEDICAL

Conecte SUS

Health records and guidance surfaces where approved copy changes need fast delivery.

Google Play installs
27.7M
Store rating
4.6
e-Título app icon SOCIAL

e-Título

Civic identity workflows where version-safe guidance matters across devices.

Google Play installs
54.9M
Store rating
4.8

Customer proof

What teams shipping with Capgo say

5.0/5 rated by developer teams 9,400+ teams Read reviews

Kapil

Founder, NuTriQ

“Being able to push production OTA updates instantly without waiting for full App Store review cycles has been a massive operational advantage.”

Portrait of Sergiu S

Sergiu S

Lead Developer, drivolino GmbH

“The Capgo Capacitor Updater plugin completely transformed how we ship updates. What used to take days now takes just minutes.”

Portrait of Luis Dominguez

Luis Dominguez

El que paga, Anirol

“Since I started using Capgo everything is faster, and I can give my users the time they deserve without neglecting my daily life.”

FAQ

Questions about direct updates

When to use them, how to set them up, and what they cost at launch.

Should we use direct updates or the default background mode?

Use the default for most releases: there is no wait at launch, and users get the update one session later. Use a direct mode when the session that starts after your upload must run the new code, for example a broken checkout or a web-layer security fix.

Update behavior docs

What is the difference between atInstall, onLaunch, and always?

atInstall applies an update immediately only after a fresh install or a store update of the native app, then behaves like the default. onLaunch applies immediately when the app starts from a killed state. always checks on every foreground and applies as soon as the download finishes, even while the user is in the app.

Updater settings

Why is the splash screen plugin required?

Direct modes apply the update while the user waits. Without @capacitor/splash-screen, autoSplashscreen: true, and launchAutoHide: false, users can see a flicker or the old UI before the reload. With them, the splash stays up until the update is applied or the updater knows none is needed.

Splash screen handling

Can we turn on direct updates with a live update?

No. autoUpdate lives in capacitor.config, which is read into the native app at build time. Ship the new setting in a store release. After that, every live update follows the new mode.

Native compatibility docs

Our config uses directUpdate. Is that still supported?

directUpdate is deprecated but still detected. Its values match the autoUpdate modes atInstall, onLaunch, and always. Move the setting to autoUpdate in your next native release.

Updater settings

Put your next fix on the first screen

Try a direct update mode on a test build during the trial and measure the launch wait on your own app.

14-day free trial. No credit card required.