diff --git a/docs/featureflags.mdx b/docs/featureflags.mdx index 6d767632..6b8bdc24 100644 --- a/docs/featureflags.mdx +++ b/docs/featureflags.mdx @@ -198,6 +198,29 @@ We support the following types of Flags: +### ID management and flag targeting + +Flags are evaluated using the ID your SDK sends, but cohort targeting is evaluated against Users in Mixpanel. How the two line up depends on your project's ID management version. See [Original ID Merge](/docs/tracking-methods/id-management/identifying-users-original) and [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users-simplified) for how each system identifies users. + +| ID management | How cohort targeting resolves a user | +| --- | --- | +| Simplified ID Merge | Each user has a single canonical ID, which is their `user_id` once identified. No additional handling is needed. | +| Original ID Merge | Any ID in a user's identity cluster can be the canonical ID. To keep targeting deterministic, Mixpanel uses the user's most recently identified ID, based on `$identify` events from the last 90 days. If there is no `$identify` event in that window, Mixpanel falls back to the user's current canonical ID. `$alias` and `$merge` events are not considered. | +| Legacy | Feature flags apply no special handling. | + +#### `identify()` only acts when the ID changes + +Client SDKs send an `$identify` event and reload flags only when the ID passed to `identify()` differs from the ID the SDK already has. Calling `identify()` again with the same ID does nothing: no new `$identify` event is sent and flags are not reloaded. + +On Original ID Merge, this affects cohort targeting. A user can open your app every day and call `identify(userId)`, but if the ID never changes, no new `$identify` events are recorded. Once the user's most recent `$identify` event is more than 90 days old, targeting falls back to their canonical ID. If that canonical ID is not the ID your SDK sends as `distinct_id`, the user may not match the cohort. + +To avoid this on Original ID Merge: + +- Call `identify()` with a stable, consistent ID for each logged-in user. +- When evaluating flags from a server SDK, pass the same `distinct_id` your client SDKs use. + +Projects on Simplified ID Merge don't have this limitation. To learn about moving to it, see [Migrating to Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system). + ### Frequently Asked Questions **How do [Data Views](/docs/data-governance/data-views-and-classification) affect feature flags?** diff --git a/docs/tracking-methods/sdks/android/android-flags.mdx b/docs/tracking-methods/sdks/android/android-flags.mdx index 8fafc90f..c9a4c650 100644 --- a/docs/tracking-methods/sdks/android/android-flags.mdx +++ b/docs/tracking-methods/sdks/android/android-flags.mdx @@ -187,6 +187,10 @@ String updatedDistinctId = ""; mixpanel.identify(updatedDistinctId); ``` + + `identify()` only sends an `$identify` event and reloads flags when the ID changes. Calling it again with the ID the SDK already has does nothing. On projects using Original ID Merge, this affects cohort-based targeting. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + 2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags: ```java diff --git a/docs/tracking-methods/sdks/flutter/flutter-flags.mdx b/docs/tracking-methods/sdks/flutter/flutter-flags.mdx index eeefcd64..424b0980 100644 --- a/docs/tracking-methods/sdks/flutter/flutter-flags.mdx +++ b/docs/tracking-methods/sdks/flutter/flutter-flags.mdx @@ -187,6 +187,10 @@ String updatedDistinctId = ""; mixpanel.identify(updatedDistinctId); ``` + + `identify()` only sends an `$identify` event and reloads flags when the ID changes. Calling it again with the ID the SDK already has does nothing. On projects using Original ID Merge, this affects cohort-based targeting. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + ### Manual Reload To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags: diff --git a/docs/tracking-methods/sdks/go/go-flags.mdx b/docs/tracking-methods/sdks/go/go-flags.mdx index a64e1bca..2286c5d2 100644 --- a/docs/tracking-methods/sdks/go/go-flags.mdx +++ b/docs/tracking-methods/sdks/go/go-flags.mdx @@ -20,6 +20,10 @@ go get github.com/mixpanel/mixpanel-go@v2.0.0 - You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens) + + Cohort-based targeting resolves each user according to your project's ID management version, and on Original ID Merge it depends on recent `$identify` events. Pass the same `distinct_id` your client SDKs use. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + ## Flag Evaluation Scenarios There are two scenarios available for using the Go SDK for feature flagging: Local Evaluation and Remote Evaluation. diff --git a/docs/tracking-methods/sdks/java/java-flags.mdx b/docs/tracking-methods/sdks/java/java-flags.mdx index cbf1f455..4db75cc9 100644 --- a/docs/tracking-methods/sdks/java/java-flags.mdx +++ b/docs/tracking-methods/sdks/java/java-flags.mdx @@ -15,6 +15,10 @@ Before implementing [Feature Flags](/docs/featureflags), ensure: - You have the appropriate version of the SDK installed (minimum supported version is `1.6.0-SNAPSHOT`). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK. - You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens) + + Cohort-based targeting resolves each user according to your project's ID management version, and on Original ID Merge it depends on recent `$identify` events. Pass the same `distinct_id` your client SDKs use. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + ## Flag Evaluation Modes There are two modes available for using the Java SDK for feature flagging: Local Evaluation and Remote Evaluation. diff --git a/docs/tracking-methods/sdks/javascript/javascript-flags.mdx b/docs/tracking-methods/sdks/javascript/javascript-flags.mdx index da5581fa..b9b59658 100644 --- a/docs/tracking-methods/sdks/javascript/javascript-flags.mdx +++ b/docs/tracking-methods/sdks/javascript/javascript-flags.mdx @@ -167,6 +167,10 @@ updated_distinct_id = "" mixpanel.identify(updated_distinct_id) ``` + + `identify()` only sends an `$identify` event and reloads flags when the ID changes. Calling it again with the ID the SDK already has does nothing. On projects using Original ID Merge, this affects cohort-based targeting. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + 2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags with a new context: ```javascript diff --git a/docs/tracking-methods/sdks/nodejs/nodejs-flags.mdx b/docs/tracking-methods/sdks/nodejs/nodejs-flags.mdx index d1b6b65e..c593a7b3 100644 --- a/docs/tracking-methods/sdks/nodejs/nodejs-flags.mdx +++ b/docs/tracking-methods/sdks/nodejs/nodejs-flags.mdx @@ -15,6 +15,10 @@ Before implementing [Feature Flags](/docs/featureflags), ensure: - You have the [Mixpanel Node.js SDK](https://github.com/mixpanel/mixpanel-node) installed. If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK. The minimum supported version is [v0.20.0](https://www.npmjs.com/package/mixpanel) - You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens) + + Cohort-based targeting resolves each user according to your project's ID management version, and on Original ID Merge it depends on recent `$identify` events. Pass the same `distinct_id` your client SDKs use. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + ## Flag Evaluation Scenarios There are two scenarios available for using the Node.js SDK for feature flagging: Local Evaluation and Remote Evaluation. diff --git a/docs/tracking-methods/sdks/python/python-flags.mdx b/docs/tracking-methods/sdks/python/python-flags.mdx index fc452d33..3891d160 100644 --- a/docs/tracking-methods/sdks/python/python-flags.mdx +++ b/docs/tracking-methods/sdks/python/python-flags.mdx @@ -15,6 +15,10 @@ Before implementing [Feature Flags](/docs/featureflags), ensure: - You have the appropriate version of the SDK installed (minimum supported version is [`v5.1.0`](https://github.com/mixpanel/mixpanel-python)). If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK. - You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens) + + Cohort-based targeting resolves each user according to your project's ID management version, and on Original ID Merge it depends on recent `$identify` events. Pass the same `distinct_id` your client SDKs use. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + ## Flag Evaluation Scenarios There are two scenarios available for using the python SDK for feature flagging, Local Evaluation and Remote Evaluation. diff --git a/docs/tracking-methods/sdks/react-native/react-native-flags.mdx b/docs/tracking-methods/sdks/react-native/react-native-flags.mdx index fed93118..f543dadc 100644 --- a/docs/tracking-methods/sdks/react-native/react-native-flags.mdx +++ b/docs/tracking-methods/sdks/react-native/react-native-flags.mdx @@ -233,6 +233,10 @@ const updatedDistinctId = "user-123"; await mixpanel.identify(updatedDistinctId); ``` + + `identify()` only sends an `$identify` event and reloads flags when the ID changes. Calling it again with the ID the SDK already has does nothing. On projects using Original ID Merge, this affects cohort-based targeting. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + ### Manual Reload You can manually reload flags at any time: diff --git a/docs/tracking-methods/sdks/ruby/ruby-flags.mdx b/docs/tracking-methods/sdks/ruby/ruby-flags.mdx index 9b2c10fb..3dde676e 100644 --- a/docs/tracking-methods/sdks/ruby/ruby-flags.mdx +++ b/docs/tracking-methods/sdks/ruby/ruby-flags.mdx @@ -15,6 +15,10 @@ Before implementing [Feature Flags](/docs/featureflags), ensure: - You have the [Mixpanel Ruby SDK](https://github.com/mixpanel/mixpanel-ruby) installed. If not, please follow [this doc](/docs/quickstart/install-mixpanel) to install the SDK. The minimum supported version is [v3.0.0](https://rubygems.org/gems/mixpanel-ruby) - You have your Project Token from your [Mixpanel Project Settings](/docs/orgs-and-projects/managing-projects#find-your-project-tokens) + + Cohort-based targeting resolves each user according to your project's ID management version, and on Original ID Merge it depends on recent `$identify` events. Pass the same `distinct_id` your client SDKs use. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + ## Flag Evaluation Scenarios There are two scenarios available for using the Ruby SDK for feature flagging: Local Evaluation and Remote Evaluation. diff --git a/docs/tracking-methods/sdks/swift/swift-flags.mdx b/docs/tracking-methods/sdks/swift/swift-flags.mdx index f5a2a254..b1c8520e 100644 --- a/docs/tracking-methods/sdks/swift/swift-flags.mdx +++ b/docs/tracking-methods/sdks/swift/swift-flags.mdx @@ -161,6 +161,10 @@ let updatedDistinctId = "" Mixpanel.mainInstance().identify(distinctId: updatedDistinctId) ``` + + `identify()` only sends an `$identify` event and reloads flags when the ID changes. Calling it again with the ID the SDK already has does nothing. On projects using Original ID Merge, this affects cohort-based targeting. See [ID management and flag targeting](/docs/featureflags#id-management-and-flag-targeting). + + 2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags. ```swift