![Magdalena Skarbińska](https://web.dev/images/authors/mskarbinska.jpg) Magdalena Skarbińska ![Demián Renzulli](https://web.dev/images/authors/demianrenzulli.jpg) Demián Renzulli [X](https://twitter.com/drenzulli) [GitHub](https://github.com/demianrenzulli)

<br />

[Isolated Web Apps (IWAs)](https://developer.chrome.com/docs/iwa/introduction.md.txt) offer a high-trust, secure,
and version-discrete runtime environment on top of the web platform. In
production environments---particularly within managed enterprises---administrators
and developers need fine-grained control over software deployments.

To meet these requirements, Chrome provides comprehensive version management
capabilities for IWAs, including **Update Channels** , **Version Pinning** , and
**Version Downgrading**. These features enable deployment predictability, and
rapid recovery controls across your user base.

## Availability

Version management behavior depends on whether the IWA is managed by an
administrator or installed directly by a user:

- **Managed IWAs:** Administrative features (including policy-driven pinning and downgrades) are available from **Chrome 133**.
- **Unmanaged (User-Installed) IWAs:** User-facing features (such as manual channel selection) are available from **Chrome 150**.

### Session type compatibility

All version management functionalities---including update channels and version
pinning---are fully compatible across all ChromeOS session types. This includes:

- Standard managed **User Sessions**
- **Managed Guest Sessions (MGS)**
- Dedicated **Kiosk mode** environments

> [!NOTE]
> **Note:** To ensure updates are recognized properly, version strings must follow the valid IWA format. The platform supports numeric-only versions with a maximum of 4 components (for example: 1, 1.2, 1.2.4, or 111.22.3.4).

> [!NOTE]
> **Note:** While pinning and channel targeting are universally supported across session types, version downgrades may initially be restricted to **Trusted
> Testers** depending on the active platform deployment timeline.

## Update channels

By using update channels, developers can segment specific application builds for
distinct deployment and testing audiences. To configure channels, add an
optional channels array field to each version entry within the application
update manifest. These channel names are not constrained to fixed platform
keywords (like `canary` or `stable`) but are instead arbitrary,
developer-defined identifiers that must be formatted as lowercase ASCII
alphanumeric strings (which can include hyphens or underscores but no spaces).
If a version entry omits the channels field entirely, Chrome implicitly defaults
its availability to the "default" channel. Ultimately, the channel name
designated in the administrative policy must exactly match the string defined in
the manifest; any typographical errors or mismatched configurations will result
in no eligible version being identified, effectively halting updates for those
clients.

### Manifest configuration

To configure channels, add an optional `channels` array to each version entry in
your
[Web App Manifest](https://developer.chrome.com/docs/iwa/introduction.md.txt#web_app_manifest).
Here are some considerations to take into account:

- **Channel mapping:** If a version entry defines a `channels` array, that version is only eligible for installation on the specified channels.
- **The default fallback:** If a version entry omits the `channels` field entirely, Chrome assumes the version belongs exclusively to the `default` channel.
- **Exact string matching:** Channel names specified in client-side policy configurations must exactly match the strings defined in the update manifest (case-sensitive). If no version matches the targeted channel name, the app will fail to find eligible updates.

### Update manifest example

The following example shows an update manifest supporting multiple release
channels:

```javascript
{
  "versions": [
    {
      "version": "0.1.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.1.0/iwa-sink.swbn",
      "channels": ["delta"]
    },
    {
      "version": "0.2.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.2.0/iwa-sink.swbn",
      "channels": ["delta", "default"]
    },
    {
      "version": "0.3.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.3.0/iwa-sink.swbn",
      "channels": ["beta", "delta"]
    },
    {
      "version": "0.4.0",
      "src": "https://github.com/chromeos/iwa-sink/releases/download/v0.4.0/iwa-sink.swbn"
    }
  ]
}
```

Based on this manifest, the following versions are available per targeted
channel:

- **default:** `0.2.0`,`0.4.0` (which lacks an explicit channel and defaults to default)
- **delta:** `0.1.0`, `0.2.0`, `0.3.0`
- **beta:** `0.3.0`

The IWA update engine supports targeting specific release channels by looking
for a channels field inside the app's Update Manifest.

## Version pinning

In high-compliance or highly stable enterprise environments, administrators must
ensure devices run exact versions of business-critical software. Version pinning
allows administrators to lock an IWA to a specific version, halting all
subsequent background updates. This provides enterprises with a highly reliable
way to maintain stable configurations and comply with strict internal or
industry regulations.

To freeze an Isolated Web App (IWA) at a specific release build, enterprise
administrators can configure the `pinned_version` property within the
[IsolatedWebAppInstallForceList](https://chromeenterprise.google/policies/#IsolatedWebAppInstallForceList)
policy. This capability is primarily managed through the interactive UI controls
in [the Google Admin
Console](https://support.google.com/chrome/a/answer/9039146) under the
application's details panel following the standard [IWA installation
workflow](https://support.google.com/chrome/a/answer/9367354), though
administrators also retain the flexibility to deploy these policy values
directly using raw JSON configurations. Once a valid version string is
successfully targeted by the administrator, Chrome pulls that explicit package
and blocks all subsequent automatic forward updates.

### Special behaviors and constraints

- **Resuming updates (Unpinning):** To restore automatic updates, remove the `pinned_version` property or change its value to a newer target version.
- **No downgrade by default:** Setting `pinned_version` to a version lower than the currently installed version will *not* trigger a rollback unless `allow_downgrades` is explicitly enabled.
- **Unavailable pin targets:** If the configured `pinned_version` is missing from the designated update channel, or is older than the installed version (with downgrades disabled), Chrome will retain the currently installed version and block any further updates.
- **Fresh deployments:** If an IWA is not yet installed on a managed device, and the specified pinned_version cannot be retrieved or is missing from the update manifest, the IWA will fail to install.

## Version downgrading

If a newly deployed update introduces a critical bug or vulnerability,
administrators may need to roll back devices to a previous stable state. Chrome
supports downgrading already installed managed IWAs to a lower version---a
capability that was previously unavailable on the platform when only forward
updates were allowed.

Downgrading is possible only if **both** of the following policy conditions are
met:

1. `pinned_version` is set to a valid, older version.
2. `allow_downgrades` is explicitly set to true.

### How downgrades work

- **Trigger mechanism:** Rollbacks are processed during the regular update check cycle (which runs every 4--6 hours).
- **Under the hood:** Chrome performs a full reinstallation of the IWA using the older web bundle (.swbn) specified in the update manifest.

> [!WARNING]
> **Warning:** **Irreversible user data loss:** Downgrading an IWA will completely wipe its associated storage partitions (including [IndexedDB](https://developer.mozilla.org/docs/Web/API/IndexedDB_API), [LocalStorage](https://developer.mozilla.org/docs/Web/API/Window/localStorage), [Cache](https://developer.mozilla.org/docs/Web/API/Cache), and [Cookies](https://developer.mozilla.org/docs/Web/HTTP/Guides/Cookies)). To safeguard user data, reserve downgrades for emergency scenarios---such as addressing severe security vulnerabilities. For non-critical bug fixes, it is highly recommended to build and publish a new, patched minor version update rather than rolling back.

> [!IMPORTANT]
> **Important:** **Immediate update freeze:** Simply toggling `allow_downgrades` to true instantly freezes all standard forward updates, even if you don't define a `pinned_version`. Once enabled, the browser blocks standard updates until you explicitly assign a higher pinned_version or toggle `allow_downgrades` back to false.

## Channel transition logic

When switching an app's targeted channel with a policy, the update engine
adheres to specific behaviors:

### Scenario A: Switching to a channel with earlier versions

- **If downgrading is allowed:** If pinned_version matches an older version on the target channel and `allow_downgrades` is true, a rollback occurs (and local user data is wiped).
- **If downgrading is disallowed:** No downgrade will occur. The device will remain on its currently installed higher version and will only update when a newer version becomes available on the newly selected channel.

### Scenario B: Switching to a channel with an identical version

- **No changes:** If the newly selected channel points to a version number equal to the currently installed one, Chrome will make no modification to the installed bundle.
- **Byte-by-Byte identity principle:** Developers must guarantee that identical version numbers across different channels contain identical, byte-matching code signatures. Deploying different codebases under the same version string across channels can result in unexpected, erratic application states.

## Administrative policy configuration

Enterprise version controls are enforced with the centralized Google Admin
Console platform using the
[IsolatedWebAppInstallForceList](https://chromeenterprise.google/policies/#IsolatedWebAppInstallForceList)
policy schema. These settings can be managed directly through UI controls in the
Admin Console, or deployed using raw JSON policy configurations.  

The following administrative policy configuration example demonstrates update
channels, version pinning, and downgrades:

### Policy value representation

```javascript
[
  {
    "update_manifest_url": "https://awesome-kitchen-sink.glitch.me/update.json",
    "web_bundle_id": "aiv4bxauvcu3zvbu6r5yynoh4atkzqqaoeof5mwz54b4zfywcrjuoaacai",
    "channel": "beta",
    "pinned_version": "0.7.0",
    "allow_downgrades": true
  }
]
```

### Schema parameter explanations

- **`channel`** *(string, optional)*: Instructs Chrome to only evaluate versions assigned to this channel in the update manifest. If omitted, Chrome evaluates the "default" channel.
- **`pinned_version`** *(string, optional)*: Explicitly locks the device to the specified version string. Subsequent automatic background updates are blocked.
- **`allow_downgrades`** *(boolean, optional)* : Enables rollback capability. If true and paired with a valid, older `pinned_version`, Chrome will trigger a downgrade reinstallation. **Warning:** Setting this parameter to true will block all standard forward updates even if the `pinned_version` field is omitted.

## Unmanaged (user-installed) IWAs (from 150)

For unmanaged, user-installed Isolated Web Apps, versioning operates with manual
user interactions:

Installation Bundle ──► User Selects Channel ──► Automatic Checks on
Selected Channel

### Manifest prerequisite for automatic updates

For user-installed IWAs to check for and receive automatic periodic updates in
the background, the app's local Web App Manifest (the metadata packaged inside
the bundle at `/.well-known/manifest.webmanifest`) **must** contain a valid
`update_manifest_url` field.

If this URL is omitted from the application's local manifest file, the unmanaged
update engine will never perform background checks, and the application will
remain permanently frozen on its initial installation version.

### Manual channel selection

During the initial installation of an unmanaged IWA, the browser checks the
update manifest and displays available channel options (for example, "Stable",
"Beta") directly to the user if the developer has configured multiple channels.

### Key lifecycle rules

1. **First install origin:** Regardless of the channel selected by the user at installation, the initial installation always deploys the files packaged inside the provided installation bundle.
2. **Subsequent updates:** Once installed, future updates are queried exclusively from the chosen channel. The app will update only when a version *higher* than the installed one is published to that targeted channel.
3. **Switching channels:** To switch to a different update channel after installation, the user must uninstall the IWA and reinstall it, choosing the selected channel during the installation flow.

## How to test managed deployments

For administrators managing devices through the Chrome Enterprise Admin Console
or configuring policies directly:

1. Navigate to the **App Details** panel under the organizational settings.
2. Apply configuration properties to test pinning and channel targets. Because these controls are fully compatible with standard User Sessions, Managed Guest Sessions (MGS), and Kiosks, you can verify behaviors across all target deployment environments.
3. To inspect update checks locally, navigate to `chrome://web-app-internals` on a test client to manually force update checks and analyze incoming manifest packets.

## Conclusion

The security architecture of Isolated Web Apps is designed to empower developers
while maintaining strict predictability and control over application lifecycle
behaviors. By taking advantage of Chrome's version management features, both
developers and IT administrators can build robust deployment pipelines that
align with strict compliance standards and operational goals.

As you design and manage your application's update strategy, keep these core
principles in mind:

- **Use progressive channels:** Update channels (like `beta`, `dev`, or custom rings) let you progressively gather telemetry and feedback. This ensures major updates undergo rigorous verification before hitting the general population on the default channel.
- **Pin for stability:** In highly structured or compliance-driven enterprise environments, lock critical endpoints to a verified, exact pinned_version to protect operations from unexpected breakages or workflow disruptions.
- **Reserve downgrades for emergencies:** Recognize that version downgrading is a powerful, corrective safety valve that was previously impossible. However, because a rollback triggers a complete reinstallation and purges all local client storage (IndexedDB, LocalStorage, cookies), it should be strictly reserved for critical security remediation. For ordinary patches, deploying a minor forward-looking update is always the ideal strategy.
- **Understand policy flags:** Be mindful of administrative switches; turning on `allow_downgrades` will halt all forward updates even if a pin is not actively defined.
- **Establish Byte-by-Byte Integrity:** Ensure that identical version numbers deployed across different channels map to identical, byte-matching bundles to avoid erratic application states when clients transition between channels.

By integrating these features directly into your Update Manifest and enterprise
policy schema, you can ensure a reliable, auditable, and secure update flow that
preserves the high-trust guarantees of the Isolated Web App ecosystem.