The six methods.

An Exposure is the “this subject saw this Variant” event that experiment analysis counts. Which methods fire one is the core thing to get right: an Exposure recorded outside the real user path inflates the denominator and biases the result.

• evaluate or evaluateDetails on the real user path. These are the calls that belong in production request handling; reach for evaluateDetails when the handler needs ResolutionDetails.
• peekVariant to inspect a resolution without polluting experiment data: admin screens, support tooling, debugging.
• verify to confirm setup end to end. Same shape as evaluateDetails, no Exposure, safe to run repeatedly in CI.
• evaluateAll to render a whole page from one request. Each fresh assignment under a live Run carries an Exposure Ticket that a client redeems when it actually reads that Flag, so a page holding 20 Flags and showing 3 records 3 Exposures.
• track to append the Metric Event an experiment measures. It is the other half of the pair: Exposures are the denominator, Metric Events are the numerator.

Reading ResolutionDetails

evaluateDetails and verify return the reason the value was chosen, not just the value. Branch on reason when you need to distinguish a real resolution from a fallback.

const details = await splitch.evaluateDetails("new-checkout", {
  targetingKey: user.id,
  defaultValue: false,
});

if (details.reason === "ERROR") {
  // details.value is your defaultValue, and details.errorCode says why.
  // Every code is documented at https://splitch.dev/docs/error/{code}
}

Recording a Metric Event

track appends one Metric Event against an Event Definition you declared beforehand. You own the eventId and reuse it when retrying, exactly as idempotencyKey works for evaluation; a replay comes back with duplicate: true and appends nothing.

const result = await splitch.track("checkout_completed", {
  targetingKey: user.id,
  idType: "user",
  eventId: crypto.randomUUID(),
  fields: { revenue: 42.5 },
  dimensions: { plan: "pro" },
});

result.duplicate; // true when this eventId was already appended

Unlike evaluate, track has no Default Variant to fall back to, so it throws SplitchSdkError on rejection rather than returning a partial result. An undeclared eventName, a payload that fails the Event Definition, or a credential without data-plane:write all surface as a throw naming the code.