From 7a1d743b9fd76efe9afe4ef17b2570037ae28da7 Mon Sep 17 00:00:00 2001 From: Mark Siebert Date: Fri, 6 Feb 2026 10:36:02 -0800 Subject: [PATCH 1/3] add detailed docs for using runtime events --- pages/docs/feature-flags/_meta.ts | 3 + pages/docs/feature-flags/runtime-events.mdx | 126 ++++++++++++++++++++ pages/docs/featureflags.mdx | 11 +- 3 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 pages/docs/feature-flags/_meta.ts create mode 100644 pages/docs/feature-flags/runtime-events.mdx diff --git a/pages/docs/feature-flags/_meta.ts b/pages/docs/feature-flags/_meta.ts new file mode 100644 index 0000000000..431cb3ba0e --- /dev/null +++ b/pages/docs/feature-flags/_meta.ts @@ -0,0 +1,3 @@ +export default { + "runtime-events": "Runtime Events", +} diff --git a/pages/docs/feature-flags/runtime-events.mdx b/pages/docs/feature-flags/runtime-events.mdx new file mode 100644 index 0000000000..75cf578f38 --- /dev/null +++ b/pages/docs/feature-flags/runtime-events.mdx @@ -0,0 +1,126 @@ +import { Callout, Steps } from 'nextra/components' + +# Runtime Events: Target Users Based on Behavior + + + Runtime Events is part of Feature Flags, a separately priced product add-on available to organizations on the Enterprise Plan. See our [pricing page](https://mixpanel.com/pricing/) for more details. + + +## Overview + +**Runtime Events** let you target users based on actions they perform, not just who they are. Instead of targeting cohorts or properties, you can trigger feature variants immediately when users complete specific events tracked with `mixpanel.track()`. + +**Traditional targeting**: "Show this variant to premium users" + +**Runtime Event targeting**: "Show this variant after the user completes their first purchase" + +### When to Use Runtime Events + +Runtime Events are ideal for behavior-driven experiences: + +- **Onboarding flows**: Show tutorial content after a user completes their first action +- **Progressive feature unlocking**: Unlock advanced features after users complete key milestones +- **Conditional promotions**: Display special offers after a user makes their first purchase +- **Behavior-gated experiments**: Run experiments only on users who have demonstrated engagement + +## How Runtime Events Work + +Think of Runtime Events as a "tripwire" that activates once. Here's the flow: + +### Before the Event + +1. User requests flag evaluation from your app +2. The flag service recognizes the user hasn't triggered the event yet +4. The SDK watches for the specified event + +### When the Event Occurs + +1. User performs the tracked event (e.g., "Purchase Complete") +3. The SDK reports the event to Mixpanel + +### After the Event + +1. On subsequent flag evaluations, the user now receives the active variant +2. The variant persists based on your duration setting (session or indefinitely) +3. If the variant is sticky, the user continues receiving it even if rollout changes + +## Configuring Runtime Events + +To add a Runtime Event targeting rule to your feature flag: + + + +### Navigate to Rollout Groups + +Open your feature flag and scroll to the **Rollout Groups** section. Click on a rollout group card or create a new one. + +### Add a Runtime Event Filter + +When adding a new filter, navigate to `+ Create New`, then click on `Runtime Event` to add a new runtime event filter. + +### Select the Event + +Click on the event dropdown (shows "Select Event" initially) and choose the Mixpanel event you want to trigger on. This can be any event tracked via `mixpanel.track()`. + +For example: `Purchase`, `Sign Up Complete`, `Dashboard Viewed` + +### Configure Time Window + +The **"While Flag Enabled"** dropdown controls when events count toward activation. Currently, only events that occur while the flag is enabled will activate the variant. + + + Only events that occur **after** the flag is enabled count toward activation. Historical events from before the flag was created or enabled are not counted. + + +### (Optional) Add First Time Filter + +Click the overflow menu (**...**) and select **"First Time"** to make this a first-time event trigger. + +When enabled, a second row appears showing: +- **"for the"** `First Time` **"until"** `[Duration]` + +The **Duration** dropdown offers: +- **End of Session**: Variant expires when the user's session ends +- **Indefinitely**: Variant persists in subsequent sessions + +### (Optional) Add Property Filters + +Click **"+ Filter"** to add conditions on event properties. This lets you target more specific behaviors. + +For example: +- Event: `Purchase` where `amount > 100` (only high-value purchases) +- Event: `Page View` where `page_path contains '/checkout'` (only checkout views) + +### Assign Variants + +On the right side of the rollout card, configure which variant users receive when they trigger the event. You can set variant splits (e.g., 50% variant A, 50% variant B) just like standard targeting. + +### Save the Flag + +Click **Save** to activate your configuration. The SDK will begin watching for the specified event. + + + +## Frequently Asked Questions + +**Can I use Runtime Events with cohort targeting?** + +Yes. You can combine Runtime Events with cohort targeting using AND logic. For example, "Premium users who complete their first purchase." + +**What happens if I disable and re-enable the flag?** + +The flag's "enabled at" timestamp updates. Users who previously triggered the event must perform it again after re-enablement to receive the variant. + +**Are Runtime Events supported on server-side SDKs?** + +Runtime Events are designed for client-side SDKs that can monitor events in real-time. Server-side implementations are not supported. + +**How quickly does the variant activate after an event?** + +The variant activates on the next call to `getVariant` or `isEnabled` after the event is reported. + +## Related Documentation + +- [Feature Flags Overview](/docs/featureflags) +- [Experiments](/docs/experiments) +- [Cohorts](/docs/cohorts) diff --git a/pages/docs/featureflags.mdx b/pages/docs/featureflags.mdx index f7f0d466bd..bc20da228b 100644 --- a/pages/docs/featureflags.mdx +++ b/pages/docs/featureflags.mdx @@ -98,13 +98,18 @@ This method enables targeting users immediately based on device or platform prop **Runtime Events** This method enables targeting users immediately when they perform specific actions tracked with `mixpanel.track()`. For example, show a feature to users the first time they complete onboarding, or target users who added items to cart. -- When building a cohort, navigate to `+ Create New`, then click on `Runtime Event` to add a new runtime event filter. -- You can optionally configure the targeting to apply only the first time a user performs an action after the flag is enabled. After the session where the user takes the action for the first time, they will exit the targeted cohort. -- Runtime events can include filters on event properties for more fine-grained control (e.g., purchase_amount > $100, page_path contains '/checkout'). +- When adding a new filter to your rollout group, navigate to `+ Create New`, then click on `Runtime Event` to add a new runtime event filter. +- Select an event, then optionally enable **"First Time"** to trigger only on the user's first occurrence of that event. +- Configure the **duration** to control how long the variant persists: "End of Session" or "Indefinitely". +- Add **property filters** for more fine-grained control (e.g., `purchase_amount > 100`, `page_path contains '/checkout'`). - **Examples**: - Target users the first time they complete the 'Sign Up' event - Target users who trigger 'Add to Cart' event with product_category = 'premium' + + For detailed configuration options and examples, see our [Runtime Events guide](/docs/feature-flags/runtime-events). + + ### Rollout Percentage This is the percentage of the requests that should be targeted, according to the Variant Assignment Key. From b94adb4931c71d7c16fef6257ae84738e6fa47d7 Mon Sep 17 00:00:00 2001 From: Mark Siebert Date: Fri, 6 Feb 2026 11:07:31 -0800 Subject: [PATCH 2/3] fix paths --- pages/docs/{feature-flags => featureflags}/_meta.ts | 0 pages/docs/{feature-flags => featureflags}/runtime-events.mdx | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename pages/docs/{feature-flags => featureflags}/_meta.ts (100%) rename pages/docs/{feature-flags => featureflags}/runtime-events.mdx (100%) diff --git a/pages/docs/feature-flags/_meta.ts b/pages/docs/featureflags/_meta.ts similarity index 100% rename from pages/docs/feature-flags/_meta.ts rename to pages/docs/featureflags/_meta.ts diff --git a/pages/docs/feature-flags/runtime-events.mdx b/pages/docs/featureflags/runtime-events.mdx similarity index 100% rename from pages/docs/feature-flags/runtime-events.mdx rename to pages/docs/featureflags/runtime-events.mdx From 0ceed5471397505010f31d1588cd39e272416652 Mon Sep 17 00:00:00 2001 From: Mark Siebert Date: Fri, 6 Feb 2026 14:23:23 -0800 Subject: [PATCH 3/3] address PR review feedback for runtime events docs - Add links to cohorts and runtime properties documentation - Move "immediately" to emphasize real-time targeting - Replace purchase example with ToFU project creation example Co-Authored-By: Claude Opus 4.5 --- pages/docs/featureflags/runtime-events.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/featureflags/runtime-events.mdx b/pages/docs/featureflags/runtime-events.mdx index 75cf578f38..24e3f0dd0b 100644 --- a/pages/docs/featureflags/runtime-events.mdx +++ b/pages/docs/featureflags/runtime-events.mdx @@ -8,11 +8,11 @@ import { Callout, Steps } from 'nextra/components' ## Overview -**Runtime Events** let you target users based on actions they perform, not just who they are. Instead of targeting cohorts or properties, you can trigger feature variants immediately when users complete specific events tracked with `mixpanel.track()`. +**Runtime Events** let you target users immediately based on actions they perform, not just who they are. Instead of targeting [cohorts](/docs/users/cohorts) or [properties](/docs/featureflags#runtime-properties), you can trigger feature variants when users complete specific events tracked with `mixpanel.track()`. **Traditional targeting**: "Show this variant to premium users" -**Runtime Event targeting**: "Show this variant after the user completes their first purchase" +**Runtime Event targeting**: "Display 'Next Steps' checklist immediately after user creates their first project" ### When to Use Runtime Events