Skip to main content

Version Targeting

Send each native version only the bundles it can run

Users update from the store at their own pace, so several native versions of your app are live at once. Capgo checks each bundle's native dependencies, blocks updates by version rules, and can route each native version to its own channel.

Check native compatibility before upload

bundle compatibility compares the native packages in your project with the bundle live on the channel. Add --fail-on-incompatible in CI to stop an upload that needs a new binary.

Native compatibility docs

Set a native version floor on every bundle

Put the channel on the metadata strategy and upload with --auto-min-update-version. Devices whose native version is below the bundle's floor skip it and keep their current bundle.

Version targeting docs

Block updates across semver lines

--disable-auto-update major, minor, or patch keeps a device from receiving a bundle outside its native version line. These rules compare version numbers only. They do not inspect native code.

Update types and version blocking

A channel per native version

Set defaultChannel in each native build's Capacitor config, for example v2 or v3. Each line gets its own bundles, and an older line can stay on its last working bundle.

Version targeting docs

How it works

How teams with several native versions ship with Capgo

A CI setup that lets the live update lane and the store lane work side by side. Every command below is from the Capgo CLI docs.

  1. Ask whether the commit needs a native build

    build needed compares your native packages with the channel. It prints yes and exits with code 1 when a store release is required, and no when a live update is enough.

    npx @capgo/cli@latest build needed com.example.app --channel production
    build needed reference

  2. Switch the channel to the metadata strategy

    Do this once. From then on, each bundle carries a minimum native version and devices below it skip the bundle.

    npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update metadata
    Version targeting docs

  3. Upload everyday live updates

    Keep --auto-min-update-version on every upload. --fail-on-incompatible stops the job if the bundle needs native code the channel does not have.

    npx @capgo/cli@latest bundle upload --channel production \
  --auto-min-update-version \
  --fail-on-incompatible
    Native compatibility docs

  4. Upload the bundle for a new native release

    When the new binary ships, upload its bundle without --fail-on-incompatible. Capgo raises the floor so older builds skip it, and later checks compare against the new native packages.

    npx @capgo/cli@latest bundle upload --channel production \
  --auto-min-update-version
    Native and OTA channel workflow

Appflow migration

Coming from Ionic Appflow?

Appflow matched live updates to native versions for you. In Capgo you get the same result with channels and version rules:

  1. Create a channel for each native line, for example v1 and v2.
  2. Set defaultChannel in each native build's Capacitor config to its channel.
  3. Upload each bundle to the channel of the native line it was built for.
  4. Keep --auto-min-update-version on uploads so a bundle that needs newer native code skips older builds.
Appflow migration guide
Channel per native line 
// capacitor.config.ts in your 2.x native builds
plugins: {
  CapacitorUpdater: {
    defaultChannel: 'v2',
  },
},

# ship a fix to 2.x users only
npx @capgo/cli@latest bundle upload --channel v2 \
  --auto-min-update-version

# 1.x devices stay on their channel's current bundle

Common situations

A new native plugin

Your 2.0 binary adds a camera plugin. Upload the bundle that uses it with --auto-min-update-version, and 1.x devices skip it until users install 2.0.

Native compatibility docs

Gradual exposure

Send a bundle to a share of one channel with --rollout, watch install and failure data, then promote it or roll it back.

Progressive rollouts docs

Retiring an old version

Stop uploading to the v1 channel. Devices on it keep their last working bundle while v2 keeps receiving updates.

Version targeting docs

Each native line points to its own channel

An example layout with three native versions in the wild.

  • Native 3.x
    v3
    New bundles
  • Native 2.x
    v2
    Fixes only
  • Native 1.x
    v1
    No new bundles

Ship features to v3, fixes to v2, and nothing to v1. Devices on v1 keep their last working bundle.

Apps built with Capacitor

Public apps must support old and new native versions

Civic, health, and forecast apps may support older Android versions and different device generations. Version targeting keeps each native build on the newest compatible web bundle without forcing one update path for everyone.

e-Título app icon SOCIAL

e-Título

Civic identity app with broad public device compatibility needs.

Google Play installs
54.9M
Store rating
4.8
Conecte SUS app icon MEDICAL

Conecte SUS

Health app where older and newer native shells may need different web bundles.

Google Play installs
27.7M
Store rating
4.6
Windy.com - Weather Forecast app icon WEATHER

Windy.com - Weather Forecast

Weather app where device capability and map performance can vary by version.

Google Play installs
32.9M
Store rating
4.7

Customer proof

What teams shipping with Capgo say

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

no-tone @ Webincode

Developer, Webincode

“Being able to add Device ID's to certain groups and push the changes to only certain groups is a life saver.”

Nate van Jole

CTO, Private

“Getting set up took less than a day. Channel-based rollouts let me test on my own device before anything hits production users.”

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.”

FAQ

Questions about versions in the wild

For teams supporting users who update the store app at different times.

What happens to users who never update the native app?

They keep receiving bundles that are compatible with their native version. With the metadata strategy, a bundle whose minimum native version is above theirs is skipped, and they stay on their current bundle.

Version targeting docs

Is --disable-auto-update major enough to prevent crashes?

No. Version rules only compare version numbers, so a native change shipped in a minor or patch release still goes out. Use --fail-on-incompatible or --auto-min-update-version, which check your native packages.

Native compatibility docs

How does CI know whether a change needs a store release?

Run build needed or bundle releaseType against the channel. Both compare native package metadata. They do not see every edit under ios/, android/, or capacitor.config, so gate those paths in git as well.

Choose OTA or native build in CI

We are moving from Ionic Appflow. Can we keep version-matched updates?

Yes. Use a channel per native line with defaultChannel, or the metadata strategy with --auto-min-update-version. The Appflow migration guide walks through the setup.

Appflow migration guide

What if an incompatible bundle already went out?

Point the channel back to the last compatible bundle from its history, or force the built-in bundle, and ship the native build. notifyAppReady() rolls back a bundle that fails to start, but it is not a substitute for compatible native code.

Rollbacks docs

Keep every native version on a bundle it can run

Set up the metadata strategy and a compatibility check in CI during the 14-day free trial. No credit card needed.