Targeting and targets

Targeting is how Fireweave decides which value a control point returns for a given identity. A target is that identity — a user or device keyed by targetingKey — optionally carrying durable properties stored by fw-server. You own the ID. The SDK never auto-generates one. The wire still says flagKey for the control point. Identity on that call is always targetingKey.

Why it exists

Percentage assignment hashes on targetingKey. If the key changes every request, users flip variants. Registration exists so durable facts (plan, region, device model) do not have to ride on every evaluate.

When to use it

Situation	What to pass as `targetingKey`
Logged-in user	Your durable user ID (`user_42`)
Org-level assignment	The org ID (`org_123`) so the whole org flips together
Anonymous visitor	An ID you generate once, persist (cookie / session), and reuse
Batch / worker	A stable job- or tenant-scoped ID, not a per-run UUID

user, org, plan, and region are not reserved SDK fields. kind on register is 'user' or 'device'. plan and region appear in examples as property names you may send — you choose the keys.

Do not mint a fresh UUID per request. Do not use request IDs or timestamps. Prefer opaque IDs over email addresses. The SDK forwards the key verbatim and does not hash or rotate it.A constant targeting key hashes every caller into one bucket. That makes a percentage ramp meaningless while looking healthy — so it must be your decision, visibly.

How it relates

Concept	Relation
Control points	Same `targetingKey` on evaluate selects the Decision
Adapters	Remote posts `POST /v1/targets/register`. Local records in-process and traces. InMemory does not persist registration
Cohort	Not an SDK type. “Cohort key” in the console is `targetingKey`

Identity rules

Never auto-generated. A missing targeting key is InvalidContext where the evaluation needs it, never a generated anonymous id.
requireTargetingKey defaults to false on the runtime config where the language exposes it. Set it true if you want keyless calls rejected even in tests.

Node
Python
Go
Java

new FireweaveRuntime(adapter, { requireTargetingKey: true });

FireweaveRuntime(adapter, require_targeting_key=True)

fireweave.NewRuntime(adapter, fireweave.Config{RequireTargetingKey: true})

FireweaveConfig.builder().requireTargetingKey(true).build();

In-memory evaluation of unconditional fixtures may succeed without a key unless you opt into that strictness.

Two identity paths

These compose; they do not compete.

registerTarget — durable properties stored by fw-server (POST /v1/targets/register). Call once per login or device provisioning.
Per-evaluate attributes — win for that call. Use for request-only facts.

There is no merge step in the SDK. fw-server resolves them: evaluate attributes win; stored target properties fill in everything not sent. A rule that targets a property the app never registers and never sends matches nobody, silently. $-prefixed attributes are backend system directives, not person properties. fw_-prefixed target property keys are reserved and stripped server-side.

Registration in every language

registerTarget exists on all seven SDKs. It never throws — it runs in sign-in paths, where a targeting concern must not break authentication. Check ok. A silently unregistered target is how targeting rules end up matching nobody.

Mode	What happens
`remote`	`POST /v1/targets/register`. One retry when the error kind is retryable (network / timeout / backend). Auth and invalid-payload failures are not retried
`local`	Recorded in-process and traced. Returns `{ ok: true }`. Nothing is sent. The log line is `[fireweave:local]` — seeing that in a production log means something booted in local mode by mistake
In-memory	Does not persist registration. Degrades with `UnsupportedCapability`

The recorded local set is readable (getRegisteredTargets / language equivalent) so tests can assert registration without capturing stdout. The log sink is injectable. The protocol test server implements evaluate, capture, and /health. It does not implement POST /v1/targets/register. Register tests use local mode, mocks, or an injected fetch. Web and Swift also expose identify: register the target, then re-prefetch under that id so percentage ramps bucket on a stable key.

What it looks like

const result = await fireweave.registerTarget('user_42', {
  kind: 'user',
  properties: { plan: 'pro', region: 'eu-west' },
});
if (!result.ok) {
  // Log it — a silent miss means targeting rules match nobody
}

const on = await fireweave.controlPoints.getBooleanValue(
  'new-checkout',
  false,
  { targetingKey: 'user_42' },
);

await fireweave.identify('user_42', {
  kind: 'user',
  properties: { plan: 'pro' },
});

const on = fireweave.controlPoints.getBooleanValue('new-checkout', false);

from fireweave import EvaluationContext, RegisterTargetOptions

client.register_target(
    "user_42", RegisterTargetOptions(kind="user", properties={"plan": "pro"})
)

on = client.control_points.get_boolean_value(
    "new-checkout", False, EvaluationContext("user_42")
)

result := client.RegisterTarget("user_42", &fireweave.RegisterTargetOptions{
    Kind:       fireweave.TargetKindUser,
    Properties: map[string]any{"plan": "pro"},
})
_ = result.OK

evalCtx := fireweave.NewEvaluationContext("user_42", map[string]any{"plan": "pro"})
on := client.ControlPoints().GetBooleanValue("new-checkout", false, &evalCtx)

client.registerTarget("user_42", RegisterTargetOptions.builder()
    .kind(TargetKind.USER)
    .property("plan", JsonValue.of("pro"))
    .build()); // never throws; check result.ok()

boolean on = client.controlPoints().getBooleanValue(
    "new-checkout",
    false,
    EvaluationContext.builder().targetingKey("user_42").build());

use fireweave::RegisterTargetOptions;

let properties = serde_json::json!({ "plan": "pro" }).as_object().unwrap().clone();
client.register_target(
    "user_42",
    Some(&RegisterTargetOptions { properties: Some(properties), ..Default::default() }),
);

let ctx = EvaluationContext::new().with_targeting_key("user_42");
let enabled = client.control_points.get_boolean_value("new-checkout", false, Some(&ctx));

let result = await client.identify("user_42")
let on = client.controlPoints.getBooleanValue("new-checkout", default: false)

Groups

Group membership and group properties travel on the evaluation context. Canonical keys: fireweave.groups and fireweave.groupProperties. Plain groups / groupProperties are accepted aliases; canonical keys win if both are present. Any other fireweave.* context key is rejected with InvalidContext. targetingKey and kind are also reserved in the evaluation context.

await fireweave.controlPoints.getBooleanValue('org-flag', false, {
  targetingKey: 'user_42',
  'fireweave.groups': { company: 'org_123' },
  'fireweave.groupProperties': { company: { plan: 'enterprise' } },
});

Privacy

The SDK adds no person properties of its own. Whatever you put on the context is forwarded to fw-server.
Prefer derived attributes (email_domain) over raw PII if you must target on identity-adjacent facts.
Error messages are secret-redacted and must not echo attribute values.
Nothing is persisted to disk by the SDK.

Control points — evaluate with this identity
Adapters — remote vs local vs in-memory registration
Testing — InMemory does not persist registration; local mode does

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

Targeting and targets

Why it exists

When to use it

How it relates

Identity rules

Two identity paths

Registration in every language

What it looks like

Groups

Privacy

​Why it exists

​When to use it

​How it relates

​Identity rules

​Two identity paths

​Registration in every language

​What it looks like

​Groups

​Privacy

​Related

Why it exists

When to use it

How it relates

Identity rules

Two identity paths

Registration in every language

What it looks like

Groups

Privacy

Related