Version Management

Magdalena Skarbińska

Demián Renzulli

Isolated Web Apps (IWAs) 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: 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: 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. 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:

{
  "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 policy. This capability is primarily managed through the interactive UI controls in the Google Admin Console under the application's details panel following the standard IWA installation workflow, 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: Irreversible user data loss: Downgrading an IWA will completely wipe its associated storage partitions (including IndexedDB, LocalStorage, Cache, and 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: 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 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

[
  {
    "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.