Update Rules

Steer specific users onto a channel, pin them to a release, or freeze their updates

Update rules change which release specific users get, without touching your channels or rollouts. Use them to move a group of testers onto a private channel, hold a user who reported a bug on a known release, or stop updates for users in one region while you investigate a problem.

Manage rules in the dashboard under Deployments → Update rules, or through the API.

How rules are applied

Each application has an ordered list of up to 50 rules. A rule has a name, an on/off switch, a target and an action.

• When a user checks for an update or loads your site, rules are checked from the top of the list down. The first enabled rule that matches the user decides, and every rule below it is ignored for that user.
• Users who match no rule get normal updates: the release their channel’s rollouts give them.
• A rule that’s switched off keeps its place in the list but matches nobody. Switch it back on to use it again.

Reorder the list to change which rule wins when a user matches more than one.

The first matching rule decides even when it doesn’t cover what’s being updated. A rule that only changes app updates still stops later rules from applying to that user’s site; their site gets normal updates.

Targeting

A rule targets users with a user id list and conditions. A user matches when both match.

• User ids: up to 1,000 user ids. An empty list matches any user.
• Conditions: built like feature flag conditions. Conditions in a group must all match, and a rule matches when any one of its groups matches. No conditions matches any user.

A rule with no user ids and no conditions matches everyone. Because of that, removing a rule’s last user id is refused: switch the rule off, delete it, or edit its targeting instead.

You can build conditions on these fields:

Field	What it is
Country, city, continent, region, region code	The user’s location, from their IP address
IP address	The user’s IP address
Channel	The channel of the user’s installed release, or the default channel if none
Release	The user’s installed app release
SDK version	The @overlayed/app version the user’s app runs

• Channel is the channel the user is on, not the one they ask for. A switchChannel request doesn’t change which rule matches them.
• Release is known only to app update checks. Site loads don’t know the installed release, so a rule conditioned on a release never matches a site load (except “release is empty”, which always does). The same user can match different rules for their app and their site.
• City and region names with non-ASCII characters may not match consistently.

Game, account, staff and signed-in conditions aren’t available: nothing knows them when a user checks for an update.

Actions

Each rule has one action.

Action	Covers	What the user gets
Force channel	App and site	The newest release on a channel you choose
Pin	App, site, or both	One release you choose
Freeze	App, site, or both	No updates: the release they have, or the site everyone had

Force channel

Moves users onto a channel and gives them its newest release.

• App: the channel’s newest built, published release that isn’t paused, whatever its rollout. Users who already have a newer paused release on that channel keep it. If the channel has no app release, the app stays on the release it has.
• Site: the newest site release on the channel that the user’s app supports (its minimum app version is met), among the channel’s 20 newest built, published site releases that aren’t paused, whatever their rollout. If none of them is supported, the user gets normal site updates. To serve a paused release, pin it.
• Private channels need no token. Matching the rule counts as access, so users get the channel’s releases without an access token.
• Users stay on the channel. Once their app installs a release from the forced channel, that’s their channel. When you remove the rule, they keep getting that channel’s normal updates (and need a token if it’s private).

A channel that a force channel rule targets can’t be deleted. Delete or change the rule first.

Pin

Gives users one release you choose, for the app, the site, or both.

• You can pin any built, published release that hasn’t been revoked, on any channel. Drafts can’t be pinned.
• Rollout and pausing don’t apply: matching users get the pinned release.
• Pinning a release on another channel moves the user there. Like a forced channel, no token is needed for a private one.
• Site compatibility. A site pin that needs a newer app than the user has falls back to normal site updates for that user.
• Revoke wins. If the pinned release is revoked or deleted, matching users get normal updates.

Freeze

Stops updates for matching users, for the app, the site, or both.

• App: users keep the release they have installed. If that release is revoked or deleted, revoke wins and they get normal updates.
• Site: users get the site release that everyone on their channel was getting when the rule was saved or last edited. That’s the release your channel served to all its users at that moment (fully rolled out), not the one a particular user happened to have. Editing a site freeze takes a new snapshot.
• Users whose app can’t load the frozen site release (its minimum app version is newer than their app) get normal site updates.
• A freeze doesn’t grant access. Users on a private channel still need a valid access token, as usual.

Moving users to an older build

A pin or forced channel can move users to an older build than the one they have. The update server marks that build as a rollback, so apps install it on their next update check like any other update: from @overlayed/app 2.9.1 because it’s marked as a rollback, and on earlier versions because they install whatever build the update check returns.

Manual site updates

Rules beat the client. When your app uses manual site updates and a rule decides a user’s site, they keep the site release they’re running only while the rule allows it: it’s one of a forced channel’s releases, or it’s the pinned or frozen release. Otherwise the site loads the rule’s release.

When rules take effect

• Apps get a rule’s change on their next update check, which runs when your app calls checkForUpdates().
• Sites get it within about a minute or two, the next time the site loads.

Rules aren’t access control

Rules trust the user id the user’s app sends. Use them to steer updates, not to protect a release: anyone who sends a matching user id gets what the rule gives. To restrict who can get a release, use a private channel and issue tokens from your own server.

Previewing a rule

The Update rules page has a preview. Type a user id, and optionally their channel, installed release, country and other targeting values, to see:

• which rule matches their app updates and which matches their site loads (these can differ, because site loads don’t know the installed release), and which rules aren’t reached;
• which app release and which site release they’d get right now.

The preview uses only the values you type. It never looks up a real user’s data and changes nothing. When the answer depends on a private channel, it says it assumed the user holds a valid access token for it.

Managing rules from the API

Manage rules with an API key that has release permissions. The same operations are tools on the hosted MCP server.

Operation	Request
listUpdateRules	GET /v1/applications/{application_id}/update-rules
getUpdateRule	GET /v1/applications/{application_id}/update-rules/{update_rule_id}
createUpdateRule	POST /v1/applications/{application_id}/update-rules (added last)
updateUpdateRule	POST /v1/applications/{application_id}/update-rules/{update_rule_id}
deleteUpdateRule	DELETE /v1/applications/{application_id}/update-rules/{update_rule_id}
reorderUpdateRules	POST /v1/applications/{application_id}/update-rules/reorder with every rule id, first first
addUpdateRuleUsers	POST /v1/applications/{application_id}/update-rules/{update_rule_id}/users/add
removeUpdateRuleUsers	POST /v1/applications/{application_id}/update-rules/{update_rule_id}/users/remove
previewUpdateRules	POST /v1/applications/{application_id}/update-rules/preview

• updateUpdateRule changes only the fields you send. Send { "enabled": false } to switch a rule off.
• addUpdateRuleUsers and removeUpdateRuleUsers take { "user_ids": [...] } and change the list without resending the rule.

For example, a rule that pins two users to an app release:

{
	"name": "Hold bug reporters on 1.4.2",
	"user_ids": ["7d3f2c1a-5b6e-4f8a-9c0d-1e2f3a4b5c6d", "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"],
	"action": { "type": "pin", "app_release_id": "YOUR_RELEASE_ID" }
}

Permissions

• Owner, Manager and Maintainer can create, edit, switch, reorder and delete rules.
• Developer and Viewer can view rules and use the preview.

Every change to a rule is recorded in the application’s audit log.