diff --git a/docs/reference/concepts/07-tracking.mdx b/docs/reference/concepts/07-tracking.mdx index 468c68fbc..db717c505 100644 --- a/docs/reference/concepts/07-tracking.mdx +++ b/docs/reference/concepts/07-tracking.mdx @@ -109,3 +109,135 @@ client.Track( + +## Experimentation-Focused Example + +Here is a complete A/B testing flow using OpenFeature. +The pattern is: evaluate a flag to assign the user to a variant, show the corresponding experience, then call `track` when the conversion event occurs. +The provider automatically links the tracking event back to the flag evaluation context (including the `targetingKey`), so your analytics platform can segment results by variant. + + + +```ts +import { OpenFeature } from '@openfeature/server-sdk'; + +// Set evaluation context with the user's targeting key. +// The targeting key is how your provider buckets users into variants consistently. +OpenFeature.setContext({ + targetingKey: 'user-123', +}); + +const client = OpenFeature.getClient(); + +// Evaluate the experiment flag — provider returns true (variant) or false (control) +const useNewCheckout = await client.getBooleanValue('checkout-experiment', false); + +if (useNewCheckout) { + // Show the new checkout UI (variant group) + await showNewCheckout(); +} else { + // Show the existing checkout UI (control group) + await showExistingCheckout(); +} + +// When the user completes the purchase, emit a tracking event. +// The provider associates this event with the flag evaluation context automatically. +client.track('checkout-completed', { value: 49.99, currencyCode: 'USD' }); +``` + + + +```java +import dev.openfeature.sdk.*; + +OpenFeatureAPI api = OpenFeatureAPI.getInstance(); + +// Set evaluation context with the user's targeting key +Map attrs = new HashMap<>(); +EvaluationContext ctx = new ImmutableContext("user-123", attrs); +api.setEvaluationContext(ctx); + +Client client = api.getClient(); + +// Evaluate the experiment flag +Boolean useNewCheckout = client.getBooleanValue("checkout-experiment", false); + +if (useNewCheckout) { + showNewCheckout(); +} else { + showExistingCheckout(); +} + +// Track the conversion event — provider links it back to the flag evaluation context +client.track("checkout-completed", new MutableTrackingEventDetails(49.99).add("currencyCode", "USD")); +``` + + + +```csharp +using OpenFeature; +using OpenFeature.Model; + +// Set evaluation context with the user's targeting key +EvaluationContextBuilder builder = EvaluationContext.Builder(); +builder.Set("targetingKey", "user-123"); +EvaluationContext ctx = builder.Build(); +Api.Instance.SetContext(ctx); + +var client = Api.Instance.GetClient(); + +// Evaluate the experiment flag — all evaluations are async in .NET SDK, note GetBooleanValueAsync +var useNewCheckout = await client.GetBooleanValueAsync("checkout-experiment", false); + +if (useNewCheckout) { + await ShowNewCheckout(); +} else { + await ShowExistingCheckout(); +} + +// Track the conversion event +client.Track("checkout-completed", trackingEventDetails: new TrackingEventDetailsBuilder() + .SetValue(49.99).Set("currencyCode", "USD").Build()); +``` + + + +```go +import ( + "context" + "github.com/open-feature/go-sdk/openfeature" +) + +// Set evaluation context with the user's targeting key +openfeature.SetEvaluationContext( + openfeature.NewEvaluationContext( + "user-123", + map[string]any{}, + ), +) + +client := openfeature.NewClient("my-app") + +// Evaluate the experiment flag +useNewCheckout, _ := client.BooleanValue( + context.TODO(), "checkout-experiment", false, openfeature.EvaluationContext{}, +) + +if useNewCheckout { + showNewCheckout() +} else { + showExistingCheckout() +} + +// Track the conversion event — provider links it back to the flag evaluation context +client.Track( + context.TODO(), + "checkout-completed", + openfeature.EvaluationContext{}, + openfeature.NewTrackingEventDetails(49.99).Add("currencyCode", "USD"), +) +``` + + + + diff --git a/docs/reference/concepts/08-experimentation.mdx b/docs/reference/concepts/08-experimentation.mdx new file mode 100644 index 000000000..35915bfb6 --- /dev/null +++ b/docs/reference/concepts/08-experimentation.mdx @@ -0,0 +1,261 @@ +--- +sidebar_position: 8 +id: experimentation +--- + +# Experimentation + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +OpenFeature provides built-in support for experimentation use cases such as A/B testing, multivariate tests, and gradual rollouts. +This page explains how three existing capabilities namely the tracking API, hooks, and targeting key, work together to support experimentation workflows. + +## How OpenFeature Supports Experimentation + +Three OpenFeature mechanisms combine to form a complete experimentation pipeline: + +- **Tracking API** : Records business events (conversions, clicks, sign-ups) and links them back to the flag evaluation context so your analytics platform can measure per-variant outcomes. +- **Hooks** : Extend the SDK at well-defined points of the flag evaluation lifecycle to capture metrics and forward data to analytics platforms without modifying application code. +- **Targeting Key** : A stable user identifier (passed via evaluation context) that your provider uses to assign users to variants consistently across sessions, and that analytics platforms use as the join key between flag evaluations and tracking events. + + +```mermaid +sequenceDiagram + participant App + participant OpenFeature SDK + participant Flag Provider + + App->>OpenFeature SDK: setContext(targetingKey, attributes) + App->>OpenFeature SDK: getBooleanValue("checkout-experiment", false) + OpenFeature SDK->>Flag Provider: resolve flag for targetingKey + Flag Provider-->>OpenFeature SDK: variant (true / false) + OpenFeature SDK-->>App: variant value + App->>App: render variant UI + App->>OpenFeature SDK: track("checkout-completed", details) + OpenFeature SDK->>Flag Provider: forward tracking event + Note over Flag Provider: Provider forwards data to your
configured analytics platform +``` + +## Experimentation Workflow + +### Step 1 : Set the Evaluation Context + +The `targetingKey` is the user identifier your provider uses to assign the user to a variant consistently across sessions. +Additional attributes (plan, geo, device) can be used by the provider for more advanced targeting rules. + + + + +```ts +import { OpenFeature } from '@openfeature/server-sdk'; + +// Set global context — targetingKey is the primary experiment identifier +OpenFeature.setContext({ + targetingKey: 'user-456', + plan: 'premium', + geo: 'EU', +}); +``` + + + + + +```java +import dev.openfeature.sdk.*; +import java.util.HashMap; +import java.util.Map; + +OpenFeatureAPI api = OpenFeatureAPI.getInstance(); + +// Build evaluation context with targeting key and attributes +Map attrs = new HashMap<>(); +attrs.put("plan", new Value("premium")); +attrs.put("geo", new Value("EU")); +EvaluationContext ctx = new ImmutableContext("user-456", attrs); + +api.setEvaluationContext(ctx); +``` + + + + + +```csharp +using OpenFeature; +using OpenFeature.Model; + +// Build evaluation context with targeting key and attributes +EvaluationContextBuilder builder = EvaluationContext.Builder(); +builder.Set("targetingKey", "user-456"); +builder.Set("plan", "premium"); +builder.Set("geo", "EU"); +EvaluationContext ctx = builder.Build(); + +Api.Instance.SetContext(ctx); +``` + + + + + +```go +import "github.com/open-feature/go-sdk/openfeature" + +// Set global context with targeting key and attributes +openfeature.SetEvaluationContext( + openfeature.NewEvaluationContext( + "user-456", + map[string]any{ + "plan": "premium", + "geo": "EU", + }, + ), +) +``` + + + + +### Step 2 : Evaluate the Experiment Flag + +Use the standard evaluation API to determine which variant the user receives. +The provider uses the `targetingKey` from the context to return a consistent variant for that user. + + + + +```ts +const client = OpenFeature.getClient(); + +// getBooleanValue: false = control group, true = variant group +const useNewCheckout = await client.getBooleanValue('checkout-experiment', false); + +if (useNewCheckout) { + renderNewCheckoutFlow(); +} else { + renderExistingCheckoutFlow(); +} +``` + + + + + +```java +Client client = api.getClient(); + +// getBooleanValue: false = control, true = variant +Boolean useNewCheckout = client.getBooleanValue("checkout-experiment", false); + +if (useNewCheckout) { + renderNewCheckoutFlow(); +} else { + renderExistingCheckoutFlow(); +} +``` + + + + + +```csharp +var client = Api.Instance.GetClient(); + +// GetBooleanValueAsync: false = control, true = variant +var useNewCheckout = await client.GetBooleanValueAsync("checkout-experiment", false); + +if (useNewCheckout) { + RenderNewCheckoutFlow(); +} else { + RenderExistingCheckoutFlow(); +} +``` + + + + + +```go +client := openfeature.NewClient("my-app") + +// BooleanValue: false = control, true = variant +useNewCheckout, _ := client.BooleanValue( + context.TODO(), "checkout-experiment", false, openfeature.EvaluationContext{}, +) + +if useNewCheckout { + renderNewCheckoutFlow() +} else { + renderExistingCheckoutFlow() +} +``` + + + + +### Step 3 : Track Conversions + +Call `track` when a business event occurs (purchase, sign-up, click). +The provider automatically links this event to the flag evaluation context — including the `targetingKey` — so your analytics platform can segment conversion rates by variant. + + + + +```ts +// When the user completes a purchase, emit a tracking event +client.track('checkout-completed', { value: 29.99, currencyCode: 'USD' }); +``` + + + + + +```java +// When the user completes a purchase, emit a tracking event +client.track("checkout-completed", + new MutableTrackingEventDetails(29.99).add("currencyCode", "USD")); +``` + + + + + +```csharp +// When the user completes a purchase, emit a tracking event +client.Track("checkout-completed", trackingEventDetails: new TrackingEventDetailsBuilder() + .SetValue(29.99).Set("currencyCode", "USD").Build()); +``` + + + + + +```go +// When the user completes a purchase, emit a tracking event +client.Track( + context.TODO(), + "checkout-completed", + openfeature.EvaluationContext{}, + openfeature.NewTrackingEventDetails(29.99).Add("currencyCode", "USD"), +) +``` + + + + +### Step 4 : Analyze Results + +Your analytics platform uses the `targetingKey` as the join key between flag evaluation data and tracking events. +This lets it compute per-variant conversion rates and determine statistical significance, so you can decide whether to roll out the winning variant. + +## The Targeting Key + +The `targetingKey` is the single most important field for experimentation. It serves three roles: + +- **Consistent assignment** : The same user always receives the same variant as long as the flag configuration does not change. +- **Unbiased splits** : Providers use consistent hashing on the targeting key to distribute users evenly across variants. +- **Join key** : Analytics platforms join flag evaluation records with tracking events using this identifier. + +Use a stable, unique user identifier as the targeting key — typically a user ID, session ID, or device ID. diff --git a/docs/reference/intro.mdx b/docs/reference/intro.mdx index 39a6c481f..a919a2e7d 100644 --- a/docs/reference/intro.mdx +++ b/docs/reference/intro.mdx @@ -84,6 +84,14 @@ Providers might wrap a vendor SDK, call a bespoke flag evaluation REST API, or e [Hooks](./concepts/04-hooks.mdx) are a mechanism that allow for the addition of arbitrary behavior at various points in the _flag evaluation life-cycle_. Hooks let you extend the OpenFeature SDK, adding functionality such as validating a resolved flag value, modifying or adding data to the evaluation context, logging, telemetry, and tracking. +### Experimentation + +OpenFeature includes support for [experimentation](./concepts/08-experimentation.mdx) use cases. +The [tracking API](./concepts/07-tracking.mdx) lets you associate user actions (conversions, clicks, sign-ups) with flag evaluations, +enabling A/B testing and other experimentation workflows. +Combined with the [evaluation context](./concepts/03-evaluation-context.mdx) (targeting key, user attributes) and [hooks](./concepts/04-hooks.mdx) +for custom metrics, OpenFeature provides a complete experimentation pipeline that works with any analytics platform. + ### Events [Events](./concepts/05-events.mdx) enable the ability to react to state changes in the provider or underlying flag management system. diff --git a/src/partials/features-zigzag.tsx b/src/partials/features-zigzag.tsx index 90f771f23..0c240d46e 100644 --- a/src/partials/features-zigzag.tsx +++ b/src/partials/features-zigzag.tsx @@ -223,6 +223,48 @@ function FeaturesZigZag() { +
+
+
+ !provider.excludeFromLandingPage).map((provider) => ({ + key: `exp-provider-${provider.name}`, + name: provider.name, + logo: provider.logo, + href: encodeURI(`/ecosystem?instant_search[refinementList][vendor][0]=${provider.name}`), + }))} + /> +
+
+
+
+
+ Data-driven decisions +
+

Built for experimentation

+

+ Run A/B tests and measure feature impact without changing your stack. +

+
    +
  • + +
    • +
  • + +
    • +
  • + +
    • +
+
+
+