Document ID management behavior for feature flag targeting

docs/featureflags.mdx

@@ -198,6 +198,29 @@ We support the following types of Flags:
   </Step>
 </Steps>
 
+### 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?**

docs/tracking-methods/sdks/android/android-flags.mdx

@@ -187,6 +187,10 @@ String updatedDistinctId = "";
 mixpanel.identify(updatedDistinctId);
 ```
 
+<Note>
+  `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).
+</Note>
+
 2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags:
 
 ```java

docs/tracking-methods/sdks/flutter/flutter-flags.mdx

@@ -187,6 +187,10 @@ String updatedDistinctId = "";
 mixpanel.identify(updatedDistinctId);
 ```
 
+<Note>
+  `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).
+</Note>
+
 ### Manual Reload
 
 To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags:

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)
 
+<Note>
+  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).
+</Note>
+
 ## Flag Evaluation Scenarios
 
 There are two scenarios available for using the Go SDK for feature flagging: Local Evaluation and Remote Evaluation.

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)
 
+<Note>
+  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).
+</Note>
+
 ## Flag Evaluation Modes
 
 There are two modes available for using the Java SDK for feature flagging: Local Evaluation and Remote Evaluation.

docs/tracking-methods/sdks/javascript/javascript-flags.mdx

@@ -167,6 +167,10 @@ updated_distinct_id = ""
 mixpanel.identify(updated_distinct_id)
 ```
 
+<Note>
+  `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).
+</Note>
+
 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

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)
 
+<Note>
+  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).
+</Note>
+
 ## Flag Evaluation Scenarios
 
 There are two scenarios available for using the Node.js SDK for feature flagging: Local Evaluation and Remote Evaluation.

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)
 
+<Note>
+  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).
+</Note>
+
 ## Flag Evaluation Scenarios
 
 There are two scenarios available for using the python SDK for feature flagging, Local Evaluation and Remote Evaluation.

docs/tracking-methods/sdks/react-native/react-native-flags.mdx

@@ -233,6 +233,10 @@ const updatedDistinctId = "user-123";
 await mixpanel.identify(updatedDistinctId);
 ```
 
+<Note>
+  `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).
+</Note>
+
 ### Manual Reload
 
 You can manually reload flags at any time:

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)
 
+<Note>
+  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).
+</Note>
+
 ## Flag Evaluation Scenarios
 
 There are two scenarios available for using the Ruby SDK for feature flagging: Local Evaluation and Remote Evaluation.

docs/tracking-methods/sdks/swift/swift-flags.mdx

@@ -161,6 +161,10 @@ let updatedDistinctId = ""
 Mixpanel.mainInstance().identify(distinctId: updatedDistinctId)
 ```
 
+<Note>
+  `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).
+</Note>
+
 2. To refresh flag variants that may have changed during the lifetime of your app, you can manually reload flags.
 
 ```swift