Feature flags

A feature flag is a remote switch for a feature in your app or website. Your developers wrap the feature in a flag once, and after that you decide in the Control Panel who gets it: users in a specific segment, a percentage of all users, or both. A flag can also carry properties, such as a button color or a discount limit, so you can change how the feature behaves for each audience without a new release. If something goes wrong, the kill switch turns the feature off for everyone.

Beta feature

Feature flags are in beta. The SDK side is available in the Web SDK. Support in the mobile SDKs is coming.

Before you start

• Plan. Feature flags are available only on plans that include them. On other plans, Feature Flags doesn’t appear in the Audience menu. To turn them on, contact your account manager. If your plan stops including feature flags, devices stop receiving flags and your app or website falls back to the defaults set in its code. Creating or restoring a flag then fails with the message Feature flags are not available on your plan, for example in a Control Panel tab that was opened before the plan changed.
• Access. You need access to segments in the Control Panel to see Feature Flags in the menu.
• Developer setup. A flag affects users only after your developers read it in the app or website code by its key. Share the Web SDK guide with them.

How a flag decides what each user gets

Every flag has a list of rules. Each rule has a segment, a rollout percentage, and optional property values. For every device, Pushwoosh checks the rules from top to bottom:

1. The first rule whose segment the device matches decides. A rule with no segment matches every device.
2. The rule’s rollout percentage decides whether this user gets the flag on. At 20%, two users in ten get it.
3. A user who gets the flag on receives the property values set in that rule. A user who gets it off receives the default property values.

A device stops at the first matching rule even when that rule turns the flag off for it, so a later rule never applies to users that an earlier rule already matched. A device that matches no rule gets the flag off.

The rollout is sticky. Pushwoosh places each user in a fixed bucket, one of 10,000, by their User ID, or by their device ID when no User ID is set, so the same user keeps the same result on every visit and on every device signed in with that User ID. When you raise the percentage, users who already have the flag keep it and new users join them.

Create a flag

1. Go to Audience → Feature Flags.
2. Click Create feature flag.

3. Enter the Key. Your developers use it in code to read the flag, for example new_checkout. Use Latin letters, digits, _, ., and -, up to 58 characters. You can’t change the key later, and you can’t reuse a key that another flag of the application has, even an archived one. Keys are compared case-insensitively.
4. Enter a Name and, optionally, a Description so your team knows what the flag controls.

Add properties

Properties are values the app or website reads from the flag, for example the text of a banner or the number of items in a recommendation block. Skip this step if the flag only turns a feature on and off.

1. In Properties, click Add property.
2. Enter the Property key, for example button_color. Use Latin letters, digits, and _, up to 64 characters.
3. Choose the type: String, Number, Boolean, or JSON. You can’t change the type after you save the flag.
4. Enter the Default value. Users who get the flag off receive this value.

A flag can have up to 50 properties.

Add rules

1. In Rules, click Add rule.
2. Enter a Rule name, for example Paying customers.
3. In Segment, choose who the rule applies to. Leave it empty to apply the rule to all users.
4. In Rollout, %, enter the share of the segment that gets the flag on, from 0 to 100 with up to two decimals.
5. In Values for users this rule turns on, change the properties that should differ from the defaults for these users. Properties you leave unchanged keep their default values.
6. To add another audience, repeat the steps. Use Move up and Move down to change the order, because the first matching rule decides.

A flag can have up to 10 rules.

Segments a rule can use

A rule segment can contain only tag, location, application, and list conditions, because the flag is evaluated each time a device asks for it. Segments with event, static, external, last-update, or best-time-to-send conditions don’t appear in the segment picker.

For example, to give a new checkout to all paying customers and to 20% of everyone else, create two rules:

Rule	Segment	Rollout, %	Values for users this rule turns on
Paying customers	Purchased something	100	button_color = green, show_apple_pay = true
Everyone else	—	20	button_color = orange

Save the flag

Click Save. The flag is created as Active, and devices receive it the next time the SDK refreshes flags.

Manage flags

The flag list shows the key, name, status, number of rules, and last update time of each flag. To see archived flags, turn on Show archived. To open a flag, click Open next to it.

A flag has one of three statuses:

Status	What users get
Active	The flag works by its rules.
Killed	The flag is off for every user, with default property values. Rules and properties are kept.
Archived	Devices no longer receive the flag, so the code falls back to the defaults your developers set in it.

The actions for a flag are at the top of its page. An active flag has Reshuffle, Kill switch, and Archive. A killed flag has Turn back on and Archive. An archived flag has Restore.

Change a flag

Open the flag, edit the name, description, properties, or rules, and click Save. To roll a feature out gradually, raise the Rollout, % of a rule step by step.

If someone else saved the flag while you were editing it, the Control Panel doesn’t overwrite their changes and asks you to reload the flag. Click Reload and make your changes again.

Turn a flag off for everyone

Use the kill switch when a feature causes problems and you need to stop it immediately:

1. Open the flag and click Kill switch.
2. Confirm. Every device gets the flag off with default property values on its next refresh.

To turn the flag back on with its rules as they were, click Turn back on.

Pick a different sample of users

Reshuffle places every user in a new bucket, so the same rollout percentage selects a different group of users. Use it when you want a fresh sample, for example to start a new test.

1. Open an active flag and click Reshuffle.
2. Confirm. Some users who have the flag on lose it immediately and others get it, while the percentages stay the same.

Archive and restore a flag

Archive a flag when the feature is fully released or removed from the code. An archived flag doesn’t count toward your plan’s limit of flags per application, and its key stays reserved.

1. Open the flag and click Archive.
2. Confirm.

An archived flag can’t be edited. To bring it back, turn on Show archived in the list, open the flag, and click Restore. A restored flag comes back as Killed, so it doesn’t reach users on its own. Click Turn back on when you’re ready.

Limits

The Control Panel and the API enforce these limits when you save a flag:

Limit	Value
Rules per flag	10
Properties per flag	50
Size of all property values of one flag	10,000 bytes
Nesting depth of a JSON value	5 levels
Flags per application	Set by your plan, archived flags don’t count
Data one device receives for all flags of the application	64 KB

Manage flags through the API

Your developers can create and change flags from their own systems with the Feature Flags API, and AI assistants connected through the Pushwoosh MCP server can manage flags with the same operations.