← Blog

Feature flag audience targeting without a customer list

Feature flag audience targeting is picking which users see a variant based on an attribute like plan, locale, or device, not based on who they are by name. Most tools do this by letting you upload or sync a customer list; dif does it by declaring an attribute and resolving its value at runtime, so no list of users ever gets stored or committed anywhere.

The common failure looks like this: someone needs to turn a feature on for the ten enterprise accounts in the beta, so they hardcode an array of emails at the call site, or they drop a CSV of customer IDs into the repo to drive the check. Six months later that file is still there, it is stale, and it is sitting in git history where it cannot be quietly removed.

This post covers what feature flag audience targeting means, why a customer list tends to end up in the codebase in the first place, and how to target an audience by attribute so no list has to exist at all.

Key Takeaways

  • Feature flag audience targeting in dif is three pieces: a declared attribute in dif/config.yaml, a TypeScript resolver function, and an include/exclude predicate in the experiment file. No customer list is stored anywhere.
  • A resolver computes an attribute (plan, device_type, locale) at runtime and returns null to fail closed, so a stale or missing value excludes the user instead of leaking into production.
  • The predicate grammar is deliberately small: equality for a scalar value, membership for a list. No regex, no numeric ranges, no operator sprawl.
  • dif validate catches an undeclared attribute (E006) or a missing resolver (E008) before the targeting logic ships, the same way a broken build fails CI.
  • The tradeoff: there is no admin UI to paste in one customer’s ID for a quick override. Every targeting change goes through a resolver and a pull request.

What feature flag audience targeting means

Audience targeting decides which users are eligible for a flag or an experiment before bucketing even runs. A targeting rule reads an attribute, like device_type: mobile or plan: enterprise, and includes or excludes the user based on it. This is different from the split itself: targeting narrows the pool, and the variant weights decide who in that pool gets what.

The attribute is the important part. “Target mobile users” is an attribute check against a value computed at request time. “Target these forty customer IDs” needs a list, and the moment targeting needs a list instead of an attribute, something has to store it: a dashboard, a database, or, worse, a file in the repo.

Why a customer list ends up in the repo

The list shows up because the actual need was never “target an attribute,” it was “let these specific ten people in.” Nobody sits down to design a targeting system for that. They write:

const BETA_USERS = ["ada@acme.com", "sam@acme.com", "priya@acme.com"];

if (BETA_USERS.includes(user.email)) {
  return <NewDashboard />;
}

It works, so it ships. The list grows as more customers join the beta, it is now personal data sitting in source control, and removing it later is harder than it looks. Git does not forget: deleting the file in a new commit leaves the emails in every prior commit’s history, and scrubbing them out means rewriting history on a shared branch. GitHub’s own guide to removing sensitive data from a repository is effectively a guide to undoing this exact mistake, and it is not a quick fix.

The dashboard version of the same problem is a CSV upload: paste a list of customer IDs into a targeting rule, and now a vendor is holding your customer list too, disconnected from the code that reads it. Either way, the targeting logic depends on data about specific people instead of a property those people happen to have.

Targeting an audience without storing one

dif’s answer is to make “who” always resolve from “what attribute,” never from a stored list. An attribute is usable in a targeting predicate only if three things exist, checked by dif validate:

  1. A declared attribute in dif/config.yaml:
audience_attributes:
  - name: plan
    type: enum
    values: [free, pro, enterprise]
  - name: device_type
    type: enum
    values: [mobile, tablet, desktop]
  1. A resolver in dif/audiences/plan.ts that computes the value at runtime, with no persisted assignment:
export default function resolve(): string | null {
  if (typeof window === "undefined") return null;
  return window.__SESSION__?.plan ?? null;
}
  1. A predicate in the experiment’s frontmatter that references the attribute by name.

Nothing in that contract names a customer. plan resolves from the current session every time the SDK needs it, the same way it would for any other user on any other request. No file anywhere says who is on the enterprise plan. A function answers that question each time it is asked.

dif scaffold-audiences writes the starter resolver files for you, so turning on a new attribute does not start from a blank file.

Writing the predicate: include, exclude, and two operators

The targeting rule itself lives in the experiment’s frontmatter, next to the variant split:

audience:
  include:
    - plan: [enterprise]
    - device_type: [desktop]
  exclude:
    - locale: [fr-FR]

include lists must all match; exclude lists must all fail to match. Inside each list, a scalar value is equality (locale: en-US) and a list of values is membership (device_type: [mobile, tablet]). That is the entire grammar: no <, >, regex, or negation operators. Negation is handled structurally by putting the attribute in exclude instead of inventing a not keyword.

This reads as a PM would describe it out loud (“enterprise accounts, on desktop, not in France”) and it still reviews like code, because it is code, sitting in the same pull request as the feature it gates.

What dif validate catches before it ships

A targeting predicate is only as good as the attributes behind it, so the validator checks all three pieces line up:

  • An attribute declared in config.yaml with no matching resolver file fails as E008.
  • A resolver file that exists but was never declared fails as W002, a warning rather than a hard stop.
  • A predicate that references a name not declared anywhere fails as E006.

Any of these fails the pull request in CI, the same way a broken build does, so a targeting typo gets caught by a reviewer before it ever reaches production.

Resolvers are expected to fail closed. If resolve() returns null, every predicate referencing that attribute evaluates to false and the user is excluded. That is what makes server-side rendering safe: the resolver returns null during the server render before session data is available, the targeted experiment is skipped, no exposure event fires, and the control branch renders. Nobody sees a half-targeted flicker.

The tradeoff: no admin UI for a one-off override

What this model costs you is the quick exception. A dashboard tool lets someone paste one customer’s user ID into a targeting rule and flip a flag on for them in thirty seconds, no deploy. In dif, every targeting change is an edit to a resolver or a predicate, reviewed in a pull request, and shipped the normal way.

For a genuine one-off, comping a feature for a single escalated support ticket, that is slower than it needs to be. For the far more common case, targeting ten enterprise accounts or every mobile user outside France, the tradeoff runs the other way: the rule is reviewable and versioned, and it never needed anyone’s name.

FAQ

What is feature flag audience targeting? It is restricting a flag or experiment to users who match a condition, like device type, plan, or locale, before the flag’s split decides their variant. Targeting narrows who is eligible; the variant weights decide what eligible users get.

Can you target a feature flag by user segment without storing a customer list? Yes. Declare the segment as an attribute (plan: enterprise, country: [BR, AR]) and compute it from live session data with a resolver function instead of a stored list of IDs. The targeting rule names a property, not a person.

Why shouldn’t you commit customer data to target a feature flag? Because git never really deletes it. A file removed in a later commit is still readable in the repo’s history, so a hardcoded list of emails or customer IDs becomes close to permanent. Martin Fowler’s writeup on feature toggles treats flags as inventory you want to keep small and clean; a customer list baked into one works against that from day one.

How is this different from LaunchDarkly’s targeting rules? LaunchDarkly’s targeting model supports rules against individually targeted users and uploaded lists in its dashboard, which is exactly the convenience a one-off override needs. dif has no equivalent list upload; every targeting rule is an attribute resolved at runtime and reviewed in a pull request, which trades the instant one-off for a rule that never needs anyone’s identity.

Does audience targeting work with server-side rendering? Yes. A resolver that returns null during server render excludes the user from any targeting rule that references it, so the control variant renders and no exposure event fires. The targeted experiment never half-applies.

Getting started

Feature flag audience targeting works best as a question about a property the user has, not a lookup against a list of who they are. Declare the attribute, write the resolver, reference it in a predicate, and let dif validate prove the three line up before it ships.

npm install -g @dif.sh/cli
dif init
dif scaffold-audiences

That scaffolds a working dif/audiences/ directory with no account, no API key, and no list to maintain. From there, see the docs for the full install and quickstart, the .md format for the complete frontmatter reference, and feature flags in git for how targeting rules like these travel through a normal pull request. The feature flags page covers the rest of the workflow.