Creating and Publishing a Feature Flag

A flag starts as a draft. Nothing reaches visitors until you publish it, so you can create it, set it up and come back later.

Create the flag

In the sidebar, open Feature flags and click Create flag. The dialog asks for these, in order:

1. 1How it runs: Editor or Code. This is fixed once the flag exists. Editor means "Change the site with the visual editor". Code means "Your code asks for it, through the SDK, the browser or HTTP". See What Is a Feature Flag? for how the two differ.
2. 2Name: up to 256 characters. You can rename a flag later from its page.
3. 3Flag key: the name your code asks for the flag by. It cannot change later.
4. 4Description: what it is for. It shows on the flag's Brief tab.
5. 5Sides: Off and On. Off is added automatically and carries the chip "default": it is your site or code as it is today, and everyone outside the rollout gets it. On is the changes you make in the visual editor, or your new code path, for the share you roll out to.

A code flag asks for two more things:

• A Payload for each side: optional JSON, such as { "color": "blue" }, that your code receives with the side. Payloads are set here and fixed after creation. Anyone who opens your site's script can read them, so never put a secret, an unreleased price or anything private in a payload.
• Bucket on: Visitor ID or Customer ID. A visitor ID flag gives each browser its side. A customer ID flag gives the same signed-in customer the same side on every device, and needs your server to pass the customer's ID. This is fixed after creation too. See Attribute Rules and Bucketing on a Customer ID.

Flag key rules

A key is lowercase letters, digits and hyphens, starting with a letter or digit, and at most 64 characters. new-checkout and menu-v2 are keys. New Checkout is not.

A key is unique per website, across flags and experiments alike. If one is taken you will see "Another flag or experiment on this website already uses the key", with the key named. Pick a key you are happy to keep: it cannot change once the flag exists, and your code will refer to it.

Before you publish

A draft can be set up in full, and some settings can only be set while it is a draft.

• Holdback can only be set before publishing. If you want a share kept Off for comparison at every step, set it on the Rollout tab now.
• Rollout and Rollout plan can be set on a draft. Both apply when you publish.
• Primary goal, on the Setup tab, is the event the guardrail judges On and Off on. It is fixed once the flag is live, so choose it now if any plan step will wait on the guardrail.
• A code flag needs the website's visitor ID turned on. Publishing without it is refused with "This flag needs the website visitor ID: turn it on in the website settings before publishing". See Anonymous Visitor ID.
• An editor flag needs its changes made in the visual editor before there is anything for On to show. See Quick Fixes with Editor Flags.
• A code flag needs your code to ask for it. The Setup tab shows snippets for the SDK, the browser and HTTP, filled in with the flag's key and website.

See Rolling Out a Feature Flag for the rollout, the plan, holdback and schedules, and Feature Flag Guardrails for the primary goal.

Publish

Publish is the main action at the top of a draft's page. What happens depends on the kind of flag and whether it has a plan:

• With a rollout plan, the flag goes live at the plan's first step and the plan starts.
• An editor flag without a plan goes live for everyone, at 100%, unless you set a rollout before publishing.
• A code flag without a plan goes live at the rollout you gave it, which is 0% by default. It ships dark: your code is live, but nobody gets On until you raise the rollout.

You can also publish at a set time with Publish at on the Schedule card. A draft whose scheduled turn-off time has already passed cannot be published: "The scheduled turn-off time has passed. Clear or move it before publishing."

How fast it reaches visitors

• On your pages, the website's script is rebuilt at once and served uncached, so the next page load sees the change.
• On your servers, the SDK sees the change within about 45 seconds.
• The scheduler that moves plans and runs scheduled publishes runs every minute, and the guardrail checks every five minutes.

After publishing

The status card under the flag's name says Live, the share who get On, where the plan is and what comes next. The Activity tab records the publish with your name. From here, the main action at the top of the page becomes Turn off. See Turning Off, Archiving and Deleting a Feature Flag.

If someone else changes the flag while you are editing it, saving is refused with "The flag changed while you were editing. Reload it and try again." Reload the page and make your change again.