Channels

A Live Update channel points to a specific JS bundle build of your app that will be shared with any devices configured to listen to that channel for updates. When you install the Capgo Live Updates SDK in your app, any native binary configured to that channel will check for available updates whenever the app is launched. You can change the build a channel points to at any time and can also roll back to previous builds if needed.

How a device picks a channel (precedence)

When a device checks for an update, Capgo decides which channel to use in this strict order (highest priority first):

1. Forced device mapping (Dashboard) – Manually pin a specific device ID to a channel. Use for urgent debugging or controlled testing with a single real user. This always wins.
2. Cloud override (per‑device) via setChannel() or Dashboard – Created when your app calls setChannel() (often exposed in a QA/debug menu) or you change the device’s channel in the dashboard. Use for QA users switching between feature / PR channels or to reproduce a user issue. Reinstalling the binary does not clear it; deleting the device entry does.
3. Capacitor config defaultChannel (test build default) – If present in capacitor.config.* and no force/override exists, the app starts on this channel (e.g. beta, qa, pr-123). Intended for TestFlight / internal builds so testers land on a pre‑release channel automatically. Production builds typically leave this unset.
4. Cloud Default Channel (primary path ~99% of users) – The default channel you marked in the dashboard. All normal end‑users (no force, no override, no config defaultChannel) attach here. Change it to roll out or roll back instantly—no new binary.

Best practice:

• Treat 1–3 as exception / testing layers; real users should flow into the Cloud Default.
• Only configure defaultChannel in binaries you explicitly ship to testers. Leaving it unset keeps production logic centralized in the dashboard.
• Use setChannel() sparingly in production—mainly for QA or targeted diagnostics.

If a channel is disabled for the platform (iOS/Android toggles) when it would otherwise be chosen, the selection process skips it and continues down the list.

Summary: Force > Override > Config defaultChannel > Cloud Default.

Setting up a Channel

Every app comes with a default channel called “Production” that cannot be deleted. To add new channels:

1. Go to the “Channels” section of the Capgo dashboard
2. Click the “New Channel” button
3. Enter a name for the channel and click “Create”

Channel names can be anything you’d like. A common strategy is to match channels to your development stages, such as:

• Development - for testing live updates on local devices or emulators
• QA - for your QA team to verify updates before wider release
• Staging - for final testing in a production-like environment
• Production - for the version of your app that end users receive from the app stores

Configuring the Channel in Your App

With your channels created, you need to configure your app to listen to the appropriate channel. In this example, we’ll use the Development channel.

Open your capacitor.config.ts (or capacitor.config.json) file. Under the plugins section, optionally set defaultChannel for test builds (internal / QA). For production builds, prefer omitting it so devices use the Cloud Default unless explicitly overridden.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // For a QA/TestFlight build – testers start on the Development channel automatically.
      defaultChannel: 'Development',
      // Production builds usually omit this so users attach to the Cloud Default channel.
    },
  },
};

Next, build your web app and run npx cap sync to copy the updated config file to your iOS and Android projects. If you skip this sync step, your native projects will continue to use whichever channel they were previously configured for.

Caution

Channel selection order: Force > Override (setChannel / dashboard) > Config defaultChannel > Cloud Default.

Use defaultChannel only in test/internal builds; leave it out for production so ~99% of users inherit the Cloud Default.

You can still force (pin) a device or apply an override later—those immediately supersede the config value.

Channel names are case sensitive.

Channel Options and Strategies

Channels have several options that control who can receive updates and how updates are delivered. The most important ones are below. You can configure these from the web app, the CLI, or the Public API.

• Default channel: Mark one channel as the default for new devices. New devices will be assigned to this channel unless overridden.
• Platform filters: Enable or disable delivery to iOS and/or Android devices per channel.
• Disable auto downgrade under native: Prevents sending an update when the device’s native app version is newer than the channel’s bundle (for example, device on 1.2.3 while channel has 1.2.2).
• Allow development builds: Permit updates to development builds (useful for testing).
• Allow emulator devices: Permit updates to emulators/simulators (useful for testing).
• Allow device self‑assignment: Lets the app switch to this channel at runtime using setChannel. If disabled, setChannel will fail for this channel.

Disable Auto Update strategies

Use this to restrict which kinds of updates the channel will automatically deliver. Options:

• major: Block cross‑major updates (0.0.0 → 1.0.0). Minor and patch updates still allowed.
• minor: Block cross‑minor updates (e.g., 1.1.0 → 1.2.0) and majors. Patch updates still allowed. Note: does not block 0.1.0 → 1.1.0.
• patch: Very strict. Allows only increasing patch versions within the same major and minor. Examples: 0.0.311 → 0.0.314 ✅, 0.1.312 → 0.0.314 ❌, 1.0.312 → 0.0.314 ❌.
• metadata: Require a minimum update version metadata on each bundle. Configure via CLI using --min-update-version or --auto-min-update-version. If missing, the channel is marked misconfigured and updates will be rejected until set.
• none: Allow all updates according to semver compatibility.

Learn more details and examples in Disable updates strategy at /docs/cli/commands/#disable-updates-strategy.

Example (CLI):

# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign

Assigning a Bundle to a Channel

To deploy a live update, you need to upload a new JS bundle build and assign it to a channel. You can do this in one step with the Capgo CLI:

npx @capgo/cli@latest bundle upload --channel=Development

This will upload your built web assets and set the new bundle as the active build for the Development channel. Any apps configured to listen to that channel will receive the update the next time they check for one.

You can also assign builds to channels from the “Bundles” section of the Capgo dashboard. Click the menu icon next to a build and select “Assign to Channel” to choose the channel for that build.

Bundle Versioning and Channels

It’s important to note that bundles in Capgo are global to your app, not specific to individual channels. The same bundle can be assigned to multiple channels.

When versioning your bundles, we recommend using semantic versioning semver with pre-release identifiers for channel-specific builds. For example, a beta release might be versioned as 1.2.3-beta.1.

This approach has several benefits:

• It clearly communicates the relationship between builds. 1.2.3-beta.1 is obviously a pre-release of 1.2.3.
• It allows for reusing version numbers across channels, reducing confusion.
• It enables clear rollback paths. If you need to roll back from 1.2.3, you know 1.2.2 is the previous stable release.

Here’s an example of how you might align your bundle versions with a typical channel setup:

• Development channel: 1.2.3-dev.1, 1.2.3-dev.2, etc.
• QA channel: 1.2.3-qa.1, 1.2.3-qa.2, etc.
• Staging channel: 1.2.3-rc.1, 1.2.3-rc.2, etc.
• Production channel: 1.2.3, 1.2.4, etc.

Using semver with pre-release identifiers is a recommended approach, but not strictly required. The key is to find a versioning scheme that clearly communicates the relationships between your builds and aligns with your team’s development process.

Rolling Back a Live Update

If you deploy a live update that introduces a bug or otherwise needs to be reverted, you can easily roll back to a previous build. From the “Channels” section of the dashboard:

1. Click the name of the channel you want to roll back
2. Find the build you want to revert to and click the crown icon
3. Confirm the action

The selected build will immediately become the active build for that channel again. Apps will receive the rolled back version the next time they check for an update.

Automating Deployments

For more advanced workflows, you can automate your live update deployments as part of your CI/CD pipeline. By integrating Capgo into your build process, you can automatically upload new bundles and assign them to channels whenever you push to certain branches or create new releases.

Check out the CI/CD Integration docs to learn more about automating Capgo live updates.

Deploying to a Device

Now that you understand channels, you’re ready to start deploying live updates to real devices. The basic process is:

1. Install the Capgo SDK in your app
2. Configure the app to listen to your desired channel
3. Upload a build and assign it to that channel
4. Launch the app and wait for the update!

For a more detailed walkthrough, see the Deploying Live Updates guide. Happy updating!

Advanced Channel Usage: User Segmentation

Channels can be used for more than just development stages. They’re a powerful tool for user segmentation, enabling features like:

• Feature flags for different user tiers
• A/B testing
• Gradual feature rollouts
• Beta testing programs

Learn how to implement these advanced use cases in our guide: How to Segment Users by Plan and Channels for Feature Flags and A/B Testing.