Feature Flags

The browser SDK loads your project’s flags for the visitor it already tracks and reads them synchronously from memory. There is nothing to list up front: add the extension and read any flag by key.

Enable FlagsCopy Anchor Link

Add the featureFlags() extension next to your other extensions.

Copy Text
"use client";

import { Analytics } from "@faststats/react";
import { featureFlags } from "@faststats/react/flags";

const flags = featureFlags();

export function FastStats() {
	return <Analytics siteKey="your_site_key" extensions={[flags]} />;
}

Create the extension once, at module scope, so every part of the app reads the same instance.

Read FlagsCopy Anchor Link

Every read takes the flag key and a default. The default is served until flags have loaded, and whenever the flag is missing, archived, or has a different type than the default.

Copy Text
import { useFlag } from "@faststats/react/flags";

export function Checkout() {
	const newCheckout = useFlag("new-checkout", false);
	const maxUploads = useFlag("max-uploads", 10);

	return newCheckout ? <NewCheckout limit={maxUploads} /> : <OldCheckout />;
}

reason explains the result: rule_match, target_match, fallthrough, disabled, or prerequisite_failed. In React, useFeatureFlags() returns the running instance for status, details(), setContext(), and reload().

ExposuresCopy Anchor Link

A flag counts as exposed the first time your code reads a served value for a visitor, not when it loads. The exposure numbers on a flag’s dashboard page, its evaluation log, and per-variant breakdowns in insights all come from these reads, so they show the people who actually saw a variant.

• Only the first read of each flag and variant is reported per visitor.
• Reads close together are sent in one small request, and anything left is sent when the page is hidden.
• Reading a default, while loading or for a missing flag, is not an exposure.

Read a flag where you branch on it, not ahead of time, so exposures match what people see.

TargetingCopy Anchor Link

Flags are evaluated for the anonymous visitor ID, and the session ID links each evaluation to analytics. The service also derives browser, browser_version, os, os_version, device, and country from the request.

Pass anything else your targeting rules match on as attributes:

Copy Text
const flags = featureFlags({
	attributes: { plan: "pro", beta: true },
});

// Later, for example after the user upgrades. Replaces the previous attributes.
await flags.setContext({ attributes: { plan: "enterprise" } });

Signed-in UsersCopy Anchor Link

identify() re-evaluates flags for that user, so percentage rollouts follow the user across devices. logout() goes back to a new anonymous visitor. While flags reload for a new user, reads serve their defaults rather than the previous user’s values.

When the user is already known at startup, pass userId to skip the anonymous load:

Copy Text
const flags = featureFlags({ userId: session.user.id });

Consent and Cookieless ModeCopy Anchor Link

Flags are not loaded while consent is "denied". Revoking consent clears loaded values and drops exposures that were not sent yet. A cookieless visitor has no lasting ID, so rollouts hold for the session only.

OptionsCopy Anchor Link

flags only limits what is loaded. Exposures are recorded for reads either way.