Skip to content

Feature flags

A feature flag is an on/off switch for a feature in your app or website. You flip it in the Control Panel, with no new release.

For each flag you choose who gets the feature: users in a segment, a percentage of all users, or both. For example, show a new screen to 10% of users first, then raise the percentage. If something goes wrong, you can turn the feature off for everyone with the Kill switch button. A flag can also carry properties, such as a button color or a discount limit, that you set per audience.

Before you start

Anchor link to
  • Limit: Each application can have one flag that isn’t archived. To run more flags at once, contact your account manager.

  • Access: Feature flags appears in every application you can see. To create and change flags, you need the Modify applications permission or the same permission for this application in its app-specific permissions.

  • Developer setup: A flag affects users only after your developers read it in the app or website code by its key. Give them:

    • The flag key.
    • The code sample. In an application with no flags yet, the Feature flags page shows ready-made code samples for Web, Android, and iOS.
    • The SDK guide: Web SDK, Android SDK, or iOS SDK.

    Your app or website needs Web SDK 3.94.1 or later, Android SDK 6.16.0 or later, or iOS SDK 7.2.10 or later.

How a flag decides what each user gets

Anchor link to

Every flag has a list of rules. Each rule has a segment, a percentage of users that get the flag on (Rollout, %), 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 Rollout, % of the rule 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.

Once a device matches a rule, the later rules are skipped, even when that rule turns the flag off for it. A device that matches no rule gets the flag off.

  • A user gets the same result on every visit.
  • Pushwoosh identifies a user by User ID, or by device ID when no User ID is set. Devices signed in with the same User ID get the same result when they match the same rule, because Pushwoosh checks segments for each device.
  • When you raise the percentage, users who already have the flag keep it and new users join them.

Create a flag

Anchor link to
  1. Go to Audience → Feature flags.

  2. Click Create feature flag.

    Feature flags page of an application with the Create feature flag button highlighted and the SDK support block listing Web, Android, and iOS
  3. Enter the Key, for example new_checkout. The key is any name you choose, but your developers read the flag in code by this exact key, letter case included. Agree on it with them before you save the flag.

  4. Enter a Name and, optionally, a Description so your team knows what the flag controls.

The key follows these rules:

  • Latin letters, digits, _, ., and -, up to 58 characters.
  • You can’t change the key later.
  • You can’t reuse a key that another flag of the application has, even an archived one, or a key that differs from it only in letter case, such as New_Checkout and new_checkout.

Add properties

Anchor link to

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. The property key is any name you choose, but your developers read the value in code by this exact key, letter case included. Agree on it with them before you save the flag.
  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.

Feature flag form with the key, name, description, and two properties: button_color of type String and show_apple_pay of type Boolean
  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 percentage 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 steps 1 to 5.
  7. After you add the rules, use Move up and Move down to change their order, because the first matching rule decides.

A flag can have up to 10 rules.

Under Rollout, %, each rule shows about how many devices it turns on, for example ≈ 1,200 devices. Pushwoosh calculates it as follows:

  • It multiplies the size of the rule segment by the percentage. For example, a segment of 1,500 devices at 80% gives ≈ 1,200 devices.
  • For a rule with no segment, it takes all devices of the application.

Read the number as the most the rule can reach, because a device that matches an earlier rule stops there.

Rule 1 of a feature flag: Paying customers for the Purchased something segment at 100%, with button_color set to green and show_apple_pay set to true

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

RuleSegmentRollout, %Values for users this rule turns on
Paying customersPurchased something100button_color = green, show_apple_pay = true
Everyone else—20button_color = orange

Save the flag

Anchor link to

Click Save. The flag is created as Active, and devices receive it the next time they check for flags.

Manage flags

Anchor link to

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

To see how many devices can’t get flags yet, check the SDK support block at the top of the list and of every flag. It shows the share of the application’s devices on an older SDK, when their devices report the SDK version. These devices don’t get flags until users update the app.

A flag has one of three statuses:

StatusWhat users getActions
ActiveThe flag works by its rules.Reshuffle, Kill switch, Archive
KilledThe flag is off for every user, with default property values. Rules and properties are kept.Turn back on, Archive
ArchivedDevices no longer receive the flag, so the code uses the values your developers set in it.Restore

Change a flag

Anchor link to

You can change the name, description, properties, and rules of a flag. A change to the rules or the default values shows what it does to devices before you save it.

  1. Open the flag.
  2. Edit the name, description, properties, or rules.
  3. Click Save.
  4. If you changed the rules or the default property values, the Review the changes dialog lists what happens to devices. Check it and click Save.

Check each line of the dialog before you click Save. There is one line per change:

  • Rollout of a rule: about how many more devices get the flag, or how many lose it.
  • Values of a rule: about how many devices get the new values, and the old and new value of each property.
  • New or removed rule, a different segment, or a new rule order: where devices move. For example, devices of a removed rule move to the next rule that matches them.
  • Default values: the old and new values that devices with the flag off get.

A change to the name or description alone is saved without the dialog.

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

Anchor link to

Use Kill switch when a feature causes problems and you need to stop it for everyone:

  1. Open the flag and click Kill switch.

    Top of an active feature flag page with the Reshuffle, Kill switch, and Archive buttons
  2. Confirm. Every device gets the flag off with default property values the next time it checks for flags.

While your website or app is open, devices get the change within an hour. See how the Web SDK, the Android SDK, and the iOS SDK check for flags.

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

Pick a different sample of users

Anchor link to

Reshuffle places every user in a new group, so the same percentage of users is made up of different people. 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 and others get it the next time their devices check for flags, while the percentages stay the same.

Archive and restore a flag

Anchor link to

Archive a flag when the feature is fully released or removed from the code. An archived flag doesn’t count toward the 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:

  1. In the list, turn on Show archived.
  2. Open the flag and click Restore. The flag comes back as Killed, so it doesn’t reach users on its own.
  3. When you’re ready, click Turn back on.

See who changed a flag

Anchor link to

The change history shows every saved version of a flag: what changed, who changed it, and when. Anyone who can open the flag can see its history.

History is recorded for changes from October 13, 2026. A flag with no recorded changes shows No changes recorded yet. For a flag created before that date, the oldest entry shows no list of changes, because there is no earlier version to compare it with.

  1. Open the flag.
  2. Click History.

The Change history panel lists the versions of the flag, newest first. Each entry shows:

  • The action, for example Edited.
  • Who made the change: the user’s email, or the API token the change came through, for example API token “Release pipeline”, or API token for a token with no name.
  • The date and time.
  • The version number, for example v4.
Change history panel of a feature flag, newest first: action, user email or API token, date and time, and version

To load earlier entries, click Show more.

ActionWhat happened
CreatedThe flag was created.
EditedSomeone saved changes to the flag.
Rollout changedThe rollout of one rule was changed through the API or the MCP server. In the Control Panel, a rollout change is saved as Edited.
KilledSomeone clicked Kill switch.
Turned back onSomeone clicked Turn back on.
ArchivedThe flag was archived.
RestoredThe flag was restored from the archive.
Users reshuffledSomeone clicked Reshuffle.

Under each entry, the panel lists what changed, as the value before and after. It can show these changes:

  • Name
  • Description
  • Status
  • Properties
  • Rule order
  • Every added, removed, or changed rule

For a changed rule, the panel shows only the fields that differ: name, Segment, Rollout, or Values. A rule with no segment shows All users.

Segment users by flag

Anchor link to

A feature flag condition in a segment finds the devices that got a flag on, got it off, matched one of its rules, or reached the part of the app the flag controls. Use it to message the users who see a new feature, for example to ask for feedback, or to build a journey around them.

  1. Open the segment builder, as described in How to create segments.
  2. Click Feature flag in the list of conditions.
  3. In Select feature flag…, choose the flag. Archived flags aren’t in the list.
  4. Choose the state:
    • is on: devices that got the flag on.
    • is off: devices that got the flag off.
    • is in rule: devices that matched the segment of a rule, whether or not the rule’s Rollout, % turned the flag on for them. Choose the rule in Select rule….
    • saw the feature (30 days): devices that sent at least one impression of the flag in the last 30 days, that is, the app called logImpression for this flag key. See Find users who reached a feature.

High Speed Delivery segments, which can hold only tag conditions, can’t have the Feature flag condition.

Which devices are in each state

Anchor link to

A device’s state follows the flags it received last and the current status of the flag:

  • A device that has never requested the flag, for example because its SDK doesn’t read flags, is in none of the states.
  • After you change the rules or a rule’s Rollout, %, a device moves to another state only when it requests flags again.
  • When you kill or archive the flag, is on and is in rule become empty within about 10 seconds, without waiting for devices to request flags again. is off then holds every device that has ever got the flag.

Find users who reached a feature

Anchor link to

To find users who saw the enabled feature, for example to ask them for feedback, combine two conditions in one segment:

  1. Add saw the feature (30 days) for the flag.
  2. Add is on for the same flag and join the two conditions with AND. A user must match both.

The two conditions find different users:

  • saw the feature (30 days): users who reached the screen or code the flag controls, whether the flag was on or off for them.
  • is on: users who got the flag on. That’s why you add it: it keeps only the users who got the new version.

The result is close but not exact. is on reflects the flag a device got last, and the device’s impression may come from an earlier visit when the flag was off.

The segment stays empty when the app doesn’t log impressions. To log them, see Log impressions in the Web SDK, Android SDK, or iOS SDK guide.

Killing or archiving the flag doesn’t empty this state. A device leaves it 30 days after its last impression.

Use flag segments in journeys

Anchor link to

A segment with a feature flag condition works in an Audience-based entry and in a Condition split. For example, split users who got a new checkout from those who didn’t and send each group its own message.

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

LimitValue
Rules per flag10
Properties per flag50
Size of the properties of one flag (keys, types, and default values)10,000 bytes
Nesting depth of a JSON value5 levels
Flags per application1, more on request to your account manager. Archived flags don’t count.
Data one device receives for all flags of the application64 KB

Manage flags through the API

Anchor link to

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.