Myronkaifung docsfeedback 20250515 (#1877)

myronkaifung · web-flow · commit 070d2fa25ea3 · 2025-05-19T12:27:21.000-07:00
* add Session Replay example init combos

* add detail about User ID Property for Cohort Sync connection setup

* Add instruction for resetting API Secret and API Key

* add callout regarding project token reset not being self-served

* add clarification about how canonical distinct ID is determined for v2 and v3
diff --git a/pages/docs/cohort-sync/integrations/braze.mdx b/pages/docs/cohort-sync/integrations/braze.mdx
@@ -1,5 +1,6 @@
-# Braze
+import { Callout } from 'nextra/components'
 
+# Braze
 
 ## Overview
 
@@ -25,6 +26,10 @@ Enter the Mixpanel project where the integration is to be performed, then:
 
 2. Select the Braze integration tab. Click **Connect**.
 
+<Callout type="info">
+    If you set a User ID Property, it should be a Mixpanel user property that matches the Braze External ID. If you do not select one, Mixpanel will default to using the `$braze_external_id` property to match users between Braze and Mixpanel. See more about [matching users between Braze and Mixpanel](/docs/cohort-sync/integrations/braze#matching-mixpanel-and-braze-users).
+</Callout>
+
 ![Braze 2 Image](/braze2.png)
 
 If you've set up a Connection already, you have the option of reconnecting the existing Connection.
@@ -91,15 +96,19 @@ In order to build a Braze Segment after importing a cohort:
 
 ## Matching Mixpanel and Braze Users
 
-> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
+<Callout type="warning">
+    **Warning:** Projects using the [Simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
+</Callout>
 
 In order to match Mixpanel users to ones on Braze's end, the user in Mixpanel should have a profile property named $braze_external_id with the value you have assigned in Braze to the same user as [external_user_id](https://www.braze.com/docs/developer_guide/platform_integration_guides/legacy_sdks/ios/analytics/setting_user_ids/#suggested-user-id-naming-convention).
 
 The recommendation would be to insert code after the user authenticates that sends a `people.set` operation to the `$braze_external_id` property with the string value so it is stored in the Mixpanel profile. This could be when they sign up (or just log in if they already had an account). By setting the property each time the user authenticates you would ensure users who have signed up previous to this code changes also have it.
 
 If you are planning to also enable sending engagement events from Braze to Mixpanel, and the Braze external_user_id differs from the user_id you identify the user with in Mixpanel, you can also alias the Braze external_user_id to the distinct_id you identify users with after they authenticate. Often times, you use the same user ID for both the external_user_id in Braze, and the ID you identify with in Mixpanel, so in that case, aliasing would not be needed.
 
->Note: SDK versions older than Android v5.9.6, Swift: v2.10.4, and Objective-C: v3.9.2 automatically created both the profile property and the alias mentioned above. This has since been deprecated due to possible ID management issues in some use cases, so on the SDK versions cited (or above), you should set the `$braze_external_id` profile property and alias when applicable.
+<Callout type="info">
+    SDK versions older than Android v5.9.6, Swift: v2.10.4, and Objective-C: v3.9.2 automatically created both the profile property and the alias mentioned above. This has since been deprecated due to possible ID management issues in some use cases, so on the SDK versions cited (or above), you should set the `$braze_external_id` profile property and alias when applicable.
+</Callout>
 
 ## Braze Events into Mixpanel & MTU exemptions
 
diff --git a/pages/docs/cohort-sync/integrations/insider.mdx b/pages/docs/cohort-sync/integrations/insider.mdx
@@ -1,5 +1,6 @@
-# Insider
+import { Callout } from 'nextra/components'
 
+# Insider
 
 ## Overview
 
@@ -11,21 +12,20 @@ You must be a Mixpanel project admin to enable the Insider integration.
 
 ## Enable the Integration
 
-To enable the integration, select **Integrations** under the **Data Management** tab in the top navigation bar.
+1. To enable the integration, select **Integrations** under the **Data Management** tab in the top navigation bar.
 
 ![insider 1 Image](/insider1.png)
 
-From the Integrations page, select the Insider dropdown, and select **Connect**.
-
-Find the Insider API Key from the Insider's Mobile App Settings > Integration tab.
+2. From the Integrations page, select the Insider dropdown, and select **Connect**.
 
-![insider_APIkey](https://github.com/mixpanel/docs/assets/13739415/086ebe51-b4ab-4f55-bb13-83de81f40561)
-
-Enter the Insider API Key in Mixpanel and select **Continue**
+<Callout type="info">
+    If you set a User ID Property, it should be a Mixpanel user property that matches the email or phone number set in Insider.
+</Callout>
 
 ![insider 2 Image](/insider2.png)
 
-The Insider integration will show a **Connected** tag in the UI once the connection succeeds.
+
+3. The Insider integration will show a **Connected** tag in the UI once the connection succeeds.
 
 ## Matching Users between Insider and Mixpanel
 
diff --git a/pages/docs/cohort-sync/integrations/moengage.mdx b/pages/docs/cohort-sync/integrations/moengage.mdx
@@ -1,3 +1,5 @@
+import { Callout } from 'nextra/components'
+
 # Moengage
 
 ## Overview
@@ -16,6 +18,10 @@ You must be a Mixpanel project admin to enable the MoEngage integration.
 
 2. From the Integrations page, select the MoEngage dropdown, and select **Connect**.
 
+<Callout type="info">
+    If you set a User ID Property, it should be a Mixpanel user property that matches the MoEngage External ID. If you do not select one, Mixpanel will default to using the `$moengage_user_id` property to match users between MoEngage and Mixpanel. See more about [matching users between MoEngage and Mixpanel](/docs/cohort-sync/integrations/moengage#matching-users-between-moengage-and-mixpanel).
+</Callout>
+
 ![Moengage 2 Image](/moengage2.png)
 
 3. The connection uses a Basic Authorization Username/Password system. You will need to provide two credentials to authorize the connection:
@@ -35,7 +41,9 @@ You can find these values in your MoEngage settings page - note that MoEngage Ap
 
 ## Matching Users between MoEngage and Mixpanel
 
-> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
+<Callout type="warning">
+    **Warning:** Projects using the [Simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
+</Callout>
 
 Mixpanel only exports identified user profiles to match to MoEngage - users without user profile properties (i.e. anonymous users) will not export.
 
diff --git a/pages/docs/cohort-sync/integrations/onesignal.mdx b/pages/docs/cohort-sync/integrations/onesignal.mdx
@@ -1,5 +1,6 @@
-# OneSignal
+import { Callout } from 'nextra/components'
 
+# OneSignal
 
 ## Overview
 
@@ -23,13 +24,19 @@ Follow these steps to enable the integration with OneSignal:
 
 2. From the Integrations page, select the OneSignal dropdown, and select **Connect**.
 
+<Callout type="info">
+    If you set a User ID Property, it should be a Mixpanel user property that matches the OneSignal External ID. If you do not select one, Mixpanel will default to using the `$onesignal_user_id` property to match users between OneSignal and Mixpanel. See more about [matching users between OneSignal and Mixpanel](/docs/cohort-sync/integrations/onesignal#matching-users-between-onesignal-and-mixpanel).
+</Callout>
+
 ![OneSignal 2 Image](/onesignal6.png)
 
 3. You will need to provide two credentials to authorize the connection: **API Key and App ID**. You can find these values in your **OneSignal settings** page. The OneSignal integration will show a **Connected** tag in the UI once the connection succeeds. 
 
 ## Matching Users between OneSignal and Mixpanel
 
-> **Warning:** Projects using the [simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
+<Callout type="warning">
+    **Warning:** Projects using the [Simplified ID merge system](/docs/tracking-methods/id-management#identity-merge-apis) must have the `$user_id` in Mixpanel match the user identifier in the partner service. Using any alternative partner properties to match users between tools may result in partner events not being attributed to the correct user in Mixpanel. Any partner properties mentioned in the below section are primarily applicable to projects on the original ID merge system.
+</Callout>
 
 Mixpanel only exports identified user profiles to match to OneSignal - users without user profile properties (i.e. anonymous users) will not export.
 
diff --git a/pages/docs/cohort-sync/integrations/segment.mdx b/pages/docs/cohort-sync/integrations/segment.mdx
@@ -1,5 +1,6 @@
-# Segment
+import { Callout } from 'nextra/components'
 
+# Segment
 
 ## Overview
 
@@ -42,6 +43,10 @@ We will use the Write Key from Segment to enable the connection in Mixpanel.
 
 2. Then select Segment, click **Connect**, and paste the** Write Key** that you generated in Segment.
 
+<Callout type="info">
+    If you set a User ID Property, it should be a Mixpanel user property that matches the Segment User ID.
+</Callout>
+
 ![Segment 5 Image](/segment5.png)
 
 3. Click **Continue** to complete the process.
diff --git a/pages/docs/orgs-and-projects/managing-projects.mdx b/pages/docs/orgs-and-projects/managing-projects.mdx
@@ -86,17 +86,25 @@ Click the Settings gear in the upper right-hand corner of your Mixpanel project
 
 ### Locate Tokens for All Projects in Your Mixpanel Account
 
-To view the project tokens for all your projects, click the **Settings** gear icon in the top right of Mixpanel and select **Personal Settings**.
+To view the project tokens for all your projects, click the **Settings** gear icon and select **Personal Settings**.
 
 ![manageprojects 7 Image](/manageprojects7.png)
 
 Then select the Projects tab.
 
 ![manageprojects 8 Image](/manageprojects8.png)
 
+#### Reset Project API Secret and API Key
+
+You can reset the API Secret and API Keys for any projects you own. To do so, go to **Settings** → **Profile** → **Projects** → **Your Projects**, and click **Reset** next to the desired project.
+
+#### Reset Project Token
+
+Project Token cannot be reset in a self-served manner. If you need to reset your project token for any reason, please [reach out to our Support team](https://mixpanel.com/get-support).
+
 ## Manage Timezones for Projects
 
-<Callout type="info" emoji="ℹ️">
+<Callout type="info">
 For projects created before 1 Jan 2023, Mixpanel converts event timestamps to your project timezone before writing the event to your Mixpanel data stores, meaning that event timestamps are stored based on the project timezone setting at the time of ingestion.
 </Callout>
 
diff --git a/pages/docs/session-replay/implement-session-replay/session-replay-web.mdx b/pages/docs/session-replay/implement-session-replay/session-replay-web.mdx
@@ -108,6 +108,16 @@ mixpanel.init(
 | `record_sessions_percent` | Percentage of SDK initializations that will qualify for replay data capture. A value of "1" = 1%. | `0` |
 | `record_canvas` | When true, Mixpanel will record snapshots of `<canvas>` elements on your site at up to 15 frames per second | `false` |
 
+**Example Usage**
+
+```javascript
+mixpanel.init('YOUR_PROJECT_TOKEN', {
+    record_sessions_percent: 1,  //records 1% of all sessions
+    record_mask_text_selector: '', //unmask all text elements
+    record_block_selector: '' //unmask images and videos
+});
+```
+
 ## Replay ID
 
 When a replay capture begins, a Replay ID is generated by the SDK and is attached as an event property (`$mp_replay_id`) to events tracked by the SDK during the capture session. Events containing the same `$mp_replay_id` will appear in the same Replay.
diff --git a/pages/docs/tracking-methods/id-management/identifying-users-original.mdx b/pages/docs/tracking-methods/id-management/identifying-users-original.mdx
@@ -104,9 +104,11 @@ If using our Web/Mobile SDKs or a CDP like Segment or Rudderstack, there are onl
 - Calling `.reset` will clear the local storage (which contains the `$user_id` and `$device_id`), and generate a new `$device_id` for the session. A best practice would be to only call `.reset()` if there is a definite intent to change user on the same device, example clicking on “Sign-up” button instead of “Login”.
 
 
-<Callout type="warning">
-    The `distinct_id` is programmatically selected by Mixpanel, using one of the IDs inside of an identity cluster, based on the most optimal merging process. This means that the canonical distinct_id could be set to a `$device_id` or your chosen `user_id`. This is not user-configurable. You can use any of the IDs in the cluster for ingestion, but only the canonical `distinct_id` can be used in queries and exports.
-</Callout>
+## Canonical Distinct ID
+
+Once a user has been identified via the `.identify(user_id)` method, their `$device_id` prior to identification will be combined with the `$user_id` to form an identity cluster containing both IDs, as well as any other IDs previously merged with the `$user_id`. During this process, the canonical `distinct_id` is programmatically selected by Mixpanel, using one of the IDs inside of the identity cluster, based on the most optimal merging process. This means that the canonical distinct_id could be set to a `$device_id` or your chosen `user_id`. This is not user-configurable.
+
+You can use any of the IDs in the cluster for ingestion, but only the canonical `distinct_id` can be used in queries and exports.
 
 ## Example User Flows
 Let's walk through a few user flows where ID Merge is useful, and when to call `.identify()` and `.reset()` to use ID Merge properly.
diff --git a/pages/docs/tracking-methods/id-management/identifying-users-simplified.mdx b/pages/docs/tracking-methods/id-management/identifying-users-simplified.mdx
@@ -65,6 +65,12 @@ If using our Web/Mobile SDKs or a CDP like Segment or Rudderstack, there are onl
 
 - Calling `.reset` will clear the local storage (which contains the `$user_id` and `$device_id`), and generate a new `$device_id` for the session. It is recommended to call `.reset` when a user logout or times out of an authenticated session to prevent the unintentional merging of multiple users sharing one device.
 
+## Canonical Distinct ID
+
+Once a user has been identified via the `.identify(user_id)` method, their `$device_id` prior to identification will be combined with the `$user_id` to form an identity cluster containing both IDs, as well as any other IDs previously merged with the `$user_id`. For projects using the Simplified ID Merge API, the canonical `distinct_id` is always set to the `$user_id`.
+
+You can use any of the IDs in the cluster for ingestion, but only the canonical `distinct_id` can be used in queries and exports.
+
 ## Example User Flows
 Let's walk through a few user flows where ID Merge is useful, and when to call `.identify()` and `.reset()` to use ID Merge properly.
 
diff --git a/pages/docs/tracking-methods/sdks/javascript.mdx b/pages/docs/tracking-methods/sdks/javascript.mdx
@@ -969,6 +969,15 @@ Customize the Replay capture behavior using the library init options outlined be
 | `record_canvas` | When true, Mixpanel will record snapshots of `<canvas>` elements on your site at up to 15 frames per second | `false` |
 | `record_heatmap_data` | When true, Mixpanel will capture click events during replays to populate Heatmaps. Viewing Heatmaps is currently in Beta. | `false` |
 
+**Example Usage**
+
+```javascript
+mixpanel.init('YOUR_PROJECT_TOKEN', {
+    record_sessions_percent: 1,  //records 1% of all sessions
+    record_mask_text_selector: '', //unmask all text elements
+    record_block_selector: '' //unmask images and videos
+});
+```
 
 ### Manual Capture
 
diff --git a/public/braze2.png b/public/braze2.png
diff --git a/public/insider2.png b/public/insider2.png
diff --git a/public/moengage2.png b/public/moengage2.png
diff --git a/public/segment5.png b/public/segment5.png
