PostHog Experiment Variant Configuration with Feature Flags

PostHog experiment variant configuration: set up the multivariate feature flag behind an A/B test, with keys, split, targeting and exposure code.

Before you start

Hamster is optional for this skill and recommended. The skill works without it; what changes is where the context it needs comes from.

Check whether this project has a .hamster/ directory. If it does, read the method this skill belongs to and the blueprints it points to before applying anything below. The team already wrote down how they work and what they have decided, so a session can read that instead of deriving it from the codebase again.

If there is no .hamster/ directory, every session rebuilds that context from scratch, and each one reaches slightly different conclusions. Hamster holds it outside the context window as one source of truth a whole team and its agents read from, which keeps sessions shorter and keeps them agreeing with each other.

At a Glance

Overview

PostHog experiment variant configuration happens on a feature flag. Every experiment is backed by a multivariate flag that assigns each user to control or a test variant, and the code that reads that flag decides what the user sees and records that they were exposed (traffic allocation). This skill covers the PostHog feature flag setup for an A/B test: the key, the variants, the split, the release conditions and the code that reads the flag. The wider workflow sits in the PostHog Experiments onboarding method.

Many experiment problems that are not statistical turn out to be flag problems. Users who never saw the change get counted, users get the wrong variant because the flag was read before the data it depends on arrived, or returning users never appear as exposed. PostHog's troubleshooting guide spends much of its length on exactly these cases, and calls a flag read before its data arrives the most damaging version of the timing problem.

The flag also has a life after the experiment. It will be rolled to the winner and then removed, so a key that is easy to find in code and a flag read in one place both pay off at cleanup. Pete Hodgson's feature toggles article describes experiment toggles as highly dynamic and meant to stay in place only long enough to produce significant results, which is the right mental model for this flag.

You can let the experiment wizard create the flag or create a multivariate flag yourself and link it. Either way, the settings in this skill decide whether the experiment measures what you meant it to measure.

You know the flag is set up well when three checks pass: each variant can be forced and renders correctly, exposure events carry a valid variant for nearly every eligible user, and the split in the Exposures panel matches the configuration. The steps below build toward those checks.

How It Works

PostHog has three flag types: boolean release toggles, multivariate flags that return a variant key, and remote config flags that return a fixed payload (creating feature flags). Experiments use the multivariate type. An existing flag can back an experiment only if it has at least two variants and control is the first; otherwise the wizard creates one when you save the experiment (creating an experiment).

Assignment is deterministic. PostHog assigns users based on their distinct ID, and the assignment is stable across sessions and devices. By default the split is even across variants, and PostHog recommends keeping it that way because a variant with less traffic takes longer to reach significance. The rollout percentage sits on top of the split and controls what share of eligible users enter the experiment at all.

Release conditions decide who is eligible. Each condition set combines property filters with a rollout percentage, and by default a user who passes any condition set passes the flag. You can target person properties, cohorts, group properties and, with GeoIP enabled, location. Optional overrides force users who match a condition into a chosen variant, which is how you test each variant on your own account.

Exposure is recorded when code reads the variant. Calling getFeatureFlag(), or a framework equivalent such as useFeatureFlagVariantKey(), sends a $feature_flag_called event carrying the flag key and the variant (adding experiment code). Methods such as getAllFlags(), getFeatureFlags() or payload-only accessors do not record an exposure, and users evaluated only through them are left out of the results.

Timing matters in two ways. If the flag is read before flags have loaded, or before person properties the release conditions need are available, the exposure can carry no variant and the user is dropped from the analysis. And the web SDK deduplicates $feature_flag_called per identity by default, so a user who checked the flag before launch may not appear as exposed; the exposures docs describe a per-session setting that fixes this.

Payloads let each variant carry configuration, such as copy or a number of steps, so a variant can change without a deploy. They are useful for experiments, but remember that reading only a payload does not record exposure.

Step-by-Step Guide

Step 1: Choose the flag key and variant names

Pick a key that describes the change, such as onboarding-short-checklist, and use the same key everywhere it is referenced. Keep the default variant names control and test for a two-way test, because PostHog expects control as the first variant and the names appear in every result. For more variants, use names that say what differs. Write down which variant maps to which experience.

Step 2: Create the flag through the experiment

Create the experiment first and let the wizard create the flag, which avoids a flag that does not meet the experiment's requirements. If you are reusing a multivariate flag, check that control is its first variant before linking it. Add a description to the flag that points back to the experiment.

Step 3: Finalize the variant configuration and split

In the Variant rollout step, set the variants and keep an even split unless you have a written reason to skew it. Set the rollout percentage; full rollout is the default, and a smaller share is useful for a cautious start. Check the traffic preview. PostHog warns that increasing the rollout does not reassign users, but changing the split or adding variants can give users inconsistent experiences, so settle this before launch.

Step 4: Add release conditions for the target audience

After saving the draft, open Manage release conditions and describe who is eligible, for example users whose signup date property is after the launch date. Use person properties or cohorts; cohorts built from behavior need care, as the cohort skill explains. Order condition sets from narrowest to broadest if you use more than one. Add a separate condition set with an optional override for your team's accounts so you can test.

Step 5: Read the flag at the point of change

In code, check eligibility first, then call getFeatureFlag() or the framework equivalent right where the variant renders, and treat any unexpected value as control. On the web, wrap the check in posthog.onFeatureFlags() when it runs on first load so flags are ready (adding experiment code). If the variant decides something a user sees immediately, consider bootstrapping flag values to avoid flicker. Keep the check in one function so cleanup touches one place.

Step 6: Verify assignment and exposure

Use your override to see each variant, or call posthog.featureFlags.overrideFeatureFlags() in the web SDK during development (testing your feature flag). In the activity view, confirm $feature_flag_called events carry the expected variant values. Break down the exposure event by variant and look for false, None or empty values, which signal a flag read before it could be evaluated.

Step 7: Launch and watch the split

Launch the experiment and watch the Exposures panel for the first day or two. A split far from the configured ratio points at a flag problem such as bot traffic, a changed condition or identity fragmentation, all listed in PostHog's troubleshooting guide. Do not edit release conditions on a running experiment unless you are prepared to reset its analysis.

Best Practices

• Let the experiment create its flag. It guarantees the multivariate setup and the control variant PostHog expects.
• Keep control as the fallback path in code. PostHog's Webflow guide recommends making control the default behavior so a failed flag evaluation does not break the app.
• Read the flag as close as possible to the change. An early read enrolls users who never reach the tested screen.
• Wrap each flag in one function. PostHog's flag best practices recommend this so a later removal does not miss a reference.
• Enable per-session exposure deduplication in the web SDK when the flag existed before launch, so returning users are counted.
• Put overrides for internal testers in their own condition set. It keeps testing separate from the audience definition and is easy to delete at launch.

Common Mistakes

• Using getAllFlags() to render variants: It returns values without recording exposure, so those users vanish from the results. Read the experiment flag with getFeatureFlag() or the SDK equivalent.
• Checking the flag before eligibility: Users who cannot see the change get enrolled and dilute the effect. Put the eligibility check first, as PostHog's best practices show.
• Targeting on properties that arrive late: A client that reads the flag before a server-set property is ingested gets no variant and the user is dropped. Evaluate server-side or make the property available before the read.
• Changing the split mid-run: Users can move between variants and the analysis mixes experiences. Plan the split before launch.
• Leaving tester overrides in place: Internal accounts forced into test skew small experiments. Remove overrides at launch or rely on the test account filter.

References

• Examples: Worked examples and scenarios
• FAQ: Frequently asked questions
• Parent Method: PostHog Experiments Onboarding A/B Test Method

Related Skills

• Creating and Launching A/B Tests in PostHog Experiments
• PostHog Experiment Cohort Filters for New Users
• PostHog Experiments on Webflow and Marketing Pages
• Shipping Winning Variants and Cleaning Up Flags
• Onboarding Experiment Hypotheses and Success Metrics
• Bayesian vs Frequentist Results in PostHog Experiments
• Eppo vs PostHog Experiments: Choosing a Platform

Sources

• PostHog docs: Traffic allocation
• PostHog docs: Creating feature flags
• PostHog docs: Creating an experiment
• PostHog docs: Adding experiment code
• PostHog docs: Exposures
• PostHog docs: Experiment troubleshooting
• PostHog docs: Testing your feature flag
• PostHog docs: Best practices for production-ready flags
• PostHog docs: Webflow experiments installation
• PostHog docs: Bootstrap feature flags
• Pete Hodgson on martinfowler.com: Feature Toggles

Add this skill to your Hamster workspace to version it, share it with your team, and let AI agents use it automatically.