From d0f5372d34a93c7d7359beb6e67d349f33316f9a Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Sun, 23 Jun 2024 14:32:08 -0700 Subject: [PATCH 01/12] Intro to staging (#1170) * Update what-is-mixpanel.mdx Add Demo/Registration CTA * Update what-is-mixpanel.mdx * Update what-is-mixpanel.mdx * Update what-to-track.mdx * Update identify-users.mdx --- pages/docs/quickstart/identify-users.mdx | 20 ++++++++++++-------- pages/docs/what-is-mixpanel.mdx | 22 ++++++++++++++++++++++ pages/docs/what-to-track.mdx | 19 +++++++++++++++---- 3 files changed, 49 insertions(+), 12 deletions(-) diff --git a/pages/docs/quickstart/identify-users.mdx b/pages/docs/quickstart/identify-users.mdx index e9920b548d..85c7bd0355 100644 --- a/pages/docs/quickstart/identify-users.mdx +++ b/pages/docs/quickstart/identify-users.mdx @@ -9,7 +9,7 @@ import { dataItems } from '/utils/constants'; ## Overview -This step introduces the `identify` method, which allows you to see which users triggered each event in Mixpanel. +This step introduces the `identify` method, which allows you to assign an ID to your users. It also introduces the `people.set` method, which allows you to define the attributes of each user. @@ -41,8 +41,8 @@ mp.people_set('USER_ID', {'$name' : 'Jane Doe', # Add anything else about the user here }) ``` - -You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -55,6 +55,8 @@ mixpanel.people.set('USER_ID', { // Add anything else about the user here }); ``` +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -72,8 +74,8 @@ err := mp.PeopleSet(ctx, []*mixpanel.PeopleProperties{ ) ``` -You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) - +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. ```ruby @@ -85,8 +87,8 @@ mp.people.set('USER_ID', { }); ``` -You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) - +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. ```java @@ -99,6 +101,8 @@ JSONObject update = messageBuilder.set("USER_ID", props); // Send the update to mixpanel mixpanel.sendMessage(update); ``` +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -279,4 +283,4 @@ or user profile update. Examples include: location, operating system, device, et For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission through the AppTrackingTransparency(ATT) framework. For more details, refer to our [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details). - \ No newline at end of file + diff --git a/pages/docs/what-is-mixpanel.mdx b/pages/docs/what-is-mixpanel.mdx index fdee0fc0c8..e05108a56f 100644 --- a/pages/docs/what-is-mixpanel.mdx +++ b/pages/docs/what-is-mixpanel.mdx @@ -71,3 +71,25 @@ Now that you understand the basics, **we recommend planning the first events you

+ +

+

+

+ +
+

Explore a demo dataset

+

Register for a free account to explore a full demo of Mixpanel. If you make a Board and like it, you can move it into your own project and add your own data.

+

+ +
+ +

+

+

+ +
+

Get an in-depth product demo

+

Want to see how Mixpanel can help your team build better products? Schedule a live demo with our product analytics experts.

+

+ +
diff --git a/pages/docs/what-to-track.mdx b/pages/docs/what-to-track.mdx index 8c7df3ef7e..5081f9f512 100644 --- a/pages/docs/what-to-track.mdx +++ b/pages/docs/what-to-track.mdx @@ -2,9 +2,9 @@ import ExtendedButton from '/components/ExtendedButton/ExtendedButton' # What to Track -In this guide, we provide guidance on what to track and how to track it. +In this page, we provide guidance on what to track and how to track it. -## Start With 2 Events +## Start With Two Events We recommend starting with just 2 events, which can provide a lot of value with little effort: * **Sign Up** - Tracking Sign Up is a quick way to understand your product's growth; by counting the number @@ -39,6 +39,7 @@ Properties add context to the event. We recommend these properties for your two * A "Message Liked" event may benefit from a "Message Type" property * Ask yourself: What is the most important information related to your value moment? + ## We Recommend Server-Side Tracking Adblockers and browsers are making it harder and harder to track users on the client-side. If you want to make sure the data you're collecting is accurate, you'll want to do most of @@ -61,5 +62,15 @@ Want to learn more? [Read our full guide](/docs/tracking-methods/choosing-the-ri

Next Steps

Once you've chosen a few events to track first, you're ready to set up Mixpanel.



- - \ No newline at end of file + + + +
+

+ +
+

Tracking Plan

+

Outline your events and properties definition in a centralized document as a source of truth on your implementation.

+

+ +
From 94b23014284665a9a61918c2666921a17e819578 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Sun, 23 Jun 2024 14:37:00 -0700 Subject: [PATCH 02/12] Revert "Intro to staging (#1170)" (#1172) This reverts commit d0f5372d34a93c7d7359beb6e67d349f33316f9a. --- pages/docs/quickstart/identify-users.mdx | 20 ++++++++------------ pages/docs/what-is-mixpanel.mdx | 22 ---------------------- pages/docs/what-to-track.mdx | 19 ++++--------------- 3 files changed, 12 insertions(+), 49 deletions(-) diff --git a/pages/docs/quickstart/identify-users.mdx b/pages/docs/quickstart/identify-users.mdx index 85c7bd0355..e9920b548d 100644 --- a/pages/docs/quickstart/identify-users.mdx +++ b/pages/docs/quickstart/identify-users.mdx @@ -9,7 +9,7 @@ import { dataItems } from '/utils/constants'; ## Overview -This step introduces the `identify` method, which allows you to assign an ID to your users. +This step introduces the `identify` method, which allows you to see which users triggered each event in Mixpanel. It also introduces the `people.set` method, which allows you to define the attributes of each user. @@ -41,8 +41,8 @@ mp.people_set('USER_ID', {'$name' : 'Jane Doe', # Add anything else about the user here }) ``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. + +You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) @@ -55,8 +55,6 @@ mixpanel.people.set('USER_ID', { // Add anything else about the user here }); ``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -74,8 +72,8 @@ err := mp.PeopleSet(ctx, []*mixpanel.PeopleProperties{ ) ``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) + ```ruby @@ -87,8 +85,8 @@ mp.people.set('USER_ID', { }); ``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) + ```java @@ -101,8 +99,6 @@ JSONObject update = messageBuilder.set("USER_ID", props); // Send the update to mixpanel mixpanel.sendMessage(update); ``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -283,4 +279,4 @@ or user profile update. Examples include: location, operating system, device, et For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission through the AppTrackingTransparency(ATT) framework. For more details, refer to our [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details). - + \ No newline at end of file diff --git a/pages/docs/what-is-mixpanel.mdx b/pages/docs/what-is-mixpanel.mdx index e05108a56f..fdee0fc0c8 100644 --- a/pages/docs/what-is-mixpanel.mdx +++ b/pages/docs/what-is-mixpanel.mdx @@ -71,25 +71,3 @@ Now that you understand the basics, **we recommend planning the first events you

- -

-

-

- -
-

Explore a demo dataset

-

Register for a free account to explore a full demo of Mixpanel. If you make a Board and like it, you can move it into your own project and add your own data.

-

- -
- -

-

-

- -
-

Get an in-depth product demo

-

Want to see how Mixpanel can help your team build better products? Schedule a live demo with our product analytics experts.

-

- -
diff --git a/pages/docs/what-to-track.mdx b/pages/docs/what-to-track.mdx index 5081f9f512..8c7df3ef7e 100644 --- a/pages/docs/what-to-track.mdx +++ b/pages/docs/what-to-track.mdx @@ -2,9 +2,9 @@ import ExtendedButton from '/components/ExtendedButton/ExtendedButton' # What to Track -In this page, we provide guidance on what to track and how to track it. +In this guide, we provide guidance on what to track and how to track it. -## Start With Two Events +## Start With 2 Events We recommend starting with just 2 events, which can provide a lot of value with little effort: * **Sign Up** - Tracking Sign Up is a quick way to understand your product's growth; by counting the number @@ -39,7 +39,6 @@ Properties add context to the event. We recommend these properties for your two * A "Message Liked" event may benefit from a "Message Type" property * Ask yourself: What is the most important information related to your value moment? - ## We Recommend Server-Side Tracking Adblockers and browsers are making it harder and harder to track users on the client-side. If you want to make sure the data you're collecting is accurate, you'll want to do most of @@ -62,15 +61,5 @@ Want to learn more? [Read our full guide](/docs/tracking-methods/choosing-the-ri

Next Steps

Once you've chosen a few events to track first, you're ready to set up Mixpanel.



- - - -
-

- -
-

Tracking Plan

-

Outline your events and properties definition in a centralized document as a source of truth on your implementation.

-

- -
+ + \ No newline at end of file From ba3feb44e68c4103ec2f1cea50771e408a96a6db Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Sun, 23 Jun 2024 14:48:56 -0700 Subject: [PATCH 03/12] Intro -> Staging (#1173) * Update what-is-mixpanel.mdx Add Demo/Registration CTA * Update what-is-mixpanel.mdx * Update what-is-mixpanel.mdx * Update what-to-track.mdx * Update identify-users.mdx * Update identify-users.mdx * Update identify-users.mdx --- pages/docs/quickstart/identify-users.mdx | 19 +++++++++++++------ pages/docs/what-is-mixpanel.mdx | 22 ++++++++++++++++++++++ pages/docs/what-to-track.mdx | 19 +++++++++++++++---- 3 files changed, 50 insertions(+), 10 deletions(-) diff --git a/pages/docs/quickstart/identify-users.mdx b/pages/docs/quickstart/identify-users.mdx index e9920b548d..9fcb2c443b 100644 --- a/pages/docs/quickstart/identify-users.mdx +++ b/pages/docs/quickstart/identify-users.mdx @@ -9,7 +9,7 @@ import { dataItems } from '/utils/constants'; ## Overview -This step introduces the `identify` method, which allows you to see which users triggered each event in Mixpanel. +This step introduces the `identify` method, which allows you to assign an ID to your users. It also introduces the `people.set` method, which allows you to define the attributes of each user. @@ -41,8 +41,8 @@ mp.people_set('USER_ID', {'$name' : 'Jane Doe', # Add anything else about the user here }) ``` - -You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -55,6 +55,8 @@ mixpanel.people.set('USER_ID', { // Add anything else about the user here }); ``` +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -72,7 +74,9 @@ err := mp.PeopleSet(ctx, []*mixpanel.PeopleProperties{ ) ``` -You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. + @@ -85,7 +89,8 @@ mp.people.set('USER_ID', { }); ``` -You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -99,6 +104,8 @@ JSONObject update = messageBuilder.set("USER_ID", props); // Send the update to mixpanel mixpanel.sendMessage(update); ``` +Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. +You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. @@ -279,4 +286,4 @@ or user profile update. Examples include: location, operating system, device, et For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission through the AppTrackingTransparency(ATT) framework. For more details, refer to our [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details). - \ No newline at end of file + diff --git a/pages/docs/what-is-mixpanel.mdx b/pages/docs/what-is-mixpanel.mdx index fdee0fc0c8..e05108a56f 100644 --- a/pages/docs/what-is-mixpanel.mdx +++ b/pages/docs/what-is-mixpanel.mdx @@ -71,3 +71,25 @@ Now that you understand the basics, **we recommend planning the first events you

+ +

+

+

+ +
+

Explore a demo dataset

+

Register for a free account to explore a full demo of Mixpanel. If you make a Board and like it, you can move it into your own project and add your own data.

+

+ +
+ +

+

+

+ +
+

Get an in-depth product demo

+

Want to see how Mixpanel can help your team build better products? Schedule a live demo with our product analytics experts.

+

+ +
diff --git a/pages/docs/what-to-track.mdx b/pages/docs/what-to-track.mdx index 8c7df3ef7e..5081f9f512 100644 --- a/pages/docs/what-to-track.mdx +++ b/pages/docs/what-to-track.mdx @@ -2,9 +2,9 @@ import ExtendedButton from '/components/ExtendedButton/ExtendedButton' # What to Track -In this guide, we provide guidance on what to track and how to track it. +In this page, we provide guidance on what to track and how to track it. -## Start With 2 Events +## Start With Two Events We recommend starting with just 2 events, which can provide a lot of value with little effort: * **Sign Up** - Tracking Sign Up is a quick way to understand your product's growth; by counting the number @@ -39,6 +39,7 @@ Properties add context to the event. We recommend these properties for your two * A "Message Liked" event may benefit from a "Message Type" property * Ask yourself: What is the most important information related to your value moment? + ## We Recommend Server-Side Tracking Adblockers and browsers are making it harder and harder to track users on the client-side. If you want to make sure the data you're collecting is accurate, you'll want to do most of @@ -61,5 +62,15 @@ Want to learn more? [Read our full guide](/docs/tracking-methods/choosing-the-ri

Next Steps

Once you've chosen a few events to track first, you're ready to set up Mixpanel.



- - \ No newline at end of file + + + +
+

+ +
+

Tracking Plan

+

Outline your events and properties definition in a centralized document as a source of truth on your implementation.

+

+ +
From e5bb44caf6caf47f2c8035882292f3feb1fdee07 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Mon, 24 Jun 2024 00:12:30 -0700 Subject: [PATCH 04/12] Myronkaifung content reorg data in (#1177) * Update user-profiles.md * Update user-profiles.md Clean up vocab FAQ for empty profiles * Update property-reference.md super properties = event properties call out * Create _meta.json * Create data-type.md * Update property-reference.md * Create default-properties.md * Update user-profiles.md * Update events-and-properties.md * Create reserved-properties.md * Update _meta.json * Rename pages/docs/data-structure/advanced/group-analytics.mdx to pages/docs/data-structure/group-analytics.mdx * Update and rename pages/docs/data-structure/advanced/utm-tags.md to pages/docs/tracking-best-practices/traffic-attribution.md * Update javascript.md * Rename ad-spend.md to ad-spend.md * Update _meta.json * Delete pages/docs/data-structure/advanced directory * Update _meta.json * Update integrations.mdx * Create sdks.mdx * Update _meta.json * Update android.md * Update flutter.md * Update go.md * Update ios.md * Update java.md * Update javascript.md * Update react-native.md * Update ruby.md * Update swift.md * Update unity.md * Update integrations.mdx * Update segment.md * Update google-tag-manager.mdx * Create id-management.md * Create original-id-merge.md * Update _meta.json * Create simplified-id-merge.md * Update server-side-best-practices.md * Update simplified-id-merge.md * Create server-side-id-management.md * Update server-side-id-management.md * Update _meta.json * Create geolocation.md * Update bot-traffic.mdx * Update tracking-plan.md --- pages/docs/data-structure/_meta.json | 4 +- pages/docs/data-structure/advanced/_meta.json | 5 - .../data-structure/events-and-properties.md | 39 --- .../{advanced => }/group-analytics.mdx | 0 .../docs/data-structure/property-reference.md | 160 +-------- .../property-reference/_meta.json | 5 + .../property-reference/data-type.md | 329 ++++++++++++++++++ .../property-reference/default-properties.md | 108 ++++++ .../property-reference/reserved-properties.md | 54 +++ pages/docs/data-structure/user-profiles.md | 66 ++-- .../tracking-best-practices/bot-traffic.mdx | 6 +- .../tracking-best-practices/geolocation.md | 152 ++++++++ .../server-side-best-practices.md | 55 --- .../tracking-best-practices/tracking-plan.md | 4 +- .../traffic-attribution.md} | 9 +- pages/docs/tracking-methods/id-management.md | 48 +++ .../tracking-methods/id-management/_meta.json | 9 +- .../id-management/original-id-merge.md | 123 +++++++ .../server-side-id-management.md | 58 +++ .../id-management/simplified-id-merge.md | 118 +++++++ pages/docs/tracking-methods/integrations.mdx | 5 +- .../tracking-methods/integrations/_meta.json | 1 + .../integrations}/ad-spend.md | 0 .../integrations/google-tag-manager.mdx | 9 + .../tracking-methods/integrations/segment.md | 24 +- pages/docs/tracking-methods/sdks.mdx | 36 ++ pages/docs/tracking-methods/sdks/_meta.json | 7 +- pages/docs/tracking-methods/sdks/android.md | 70 ++-- pages/docs/tracking-methods/sdks/flutter.md | 29 +- pages/docs/tracking-methods/sdks/go.md | 20 +- pages/docs/tracking-methods/sdks/ios.md | 51 +-- pages/docs/tracking-methods/sdks/java.md | 36 -- .../docs/tracking-methods/sdks/javascript.md | 19 +- .../tracking-methods/sdks/react-native.md | 21 +- pages/docs/tracking-methods/sdks/ruby.md | 32 +- pages/docs/tracking-methods/sdks/swift.md | 45 ++- pages/docs/tracking-methods/sdks/unity.md | 29 +- 37 files changed, 1313 insertions(+), 473 deletions(-) delete mode 100644 pages/docs/data-structure/advanced/_meta.json rename pages/docs/data-structure/{advanced => }/group-analytics.mdx (100%) create mode 100644 pages/docs/data-structure/property-reference/_meta.json create mode 100644 pages/docs/data-structure/property-reference/data-type.md create mode 100644 pages/docs/data-structure/property-reference/default-properties.md create mode 100644 pages/docs/data-structure/property-reference/reserved-properties.md create mode 100644 pages/docs/tracking-best-practices/geolocation.md rename pages/docs/{data-structure/advanced/utm-tags.md => tracking-best-practices/traffic-attribution.md} (90%) create mode 100644 pages/docs/tracking-methods/id-management.md create mode 100644 pages/docs/tracking-methods/id-management/original-id-merge.md create mode 100644 pages/docs/tracking-methods/id-management/server-side-id-management.md create mode 100644 pages/docs/tracking-methods/id-management/simplified-id-merge.md rename pages/docs/{data-structure/advanced => tracking-methods/integrations}/ad-spend.md (100%) create mode 100644 pages/docs/tracking-methods/sdks.mdx diff --git a/pages/docs/data-structure/_meta.json b/pages/docs/data-structure/_meta.json index bab81f8d94..0074fb8daa 100644 --- a/pages/docs/data-structure/_meta.json +++ b/pages/docs/data-structure/_meta.json @@ -2,7 +2,7 @@ "concepts": "Concepts", "events-and-properties": "Events & Properties", "user-profiles": "User Profiles", + "group-analytics": "Group Analytics", "lookup-tables": "Lookup Tables", - "property-reference": "Property Reference", - "advanced": "Advanced" + "property-reference": "Property Reference" } diff --git a/pages/docs/data-structure/advanced/_meta.json b/pages/docs/data-structure/advanced/_meta.json deleted file mode 100644 index 3bb718dbf0..0000000000 --- a/pages/docs/data-structure/advanced/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "ad-spend": "Ad Spend", - "group-analytics": "Group Analytics", - "utm-tags": "UTM Tags" -} diff --git a/pages/docs/data-structure/events-and-properties.md b/pages/docs/data-structure/events-and-properties.md index 7198857660..51653fbcef 100644 --- a/pages/docs/data-structure/events-and-properties.md +++ b/pages/docs/data-structure/events-and-properties.md @@ -59,45 +59,6 @@ For example, don't create an event name like `Purchase (11-01-2019)`. Instead, c > **Tip:** Learn more best practices around defining your events and properties under our tutorials for [Creating a Tracking Plan](/docs/tutorials/plan/tracking-strategy#tracking-plan-methodology). -## Reserved Event Properties - -Mixpanel reserves certain event property names for special processing or for specific system features. These properties, when populated, will affect the way Mixpanel processes your data. - -> **Note:** Also refer to the list of Mixpanel [Default Properties](/docs/data-structure/property-reference#default-properties) indicated in our documentation. - -| **Raw Name** | **Display Name** | **Description** | -| ------------ | ---------------- | --------------- | -| token | - | The project's token when sending data via [/track API](https://developer.mixpanel.com/reference/track-event). Not visible via Mixpanel UI reports. | -| ip | - | The `ip` event property is the value to be used for geo location parsing (i.e. `$city`, `$region`, and `mp_country_code`) if `ip` as param to the [/track endpoint](https://developer.mixpanel.com/reference/track-event) has **not been** set to 1. Our client-side libraries, by default, will set the `ip` param to 1 so geo location is parsed from the incoming request, but this can be disabled or, if you're implementing from the [server-side](/docs/best-practices/server-side-best-practices#tracking-geolocation-http-api), you can include the `ip` event property so it's parsed from it instead of the IP of the incoming request. The `ip` event property is not stored in Mixpanel. | -| $bucket / bucket | - | A reserved property that is hidden from the Mixpanel interface, and will cause other events to not appear in the interface. Do not name any property bucket or $bucket. | -| $distinct_id / distinct_id | Distinct ID | Mixpanel's internal unique identifier for a user. See [Identifying Users](/docs/tracking-methods/id-management/identifying-users). | -| $device_id | Device ID | In [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users#example-user-flows): unique identifier used to track a device while the user is in anynymous state. | -| $user_id | User ID | In [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users#example-user-flows): unique identifier used to track a user across devices when user is in identified state. | -| $event_name | Event Name | Name of the tracked event used in the Mixpanel UI. | -| $time / time | Time or Date | A unix time epoch that is used to determine the time of an event. If no time property is provided, we will use the time when the event arrives at our servers. | -| $insert_id | Insert ID | A unique identifier for the event, used to deduplicate events that are accidentally sent multiple times. More details [here](https://developer.mixpanel.com/reference/import-events#propertiesinsert_id). | -| $identified_id | Identified ID | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the identifier passed into the [`$identify`](https://developer.mixpanel.com/reference/create-identity) event. | -| $anon_id | Anonymous ID | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the anonymous ID passed into the [`$identify`](https://developer.mixpanel.com/reference/create-identity) event. | -| alias | Alias | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the alias passed into the [`$create_alias`](https://developer.mixpanel.com/reference/identity-create-alias) event. | -| $distinct_ids | Distinct Ids | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the distinct IDs passed into the [`$merge`](https://developer.mixpanel.com/reference/identity-merge) event. | -| $distinct_id_before_identity | Distinct ID Before Identity | Internal Mixpanel property to track an event's original $distinct_id before it was updated due to identity merging. Used in [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge) and [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge). | -| $is_reshuffled | Is Reshuffled | Internal Mixpanel property to denote an event was reshuffled (sets to true if original $distinct_id was updated) due to identity merging. Used in [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge) and [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge). | -| $failure_description | Failure Description | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Mixpanel property explaining in detail why identity merging was not executed. | -| $failure_reason | Failure Reason | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Mixpanel property summarizing why identity merging was not executed. | -| $identity_failure_reason | Identity Failure Reason | In [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge): Mixpanel property summarizing why identity merging was not executed. | -|mp_original_distinct_id | Hotshard Original Distinct ID | Original $distinct_id for an event that was identified as contributing to a [hot shard](https://docs.mixpanel.com/docs/debugging/distinct-id-limits#what-is-a-hot-shard). | -| mp_original_event_name | Hotshard Original Event Name | Original $event_name for an event that was identified as contributing to [hot shard](https://docs.mixpanel.com/docs/debugging/distinct-id-limits#what-is-a-hot-shard). | -| $source | Source | Hidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under [Cohort Sync -> Integrations](/docs/cohort-sync/integrations/airship). | -| $partner_id | Partner Id | Hidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under [Cohort Sync -> Integrations](/docs/cohort-sync/integrations/airship). | -| $warehouse_type | Warehouse Type | The type of the warehouse sync setup to send the event. See [Supported Warehouses](/docs/tracking-methods/data-warehouse/overview#supported-warehouses). | -| $warehouse_import_id | Warehouse Import ID | The ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/data-warehouse/overview). | -| $warehouse_import_job_id | Warehouse Import Job ID | The internal Mixpanel Job ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/data-warehouse/overview). | -| $warehouse_import_run_id | Warehouse Import Run ID | The internal Mixpanel Run ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/data-warehouse/overview). | -| $duration_s | Session Duration (Seconds) | The duration between Session Start and Session End events in seconds. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | -| $event_count | Session Event Count | The number of events during a session (i.e. Session Start and Session End). This does not include [Excluded Events](/docs/features/sessions#excluded-events) and [Hidden Events](/docs/data-governance/lexicon#hide-events-and-properties) in Lexicon. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | -| $origin_start | Session Start Event Name | The original event name that triggered Session Start event. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | -| $origin_end | Session End Event Name | The original event name that triggered Session End event. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | - ## FAQ ### What types of data can I send as properties? diff --git a/pages/docs/data-structure/advanced/group-analytics.mdx b/pages/docs/data-structure/group-analytics.mdx similarity index 100% rename from pages/docs/data-structure/advanced/group-analytics.mdx rename to pages/docs/data-structure/group-analytics.mdx diff --git a/pages/docs/data-structure/property-reference.md b/pages/docs/data-structure/property-reference.md index db17b3948d..54bf6d98ec 100644 --- a/pages/docs/data-structure/property-reference.md +++ b/pages/docs/data-structure/property-reference.md @@ -7,169 +7,11 @@ Mixpanel has many Properties defined in its Data Model. | **Property Type** | **Description** | | ----------------- | --------------- | | [Event Properties](/docs/data-structure/events-and-properties) | Event Properties describes the events that are tracked within your product. | -| [Super Properties](/docs/tracking-methods/sdks/javascript#super-properties) | Super Properties are a logical term for global Event Properties that, after registration, are saved into the end user's device, and appended to every event from that device until persistence is cleared. This logical term is mostly applicable to our client-side libraries. | +| [Super Properties](/docs/tracking-methods/sdks/javascript#super-properties) | Super Properties are a logical term for global Event Properties that, after registration, are saved into the end user's device, and appended to every event from that device until persistence is cleared. This logical term is mostly applicable to our client-side libraries. Super Properties are indistinguishable from Event Properties after entering your project. | | [User Profile Properties](/docs/data-structure/user-profiles) | User Profile Properties describe your users (they typically store current demographical information). User profiles are joined to events based on [Distinct ID](/docs/tracking-methods/identifying-users#what-is-distinct-id). | | [Group Profile Properties](/docs/data-structure/advanced/group-analytics#group-profiles) | Group Profile Properties describe group level information (similar to User Profiles Properties at user level). With Mixpanel’s [Group Analytics](/docs/data-structure/advanced/group-analytics), multiple users can be grouped and behavioural data analysed at a customised group level (such as company, account). Group profiles are joined to events on your chosen [Group Key](/docs/data-structure/advanced/group-analytics#group-keys-tracked-as-event-properties). | | [Lookup Tables](/docs/data-structure/lookup-tables) | Lookup Tables allow you to dynamically extend additional properties mapped to an existing Event or User Property. For example, if you create a lookup table for "Songs" (that contains additional properties like `hash_tags`, `top_10`, `all_time_favorite`) and map it to an event property `song_id`; you can use these additional properties when doing filtering or breakdowns for events that has `song_id` as an event property. | | [Default Properties](/docs/data-structure/property-reference#default-properties) | Default Properties (for Events and User Profiles) are collected and populated with values automatically in Mixpanel. This can happen upon data ingestion or when using certain Mixpanel client-side SDKs. Typically, they have a dollar sign ($) or “mp\_” as prefix to distinguish them from normal properties. | | Reserved Properties | Mixpanel reserves certain property names (for [Events](/docs/data-structure/events-and-properties#reserved-event-properties) and [User Profiles](/docs/data-structure/user-profiles#reserved-user-properties)) for special use cases, and these may or may not be automatically populated with values. The purpose of such Reserved Properties are for processing (ie event time stamping) or for specific system features (eg: cohort exports). Examples: `time`, `$email`, `$phone`, `$name`, `$created`. | -## Default Properties -Mixpanel's [Data Ingestion APIs](https://developer.mixpanel.com/reference/ingestion-api) and [Client-Side SDKs](/docs/tracking-methods/choosing-the-right-method#client-side-tracking) automatically collect certain properties on every event or user profile. Do also note that some Customer Data Platforms (CDPs) that integrate with Mixpanel may also map their own properties to Mixpanel default properties. This document describes what those properties mean. -### Ingestion APIs - -To disable capturing of geolocation properties (i.e. City, Region, Country) refer to the respective SDKs or API documentation. For a quick reference, refer to examples on [disabling geolocation on client-side SDKs](/docs/privacy/protecting-user-data#disabling-geolocation) and [server-side best practice on tracking geolocation](/docs/best-practices/server-side-best-practices#tracking-geolocation-http-api). - -#### Event Properties - -| **Raw Name** | **Display Name** | **Description** | -| ------------ | ---------------- | --------------- | -| $city | City | The city of the event sender parsed from the IP property or the Latitude and Longitude properties. | -| $region | Region | The region (state or province) of the event sender parsed from the IP property or the Latitude and Longitude properties. | -| mp_country_code | Country | The country of the event sender parsed from the IP property or the Latitude and Longitude properties. The value is stored as a 2-letter country code in the raw data and parsed into the country name in the UI. | -| $mp_api_endpoint | API Endpoint | Mixpanel property to record the API endpoint the data was sent to:
**api.mixpanel.com** - default ingestion
**api-eu.mixpanel.com** - EU data ingestion
**api-js.mixpanel.com** - Javascript SDK | -| $import | Import | Internal Mixpanel property set to `true` to indicate that events were sent through [/import API](https://developer.mixpanel.com/reference/import-events). | -| $mp_api_timestamp_ms | API Timestamp | UTC timestamp in milliseconds when the event was received by our API. | -| mp_processing_time_ms | Time Processed (UTC) | UTC timestamp in milliseconds when the event was processed by Mixpanel servers. | - -#### User Properties - -Do note that Mixpanel's default user properties are only updated when you send or update at least one property yourself (via [\$set](https://developer.mixpanel.com/reference/profile-set) or [\$set_once](https://developer.mixpanel.com/reference/profile-set-property-once) operations). Please, refer to this article to [understand how to send or update profile properties](/docs/data-structure/user-profiles). - -| **Raw Name** | **Display Name** | **Description** | -| ------------ | ---------------- | --------------- | -| $city | City | The city of the user parsed from the IP property or the Latitude and Longitude properties. | -| $region | Region | The region (state or province) of the user parsed from the IP property or the Latitude and Longitude properties. | -| $country_code | Country Code | The country of the user parsed from the IP property or the Latitude and Longitude properties. The value is stored as a 2-letter country code in the raw data and parsed into the country name in the UI. | -| $geo_source | Geo Source | Set to "reverse_geocoding" if profile geolocation properties (Country Code, Region, and City) were determined through [Latitude and Longitude](/docs/best-practices/server-side-best-practices#tracking-geolocation-latitude-and-longitude). | -| $timezone | Timezone | Timezone of the user parsed from the IP property or the Latitude and Longitude properties. | -| $last_seen | Updated at | The last time a user profile property was set or updated **(this should not be set manually)**. Passing `$ignore_time` as `true`, typically for server-side updates, will skip updating the $last_seen property. See example [here](/docs/tracking-methods/sdks/php#setting-profile-properties). | - - -### Client-side SDKs - -Note that the following SDKs wrap around our other SDKs; and as such, would also inherit the appropriate default properties from these wrapped SDKs indicated in the tables below: -- [React Native](/docs/tracking-methods/sdks/react-native) wraps around Android and Swift SDK; `mp_lib` will be set to `react-native` with `$lib_version` set as React Native's library version. -- [Flutter](/docs/tracking-methods/sdks/flutter) wraps around Javscript, Android, and Swift SDK; `mp_lib` will be set to `flutter` with `$lib_version` set as the Flutter's library version. - -#### Event Properties - -| **Raw Name** | **Display Name** | **Description**
*Scroll right to see more columns -->* | **[Javascript](/docs/tracking-methods/sdks/javascript)** | **[Android](/docs/tracking-methods/sdks/android)** | **iOS [Objective-C](/docs/tracking-methods/sdks/ios) / [Swift](/docs/tracking-methods/sdks/swift)** | **[Unity](/docs/tracking-methods/sdks/unity)** | -| -------- | ------------ | ----------- | :-----------: | :-----------: | :-----------: | :-----------: | -| $device_id | Device ID | Autogenerated ID that is local to the device. Calling reset() regenerates this value. More details [here](/docs/tracking-methods/identifying-users). | ✅ | ✅ | ✅ | ❌ | -| $user_id | User ID | The identified ID of the user. Calling identify() sets this. More details [here](/docs/tracking-methods/identifying-users). | ✅ | ✅ | ✅ | ❌ | -| $insert_id | Insert ID | A unique identifier for the event, used to deduplicate events that are accidentally sent multiple times. More details [here](https://developer.mixpanel.com/reference/import-events#propertiesinsert_id). | ✅ | ✅ | ✅ | ✅ | -| mp_lib | Mixpanel Library | The Mixpanel library that sent the event. | `web` | `android` | `iphone` / `swift` | `unity` | -| $lib_version | Library Version | Mixpanel library version. | ✅ | ✅ | ✅ | ✅ | -| mp_sent_by_lib_version | Sent By Library Version | Mixpanel library version used to send data (not necessarily the same as the version which enqueued the data). | ✅ | ❌ | ❌ | ❌ | -| $os | Operating System | OS of the event sender. | ✅ | ✅ | ✅ | ✅ | -| $os_version | OS Version | The current version of operating system on the device. | ❌ | ✅ | ✅ | ✅ | -| $browser | Browser | Name of the browser. | ✅ | ❌ | ❌ | ❌ | -| $browser_version | Browser Version | Version of the browser. | ✅ | ❌ | ❌ | ❌ | -| $app_build_number | App Build Number | General build of the app. | ❌ | ✅ | ✅ | ❌ | -| $app_version_string | App Version | Current app version. | ❌ | ✅ | ✅ | ✅ | -| $device | Device | Name of the event sender’s device, if they’re on mobile web. | ✅ | ❌ | ❌ | ✅ | -| $screen_height | Screen Height | The height of the device screen in pixels / points (iOS). | ✅ | ✅ | ✅ | ✅ | -| $screen_width | Screen Width | The width of the device screen in pixels / points (iOS). | ✅ | ✅ | ✅ | ✅ | -| $screen_dpi | Screen DPI | Pixel density of the device screen. | ❌ | ✅ | ❌ | ✅ | -| $current_url | Current URL | The URL of the page on which the event was tracked. | ✅ | ❌ | ❌ | ❌ | -| $initial_referrer | Initial Referrer | Referring URL when the user first arrived on your site. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | -| $initial_referring_domain | Initial Referring Domain | Referring domain at first arrival. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | -$referrer | Referrer | Referring URL including your own domain. Might not be present if document.referrer does not return a value. As opposed to \$initial_referrer and \$initial_referring_domain, this property will be omitted if the user lands directly or the referring website adds the rel="noreferrer" parameter. | ✅ | ❌ | ❌ | ❌ | -| $referring_domain | Referring Domain | Referring domain including your own domain. Might not be present if document.referrer does not return a value. As opposed to \$initial_referrer and \$initial_referring_domain, this property will be omitted if the user lands directly or the referring website adds the rel="noreferrer" parameter. | ✅ | ❌ | ❌ | ❌ | -| $search_engine | Search Engine | The search engine that the customer used when they arrived at your domain. | ✅ | ❌ | ❌ | ❌ | -| mp_keyword | Search Keyword | Search keywords detected on the referrer from a search engine to your domain. This property is only collected when search keywords are included in a URL. | ✅ | ❌ | ❌ | ❌ | -| utm_source, utm_medium, etc. | UTM Parameters | UTM tags derived from the URL a customer clicked to arrive at your domain. Each UTM will be collected under its own property. More details [here](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters). | ✅ | ❌ | ❌ | ❌ | -| $manufacturer | Manufacturer | Device manufacturer. | ❌ | ✅ | ✅ | ✅ | -| $brand | Brand | Device brand. | ❌ | ✅ | ❌ | ❌ | -| $model | Model | The model of the device. | ❌ | ✅ | ✅ | ✅ | -| $watch_model | Watch Model | The model of the iOS watch. | ❌ | ❌ | ✅ | ❌ | -| $carrier | Carrier | Wireless carrier of the device owner. | ❌ | ✅ | ✅ | ❌ | -| $radio | Radio | Current [cellular network communication standard](https://www.objc.io/issues/5-ios7/iOS7-hidden-gems-and-workarounds/#know-your-radio)(opens in a new tab) (3G, 4G, LTE, etc). | ❌ | ❌ | ✅ | ✅ | -| $wifi | Wifi | Set to true if the user’s device has an active, available Wifi connection, false if not. | ❌ | ✅ | ✅ | ✅ | -| $bluetooth_enabled | Bluetooth | Set to true if Bluetooth is enabled, false if not. | ❌ | ✅ | ❌ | ❌ | -| $bluetooth_version | Bluetooth Version | Set to "none", "ble", or "classic". | ❌ | ✅ | ❌ | ❌ | -| $has_nfc | Has NFC | Set to true if Near Field Communication is being used, false if not. | ❌ | ✅ | ❌ | ❌ | -| $has_telephone | Has Telephone | Set to true if this device has telephone functionality, false if not. | ❌ | ✅ | ❌ | ❌ | -| $google_play_services | Google Play Services | Verifies that Google Play services is installed and enabled on this device, and that the version installed on this device is no older than the one required by this client. | ❌ | ✅ | ❌ | ❌ | -| $duration | Duration | A property that is appended to an event to capture the elapsed time (in seconds) between a `time_event` and a `track` call. See [time_event](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltime_event) in Javascript SDK for example. | ✅ | ✅ | ✅ | ✅ | - -#### User Properties - -Do note that Mixpanel's default user properties are only updated when you send or update at least one property yourself (via [\$set](https://developer.mixpanel.com/reference/profile-set) or [\$set_once](https://developer.mixpanel.com/reference/profile-set-property-once) operations). Please, refer to this article to [understand how to send or update profile properties](/docs/data-structure/user-profiles). - -| **Raw Name** | **Display Name** | **Description**
*Scroll right to see more columns -->* | **[Javascript](/docs/tracking-methods/sdks/javascript)** | **[Android](/docs/tracking-methods/sdks/android)** | **iOS [Objective-C](/docs/tracking-methods/sdks/ios) / [Swift](/docs/tracking-methods/sdks/swift)** | **[Unity](/docs/tracking-methods/sdks/unity)** | -| -------- | ------------ | ----------- | :-----------: | :-----------: | :-----------: | :-----------: | -| $lib_version | Library Version | Last used Mixpanel library version (also applies to React Native and Flutter wrapper SDKs). | ❌ | ❌ | ❌ | ✅ | -| $android_lib_version | Android Lib Version | Last used Mixpanel Android / Unity library version. | ❌ | ✅ | ❌ | ✅ | -| $ios_lib_version | iOS Lib Version | Last used Mixpanel iOS / Unity library version. | ❌ | ❌ | ✅ | ✅ | -| $swift_lib_version | Swift Lib Version | Last used Mixpanel Swift library version. | ❌ | ❌ | ✅ | ❌ | -| $os | Operating System | Last OS of the event sender. | ✅ | ✅ | ✅ | ✅ | -| $android_os | Android OS | Set when Android operating system was used. | ❌ | ✅ | ❌ | ✅ | -| $android_os_version | Android OS Version | Last version of Android on the device. | ❌ | ✅ | ❌ | ✅ | -| $ios_version | iOS Version | Last version of iOS on the device. | ❌ | ❌ | ✅ | ✅ | -| $browser | Browser | Name of the browser. | ✅ | ❌ | ❌ | ❌ | -| $browser_version | Browser Version | Version of the browser. | ✅ | ❌ | ❌ | ❌ | -| $android_app_version | Android App Version | Current Android app version ([versionName](https://developer.android.com/studio/publish/versioning)). | ❌ | ✅ | ❌ | ✅ | -| $android_app_version_code | Android App Version Code | Current Android app version code ([versionCode](https://developer.android.com/studio/publish/versioning)). | ❌ | ✅ | ❌ | ❌ | -| $ios_app_release | iOS App Release | The release or version number of the iOS app ([CFBundleShortVersionString](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleshortversionstring)). | ❌ | ❌ | ✅ | ✅ | -| $ios_app_version | iOS App Version | The version of the build that identifies an iteration of the iOS app ([CFBundleVersion](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleversion)). | ❌ | ❌ | ✅ | ❌ | -| $initial_referrer | Initial Referrer | Referring URL when the user first arrived on your site. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | -| $initial_referring_domain | Initial Referring Domain | Referring domain at first arrival. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | -| initial_utm_source, initial_utm_medium, etc. | Initial UTM Parameters | UTM tags seen for the first time from the URL a customer clicked to arrive at your domain. Each UTM will be collected under its own property. More details [here](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters). | ✅ | ❌ | ❌ | ❌ | -| $android_manufacturer | Android Manufacturer | Android device manufacturer. | ❌ | ✅ | ❌ | ❌ | -| $android_brand | Android Brand | Android device brand. | ❌ | ✅ | ❌ | ❌ | -| $android_model | Android Model | The model of the Anroid device. | ❌ | ✅ | ❌ | ✅ | -| $ios_device_model | iOS Device Model | The model of the iOS device. | ❌ | ❌ | ✅ | ✅ | - -## Supported Data Types - -Mixpanel supports five data types for properties: String, Numeric, Boolean, Date and List. By choosing the most suitable data type for your properties, you'd be able to apply a set of operators that are most relevant to your properties in Mixpanel reports, and this will give you richer insights about your data. - -### String - -- Alphanumeric value e.g. Plan Type = "Free", Artist Name = "Bruno Mars" -- String properties have a character limit of 255 bytes. -- Mixpanel will treat any property value that doesn’t match any other data type as a String. - -### Numeric - -- Numeric (integer or decimal) value e.g. Cost = 15.00, Quantity = 5 -- You can apply operators such as sum, median and percentile on numeric properties. - -### Boolean - -- Mixpanel treats properties as boolean if the value is either the JSON constant `true` or `false` e.g. Favorited = true, Bookmarked = false. -- On Mixpanel, you can typecast any non-boolean property to boolean, -- "false", 0, null, undefined, and empty string will be typecasted to boolean `false` -- "true" and any set value that is not 0 or empty string will be typecasted to boolean `true` - -### Date - -- An ISO formatted date `YYYY-MM-DDTHH:MM:SS` in UTC e.g. Last Purchase = "2022-10-30T13:30:25", Last Login = "2022-10-29". Note that all timestamps need to be sent in UTC timezone in an ISO format. -- Mixpanel treats unix timestamps as Numeric property, however, you can typecast it to Date data type. - -### List - -- A list of values as a JSON array e.g Favourite Genres = ["Folk","Alternative"] or Favourite Numbers = [1,5,10.0] -- Limits of a List property: Event Property = 8KB, User Profile Property = 256KB -- Each item in a list would be futher limited by their data type's limits; example: a list of strings would be limited by 255 bytes per string. Also refer to [List of Objects](/docs/data-structure/property-reference#list-of-objects) covered below. -- Mixpanel lists are not ordered (i.e. position of values in a list are not significant in Mixpanel reports) and are useful for grouping or analysing similar values across events. Read more details on [List Property Support](/docs/features/advanced#list-property-support) in reports. - -## Object and List of Objects Data Types - -Mixpanel also supports object and [list of objects](/docs/features/advanced#list-of-objects-property-support) data types in a limited capacity. These are typically for very specific use cases such as in e-commerce (eg Cart Items, Search Filters). It is highly encouraged that you use the five primary data types as they are fully supported in the Mixpanel UI. - -### Object - -- Arbitrarily-nested groups of JSON key-value pairs e.g. Experiments = {"Exp Onboarding":"Quick","Exp Checkout":"Without Coupon"} -- Limits of a Object property: Event Property = 8KB, User Profile Property = 256KB, max 255 keys per nested object with a max nesting depth of 3 -- Mainly supported in core reports (i.e. Insights, Funnels, Flows, Retention, Users / Cohorts, Events) as filters and breakdowns. Property Names (ie keys) within an object are not supported in Lexicon. - -### List of Objects - -- A JSON array of 1 level JSON objects with each object having similar sets of key-value pairs e.g. Cart = [{"Brand":"Puma","Category":"Jacket","Price":30}, {"Brand":"Adidas","Category":"Hats","Price":15}] -- Limits of a List of Objects: Event Property = 8KB, User Profile Property = 256KB, max 255 keys and no nesting -- By default, only the first 5 objects within the list will be parsed in Mixpanel UI, more details [here](/docs/features/advanced#limits-1). -- Mainly supported in core reports (i.e. Insights, Funnels, Flows, Retention, Users / Cohorts, Events) as filters and breakdowns. Property Names (ie keys) within an object are not supported in Lexicon. diff --git a/pages/docs/data-structure/property-reference/_meta.json b/pages/docs/data-structure/property-reference/_meta.json new file mode 100644 index 0000000000..44b5c3fbcd --- /dev/null +++ b/pages/docs/data-structure/property-reference/_meta.json @@ -0,0 +1,5 @@ +{ + "data-type": "Data Type", + "default-properties": "Default Properties", + "reserved-properties": "Reserved Properties" +} diff --git a/pages/docs/data-structure/property-reference/data-type.md b/pages/docs/data-structure/property-reference/data-type.md new file mode 100644 index 0000000000..60ecc7644d --- /dev/null +++ b/pages/docs/data-structure/property-reference/data-type.md @@ -0,0 +1,329 @@ +# Data Types + +## Overview +Mixpanel supports five data types for properties: String, Numeric, Boolean, Date and List. By choosing the most suitable data type for your properties, you'd be able to apply a set of operators that are most relevant to your properties in Mixpanel reports, and this will give you richer insights about your data. + +### String + +- Alphanumeric value e.g. Plan Type = "Free", Artist Name = "Bruno Mars" +- String properties have a character limit of 255 bytes. +- Mixpanel will treat any property value that doesn’t match any other data type as a String. + +### Numeric + +- Numeric (integer or decimal) value e.g. Cost = 15.00, Quantity = 5 +- You can apply operators such as sum, median and percentile on numeric properties. + +### Boolean + +- Mixpanel treats properties as boolean if the value is either the JSON constant `true` or `false` e.g. Favorited = true, Bookmarked = false. +- On Mixpanel, you can typecast any non-boolean property to boolean, +- "false", 0, null, undefined, and empty string will be typecasted to boolean `false` +- "true" and any set value that is not 0 or empty string will be typecasted to boolean `true` + +### Date + +- An ISO formatted date `YYYY-MM-DDTHH:MM:SS` in UTC e.g. Last Purchase = "2022-10-30T13:30:25", Last Login = "2022-10-29". Note that all timestamps need to be sent in UTC timezone in an ISO format. +- Mixpanel treats unix timestamps as Numeric property, however, you can typecast it to Date data type. +- Timestamps are ingested with [millisecond precision](https://docs.mixpanel.com/changelogs/2022-11-07-millisecond), but exported with second precision. +- You can break down your results by the "Time" event property and breakdown by Hour, Day, Week, Month, Quarter, Year, Hour of Day, or Day of Week. + +![/breakdown_by_date.gif](/breakdown_by_date.gif) + +### List + +- A list of values as a JSON array e.g Favourite Genres = ["Folk","Alternative"] or Favourite Numbers = [1,5,10.0] +- Limits of a List property: Event Property = 8KB, User Profile Property = 256KB +- Each item in a list would be futher limited by their data type's limits; example: a list of strings would be limited by 255 bytes per string. Also refer to [List of Objects](/docs/data-structure/property-reference#list-of-objects) covered below. +- Mixpanel lists are not ordered (i.e. position of values in a list are not significant in Mixpanel reports) and are useful for grouping or analysing similar values across events. Read more details on [List Property Support](/docs/features/advanced#list-property-support) in reports. + +### Object +> Mixpanel supports object in a limited capacity. We recommend using the five non-object data types for most use cases as they are fully supported in the UI. + +- Arbitrarily-nested groups of JSON key-value pairs e.g. Experiments = {"Exp Onboarding":"Quick","Exp Checkout":"Without Coupon"} +- Limits of a Object property: Event Property = 8KB, User Profile Property = 256KB, max 255 keys per nested object with a max nesting depth of 3 +- Mainly supported in core reports (i.e. Insights, Funnels, Flows, Retention, Users / Cohorts, Events) as filters and breakdowns. Property Names (ie keys) within an object are not supported in Lexicon. + +### List of Objects +> Mixpanel supports object in a limited capacity. We recommend using the five non-object data types for most use cases as they are fully supported in the UI. + +- A JSON array of 1 level JSON objects with each object having similar sets of key-value pairs e.g. Cart = [{"Brand":"Puma","Category":"Jacket","Price":30}, {"Brand":"Adidas","Category":"Hats","Price":15}] +- Limits of a List of Objects: Event Property = 8KB, User Profile Property = 256KB, max 255 keys and no nesting +- Only the first 5 objects within the list will be parsed in Mixpanel UI. (Customers on a paid plan may submit a request for approval to have this limit increased by opening a support ticket within the UI (or by sending an email to [support@mixpanel.com](mailto:support@mixpanel.com)) with the subject line: “Request for List of Objects Limit Increase”. An increase will not be guaranteed, but your project will be reviewed for feasibility of increasing this limit. +) +- Mainly supported in core reports (i.e. Insights, Funnels, Flows, Retention, Users / Cohorts, Events) as filters and breakdowns. Property Names (ie keys) within an object are not supported in Lexicon. + +## List Property Support + +List is an iterable data type, which makes them inherently diffrent from non-iterable data types (ie: strings, numbers, time). This section highlights a few scenarios on how list properties behave within Mixpanel. The examples used here are from the Insights report, but the principles of how filter and breakdowns work with list properties remain the same across reports. + +### Sample Scenario +Let's assume an e-commerce platform has these 3 events: + +- Event 1: *PurchaseCompleted* + - *List of ProductIDs* = ["P1", "P2", "P4"] +- Event 2: *PurchaseCompleted* + - *List of ProductIDs* = ["P2", "P3", "P4"] +- Event 3: *PurchaseCompleted* + - *List of ProductIDs* = ["P3", "P4"] + +Now let's assume that *"List of ProductIDs"* is mapped to a [lookup table](/docs/data-structure/lookup-tables) called *Products* which looks like this: + +| ProductID | Category | Price | +| --- | --- | --- | +| P1 | Clothing - pants | 100 | +| P2 | Clothing - shirt | 54 | +| P3 | Shoes | 109 | +| P4 | Electronics - music | 199 | + +**** + +### List Breakdown + +- Breakdown a list property + - **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* + - **Answer:** + + + | List of ProductIDs | Total | + | --- | --- | + | P1 | 1 | + | P2 | 2 | + | P3 | 2 | + | P4 | 3 | + - **What's going on here?** When breaking down, each of the list's contents is evaluated as a single item. So for example, P2 is present in Event 1 and Event 2, so the TOTAL (of the *PurchaseCompleted* event) where "P2" is present is 2. +- Breakdown by [lookup profile property](/docs/data-structure/lookup-tables) that's joined to a list property + - **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* → *Category* + - **Answer:** + + + | List of ProductIDs | Total | + | --- | --- | + | Clothing - pants | 1 | + | Clothing - shirt | 2 | + | Shoes | 2 | + | Electronics - music | 3 | + - **What's going on here?** When breaking down, each of the list's contents is evaluated as a single item after being mapped to the lookup table. So for example, P2 is present in Event 1 and Event 2, and P2 mapped to the lookup table which gets us *Category* = "Clothing - shirt", so the TOTAL (of *PurchaseCompleted* events) where "Clothing - shirt" is present is 2. The thing to note here is that the results are identical to when *PurchaseCompleted* was broken down by *"List of ProductDs"*, except the *ProductIDs* are replaced by *Category*. +- Breakdown by lookup profile property that's joined to a list property AND by the list property itself + - **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* → *Category* AND *"List of ProductIDs"* (2 breakdowns applied) + - **Answer:** + + + | List of ProductIDs.Category | List of ProductIDs | Total | + | --- | --- | --- | + | Clothing - pants | P1 | 1 | + | | P2 | 1 | + | | P4 | 1 | + | Clothing - shirt | P1 | 1 | + | | P2 | 2 | + | | P3 | 1 | + | | P4 | 2 | + | Shoes | P2 | 1 | + | | P3 | 2 | + | | P4 | 2 | + | Electronics - music | P1 | 1 | + | | P2 | 2 | + | | P3 | 2 | + | | P4 | 3 | + - **What's going on here?** For each breakdown value, Mixpanel recomputes the list breakdown. So for example, TOTAL (*PurchaseCompleted*) with "*List of ProductIDs*" → *Category* = "Shoes" should get us Event 2 and Event 3:When these 2 events are broken down by *"List of ProductIDs"*, we get these results for "Shoes"(*ProductID* = "P3"): + - Event 2: *PurchaseCompleted* + - *List of ProductIDs* = ["P2", "P3", "P4"] + - Event 3: PurchaseCompleted + - *List of ProductIDs* = ["P3", "P4"] + - P2: 1 + - P3: 2 + - P4: 2 + +### List Filter + +- Filter by any element of a list property + - **Question:** TOTAL of *PurchaseCompleted* filtered by + + + | "List of ProductIDs" | Any | = (equals) | "P1" | + | --- | --- | --- | --- | + - **Answer:** *PurchaseCompleted - TOTAL*: 1 + - **What's going on here?** The "Any" operator filters down events when the filtered value matches ANY item in the list property. So in this example, the only event in which "List of ProductIDs" has "P1" present even once is Event 1, so the total event count for this filter is 1. +- Filter by all elements of a list property + - **Question**: TOTAL of *PurchaseCompleted* filtered by + + + | "List of ProductIDs" | All | = (equals) | "P1" | + | --- | --- | --- | --- | + - **Answer:** *PurchaseCompleted - TOTAL*: 0 + - **What's going on here?** The "All" operator filters down events when the filtered value matches ALL of the items in the list property. So in this example, there is no event in which "List of ProductIDs" has all the elements equal to "P1", so the total event count for this filter is 0. +- Filter by list property and broken down by list property + - **Question:** TOTAL of PurchaseCompleted filtered byBroken down by "List of ProductIDs" + + + | "List of ProductIDs" | Any | = (equals) | "P1" | + | --- | --- | --- | --- | + - **Answer:** + + + | List of ProductIDs | Total | + | --- | --- | + | P1 | 1 | + | P2 | 1 | + | P4 | 1 | + - **What's going on here?** There is only 1 event that contains "P1" (Event 1, *"List of ProductIDs"* = ["P1", "P2", "P4"]), so when that one event is broken down by *"List of ProductIDs"*, Mixpanel evaluates each list item individually, thereby getting us: + - P1: 1 (1 event) + - P2: 1 (1 event) + - P4: 1 (1 event) +- Filter by lookup profile property that's joined to a list property and then broken down by list property + - **Question:** TOTAL of *PurchaseCompleted* filtered byBroken down by "List of ProductIDs" + + + | "List of ProductIDs" → Category | Any | = (equals) | "Shoes" | + | --- | --- | --- | --- | + - **Answer:** + + + | List of ProductIDs | Total | + | --- | --- | + | P2 | 1 | + | P3 | 2 | + | P4 | 2 | + - **What's going on here?** There are 2 events that contain where the *Category* mapping for at least one of the *ProductIDs* in "*List of ProductIDs*" is equal to "Shoes" (i.e. *ProductID* = P3).When these two events are broken down by *"List of ProductIDs"*, Mixpanel evaluates each list item individually, thereby getting us: + - Event 2: PurchaseCompleted + - List of ProductIDs = ["P2", "P3", "P4"] + - Event 3: PurchaseCompleted + - List of ProductIDs = ["P3", "P4"] + - P2: 1 (1 event) + - P3: 2(2 events) + - P4: 2 (2 events) +- Filter by lookup profile property that's joined to a list property (with multiple matching values) and then broken down by list property + - **Question**: TOTAL of *PurchaseCompleted* filtered byBroken down by "List of ProductIDs" + + + | "List of ProductIDs" → Category | Any | ∋ (contains) | "Clothing" | + | --- | --- | --- | --- | + - **Answer:** + + + | List of ProductIDs | Total | + | --- | --- | + | P1 | 1 | + | P2 | 2 | + | P3 | 1 | + | P4 | 2 | + - **What's going on here?** This filter can be read as "for any of the items in *'List of ProductIDs'* , the lookup property *Category* contains the string 'Clothing'". This operation is filtering down to all the events that contain the *Category* mapping for the *ProductID* contains EITHER "Clothing - pants" or "Clothing - shirt", and that gives us 2 events: + - Event 1: PurchaseCompleted + - List of ProductIDs ["P1","P2","P4"] + - Event 2: PurchaseCompleted + - List of ProductIDs ["P2","P3","P4"] + - Therefore, when those two events are broken down by "List of ProductIDs", Mixpanel evaluates each item of the list individually and we end up getting: + - P1: 1 + - P2: 2 + - P3: 1 + - P4: 2 +- Filter by lookup profile property that's joined to a list property (numeric filter) and then broken down by list property + - **Question**: TOTAL of *PurchaseCompleted* filtered byBroken down by *"List of ProductIDs"* + + + | "List of ProductIDs" → Price (number) | Any | < (less than) | 100 | + | --- | --- | --- | --- | + - **Answer:** + + + | List of ProductIDs | Total | + | --- | --- | + | P1 | 1 | + | P2 | 2 | + | P3 | 1 | + | P4 | 2 | + - **What's going on here?** The filter can be read as "for any item in *'List of ProductIDs',* the lookup property *Price* is less than 100" and it only matches 1 product, and that is P2. Therefore, what this operation is doing is filtering down to all the events that contain P2 as ANY of the values in "List of ProductDs", and that gives us 2 events:Therefore, when those two events are broken down by *"List of ProductIDs"*, Mixpanel evaluates each item of the list individually and we end up getting: + - Event 1: *PurchaseCompleted* + - *List of ProductIDs* = ["P1", "P2", "P4"] + - Event 2: PurchaseCompleted + - *List of ProductIDs* = ["P2", "P3", "P4"] + - P1: 1 + - P2: 2 + - P3: 1 + - P4: 2 + + +## List of Objects Property Support + +List of objects is a List property where all items contained are Objects. List of objects are generally useful when tracking a list of complex things. Some examples: + +- items in a cart +- search results +- images in a slideshow + +In each case, the object will have multiple properties, such as "price" and "brand" for items in a cart. + +``` +"event": "Product Added", +"properties": { + "cart": [ + { + "brand": "Puma", + "category": "Jacket", + "price": 30 + }, + { + "brand": "Adidas", + "category": "Hats", + "price": 15 + } + ] +} +``` +> The list of objects property support will be limited to the first 5 objects within the list property. Customers on a paid plan may submit a request for approval to increase the limit by opening a support ticket. + +### Breakdown and Filter +List of objects can be used like other properties in Mixpanel. Upon selecting a list of objects property, you will be prompted to select another property common to the objects in the list. Usage in measurements, filters, and breakdowns follows the same behavior as other [list properties](/docs/data-structure/property-reference/data-type#list-property-support). + +### Computed Properties + +We provide a few convenient computed properties after a list of objects property is selected. This does a computation on the property, and works similarly to [custom properties](/docs/features/custom-properties). + +![list computed properties](/list-computed-properties.png) + +#### Size + +The size, or length of the list as a numeric property. + +#### Sum + +Prompts a selection of a numeric property contained within the objects of the list. This will give the total for the whole list for that property. + +#### Distinct Count + +Prompts a selection of a property contained within the objects of the list. This will give the number of unique values for that property in the list. + +## Falsy Values + +### Undefined and Null + +**Undefined** + +Undefined values are seen when one or more of the events being measured in a query do not contain the property used for breakdown. For example, building a report using Page View events broken down by a campaign ID property would Page Views with a set campaign ID property by their value, and group events without a set Campaign ID property to undefined. Undefined values are parsed as `(not set)` in the UI. + +There are several reasons why you might see "undefined" values throughout Mixpanel reports when segmenting: + +- ***The specific property you’re segmenting by isn’t always sent along with the event you’re analyzing.*** For example, let’s say you’re segmenting the event “App Open” by the property “Account type” If there are instances where App Open fires without the Account type property getting sent with it, these will be categorized as “undefined” when you segment by Account type. Another common example is UTM parameters - “undefined” represents users who fired an event without any UTM in the URL that brought the user to your site. +- When segmenting an event by a User Profile property, ***you’ll see “undefined” if there are User Profile profiles that don’t contain that property or if the event was triggered by a user without a User Profile at all.*** For example, let’s say you’re segmenting the event “Song Play” by the User Profile property “Favorite Genre.” If there are profiles that have triggered Song Play but don’t have the Favorite Genre property, that value will be “undefined.” Triggers of Song Play by users without a User Profile will also show up under “undefined.” +- ***For geolocation data (City, Region, Country), the user’s IP couldn’t be mapped to a location, or their IP was not included with the request.*** For JavaScript implementations, City, Region, and Country are [default properties](https://help.mixpanel.com/hc/en-us/articles/115004613766-What-properties-do-Mixpanel-s-libraries-store-by-default-). However, if the IP address of the user is not in Mixpanel’s geolocation database and can’t be mapped to a city, region, or country, they will be “undefined” in reports. For server-side implementations, City, Region, and Country can be “undefined” if the IP address is not included with the request. [Read more about how Mixpanel maps IP to location.](/docs/privacy/protecting-user-data#disabling-geolocation) + +**Null** + +[Null values](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null) represents the intentional absence of any object value. Unlike undefined values, null values are usually explicitly defined as a value of a property. Null values are parsed as `(not set)` in the UI, but will appear as `` or `null` when looking at raw data. + +#### Remove “undefined” & "null" values from reports + +If you don’t want to see “undefined” or "null" values in your report, you can remove them by: + +1. Unchecking the “undefined/null” box in the visualization legend. +2. Looking only at instances where the property in question “is set" - this will exclude values where you see "undefined" or "null": + +![image](https://github.com/mixpanel/docs/assets/2077899/1a2465e1-da8d-4fe4-937a-5753716129b3) + +3. Directly exclude undefined or null values from an Insights visualization by hitting the exclude action: + +![image](https://github.com/mixpanel/docs/assets/2077899/4d010827-cc4e-4a11-9716-cd3bfbaebadd) + +### Empty String + +Empty string refers to a string with a length of zeros, meaning there are no characters or symbols. This happens when a property is sent with a value of `""`. Empty string are parsed as `(empty string)` in the UI. diff --git a/pages/docs/data-structure/property-reference/default-properties.md b/pages/docs/data-structure/property-reference/default-properties.md new file mode 100644 index 0000000000..033d64d04d --- /dev/null +++ b/pages/docs/data-structure/property-reference/default-properties.md @@ -0,0 +1,108 @@ +# Default Properties +Mixpanel's [Data Ingestion APIs](https://developer.mixpanel.com/reference/ingestion-api) and [Client-Side SDKs](/docs/tracking-methods/choosing-the-right-method#client-side-tracking) automatically collect certain properties on every event or user profile. Do also note that some Customer Data Platforms (CDPs) that integrate with Mixpanel may also map their own properties to Mixpanel default properties. This document describes what those properties mean. + +## Ingestion APIs + +To disable capturing of geolocation properties (i.e. City, Region, Country) refer to the respective SDKs or API documentation. For a quick reference, refer to examples on [disabling geolocation on client-side SDKs](/docs/privacy/protecting-user-data#disabling-geolocation) and [server-side best practice on tracking geolocation](/docs/best-practices/server-side-best-practices#tracking-geolocation-http-api). + +### Event Properties + +| **Raw Name** | **Display Name** | **Description** | +| ------------ | ---------------- | --------------- | +| $city | City | The city of the event sender parsed from the IP property or the Latitude and Longitude properties. | +| $region | Region | The region (state or province) of the event sender parsed from the IP property or the Latitude and Longitude properties. | +| mp_country_code | Country | The country of the event sender parsed from the IP property or the Latitude and Longitude properties. The value is stored as a 2-letter country code in the raw data and parsed into the country name in the UI. | +| $mp_api_endpoint | API Endpoint | Mixpanel property to record the API endpoint the data was sent to:
**api.mixpanel.com** - default ingestion
**api-eu.mixpanel.com** - EU data ingestion
**api-js.mixpanel.com** - Javascript SDK | +| $import | Import | Internal Mixpanel property set to `true` to indicate that events were sent through [/import API](https://developer.mixpanel.com/reference/import-events). | +| $mp_api_timestamp_ms | API Timestamp | UTC timestamp in milliseconds when the event was received by our API. | +| mp_processing_time_ms | Time Processed (UTC) | UTC timestamp in milliseconds when the event was processed by Mixpanel servers. | + +### User Properties + +Do note that Mixpanel's default user properties are only updated when you send or update at least one property yourself (via [\$set](https://developer.mixpanel.com/reference/profile-set) or [\$set_once](https://developer.mixpanel.com/reference/profile-set-property-once) operations). Please, refer to this article to [understand how to send or update profile properties](/docs/data-structure/user-profiles). + +| **Raw Name** | **Display Name** | **Description** | +| ------------ | ---------------- | --------------- | +| $city | City | The city of the user parsed from the IP property or the Latitude and Longitude properties. | +| $region | Region | The region (state or province) of the user parsed from the IP property or the Latitude and Longitude properties. | +| $country_code | Country Code | The country of the user parsed from the IP property or the Latitude and Longitude properties. The value is stored as a 2-letter country code in the raw data and parsed into the country name in the UI. | +| $geo_source | Geo Source | Set to "reverse_geocoding" if profile geolocation properties (Country Code, Region, and City) were determined through [Latitude and Longitude](/docs/best-practices/server-side-best-practices#tracking-geolocation-latitude-and-longitude). | +| $timezone | Timezone | Timezone of the user parsed from the IP property or the Latitude and Longitude properties. | +| $last_seen | Updated at | The last time a user profile property was set or updated **(this should not be set manually)**. Passing `$ignore_time` as `true`, typically for server-side updates, will skip updating the $last_seen property. See example [here](/docs/tracking-methods/sdks/php#setting-profile-properties). | + + +## Client-side SDKs + +Note that the following SDKs wrap around our other SDKs; and as such, would also inherit the appropriate default properties from these wrapped SDKs indicated in the tables below: +- [React Native](/docs/tracking-methods/sdks/react-native) wraps around Android and Swift SDK; `mp_lib` will be set to `react-native` with `$lib_version` set as React Native's library version. +- [Flutter](/docs/tracking-methods/sdks/flutter) wraps around Javscript, Android, and Swift SDK; `mp_lib` will be set to `flutter` with `$lib_version` set as the Flutter's library version. + +### Event Properties + +| **Raw Name** | **Display Name** | **Description**
*Scroll right to see more columns -->* | **[Javascript](/docs/tracking-methods/sdks/javascript)** | **[Android](/docs/tracking-methods/sdks/android)** | **iOS [Objective-C](/docs/tracking-methods/sdks/ios) / [Swift](/docs/tracking-methods/sdks/swift)** | **[Unity](/docs/tracking-methods/sdks/unity)** | +| -------- | ------------ | ----------- | :-----------: | :-----------: | :-----------: | :-----------: | +| $device_id | Device ID | Autogenerated ID that is local to the device. Calling reset() regenerates this value. More details [here](/docs/tracking-methods/identifying-users). | ✅ | ✅ | ✅ | ❌ | +| $user_id | User ID | The identified ID of the user. Calling identify() sets this. More details [here](/docs/tracking-methods/identifying-users). | ✅ | ✅ | ✅ | ❌ | +| $insert_id | Insert ID | A unique identifier for the event, used to deduplicate events that are accidentally sent multiple times. More details [here](https://developer.mixpanel.com/reference/import-events#propertiesinsert_id). | ✅ | ✅ | ✅ | ✅ | +| mp_lib | Mixpanel Library | The Mixpanel library that sent the event. | `web` | `android` | `iphone` / `swift` | `unity` | +| $lib_version | Library Version | Mixpanel library version. | ✅ | ✅ | ✅ | ✅ | +| mp_sent_by_lib_version | Sent By Library Version | Mixpanel library version used to send data (not necessarily the same as the version which enqueued the data). | ✅ | ❌ | ❌ | ❌ | +| $os | Operating System | OS of the event sender. | ✅ | ✅ | ✅ | ✅ | +| $os_version | OS Version | The current version of operating system on the device. | ❌ | ✅ | ✅ | ✅ | +| $browser | Browser | Name of the browser. | ✅ | ❌ | ❌ | ❌ | +| $browser_version | Browser Version | Version of the browser. | ✅ | ❌ | ❌ | ❌ | +| $app_build_number | App Build Number | General build of the app. | ❌ | ✅ | ✅ | ❌ | +| $app_version_string | App Version | Current app version. | ❌ | ✅ | ✅ | ✅ | +| $device | Device | Name of the event sender’s device, if they’re on mobile web. | ✅ | ❌ | ❌ | ✅ | +| $screen_height | Screen Height | The height of the device screen in pixels / points (iOS). | ✅ | ✅ | ✅ | ✅ | +| $screen_width | Screen Width | The width of the device screen in pixels / points (iOS). | ✅ | ✅ | ✅ | ✅ | +| $screen_dpi | Screen DPI | Pixel density of the device screen. | ❌ | ✅ | ❌ | ✅ | +| $current_url | Current URL | The URL of the page on which the event was tracked. | ✅ | ❌ | ❌ | ❌ | +| $initial_referrer | Initial Referrer | Referring URL when the user first arrived on your site. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | +| $initial_referring_domain | Initial Referring Domain | Referring domain at first arrival. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | +$referrer | Referrer | Referring URL including your own domain. Might not be present if document.referrer does not return a value. As opposed to \$initial_referrer and \$initial_referring_domain, this property will be omitted if the user lands directly or the referring website adds the rel="noreferrer" parameter. | ✅ | ❌ | ❌ | ❌ | +| $referring_domain | Referring Domain | Referring domain including your own domain. Might not be present if document.referrer does not return a value. As opposed to \$initial_referrer and \$initial_referring_domain, this property will be omitted if the user lands directly or the referring website adds the rel="noreferrer" parameter. | ✅ | ❌ | ❌ | ❌ | +| $search_engine | Search Engine | The search engine that the customer used when they arrived at your domain. | ✅ | ❌ | ❌ | ❌ | +| mp_keyword | Search Keyword | Search keywords detected on the referrer from a search engine to your domain. This property is only collected when search keywords are included in a URL. | ✅ | ❌ | ❌ | ❌ | +| utm_source, utm_medium, etc. | UTM Parameters | UTM tags derived from the URL a customer clicked to arrive at your domain. Each UTM will be collected under its own property. More details [here](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters). | ✅ | ❌ | ❌ | ❌ | +| $manufacturer | Manufacturer | Device manufacturer. | ❌ | ✅ | ✅ | ✅ | +| $brand | Brand | Device brand. | ❌ | ✅ | ❌ | ❌ | +| $model | Model | The model of the device. | ❌ | ✅ | ✅ | ✅ | +| $watch_model | Watch Model | The model of the iOS watch. | ❌ | ❌ | ✅ | ❌ | +| $carrier | Carrier | Wireless carrier of the device owner. | ❌ | ✅ | ✅ | ❌ | +| $radio | Radio | Current [cellular network communication standard](https://www.objc.io/issues/5-ios7/iOS7-hidden-gems-and-workarounds/#know-your-radio)(opens in a new tab) (3G, 4G, LTE, etc). | ❌ | ❌ | ✅ | ✅ | +| $wifi | Wifi | Set to true if the user’s device has an active, available Wifi connection, false if not. | ❌ | ✅ | ✅ | ✅ | +| $bluetooth_enabled | Bluetooth | Set to true if Bluetooth is enabled, false if not. | ❌ | ✅ | ❌ | ❌ | +| $bluetooth_version | Bluetooth Version | Set to "none", "ble", or "classic". | ❌ | ✅ | ❌ | ❌ | +| $has_nfc | Has NFC | Set to true if Near Field Communication is being used, false if not. | ❌ | ✅ | ❌ | ❌ | +| $has_telephone | Has Telephone | Set to true if this device has telephone functionality, false if not. | ❌ | ✅ | ❌ | ❌ | +| $google_play_services | Google Play Services | Verifies that Google Play services is installed and enabled on this device, and that the version installed on this device is no older than the one required by this client. | ❌ | ✅ | ❌ | ❌ | +| $duration | Duration | A property that is appended to an event to capture the elapsed time (in seconds) between a `time_event` and a `track` call. See [time_event](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpaneltime_event) in Javascript SDK for example. | ✅ | ✅ | ✅ | ✅ | + +### User Properties + +Do note that Mixpanel's default user properties are only updated when you send or update at least one property yourself (via [\$set](https://developer.mixpanel.com/reference/profile-set) or [\$set_once](https://developer.mixpanel.com/reference/profile-set-property-once) operations). Please, refer to this article to [understand how to send or update profile properties](/docs/data-structure/user-profiles). + +| **Raw Name** | **Display Name** | **Description**
*Scroll right to see more columns -->* | **[Javascript](/docs/tracking-methods/sdks/javascript)** | **[Android](/docs/tracking-methods/sdks/android)** | **iOS [Objective-C](/docs/tracking-methods/sdks/ios) / [Swift](/docs/tracking-methods/sdks/swift)** | **[Unity](/docs/tracking-methods/sdks/unity)** | +| -------- | ------------ | ----------- | :-----------: | :-----------: | :-----------: | :-----------: | +| $lib_version | Library Version | Last used Mixpanel library version (also applies to React Native and Flutter wrapper SDKs). | ❌ | ❌ | ❌ | ✅ | +| $android_lib_version | Android Lib Version | Last used Mixpanel Android / Unity library version. | ❌ | ✅ | ❌ | ✅ | +| $ios_lib_version | iOS Lib Version | Last used Mixpanel iOS / Unity library version. | ❌ | ❌ | ✅ | ✅ | +| $swift_lib_version | Swift Lib Version | Last used Mixpanel Swift library version. | ❌ | ❌ | ✅ | ❌ | +| $os | Operating System | Last OS of the event sender. | ✅ | ✅ | ✅ | ✅ | +| $android_os | Android OS | Set when Android operating system was used. | ❌ | ✅ | ❌ | ✅ | +| $android_os_version | Android OS Version | Last version of Android on the device. | ❌ | ✅ | ❌ | ✅ | +| $ios_version | iOS Version | Last version of iOS on the device. | ❌ | ❌ | ✅ | ✅ | +| $browser | Browser | Name of the browser. | ✅ | ❌ | ❌ | ❌ | +| $browser_version | Browser Version | Version of the browser. | ✅ | ❌ | ❌ | ❌ | +| $android_app_version | Android App Version | Current Android app version ([versionName](https://developer.android.com/studio/publish/versioning)). | ❌ | ✅ | ❌ | ✅ | +| $android_app_version_code | Android App Version Code | Current Android app version code ([versionCode](https://developer.android.com/studio/publish/versioning)). | ❌ | ✅ | ❌ | ❌ | +| $ios_app_release | iOS App Release | The release or version number of the iOS app ([CFBundleShortVersionString](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleshortversionstring)). | ❌ | ❌ | ✅ | ✅ | +| $ios_app_version | iOS App Version | The version of the build that identifies an iteration of the iOS app ([CFBundleVersion](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleversion)). | ❌ | ❌ | ✅ | ❌ | +| $initial_referrer | Initial Referrer | Referring URL when the user first arrived on your site. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | +| $initial_referring_domain | Initial Referring Domain | Referring domain at first arrival. Defaults to "$direct" if the user is not referred. | ✅ | ❌ | ❌ | ❌ | +| initial_utm_source, initial_utm_medium, etc. | Initial UTM Parameters | UTM tags seen for the first time from the URL a customer clicked to arrive at your domain. Each UTM will be collected under its own property. More details [here](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters). | ✅ | ❌ | ❌ | ❌ | +| $android_manufacturer | Android Manufacturer | Android device manufacturer. | ❌ | ✅ | ❌ | ❌ | +| $android_brand | Android Brand | Android device brand. | ❌ | ✅ | ❌ | ❌ | +| $android_model | Android Model | The model of the Anroid device. | ❌ | ✅ | ❌ | ✅ | +| $ios_device_model | iOS Device Model | The model of the iOS device. | ❌ | ❌ | ✅ | ✅ | diff --git a/pages/docs/data-structure/property-reference/reserved-properties.md b/pages/docs/data-structure/property-reference/reserved-properties.md new file mode 100644 index 0000000000..dcbebdbe4f --- /dev/null +++ b/pages/docs/data-structure/property-reference/reserved-properties.md @@ -0,0 +1,54 @@ +# Reserved Properties + +Mixpanel reserves certain property names for special processing or for specific system features. These properties, when populated, will affect the way Mixpanel processes your data. + +## Reserved Profile Properties + +> **Note:** Also refer to the list of Mixpanel [Default Properties](/docs/data-structure/property-reference#default-properties) indicated in our documentation. + +| **Raw Name** | **Display Name** | **Description** | +| ------------ | ---------------- | --------------- | +| $distinct_id | Distinct ID | Mixpanel's internal unique identifier for a profile. See [Identifying Users](/docs/tracking-methods/id-management/identifying-users) and [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles) | +| \$name,
\$first_name,
\$last_name | Name,
First Name,
Last Name | The user's / group's general name, as well as, first and last names. These are primarily useful because they are used, if available, in various Mixpanel UI / reports. For user [Cohort Syncs](/docs/cohort-sync/overview), only `$first_name` and `$last_name` is exported. | +| $email | Email | The user's / group's email address. You must set this property if you want to send emails to users via partners receiving cohorts from our [Cohort Syncs](/docs/cohort-sync/overview). | +| $phone | Phone | The user's / group's phone number. You must set this property if you want to send SMS to users via partners receiving cohorts from our [Cohort Syncs](/docs/cohort-sync/overview). Note that a '+' needs to precede international phone numbers. If the user does not import a phone number with the '+' sign in front, the country code will be prefixed to the front of the number based on the $country_code default property, resulting in a phone number with two country codes. | +| $avatar | Avatar URL | Set this property to a URL resource of a gif, jpg, jpeg, or png to update the profile picture in a profile. This property will override a profile picture pulled from [Gravatar](https://gravatar.com/). | +| $created | Created | The time that the profile was created. Note that this is not auto-populated. | +| $mp_first_event_time | First Seen | Mixpanel calculated property that represents the time of the user's (or group's) very first event in Mixpanel. This can be used to filter/segment reports by users (or groups) who were "new" in a particular timeframe. | + +## Reserved Event Properties + +> **Note:** Also refer to the list of Mixpanel [Default Properties](/docs/data-structure/property-reference#default-properties) indicated in our documentation. + +| **Raw Name** | **Display Name** | **Description** | +| ------------ | ---------------- | --------------- | +| token | - | The project's token when sending data via [/track API](https://developer.mixpanel.com/reference/track-event). Not visible via Mixpanel UI reports. | +| ip | - | The `ip` event property is the value to be used for geo location parsing (i.e. `$city`, `$region`, and `mp_country_code`) if `ip` as param to the [/track endpoint](https://developer.mixpanel.com/reference/track-event) has **not been** set to 1. Our client-side libraries, by default, will set the `ip` param to 1 so geo location is parsed from the incoming request, but this can be disabled or, if you're implementing from the [server-side](/docs/best-practices/server-side-best-practices#tracking-geolocation-http-api), you can include the `ip` event property so it's parsed from it instead of the IP of the incoming request. The `ip` event property is not stored in Mixpanel. | +| $bucket / bucket | - | A reserved property that is hidden from the Mixpanel interface, and will cause other events to not appear in the interface. Do not name any property bucket or $bucket. | +| $distinct_id / distinct_id | Distinct ID | Mixpanel's internal unique identifier for a user. See [Identifying Users](/docs/tracking-methods/id-management/identifying-users). | +| $device_id | Device ID | In [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users#example-user-flows): unique identifier used to track a device while the user is in anynymous state. | +| $user_id | User ID | In [Simplified ID Merge](/docs/tracking-methods/id-management/identifying-users#example-user-flows): unique identifier used to track a user across devices when user is in identified state. | +| $event_name | Event Name | Name of the tracked event used in the Mixpanel UI. | +| $time / time | Time or Date | A unix time epoch that is used to determine the time of an event. If no time property is provided, we will use the time when the event arrives at our servers. | +| $insert_id | Insert ID | A unique identifier for the event, used to deduplicate events that are accidentally sent multiple times. More details [here](https://developer.mixpanel.com/reference/import-events#propertiesinsert_id). | +| $identified_id | Identified ID | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the identifier passed into the [`$identify`](https://developer.mixpanel.com/reference/create-identity) event. | +| $anon_id | Anonymous ID | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the anonymous ID passed into the [`$identify`](https://developer.mixpanel.com/reference/create-identity) event. | +| alias | Alias | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the alias passed into the [`$create_alias`](https://developer.mixpanel.com/reference/identity-create-alias) event. | +| $distinct_ids | Distinct Ids | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Internal Mixpanel property to track the distinct IDs passed into the [`$merge`](https://developer.mixpanel.com/reference/identity-merge) event. | +| $distinct_id_before_identity | Distinct ID Before Identity | Internal Mixpanel property to track an event's original $distinct_id before it was updated due to identity merging. Used in [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge) and [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge). | +| $is_reshuffled | Is Reshuffled | Internal Mixpanel property to denote an event was reshuffled (sets to true if original $distinct_id was updated) due to identity merging. Used in [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge) and [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge). | +| $failure_description | Failure Description | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Mixpanel property explaining in detail why identity merging was not executed. | +| $failure_reason | Failure Reason | In [Original ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#on-original-id-merge): Mixpanel property summarizing why identity merging was not executed. | +| $identity_failure_reason | Identity Failure Reason | In [Simplified ID Merge](/docs/tracking-methods/id-management/migrating-to-simplified-id-merge-system#understanding-simplified-id-merge): Mixpanel property summarizing why identity merging was not executed. | +|mp_original_distinct_id | Hotshard Original Distinct ID | Original $distinct_id for an event that was identified as contributing to a [hot shard](https://docs.mixpanel.com/docs/debugging/distinct-id-limits#what-is-a-hot-shard). | +| mp_original_event_name | Hotshard Original Event Name | Original $event_name for an event that was identified as contributing to [hot shard](https://docs.mixpanel.com/docs/debugging/distinct-id-limits#what-is-a-hot-shard). | +| $source | Source | Hidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under [Cohort Sync -> Integrations](/docs/cohort-sync/integrations/airship). | +| $partner_id | Partner Id | Hidden property used by certain integration partners to denote events were sent by them. Refer to the respective partners under [Cohort Sync -> Integrations](/docs/cohort-sync/integrations/airship). | +| $warehouse_type | Warehouse Type | The type of the warehouse sync setup to send the event. See [Supported Warehouses](/docs/tracking-methods/data-warehouse/overview#supported-warehouses). | +| $warehouse_import_id | Warehouse Import ID | The ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/data-warehouse/overview). | +| $warehouse_import_job_id | Warehouse Import Job ID | The internal Mixpanel Job ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/data-warehouse/overview). | +| $warehouse_import_run_id | Warehouse Import Run ID | The internal Mixpanel Run ID of the warehouse sync setup to send this event. See [Data Warehouse](/docs/tracking-methods/data-warehouse/overview). | +| $duration_s | Session Duration (Seconds) | The duration between Session Start and Session End events in seconds. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | +| $event_count | Session Event Count | The number of events during a session (i.e. Session Start and Session End). This does not include [Excluded Events](/docs/features/sessions#excluded-events) and [Hidden Events](/docs/data-governance/lexicon#hide-events-and-properties) in Lexicon. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | +| $origin_start | Session Start Event Name | The original event name that triggered Session Start event. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | +| $origin_end | Session End Event Name | The original event name that triggered Session End event. See [How Sessions Work](/docs/features/sessions#how-sessions-work). | diff --git a/pages/docs/data-structure/user-profiles.md b/pages/docs/data-structure/user-profiles.md index 2f4914a7f6..a82d5f9e28 100644 --- a/pages/docs/data-structure/user-profiles.md +++ b/pages/docs/data-structure/user-profiles.md @@ -1,16 +1,14 @@ # User Profiles > **Note:** The following terms are used in this section: -> - "User Profile Properties" and "User Properties" are used interchangeably to refer to properties under a User Profile -> - "Group Profile Properties" and "Group Properties" are used interchangeably to refer to properties under a Group Profile > - "Profiles" is used to refer to both "User Profiles" and "Group Profiles" > - "Profile Properties" is used to refer to both "User Profile Properties" and "Group Profile Properties" ## Overview -User Profiles let you enrich events with demographic attributes (i.e. user properties) about the users that performed those events. User profiles are optional and we recommend starting with events and only adding user profiles if you need them. +User Profiles let you enrich events with demographic attributes (i.e. user properties) about the users that performed those events. User Profiles are optional. We recommend starting with events and adding user profiles only if needed. -A user profile has a set of properties associated with a given user. Under the hood, Mixpanel stores user profiles for your project in a table wherein each user's profile is 1 row with user properties (e.g. Name, Email, Department) that can be updated: +A user profile has a set of user properties associated with a given user. Under the hood, Mixpanel stores user data for your project in a table wherein each row of user profile contain columns of user properties (e.g. Name, Email, Department) that can be updated: | **Distinct ID** | **Name** | **Email** | **Department** | | --------------- | -------- | --------- | -------------- | @@ -18,28 +16,30 @@ A user profile has a set of properties associated with a given user. Under the h | 456 | Bob | `bob@notion.so` | Product | | 789 | Carol | `carol@figma.com` | Design | -User profiles are joined onto your events based on their **[Distinct ID](/docs/tracking-methods/id-management/identifying-users#what-is-distinct-id)** (Mixpanel's identifier for a user). This lets you join the events performed by a user with properties about who that user is. Thus, it's very important that you use the same Distinct ID for both the events and user profile for the same user. +User profiles are joined onto your events based on their **[Distinct ID](/docs/tracking-methods/id-management/identifying-users#what-is-distinct-id)** (Mixpanel's identifier for a user). This lets you join the events performed by a user with user properties describing them. Thus, it is very important that you use the same Distinct ID for both the events and user profile for the same user. For more information about user profiles refer to the documentation on [The Mixpanel Data Model](/docs/tutorials/plan/tracking-strategy#the-mixpanel-data-model). > **Note:** If you have [Group Analytics](/docs/data-structure/advanced/group-analytics) as an add-on, this section also applies to [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles). -## Importing User Profiles via our API +## Importing Profiles via API You can create or update User Profiles in similar ways you track events: from our [SDKs](/docs/tracking-methods/sdks/javascript#storing-user-profiles), via our [HTTP Engage API](https://developer.mixpanel.com/reference/profile-set), [Warehouse Connectors](/docs/tracking-methods/data-warehouse/sending-user-profiles), or via our integrations partners. -We recommend tracking user profiles from as close as possible to the source of truth, which is usually your application database or your CRM. One typical approach (especially for [Server-Side Tracking](/docs/tracking-methods/choosing-the-right-method#server-side-tracking)) is to run an hourly or daily script on your servers that pull the list of user profiles from your database and pushes them to Mixpanel. - Similarly for [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles), they can be created or updated using our [SDKs](/docs/tracking-methods/sdks/javascript#creating-group-profiles), via our [HTTP Groups API](https://developer.mixpanel.com/reference/group-set-property), [Warehouse Connectors](/docs/tracking-methods/data-warehouse/sending-group-profiles), or via our integration partners. +We recommend tracking profiles from as close as possible to the source of truth, which is usually your application database or your CRM. One typical approach (especially for [Server-Side Tracking](/docs/tracking-methods/choosing-the-right-method#server-side-tracking)) is to run an hourly or daily script on your servers that pulls the list of profiles from your database and pushes them to Mixpanel. + ### Operators +The [HTTP Engage API](https://developer.mixpanel.com/reference/profile-set) and [HTTP Groups API](https://developer.mixpanel.com/reference/group-set-property) share the same operators. + **Setting profile property** - `$set` - Sets a profile property or updates a profile property value (if it already exists). - `$set_once` - Sets a profile property only if they do not yet exist on Mixpanel. This ensures that the previous profile property value is not overwritten. -**Updating numeric user profile property** +**Updating numeric profile property** - `$add` - Increments or decrements a numeric user profile property *(not supported in group profiles)*. To increment, pass in a positive numeric value, and to decrement pass in a negative numeric value. If the property does not yet exist, it will set the value passed in as the initial value. @@ -96,7 +96,7 @@ resp = requests.post( print(resp.json()) ``` -## Importing User Profiles via our UI +## Importing Profiles via the UI To get started, click on **Add/Edit Profile** from the [Users](https://mixpanel.com/report/users) page and follow the workflow below. @@ -104,13 +104,13 @@ To get started, click on **Add/Edit Profile** from the [Users](https://mixpanel ![/Screen_Shot_2021-12-01_at_11.44.03_AM.png](/Screen_Shot_2021-12-01_at_11.44.03_AM.png) -### Importing (Create or Modify) a Single User Profile +### Create/Update a Single Profile -#### Set an Identifier Column +**Set an Identifier Column** The most important column is `$distinct_id` for user profiles (or `$group_id` for [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles)). The value needs to match the `distinct_id` property's value (or the value for the [Group Key](/docs/data-structure/advanced/group-analytics#implementation)'s Group ID) that you're sending on your events. -#### Add Additional Properties +**Add Additional Properties** After `$distinct_id`, you can add additional properties to the profile by pressing the **"+ Add Property"** button. Mixpanel will help autocomplete profile properties that you may want to set. @@ -118,7 +118,7 @@ After `$distinct_id`, you can add additional properties to the profile by press We recommend using the `$name` (or `$first_name`, `$last_name`), `$email`, and `$phone` [Reserved Profile Properties](/docs/data-structure/user-profiles#reserved-profile-properties)) if you're uploading a user's name, email, or phone. Mixpanel shows these properties by default in various parts of our UI and are used for [Cohort Syncs](/docs/cohort-sync/overview) as well. -### Importing from CSV +### Bulk Import from CSV When preparing the CSV that you want to upload as profiles, you should **not** include column headers (e.g., \$name, \$email, etc.). Instead, you’ll identify column headers through the CSV upload wizard in the Mixpanel UI. @@ -135,6 +135,8 @@ Go to the **Import from CSV** tab and select your prepared CSV to begin the proc The most important column in your CSV is the `$distinct_id` for user profiles (or `$group_id` for [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles)). The value needs to match the `distinct_id` property's value (or the value for the [Group Key](/docs/data-structure/advanced/group-analytics#implementation)'s Group ID) that you're sending on your events. +The import module will preview the column values from your CSV on the right, corresponding to the property name you are currently defining. + If you do not assign an identifier column, Mixpanel will use your `$email` column as the `$distinct_id` (or `$group_id`) value; if you don’t have an `$email` column either, then the `$distinct_id` (or `$group_id`) value will be assigned randomly by default. Thus, it is highly recommended that you assign an identifier column to avoid unexpected results. #### Choose Desired CSV Columns @@ -143,34 +145,18 @@ You'll have the opportunity to look through all columns in the CSV to preview th ![/Screen_Shot_2021-12-01_at_12.24.00_PM.png](/Screen_Shot_2021-12-01_at_12.24.00_PM.png) -## Deleting User Profiles +## Deleting Profiles User Profiles can be deleted either via the [Users](https://mixpanel.com/report/users) page or programmatically via our [Engage API](https://developer.mixpanel.com/reference/delete-profile). We also provide a `people_delete` method in the mixpanel-utils library [here](https://github.com/mixpanel/mixpanel-utils#people-delete). Similarly, [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles) can also be deleted either via the [Users](https://mixpanel.com/report/users) page or programmatically via our [Groups API](https://developer.mixpanel.com/reference/delete-group). -## Reserved Profile Properties - -Mixpanel reserves certain profile property names for special processing or for specific system features. These properties, when populated, will affect the way Mixpanel processes your data. - -> **Note:** Also refer to the list of Mixpanel [Default Properties](/docs/data-structure/property-reference#default-properties) indicated in our documentation. - -| **Raw Name** | **Display Name** | **Description** | -| ------------ | ---------------- | --------------- | -| $distinct_id | Distinct ID | Mixpanel's internal unique identifier for a profile. See [Identifying Users](/docs/tracking-methods/id-management/identifying-users) and [Group Profiles](/docs/data-structure/advanced/group-analytics#group-profiles) | -| \$name,
\$first_name,
\$last_name | Name,
First Name,
Last Name | The user's / group's general name, as well as, first and last names. These are primarily useful because they are used, if available, in various Mixpanel UI / reports. For user [Cohort Syncs](/docs/cohort-sync/overview), only `$first_name` and `$last_name` is exported. | -| $email | Email | The user's / group's email address. You must set this property if you want to send emails to users via partners receiving cohorts from our [Cohort Syncs](/docs/cohort-sync/overview). | -| $phone | Phone | The user's / group's phone number. You must set this property if you want to send SMS to users via partners receiving cohorts from our [Cohort Syncs](/docs/cohort-sync/overview). Note that a '+' needs to precede international phone numbers. If the user does not import a phone number with the '+' sign in front, the country code will be prefixed to the front of the number based on the $country_code default property, resulting in a phone number with two country codes. | -| $avatar | Avatar URL | Set this property to a URL resource of a gif, jpg, jpeg, or png to update the profile picture in a profile. This property will override a profile picture pulled from [Gravatar](https://gravatar.com/). | -| $created | Created | The time that the profile was created. Note that this is not auto-populated. | -| $mp_first_event_time | First Seen | Mixpanel calculated property that represents the time of the user's (or group's) very first event in Mixpanel. This can be used to filter/segment reports by users (or groups) who were "new" in a particular timeframe. | - ## FAQ -### What should I send as a User Profile Property vs an Event Property? -We recommend primarily using User Profile Properties to track demographic attributes of the user, like their name, email, and domain. Most other properties are better tracked as [Event Properties](/docs/data-structure/events-and-properties). +### What should I send as a User Property vs an Event Property? +We recommend primarily using User Properties to track demographic attributes of the user, like their name, email, and domain. Most other properties are better tracked as [Event Properties](/docs/data-structure/events-and-properties). -That said, User Profile Properties are as flexible as any other properties in Mixpanel, so you can send arbitrary JSON. +That said, User Properties are as flexible as any other properties in Mixpanel, so you can send arbitrary JSON. ### How does Mixpanel join Events and User Profiles? Mixpanel stores Events and User Profiles in two separate tables under the hood. These two tables are joined at query-time, rather than ingestion-time. This means that when you make a report in our UI that uses User Profiles, we run a query that joins the Events table with the User Profiles table. This has two implications: @@ -178,13 +164,19 @@ Mixpanel stores Events and User Profiles in two separate tables under the hood. * If you track User Profiles after you track events, they'll still join retroactively with all past events. This means that you don't need to worry about tracking Events and User Profiles in lockstep with each other. As long as they have the same values for Distinct ID, they'll join with each other. * All Events join with the latest state of a User Profile, rather than its state at a point in time. If there are aspects of a user's state that change over time (for example, their plan type), we recommend tracking that as a property on their events, so that you can analyze that change over time. -### How can I update User Profile Properties? +### How can I update User Properties? User Profiles are mutable; Mixpanel only stores the latest value of each profile property. We have methods to update profile properties via our [HTTP API](https://developer.mixpanel.com/reference/profile-set). -### What are the limits of User Profile Properties? +### Why are empty profiles created when I import profiles from a CSV? +This may occur if you set the incorrect column from your CSV as the `$distinct_id` during your import. You can see which column was erroneously set as the `$distinct_id` by checking the distinct_id value set on these empty profiles. As a best practice, always check the sample values shown in the import module for each selected profile property. + +### How do I bulk delete profiles? +We recommend deleting profiles programmatically via our [Engage API](https://developer.mixpanel.com/reference/delete-profile). We also provide a `people_delete` method in the mixpanel-utils library [here](https://github.com/mixpanel/mixpanel-utils#people-delete). + +### What are the limits of User Properties? Each User Profile can contain up to 2000 properties. User property names can be at most 255 characters in length (longer names are truncated). User property values are limited based on data type, refer to these limits under [Supported Data Types](/docs/data-structure/property-reference#supported-data-types). -Attempts to add more than 2000 user properties for a user profile will fail. You can remove user profile properties using the [$unset](https://developer.mixpanel.com/reference/profile-delete-property) engage operation if you find yourself close to the 2000 per profile limit. +Attempts to add more than 2000 user properties for a user profile will fail. You can remove User Properties using the [$unset](https://developer.mixpanel.com/reference/profile-delete-property) engage operation if you find yourself close to the 2000 per profile limit. ### How can I send User Profiles if I use Segment? Mixpanel is 100% compatible with Segment; just follow Segment's best practices. If you call the [`analytics.identify()`](https://segment.com/docs/connections/spec/identify/) method, Segment will create a User Profile in Mixpanel. You can learn more about our integration in Segment's [docs](https://segment.com/docs/connections/destinations/catalog/actions-mixpanel/#identify-user). diff --git a/pages/docs/tracking-best-practices/bot-traffic.mdx b/pages/docs/tracking-best-practices/bot-traffic.mdx index aba1056681..ebdc2c5879 100644 --- a/pages/docs/tracking-best-practices/bot-traffic.mdx +++ b/pages/docs/tracking-best-practices/bot-traffic.mdx @@ -17,7 +17,9 @@ Any other bot hitting your site will affect your Mixpanel data. That being said, 1. Find the user agent information of the individual accessing the site. 2. Look for the word “bot” anywhere in the user agent information. -3. If you find “bot,” set the $ignore property to true. +3. If you find “bot,” set the $ignore property to true and register it as a super property. + +Any time $ignore is set to true in an event payload, our API drops the payload and prevents it from getting ingested. If you can, identify a common pattern in the bots to block them all in one shot by filtering out any interaction with your site that comes from a web framework that is not a consumer-facing browser. As an example, for GTM bots, this code would look like this: @@ -33,6 +35,8 @@ If you implement this code, you will block all userAgents with "Mozilla/4.0" in If this does not work, you can start tracking this userAgent going forward so you can find the common pattern among all of the bots crawling your site. +It is also common for bots and crawlers to stem from a specific IP address. In this case, you will want to set conditional logic in your implementation to set the $ignore event property to true, then register it as a super property. + Note: `$ignore` must have a string or at least be set to true, or else the event will fire. For example, if I have `'$ignore': ''`, the event will still fire since it's an empty string. `'$ignore': false` will also fire the event. ## Remove Bot Traffic Historically diff --git a/pages/docs/tracking-best-practices/geolocation.md b/pages/docs/tracking-best-practices/geolocation.md new file mode 100644 index 0000000000..ab0c81bcd8 --- /dev/null +++ b/pages/docs/tracking-best-practices/geolocation.md @@ -0,0 +1,152 @@ +# Geolocation + +## Overview +- Geolocation properties found in events and profiles +- $country, $region, $city are default properties tracked by ingestion API +- Also reserved properties; appears in reserved locations in the UI (profile page, etc.) + +## Default Geolocation Tracking +- geolocation properties are automatically set by default +- Event geo props set when events are tracked, using IP of the request at the time of tracking. +- Profile geo props are updated whenever profile properties are update or identify is called. + +### IP address Parsing +- IP address is not stored +- We pass IP addresses from request, parse it through Maxmind into geolocation properties, then discard IP address value before ingestion. +- IP address is only an approximation. If precision needed, you can manually configure the location of your payloads. See below + +## Server-side Geolocation Tracking +- sometimes you want to over-ride default behavior. +- Ex: have that info already in DB, server-side implementations, precision using lat/long, etc. +- 3 ways to customize geolocation in your payloads + +### Define Geolocation Properties +- can override default behavior by manually defining the $country, $region, $city properties in your payload. Detecting these properties in payload will bypass IP parsing mechanism. + +**Events** +- define in properties object + +``` +{ + "event": "Signed Up", + "properties": { + "distinct_id": "13793", + "token": "mytoken", + "mp_country_code": "US", + "$city": "San Francisco", + "$region":"California" + } +} +``` + +**Users** +- define om $set object + +``` +{ + "$token": "mytoken", + "$distinct_id": "13793", + "$set": { + "My_property": "my_value", + "$country_code": "US", + "$region": "California", + "$city": "San Francisco" + } +} +``` + + +### Define Latitude and Longitude +If you have access to Latitude and Longitude information, you can specify `$latitude` and `$longitude` in the payload so that Mixpanel will use these properties (instead of the IP address) to infer the closest city. + +**Events** + +On events, the event properties must be named `$latitude` and `$longitude` and the values should be in floating point decimal degrees. +``` +{ + "event": "Signed Up", + "properties": { + "distinct_id": "13793", + "token": "mytoken", + "$latitude": 37.77, + "$longitude": -122.42 + } +} +``` + +**User Profiles** + +On user profile updates, the data must be named `$latitude` and `$longitude` and the values should be in floating point decimal degrees. + +You would also need to set `$latitude` and `$longitude` outside of the `$set` dictionary. + +You will see profile property `$geo_source=reverse_geocoding` in the Profile UI if location properties were determined through `$latitude` and `$longitude`. + +Do note: Reverse geocoding for user profiles is not supported via client-side SDKs. +``` +{ + "$token": "mytoken", + "$distinct_id": "13793", + "$latitude": 37.77, + "$longitude": -122.42, + "$set": { + "My_property": "my_value" + } +} +``` + +### Define IP Address +- Can manually define IP address value to have Mixpanel parse your chosen IP address instead +- Mixpanel drops IP address at ingestion. If you want to store it, name the property something else +- Events uses "ip", engage uses "$ip" + +**Events** +- Events use "ip" inside properties object +``` +{ + "event": "Signed Up", + "properties": { + "distinct_id": "13793", + "token": "mytoken", + "ip": "136.24.0.114" + } +} +``` + +**Users** +- Engage use "$ip" outside $set onject + +``` +{ + "$token": "mytoken", + "$distinct_id": "13793", + "$ip": "136.24.0.114", + "$set": { + "My_property": "my_value" + } +} +``` + +#### Ignore IP Address + +As all server-side requests originate from the same IP, such as the IP of your server, it can have the unintended effect of setting the location of all of your users to the location of your datacenter. To prevent the Engage API from updating your profile geolocation using the IP address of the incoming request, you can set the $ip to 0 in your payload. + +``` +// $ip set to 0 +// Engage API will ignore not parse the IP address +// Geolocation will not be updated +{ + "$token": "mytoken", + "$distinct_id": "13793", + "$ip": "0", + "$set": { + "My_property": "my_value" + } +} +``` + +You can set append `ip=0` to your request URL to set $ip to 0 for all your Engage requests. + +``` +api.mixpanel.com/engage?verbose=1&ip=0 +``` diff --git a/pages/docs/tracking-best-practices/server-side-best-practices.md b/pages/docs/tracking-best-practices/server-side-best-practices.md index 12d940b061..aaa0648afa 100644 --- a/pages/docs/tracking-best-practices/server-side-best-practices.md +++ b/pages/docs/tracking-best-practices/server-side-best-practices.md @@ -171,58 +171,3 @@ Page view tracking must be done manually for server-side implementations. Here a - Fire page view events only on successful responses to the client - Parse headers and the request URL for common web analytics properties such as referrer and UTM parameters - See above for [parsing user agent](#tracking-browser-device-and-os) and [marketing attribution properties](#tracking-utms-and-referrer) - -## Identifying Users -Our server libraries normally require that you specify the distinct_id value for each event. If you _don't_ know the user's identity at the time the event is tracked, then they're an anonymous user. When using our Web or Mobile SDKs, Mixpanel will automatically generate an ID that's local to that user's device. This ID will persist on all events tracked by that user on that device, until you call `identify()` or `reset()`. More on that in our [identity management guide](/docs/tracking-methods/id-management/identifying-users). - -If you're tracking from servers, you'll need to generate and manage that ID yourself. When you have hybrid implementations (events also come from the client-side), you could optionally send the ID generated on the client to the server and keep it as a session variable instead of generating a new one. - -As an outline, you will want to follow the approach below: - -### Step 1: Generate an anonymous ID -The key is to have an ID that is unique to each user and persists during that user's session. We recommend generating a UUID and storing that value in a cookie. All common server frameworks provide a simple way to set and retrieve cookies per request. - -### Step 2: Leverage this ID for anonymous events -When tracking events from your server, set the `distinct_id` property of events to the anonymous ID generated. - -***In case your project has Simplied ID management specifically***, and the user is anonymous, you should include a property named `$device_id` with this value. You can then optionally also include the `distinct_id` (requires for you to prefix the ID with the string `'$device:'`) but do note that if you don't include it, it will be assumed. You can see more in the python code example. - -### Step 3: Set the authenticated ID once users log in - -Once the user logs in, you know their true ID, you should leverage the new ID for the user. Depending on the ID management model on your project (see project settings), you can do the following: - -**If you are using the original ID merge API** - -Send an `$identify` event combining the anonymous and authenticated IDs. Events after this should use the authenticated ID. Learn more in our [ID Merge guide](/docs/tracking-methods/id-management/identifying-users). - -**If you are using the Simplified ID merge API** -Set the `$user_id` property to that ID. Continue setting `$device_id` to the ID generated in step 1. If Mixpanel receives an event with both `$device_id` and `$user_id` set, it will create a link between those two users. This is essential to track pre-login and post-login behavior accurately. - -The `distinct_id` will be assumed but if you include it, it should be the same value as the `$user_id`. - -**Example python code** - -Here's a pseudocode example using Django's [cookies](https://django-book.readthedocs.io/en/latest/chapter14.html#cookies) and [authentication](https://django-book.readthedocs.io/en/latest/chapter14.html#using-users). It assumes the client is setting and sending cookies: -```python -import uuid - -def track_to_mp(request, event_name, properties): - # This assumes you've previously set a cookie called "SESSION_ID" that is local to the user's session - # Set `$device_id` to that cookie's value - properties["$device_id"] = request.cookies.get('SESSION_ID') - - # Set $user_id if the user is authenticated (logged in). - if request.user.is_authenticated(): - properties["$user_id"] = request.user.username - - # Note: leave the first argument blank here, since we're passing $device_id and $user_id as properties. - mp.track("", event_name, properties) - -def identify_user(request): - properties = { - "$device_id": uuid.uuid4(), - "$identified_id": request.user.username - - } - track_to_mp(request, "$identify", properties) -``` diff --git a/pages/docs/tracking-best-practices/tracking-plan.md b/pages/docs/tracking-best-practices/tracking-plan.md index d80c9e3013..2db49029a4 100644 --- a/pages/docs/tracking-best-practices/tracking-plan.md +++ b/pages/docs/tracking-best-practices/tracking-plan.md @@ -30,4 +30,6 @@ Mixpanel provides the following templates for vertical-specific tracking plans: - [SaaS](https://docs.google.com/spreadsheets/d/1A5wm5MKzRfSOZfUfCAg8YpePiz8Jn3Ar_u8KBo5lD6g/#gid=1641519238) - [Financial Services](https://docs.google.com/spreadsheets/d/1oGv6vbIFiYbima9IX4ItpBJvuChs-zzh83MRt_dSPgg/#gid=1641519238) -You can also access a copy of a [blank Tracking Plan from here](https://docs.google.com/spreadsheets/d/1ZdOZ6TMtRPxy7qRxiLsvH9HWcHJM6nZydWKoThRxFKc/edit#gid=1641519238). Save a copy to your device to get started on your tracking plan. +You can access a copy of a [blank Tracking Plan from here](https://docs.google.com/spreadsheets/d/1ZdOZ6TMtRPxy7qRxiLsvH9HWcHJM6nZydWKoThRxFKc/edit#gid=1641519238). Save a copy to your device to get started on your tracking plan. + +Consider hiring a [Mixpanel Expert](https://mixpanel.com/partners/experts). All consultancies, agencies, and freelancers in our directory have been trained by Mixpanel and earned a Certified Partner badge. diff --git a/pages/docs/data-structure/advanced/utm-tags.md b/pages/docs/tracking-best-practices/traffic-attribution.md similarity index 90% rename from pages/docs/data-structure/advanced/utm-tags.md rename to pages/docs/tracking-best-practices/traffic-attribution.md index 820928956e..e46c56d6f5 100644 --- a/pages/docs/data-structure/advanced/utm-tags.md +++ b/pages/docs/tracking-best-practices/traffic-attribution.md @@ -1,10 +1,9 @@ -# UTM Tags +# Traffic Attribution +## Web Attribution When setting up your Mixpanel implementation, one issue of particular interest is tracking users by their original source of traffic. By default, Mixpanel does some of this tracking for you on the web in the form of several [default properties](/docs/data-structure/property-reference). -## Web Attribution - ### UTM Properties Mixpanel's Javascript library tracks all [UTM tags](/docs/tracking-methods/sdks/javascript#tracking-utm-parameters) by default. This allows you to segment key actions by relevant campaign information using [attribution models](/docs/features/attribution), so that you can quantify the effectiveness of specific campaigns. @@ -32,13 +31,13 @@ An initial referrer is equal to $direct when a user first lands on a site withou ## Mobile Attribution -Mobile attribution, or tracking campaign source for app installs on iOS/Android, can be more complex than the web due to the way mobile devices store attribution information. +Mobile attribution, or tracking campaign sources for app installs/uninstalls/downloads on mobile devices, can be more complex than the web due to the way mobile devices store attribution information. For Android, Google provides a [Play Install Referrer Library](https://developer.android.com/google/play/installreferrer/library) so you know where your installations came from. You can use the [getInstallReferrer ( )](https://developer.android.com/reference/com/android/installreferrer/api/ReferrerDetails#getinstallreferrer) method to retrieve the referrer URL string, parse it and send that data to Mixpanel as properties in events. For iOS, users enter the Apple App Store carrying data about where they came from, but the App Store strips that data once the user arrives in the store. Therefore, users who download your application don’t come with any data showing where they were before arriving at the App Store. -In order to track channel attribution on iOS, you'll need to use a mobile attribution tool. You can see a list of the partners we integrate with on our [tech partners page](https://mixpanel.com/partners/integrations?categories=attribution-deep-linking). +In order to track channel attribution on iOS, you'll need to use a [mobile attribution tool](/docs/tracking-methods/integrations/mobile-attribution-tracking). You can see a list of the partners we integrate with on our [tech partners page](https://mixpanel.com/partners/integrations?categories=attribution-deep-linking). ## Server-Side Attribution diff --git a/pages/docs/tracking-methods/id-management.md b/pages/docs/tracking-methods/id-management.md new file mode 100644 index 0000000000..2e034aea77 --- /dev/null +++ b/pages/docs/tracking-methods/id-management.md @@ -0,0 +1,48 @@ +# Identity Management + +## Overview +- What is ID management? - Assigning ID and maintaining ID mapping to make sure data gets attributed to users accurately. +- Why is ID Management important? - Reporting, accuracy, funnel conversion, tying users to events, MTU pricing, etc. + +## Distinct ID +- What is distinct id? +- If 2 event have 2 IDs, Mixpanel will consider it as 2 users + +## ID Management in Action +- show Charlie example; one user, different device +- show scenario without id management (separate users) +- show scenario with identify call (merged accurately +- Summary: ID management is the process of assigning and maintaining ID mapping to make sure data is attributed to users accurately. + +## Identity Merge +- There are 2 versions. New orgs default to v3 +- How are the 2 versions different? +- How achieve goal of managing ID, just through different means under the hood + +### Legacy API +- Briefly touch on this, just link to [unlisted doc here](https://github.com/mixpanel/docs/blob/main/legacy/aliases.md) + +### Check your ID management version +- something about checking settings, simplified, original, disabled. + +## Best Practice +#### Use a unique identifier that is consistent over time +We recommend using an ID that is unique to each user and does not change, for example, a database ID. While using an identifier like email may be more convenient, keep in mind that you cannot merge 2 `$user_id`s or change a `$user_id`, so if the user changes their email, they will count as a separate user. + +#### Track the unique identifier as a super property and user property to assist in troubleshooting +You can track the user's unique identifier as a [super property via mixpanel.register](https://developer.mixpanel.com/docs/javascript#super-properties) and [user property via mixpanel.people.set](https://developer.mixpanel.com/docs/javascript#setting-profile-properties) as soon as it is available in the app i.e. on a successful sign-up / login or when an app is re-opened in a logged in state. +In the cases when ID Merge is not implemented properly, you can rely on these properties for troubleshooting purposes. + +#### Avoid creating profiles for anonymous users +Avoid creating profiles for anonymous users. If possible, cache user profile properties update in cookie or local storage and only send them to Mixpanel after the user is identified (ie logged-in state). + +It is possible to set user profile properties for unidentified users by sending the profile updates to $distinct_id=$device:. However, user profile properties are not preserved when $device_ids are linked to $user_ids, so any properties set before the IDs became linked will need to be set again using $distinct_id= once the user is identified. + +#### QA your ID management implementation during the development phase +Here are a few things to look out for: +- Ensure that cross-platform, pre and post-registration events are linked to the same user on Mixpanel. +- Ensure that no duplicate profiles are created as the users go through the onboarding, registration, login, and cross-platform user journey. +- Ensure that all the user’s identifiers are stored in the same Identity Cluster and that all their events are displayed on a single profile on Mixpanel. + +#### Keep a record of your ID management implementation +We encourage you to document your implementation (or create a diagram of the implementation). This will come in handy when you need to re-implement this on a new platform or troubleshoot ID management issue. diff --git a/pages/docs/tracking-methods/id-management/_meta.json b/pages/docs/tracking-methods/id-management/_meta.json index 1b30eea926..966d831975 100644 --- a/pages/docs/tracking-methods/id-management/_meta.json +++ b/pages/docs/tracking-methods/id-management/_meta.json @@ -1,4 +1,9 @@ { - "identifying-users": "Identifying Users", - "migrating-to-simplified-id-merge-system": "Migrating to Simplified ID Merge" + "original-id-merge": "Original ID Merge", + "simplified-id-merge": "Simplified ID Merge", + "server-side-id-management": "Server-side ID Management", + "migrating-to-simplified-id-merge-system": "Migrating to Simplified ID Merge", + "identifying-users": { + "display": "hidden" + } } diff --git a/pages/docs/tracking-methods/id-management/original-id-merge.md b/pages/docs/tracking-methods/id-management/original-id-merge.md new file mode 100644 index 0000000000..d8ce0d5c23 --- /dev/null +++ b/pages/docs/tracking-methods/id-management/original-id-merge.md @@ -0,0 +1,123 @@ +# Original ID Merge + +> Call out to check ID management version in settings and link to Simplified doc + +## Overview +- System use 3 events to manipulate distinct_id + +## Usage +If using our Web/Mobile SDKs or a CDP like Segment or Rudderstack, there are only 2 steps: +1. Call `.identify()` when a user signs up or logs in. Pass in the user's known identifier (eg: their ID from your database). +2. Call `.reset()` when a user logs out. + +Any events prior to calling `.identify` are considered anonymous events. Mixpanel's SDKs will generate a `$device_id` to associate these events to the same anonymous user. By calling `.identify()` when a user signs up or logs in, you're telling Mixpanel that `$device_id` belongs to a known user with ID `user_id`. Under the hood, Mixpanel will stitch the event streams of those users together. This works even if a user has multiple anonymous sessions (eg: on desktop and mobile). As long as you always call `.identify` when the user logs in, all of that activity will be stitched together. + +## Mechanism +- talk about the 3 events in detail +- link to Identity API Dev Doc +- +### $identify +- example payload +- this is the event payload underneath identify SDK function (function is basically this event) +- logic tree +- failure reason, other identify reserved props + +### $merge +- example payload +- API only event +- No logic tree +- merge any clusters together under 500 IDs +- Good for fixing mistakes + +### $create_alias +- example payload +- this is the event payload underneath alias SDK function (function is basically sending an event)] +- Not necessary in this version; preserved to make easier for leagacy users to transition + +## Example User Flows +- Charlie example. + +> Mimic below but update to Original ID Merge + +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. + +Note: these flows walk through how `distinct_id` is set in Simplified ID Merge; in Original ID Merge, the value of `distinct_id` is not deterministic. See the [FAQ](#what-is-distinct-id) for more details on how `distinct_id` is set. + +### New User Signup + +1. A user lands in your product on a new device and interacts with your product before signing up. Our SDK will assign the user a random `$device_id` and persist it. All events tracked at this point will send only a `$device_id`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | ----- | + | 1 | D1 | | $device:D1 | | + | 2 | D1 | | $device:D1 | | + +2. The user returns later and signs up for your product. You call `.identify()`. All events sent after this point are tracked with both the original `$device_id` and the new `$user_id`. Mixpanel will retroactively set the `$user_id` on any prior events with the user’s `$device_id` so that both event streams are joined. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | --------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | Retroactively updated | + | 2 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | Retroactively updated | + | 3 | D1 | U1 | U1 | Links D1 ⇒ U1 | + +### Returning User + +1. The user from the previous flow returns, but is on a new device and has not logged in yet. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | ------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 3 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 4 | D2 | | $device:D2 | New device D2 | + | 5 | D2 | | $device:D2 | | + +2. The user logs in. Call `.identify(U1)` to tell us that the user on this device is the same `$user_id` we have seen before. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | --------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 3 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 4 | D2 | | ~~*$device:D2*~~ ⇒ **U1** | Retroactively updated | + | 5 | D2 | | ~~*$device:D2*~~ ⇒ **U1** | Retroactively updated | + | 6 | D2 | U1 | U1 | Links D2 ⇒ U1 | + +### Multiple Users, One Device + +1. A first user begins using a new device. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | ----- | + | 1 | D1 | | $device:D1 | | + +2. The user logs in. Call `.identify(U1)`, which links the `$device_id` to their `$user_id`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | --------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | Retroactively updated | + | 2 | D1 | U1 | U1 | Links D1 ⇒ U1 | + +3. The user logs out. At this point, you should call `.reset()`, or manually generate a new `$device_id` if you are managing it yourself. A new user shows up and tracks events using this new `$device_id`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | -------------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 3 | D2 | | $device:D2 | Reset generated new ID: D2 | + | 4 | D2 | | $device:D2 | | + +4. This new user (U2) now logs in. Call `.identify(U2)`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | -------------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 3 | D2 | | ~~*$device:D2*~~ ⇒ **U2** | Retroactively updated | + | 4 | D2 | | ~~*$device:D2*~~ ⇒ **U2** | Retroactively updated | + | 5 | D2 | U2 | U2 | Links D2 ⇒ U2 | + +## Limitations +- canonical distinct_id not configurable +- 500 ID limit +- $merge profile direction not predictable diff --git a/pages/docs/tracking-methods/id-management/server-side-id-management.md b/pages/docs/tracking-methods/id-management/server-side-id-management.md new file mode 100644 index 0000000000..741a4defcd --- /dev/null +++ b/pages/docs/tracking-methods/id-management/server-side-id-management.md @@ -0,0 +1,58 @@ +# Server-side ID Management + +> Call out to check ID Management version + +## Overview + +Our server libraries normally require that you specify the distinct_id value for each event. If you _don't_ know the user's identity at the time the event is tracked, then they're an anonymous user. When using our Web or Mobile SDKs, Mixpanel will automatically generate an ID that's local to that user's device. This ID will persist on all events tracked by that user on that device, until you call `identify()` or `reset()`. More on that in our [identity management guide](/docs/tracking-methods/id-management/). + +If you're tracking from servers, you'll need to generate and manage that ID yourself. When you have hybrid implementations (events also come from the client-side), you could optionally send the ID generated on the client to the server and keep it as a session variable instead of generating a new one. + +## Identifying Users Server-side + +### Step 1: Generate an anonymous ID +The key is to have an ID that is unique to each user and persists during that user's session. We recommend generating a UUID and storing that value in a cookie. All common server frameworks provide a simple way to set and retrieve cookies per request. + +### Step 2: Leverage this ID for anonymous events + +If your project is using [Original ID Merge API](/docs/tracking-methods/id-management/original-id-merge/), track anonymous user events from your server, setting the `distinct_id` event property to the anonymous ID generated. + +If your project is using [Simplified ID Merge API](/docs/tracking-methods/id-management/simplified-id-merge/), track anonymous user events from your server, setting the `$device_id` event property to the anonymous ID generated. You do not need to set the `distinct_id` property since it will be assumed to `$device_id` if there is no `$user_id` in the event. + +### Step 3: Set the authenticated ID once users log in + +Once the user logs in, you know their true ID, you should leverage the new ID for the user. + +If your project is using [Original ID Merge API](/docs/tracking-methods/id-management/original-id-merge/), send an `$identify` event, combining the anonymous ID and the authenticated ID. Events after this should use the authenticated ID. Learn more in our [Original ID Merge guide](/docs/tracking-methods/id-management/original-id-merge/). + +If your project is using [Simplified ID Merge API](/docs/tracking-methods/id-management/simplified-id-merge/), set the `$user_id` property to the authenticated ID and continue setting `$device_id` to the anonymous ID generated in step 1, including both the `$user_id` and `$device_id` in your events moving forward. If Mixpanel receives an event with both `$device_id` and `$user_id` set, it will merge the two IDs together. This is essential to track pre-login and post-login behavior accurately. The `distinct_id` will be assumed to the `$user_id`. If you choose to manually define the `distinct_id` property, it should be the same value as the `$user_id`. + +### Example python code** + +Here's a pseudocode example using Django's [cookies](https://django-book.readthedocs.io/en/latest/chapter14.html#cookies) and [authentication](https://django-book.readthedocs.io/en/latest/chapter14.html#using-users). It assumes the client is setting and sending cookies: +```python +import uuid + +def track_to_mp(request, event_name, properties): + # This assumes you've previously set a cookie called "SESSION_ID" that is local to the user's session + # Set `$device_id` to that cookie's value + properties["$device_id"] = request.cookies.get('SESSION_ID') + + # Set $user_id if the user is authenticated (logged in). + if request.user.is_authenticated(): + properties["$user_id"] = request.user.username + + # Note: leave the first argument blank here, since we're passing $device_id and $user_id as properties. + mp.track("", event_name, properties) + +def identify_user(request): + properties = { + "$device_id": uuid.uuid4(), + "$identified_id": request.user.username + + } + track_to_mp(request, "$identify", properties) +``` + +## Hybrid implementations +- add short call out for best practices diff --git a/pages/docs/tracking-methods/id-management/simplified-id-merge.md b/pages/docs/tracking-methods/id-management/simplified-id-merge.md new file mode 100644 index 0000000000..883a013c1d --- /dev/null +++ b/pages/docs/tracking-methods/id-management/simplified-id-merge.md @@ -0,0 +1,118 @@ +# Simplified ID Merge + +> Call out to check ID management version in settings and link to Original doc + +## Overview +- System use $device_id and $user_id to manipulate distinct_id + +## Usage +If using our Web/Mobile SDKs or a CDP like Segment or Rudderstack, there are only 2 steps: +1. Call `.identify()` when a user signs up or logs in. Pass in the user's known identifier (eg: their ID from your database). +2. Call `.reset()` when a user logs out. + +Any events prior to calling `.identify` are considered anonymous events. Mixpanel's SDKs will generate a `$device_id` to associate these events to the same anonymous user. By calling `.identify()` when a user signs up or logs in, you're telling Mixpanel that `$device_id` belongs to a known user with ID `user_id`. Under the hood, Mixpanel will stitch the event streams of those users together. This works even if a user has multiple anonymous sessions (eg: on desktop and mobile). As long as you always call `.identify` when the user logs in, all of that activity will be stitched together. + +## Mechanism +- talk about the $user_id and $device_id in detail + +### $device_id +- autogenerated by client-side SDK and attached to all events +- this becomes distinct_id attached to event if $user_id not present +- all events should have this property +- aka anonnymous ID + +### $user_id +- Calling identify SDK function sets the `user_id` value passed to the function as the $user_id for all events moving forward +- `$user_id` will always becomes distinct_id for the event whenever it is present +- when `$user_id` and `$device_id` are detected in the same event for the first time, merge occurs + + + +## Example User Flows +- Charlie example. + +> Mimic below but update to Original ID Merge + +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. + +Note: these flows walk through how `distinct_id` is set in Simplified ID Merge; in Original ID Merge, the value of `distinct_id` is not deterministic. See the [FAQ](#what-is-distinct-id) for more details on how `distinct_id` is set. + +### New User Signup + +1. A user lands in your product on a new device and interacts with your product before signing up. Our SDK will assign the user a random `$device_id` and persist it. All events tracked at this point will send only a `$device_id`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | ----- | + | 1 | D1 | | $device:D1 | | + | 2 | D1 | | $device:D1 | | + +2. The user returns later and signs up for your product. You call `.identify()`. All events sent after this point are tracked with both the original `$device_id` and the new `$user_id`. Mixpanel will retroactively set the `$user_id` on any prior events with the user’s `$device_id` so that both event streams are joined. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | --------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | Retroactively updated | + | 2 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | Retroactively updated | + | 3 | D1 | U1 | U1 | Links D1 ⇒ U1 | + +### Returning User + +1. The user from the previous flow returns, but is on a new device and has not logged in yet. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | ------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 3 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 4 | D2 | | $device:D2 | New device D2 | + | 5 | D2 | | $device:D2 | | + +2. The user logs in. Call `.identify(U1)` to tell us that the user on this device is the same `$user_id` we have seen before. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | --------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 3 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 4 | D2 | | ~~*$device:D2*~~ ⇒ **U1** | Retroactively updated | + | 5 | D2 | | ~~*$device:D2*~~ ⇒ **U1** | Retroactively updated | + | 6 | D2 | U1 | U1 | Links D2 ⇒ U1 | + +### Multiple Users, One Device + +1. A first user begins using a new device. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | ----- | + | 1 | D1 | | $device:D1 | | + +2. The user logs in. Call `.identify(U1)`, which links the `$device_id` to their `$user_id`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | --------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | Retroactively updated | + | 2 | D1 | U1 | U1 | Links D1 ⇒ U1 | + +3. The user logs out. At this point, you should call `.reset()`, or manually generate a new `$device_id` if you are managing it yourself. A new user shows up and tracks events using this new `$device_id`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | -------------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 3 | D2 | | $device:D2 | Reset generated new ID: D2 | + | 4 | D2 | | $device:D2 | | + +4. This new user (U2) now logs in. Call `.identify(U2)`. + + | Event | $device_id | $user_id | distinct_id (set by Mixpanel) | Notes | + | ----- | ---------- | -------- | ----------------------------- | -------------------------- | + | 1 | D1 | | ~~*$device:D1*~~ ⇒ **U1** | | + | 2 | D1 | U1 | U1 | Links D1 ⇒ U1 | + | 3 | D2 | | ~~*$device:D2*~~ ⇒ **U2** | Retroactively updated | + | 4 | D2 | | ~~*$device:D2*~~ ⇒ **U2** | Retroactively updated | + | 5 | D2 | U2 | U2 | Links D2 ⇒ U2 | + +## Limitations +- cannot link 2 anon $device_id without assigning a $user_id +- cannot have 2 $user_id in a cluster +- no $merge for fixing mistakes +- $merge profile direction not predictable diff --git a/pages/docs/tracking-methods/integrations.mdx b/pages/docs/tracking-methods/integrations.mdx index dd52af3668..c6519b558b 100644 --- a/pages/docs/tracking-methods/integrations.mdx +++ b/pages/docs/tracking-methods/integrations.mdx @@ -1,8 +1,10 @@ # Integrations +> This page highlights integrations that send data into Mixpanel. For integrations that export Mixpanel data to other destinations, see [Data Pipelines](/docs/data-pipelines/overview) and [Cohort Syncs](/docs/cohort-sync/overview). + import { Card, Cards } from 'nextra/components' -These integrations allow you to send your tracking data to Mixpanel. You may review our complete integrations directory [here](https://mixpanel.com/partners/integrations). If you don't see what +These integrations allow you to send your tracking data into Mixpanel. You may review our complete integrations directory [here](https://mixpanel.com/partners/integrations). If you don't see what you're looking for [reach out to us](https://mixpanel.com/get-support). ### Featured Integrations @@ -15,6 +17,7 @@ you're looking for [reach out to us](https://mixpanel.com/get-support). ### All Integrations + diff --git a/pages/docs/tracking-methods/integrations/_meta.json b/pages/docs/tracking-methods/integrations/_meta.json index 4494a734b0..6ad83fd4e1 100644 --- a/pages/docs/tracking-methods/integrations/_meta.json +++ b/pages/docs/tracking-methods/integrations/_meta.json @@ -1,4 +1,5 @@ { + "ad-spend": "Ad Spend", "amazon-s3": "Amazon S3", "cms-ecommerce": "CMS & E-Commerce", "customer-io": { diff --git a/pages/docs/data-structure/advanced/ad-spend.md b/pages/docs/tracking-methods/integrations/ad-spend.md similarity index 100% rename from pages/docs/data-structure/advanced/ad-spend.md rename to pages/docs/tracking-methods/integrations/ad-spend.md diff --git a/pages/docs/tracking-methods/integrations/google-tag-manager.mdx b/pages/docs/tracking-methods/integrations/google-tag-manager.mdx index 39a64cd48b..527010db6c 100644 --- a/pages/docs/tracking-methods/integrations/google-tag-manager.mdx +++ b/pages/docs/tracking-methods/integrations/google-tag-manager.mdx @@ -52,3 +52,12 @@ Save the tag when done. ### Testing You can then enter **Preview** mode by clicking the blue **Preview** button in the Google Tag Manager UI. This opens a new tab with your website running the GTM container, and you can proceed to test the Mixpanel tag as if the container were published. In the Tag Assistant Preview tab, you can see additional information about the trigger events, tags, and variables that fire while you are browsing the page in Preview mode. + +## Tags Template +- describe each GTM tag +- Show screenshots of tags +- Share corresponding JS SDK function + +## Debugging +- content on troubleshooting steps here + diff --git a/pages/docs/tracking-methods/integrations/segment.md b/pages/docs/tracking-methods/integrations/segment.md index 72d5219f6c..368bd4c8a6 100644 --- a/pages/docs/tracking-methods/integrations/segment.md +++ b/pages/docs/tracking-methods/integrations/segment.md @@ -1,16 +1,9 @@ # Segment +>Eligible startups receive their first year of Mixpanel free, valued up to $50,000. Learn more about the [Startup Program](/docs/pricing/startup-program) and [apply today](https://mixpanel.com/startups/). +## Overview Segment is a CDP (Customer Data Platform) which lets you track event data and route it to various downstream destinations. Mixpanel integrates seamlessly with Segment -- if you use Segment, it takes just a few clicks to set up Mixpanel. -## Startup Credit Program -Mixpanel offers \$50K in credits to [eligible startups](https://mixpanel.com/startups). Because of our Segment partnership, we're also able to offer startups \$50k in Segment credits. This gives startups the runway to use both tools for free. - -Once you create your Segment and Mixpanel accounts, you can fill out [this form](https://airtable.com/shrLP3GSZnxt1WT2v?prefill_Partner%20Code=Mixpanel) and Segment will get back to you within 48 hours to confirm your credits are applied. - -Startup eligibility requirements: -* Founded less than 2 years ago -* Raised no more than $8MM USD in total funding - ## How the Integration Works In the simplest form, the Segment libraries (“Sources”) generate messages about what’s happening in your site or app, and send them to the Segment servers. Segment then translates the content of those messages into different formats for use by other tools (which we call ‘Destinations’), and sends the translated messages to those tools. The Segment servers also archive a copy of the data, and can send data to your storage systems (such as databases, warehouses, or bulk-storage buckets). @@ -70,6 +63,7 @@ If you are using [Segment Device Mode](https://segment.com/docs/connections/dest * By default, all traits specified in the identify call will be registered as super properties. This means if you have the [“Automatically set all Traits as Super Properties and People Properties”](https://segment.com/docs/connections/destinations/catalog/mixpanel/#settings) setting turned on, all traits specified in the identify call will be added as both a super property and profile property for the user. ## Debugging +### Segment Source Debugger For debugging purposes, it can be useful to see exactly what Segment is sending to Mixpanel. You can validate this data through the [Segment Source Debugger](https://segment.com/docs/connections/sources/debugger/). In the Segment Source Debugger, you can select the event you are looking to validate: yGK1yH7zGy_cv5hLBEHgdU9oMyALishD6S0kObRRJANGxbjIEL @@ -78,6 +72,15 @@ Click the “Validate” button in the top right corner and choose “Mixpanel You can then copy the data payload and decode it in a [base64 decoder](https://www.base64decode.org/) to see the JSON event that was sent to Mixpanel. +### Delivery Overview + +Content about delivery overview + +### Event Tester + +Content about event tester + + ## FAQ ### Why are my Segment data not appearing in my project? This could be due to several reasons: @@ -103,3 +106,6 @@ Super properties can only be set when you are running in device mode. The super ### How do I track page views using Segment? Page calls are automatically tracked via Segment. These can be tracked from Segment to Mixpanel as Loaded a Page or Loaded a Screen. To turn them off, you need to [configure this in your Segment settings](https://segment.com/docs/connections/destinations/catalog/mixpanel/#page). + +### Why is Boardman, Oregon appearing in my user's geolocation properties? +If you are seeing high traffic coming from Boardman, Oregon, your Segment Source might be sending server-side requests to your Mixpanel destination. To correct this, manually pass in the IP information to your payloads, or set the IP to `0` which will cause Mixpanel API to ignore the location. diff --git a/pages/docs/tracking-methods/sdks.mdx b/pages/docs/tracking-methods/sdks.mdx new file mode 100644 index 0000000000..365efc06ed --- /dev/null +++ b/pages/docs/tracking-methods/sdks.mdx @@ -0,0 +1,36 @@ +# SDKs + +import { Card, Cards } from 'nextra/components' + +Our SDKs allow you to implement Mixpanel in a wide range of environments. Visit our [Github repo](https://mixpanel.com/partners/integrations) to see the library source code. + +If you do not see an SDK in your preferred language, leverage our [HTTP APIs](https://developer.mixpanel.com/reference/ingestion-api) directly. + +### Client-Side SDKs + + + + + + + + + + + +### Server-Side SDKs + + + + + + + + + + +### Utility + + + + diff --git a/pages/docs/tracking-methods/sdks/_meta.json b/pages/docs/tracking-methods/sdks/_meta.json index 66eee2d2d0..1c8efd55c4 100644 --- a/pages/docs/tracking-methods/sdks/_meta.json +++ b/pages/docs/tracking-methods/sdks/_meta.json @@ -11,5 +11,10 @@ "ruby": "Ruby", "php": "PHP", "go": "Go", - "java": "Java" + "java": "Java", + "mp-utils": { + "title": "Mixpanel-utils↗", + "href": "https://github.com/mixpanel/mixpanel-utils", + "newWindow": true + } } diff --git a/pages/docs/tracking-methods/sdks/android.md b/pages/docs/tracking-methods/sdks/android.md index 2a5008510c..440e2839e9 100644 --- a/pages/docs/tracking-methods/sdks/android.md +++ b/pages/docs/tracking-methods/sdks/android.md @@ -6,6 +6,28 @@ Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=an The [Full API Reference](http://mixpanel.github.io/mixpanel-android/index.html), [Library Source Code](https://github.com/mixpanel/mixpanel-android), and an [Example Application](https://github.com/mixpanel/sample-android-mixpanel-integration) is documented in our GitHub repo. +## Initialize the Library +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). +```java +import com.mixpanel.android.mpmetrics.MixpanelAPI; + +public class MainActivity extends ActionBarActivity { + private MixpanelAPI mp; + + @Override + protected void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + + trackAutomaticEvents = false; + // Replace with your Project Token + mp = MixpanelAPI.getInstance(this, "YOUR_TOKEN", trackAutomaticEvents); + } +} +``` +### Configuration Options +See all [config options](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MPConfig.html). + ## Sending Events Once you've initialized the library, you can track an event using `.track()` with the event name and properties. @@ -43,7 +65,9 @@ if(imageUpload()){ It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event - for example, the user's age, gender, source, or initial referrer. -To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are saved to device storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). +To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are saved to device storage, and will persist across invocations of your app. Super properties are indistinguishable from other event properties once ingested in your project. + +Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference/default-properties). To set super properties, call `.registerSuperProperties()` ``` @@ -165,33 +189,6 @@ mixpanel.getPeople().append("Favorite Colors", "Green") There are a few other types of profile updates. They can be accessed through the [MixpanelPeople class](http://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html). -## Tracking Revenue - -Mixpanel makes it easy to analyze the revenue you make from individual customers. By associating charges with User Analytics profiles, you can compare revenue across different customer segments and calculate customer lifetime value. - -You can track a single transaction with `MixpanelAPI.getPeople().trackCharge()`. This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report. - -```java Java -MixpanelAPI mixpanel = - MixpanelAPI.getInstance(context, MIXPANEL_TOKEN, true); - -// Make getPeople() identify has been -// called before making revenue updates -mixpanel.identify("13793"); - -// Tracks $100 in revenue for user 13793 -mixpanel.getPeople().trackCharge(100, null); - -// Refund this user 50 dollars -mixpanel.getPeople().trackCharge(-50, null); - -// Tracks $25 in revenue for user 13793 -// on the 2nd of january -JSONObject properties = new JSONObject() -properties.put("$time", "2012-01-02T00:00:00"); -mixpanel.getPeople().trackCharge(25, properties); -``` - ## Group Analytics Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users. @@ -304,6 +301,20 @@ bolts.AppLinkNavigation.navigateInBackground(this, "http://anotherapp.com/app/li ... ``` +## Flushing Events + +To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background. You can call `flush` manually if you want to force a flush at a particular moment. + +```java Java +MixpanelAPI mixpanel = + MixpanelAPI.getInstance(context, MIXPANEL_TOKEN, true); + +// Push all queued Mixpanel events and +// profile changes to Mixpanel servers +mixpanel.flush(); +``` + + ## EU Data Residency Route data to Mixpanel's EU servers by adding meta-data entries under the `` tag of your app's `AndroidManifest.xml`. @@ -319,6 +330,9 @@ Route data to Mixpanel's EU servers by adding meta-data entries under the ` ``` +## Mobile Attribution +Learn more about [mobile attribution here](/docs/tracking-best-practices/traffic-attribution). + ## [Legacy] Automatically Tracked Events Mixpanel's SDKs have a legacy feature to automatically collect common mobile events. We don't recommend enabling this, as these events rely on client-side state and can be unreliable. diff --git a/pages/docs/tracking-methods/sdks/flutter.md b/pages/docs/tracking-methods/sdks/flutter.md index c8cfcaf964..55f754cbca 100644 --- a/pages/docs/tracking-methods/sdks/flutter.md +++ b/pages/docs/tracking-methods/sdks/flutter.md @@ -6,7 +6,27 @@ Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=fl The [Full API Reference](https://mixpanel.github.io/mixpanel-flutter), [Library Source Code](https://github.com/mixpanel/mixpanel-flutter), and an [Example Application](https://github.com/mixpanel/mixpanel-flutter/tree/main/example) is documented in our GitHub repo. - +## Initialize the Library + +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + +```dart +import 'package:mixpanel_flutter/mixpanel_flutter.dart'; +class _YourClassState extends State { + Mixpanel mixpanel; + + @override + void initState() { + super.initState(); + initMixpanel(); + } + + Future initMixpanel() async { + // Once you've called this method once, you can access `mixpanel` throughout the rest of your application. + mixpanel = await Mixpanel.init("YOUR_TOKEN", trackAutomaticEvents: false); + } +} +``` ## Sending Events @@ -34,7 +54,9 @@ mixpanel.track("Image Upload"); It's common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event - for example, the user's age, gender, source, or initial referrer. -To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are saved to local storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). +To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are saved to local storage, and will persist across invocations of your app. Super properties are indistinguishable from other event properties once ingested in your project. + +Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference/default-properties). To set super properties, call [`registerSuperProperties`](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/registerSuperProperties.html) @@ -249,6 +271,9 @@ Specifically for Flutter Web, add your proxy server to the `mixpanel.init` call: mixpanel.init("", {api_host: "https://"}); ``` +## Mobile Attribution +Learn more about [mobile attribution here](/docs/tracking-best-practices/traffic-attribution). + ## Debugging and Logging Enabling Mixpanel debugging and logging allows you to see the debug output from the Mixpanel library. This may be useful in determining when track calls go out. To enable Mixpanel debugging and logging, you can call [setLoggingEnabled(true)](https://mixpanel.github.io/mixpanel-flutter/mixpanel_flutter/Mixpanel/setLoggingEnabled.html) with `true`, then run your iOS project with Xcode or android project with Android Studio. The logs should be available in the console. diff --git a/pages/docs/tracking-methods/sdks/go.md b/pages/docs/tracking-methods/sdks/go.md index 1f31ac69fa..067f42e9cc 100644 --- a/pages/docs/tracking-methods/sdks/go.md +++ b/pages/docs/tracking-methods/sdks/go.md @@ -6,17 +6,21 @@ The Mixpanel Go library is designed to be used for scripting, or in circumstance The [Full API Reference](https://pkg.go.dev/github.com/mixpanel/mixpanel-go), [Library Source Code](https://github.com/mixpanel/mixpanel-go). Also checkout our [Examples](https://github.com/mixpanel/mixpanel-go/tree/main/examples) -## Installing the Library +## Initialize the Library -You can get the library using go get. -```shell -go get github.com/mixpanel/mixpanel-go -``` +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). +```shell Go +package main -Once the library is installed, use the Mixpanel library in your applications with: +import ( + "context" + "github.com/mixpanel/mixpanel-go" +) -```go -mp := mixpanel.NewApiClient("PROJECT_TOKEN") +func main() { + ctx := context.Background() + mp := mixpanel.NewApiClient("YOUR_TOKEN") +} ``` ## EU Data Residency diff --git a/pages/docs/tracking-methods/sdks/ios.md b/pages/docs/tracking-methods/sdks/ios.md index e2e38e2261..495cdc9786 100644 --- a/pages/docs/tracking-methods/sdks/ios.md +++ b/pages/docs/tracking-methods/sdks/ios.md @@ -6,6 +6,22 @@ Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=io The [Full API Reference](https://mixpanel.github.io/mixpanel-iphone/index.html), [Library Source Code](https://github.com/mixpanel/mixpanel-iphone/), and an [Example Application](https://github.com/mixpanel/mixpanel-iphone/tree/master/HelloMixpanel) is documented in our GitHub repo. +## Configure the SDK + +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + +```objc +#import "Mixpanel/Mixpanel.h" + +- (BOOL)application:(UIApplication _)application + didFinishLaunchingWithOptions:(NSDictionary _)launchOptions { + ... + Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR_TOKEN" + trackAutomaticEvents: NO]; + ... +} +``` + ## Sending Events We recommend tracking only five to seven events in your application instead of tracking too many things to start. Ideally, you track users going through your initial user experience and one key metric that matters for your application (e.g. a video streaming service might choose "Watched Video" as a key metric). @@ -34,7 +50,9 @@ Mixpanel *mixpanel = [Mixpanel sharedInstance]; It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event—for example, the user's age, gender, or source. -To make things easier, you can register these properties as super properties. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). +To make things easier, you can register these properties as super properties. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app. Super properties are indistinguishable from other event properties once ingested in your project. + +Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). To set super properties, call [`registerSuperProperties:`](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/registerSuperProperties:) @@ -134,25 +152,6 @@ You can use [`people increment:`](https://mixpanel.github.io/mixpanel-iphone/Cla ### Other Types of Profile Updates There are a few other types of profile updates. To learn more, please review the full [MixpanelPeople API documentation](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html). -## Tracking Revenue - -Mixpanel makes it easy to analyze the revenue you earn from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value. - -You can track a single transaction with [`people trackCharge:`](https://mixpanel.github.io/mixpanel-iphone/Classes/MixpanelPeople.html#//api/name/trackCharge:). This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report. -```objc Objective-C -// Tracks $100.77 in revenue for user 13793 -[mixpanel.people trackCharge:@(100.77)]; - -// Refund this user $50 -[mixpanel.people trackCharge:@-50]; - -// Tracks $25 in revenue for user 13793 on the 2nd of -// January -[mixpanel.people trackCharge:@25 withProperties:@{ - @"$time": "2016-01-02T00:00:00" -}]; -``` - ## Group Analytics Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users. @@ -231,6 +230,18 @@ post_install do |installer| end ``` +## Flushing Events + +To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background. You can call [flush()](https://mixpanel.github.io/mixpanel-iphone/Classes/Mixpanel.html#//api/name/flush) manually if you want to force a flush at a particular moment. + +```objc +[mixpanel flush]; +``` + +## Mobile Attribution +Learn more about [mobile attribution here](/docs/tracking-best-practices/traffic-attribution). + + ## EU Data Residency Route data to Mixpanel's EU servers by setting the `serverURL` property after initializing the client. diff --git a/pages/docs/tracking-methods/sdks/java.md b/pages/docs/tracking-methods/sdks/java.md index 75b19122d2..6f20c6234b 100644 --- a/pages/docs/tracking-methods/sdks/java.md +++ b/pages/docs/tracking-methods/sdks/java.md @@ -262,39 +262,3 @@ try { ``` For all Group methods, see our [reference](http://mixpanel.github.io/mixpanel-java/). - -## Tracking Revenue - -Mixpanel makes it easy to analyze the revenue you make from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value. - -You can track a single transaction with [`MessageBuilder.trackCharge`](http://mixpanel.github.io/mixpanel-java/com/mixpanel/mixpanelapi/MessageBuilder.html#trackCharge(java.lang.String,%20double,%20org.json.JSONObject)). Sending a message created with `trackCharge` will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report. - -```javascript -import com.mixpanel.mixpanelapi.MessageBuilder; -import com.mixpanel.mixpanelapi.MixpanelAPI; - -MessageBuilder messageBuilder = - new MessageBuilder(PROJECT_TOKEN); - -// Track a charge of $29.99 for the user identified by 13793 -JSONObject update = - messageBuilder.trackCharge("13793", 29.99, null); - -// Send the update to mixpanel -MixpanelAPI mixpanel = new MixpanelAPI(); -mixpanel.sendMessage(update); - -// Track a refund of $50 for the user identified by 13793 -JSONObject update = - messageBuilder.trackCharge("13793", -50, null); -mixpanel.sendMessage(update); - -// Track a charge of 25 dollars on January 2, 2012 -JSONObject properties = new JSONObject() -properties.put("$time", "2012-01-02T00:00:00"); -JSONObject update = - messageBuilder.trackCharge("13793", -50, properties); -mixpanel.sendMessage(update); -``` - -The Java library [appends a time stamp](https://github.com/mixpanel/mixpanel-java/blob/b64086b250107a8559989665051525d90a58b1e7/src/main/java/com/mixpanel/mixpanelapi/MessageBuilder.java#L51) to events by default. You have to manually use the $time property to append a time stamp to user profile properties. diff --git a/pages/docs/tracking-methods/sdks/javascript.md b/pages/docs/tracking-methods/sdks/javascript.md index c186dbd1bd..af6abbfa8c 100644 --- a/pages/docs/tracking-methods/sdks/javascript.md +++ b/pages/docs/tracking-methods/sdks/javascript.md @@ -6,6 +6,20 @@ Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=ja The [Full API Reference](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanel), [Library Source Code](https://github.com/mixpanel/mixpanel-js), and an [Example Application](https://github.com/mixpanel/mixpanel-js/tree/master/examples) is documented in our GitHub repo. +## Initialize the Library + +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + +```js Javascript +//Import Mixpanel SDK +import mixpanel from 'mixpanel-browser'; + +// Near entry of your product, init Mixpanel +mixpanel.init('YOUR_TOKEN', {debug: true, track_pageview: true, persistence: 'localStorage'}); +``` +### Configuration Options +See library [config options here](https://github.com/mixpanel/mixpanel-js/blob/v2.46.0/src/mixpanel-core.js#L88-L127). + ## Track Events ### Sending Events @@ -60,6 +74,7 @@ When UTM parameters for an identified user are seen for the first time, these wi In addition to UTM parameters, Mixpanel will also add any advertising click IDs to events fired. These include `dclid`, `fbclid`, `gclid`, `ko_click_id`, `li_fat_id`, `msclkid`, `ttclid`, `twclid`, `wbraid` +[Read our full guide](/docs/tracking-best-practices/traffic-attribution) on traffic attribution. ### Tracking Website Links @@ -105,7 +120,9 @@ For domains that don't allow cross-subdomain cookies, you should be setting `cro It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event - for example, the user's age, gender, source, or initial referrer. -To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are stored in a browser cookie, and will persist between visits to your site. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). +To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are stored in a browser cookie, and will persist between visits to your site. Super properties are indistinguishable from other event properties once ingested in your project. + +Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). To set super properties, call [`mixpanel.register()`](https://github.com/mixpanel/mixpanel-js/blob/master/doc/readme.io/javascript-full-api-reference.md#mixpanelregister). diff --git a/pages/docs/tracking-methods/sdks/react-native.md b/pages/docs/tracking-methods/sdks/react-native.md index a88d344d48..e6631485b0 100644 --- a/pages/docs/tracking-methods/sdks/react-native.md +++ b/pages/docs/tracking-methods/sdks/react-native.md @@ -6,6 +6,23 @@ Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=re The [Full API Reference](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html), [Library Source Code](https://github.com/mixpanel/mixpanel-react-native), and an [Example Application](https://github.com/mixpanel/mixpanel-react-native/tree/master/Samples) is documented in our GitHub repo. +## Initialize the Library + +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + +```javascript +//Import Mixpanel API +import { Mixpanel } from "mixpanel-react-native"; + +// Set up an instance of Mixpanel +const trackAutomaticEvents = false; +const mixpanel = new Mixpanel("YOUR_TOKEN", trackAutomaticEvents); +mixpanel.init(); +``` + +### Configuration Options +See library [config options here](https://github.com/mixpanel/mixpanel-react-native/blob/6d8da0b503f77d49c244900ee8a4f6e77c4251e0/javascript/mixpanel-config.js). + ## Sending Events We recommend tracking only five to seven events in your application instead of tracking too many things to start. Ideally, you track users going through your initial user experience and one key metric that matters for your application (e.g. YouTube might choose "Watched Video" as a key metric). @@ -31,7 +48,9 @@ mixpanel.track("Image Upload"); It's common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event - for example, the user's age, gender, source, or initial referrer. -To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are saved to local storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). +To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are saved to local storage, and will persist across invocations of your app. Super properties are indistinguishable from other event properties once ingested in your project. + +Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). To set super properties, call [`registerSuperProperties`](https://mixpanel.github.io/mixpanel-react-native/Mixpanel.html#registerSuperProperties) diff --git a/pages/docs/tracking-methods/sdks/ruby.md b/pages/docs/tracking-methods/sdks/ruby.md index eb9efab73e..5b0e370947 100644 --- a/pages/docs/tracking-methods/sdks/ruby.md +++ b/pages/docs/tracking-methods/sdks/ruby.md @@ -1,11 +1,22 @@ # Ruby +## Getting Started + +Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=ruby). + The Mixpanel Ruby library is designed to be used for scripting, or in circumstances when a user isn't directly interacting with your application on the web or a mobile device. The [Full API Reference](http://mixpanel.github.io/mixpanel-ruby), [Library Source Code](https://github.com/mixpanel/mixpanel-ruby), and an [Example Script](https://github.com/mixpanel/mixpanel-ruby/tree/master/demo) is documented in our GitHub repo. -## Getting Started -See our [server](/docs/quickstart/connect-your-data?sdk=ruby) quickstart for how to get started with the Ruby SDK. +## Initialize the Library + +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + +```ruby Ruby +require 'mixpanel-ruby' + +mp = Mixpanel::Tracker.new(YOUR_TOKEN) +``` ## EU Data Residency @@ -149,20 +160,3 @@ tracker.groups.set('Company', 'Acme', { ``` For all Group methods, see our [reference](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/Groups.html). - - -## Tracking Revenue - -Mixpanel makes it easy to analyze the revenue you make from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value. - -You can track a single transaction with the [`track_charge method of Mixpanel::Tracker#people`](http://mixpanel.github.io/mixpanel-ruby/Mixpanel/People.html#method-i-track_charge). Sending a message created with `track_charge` will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report. - -```ruby -## Records a charge of $9.99 from user '12345' -tracker.people.track_charge('12345', 9.99) - -## records a charge of $30.50 on the 2nd of January -mixpanel.people.track_charge("12345", 30.50, { - '$time' => DateTime.parse("Jan 2 2013"), -}) -``` diff --git a/pages/docs/tracking-methods/sdks/swift.md b/pages/docs/tracking-methods/sdks/swift.md index 403dedac64..ff12fa823a 100644 --- a/pages/docs/tracking-methods/sdks/swift.md +++ b/pages/docs/tracking-methods/sdks/swift.md @@ -6,6 +6,24 @@ Please refer to our [Quickstart Guide](/docs/quickstart/connect-your-data?sdk=sw The [Full API Reference](https://mixpanel.github.io/mixpanel-swift/), [Library Source Code](https://github.com/mixpanel/mixpanel-swift), and an [Example Application](https://github.com/mixpanel/mixpanel-swift/tree/master/MixpanelDemo/MixpanelDemo) is documented in our GitHub repo. +## Initialize the Library + +Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). +```objc +#import "Mixpanel/Mixpanel.h" + +- (BOOL)application:(UIApplication _)application + didFinishLaunchingWithOptions:(NSDictionary _)launchOptions { + ... + Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR_TOKEN" + trackAutomaticEvents: NO]; + ... +} +``` + +### Configuration Options +See all [config options here](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html). + ## Sending Events We recommend tracking only five to seven events in your application instead of tracking too many things to start. Ideally, you track users going through your initial user experience and one key metric that matters for your application (e.g. YouTube might choose "Watched Video" as a key metric). @@ -30,7 +48,8 @@ Mixpanel.mainInstance().track(event: "Image Upload") It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event—for example, the user's age, gender, or source. -To make things easier, you can register these properties as super properties. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). +To make things easier, you can register these properties as super properties. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app. Super properties are indistinguishable from other event properties once ingested in your project. +Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference#default-properties). To set super properties, call [`registerSuperProperties(_:)`](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:FC8Mixpanel16MixpanelInstance23registerSuperPropertiesFGVs10DictionarySSPs9AnyObject__T_) @@ -128,20 +147,6 @@ Mixpanel.mainInstance().people.increment(properties: ### Other Types of Profile Updates There are a few other types of profile updates. To learn more, please review the [full MixpanelPeople API documentation](https://mixpanel.github.io/mixpanel-swift/Classes/People.html). -## Tracking Revenue - -Mixpanel makes it easy to analyze the revenue you earn from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value. - -You can track a single transaction with [`people.trackCharge(amount:)`](https://mixpanel.github.io/mixpanel-swift/Classes/People.html#/s:FC8Mixpanel6People11trackChargeFT6amountSd10propertiesGSqGVs10DictionarySSPs9AnyObject____T_). This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report. - -```swift Swift -// Tracks $100.77 in revenue for user 13793 -Mixpanel.mainInstance().people.trackCharge(amount: 100.77) - -// Refund this user 50 dollars -Mixpanel.mainInstance().people.trackCharge(amount: -50) -``` - ## Group Analytics Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users. @@ -220,6 +225,16 @@ You can turn on Mixpanel logging by enabling the following flag: Mixpanel.mainInstance().loggingEnabled = true ``` +## Flushing Events + +To preserve battery life and customer bandwidth, the Mixpanel library doesn't send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background. You can call [flush()](https://mixpanel.github.io/mixpanel-swift/Classes/MixpanelInstance.html#/s:8Mixpanel0A8InstanceC5flush10completionyyycSg_tF) manually if you want to force a flush at a particular moment. + +```swift +Mixpanel.mainInstance().flush() +``` + +## Mobile Attribution +Learn more about [mobile attribution here](/docs/tracking-best-practices/traffic-attribution). ## EU Data Residency diff --git a/pages/docs/tracking-methods/sdks/unity.md b/pages/docs/tracking-methods/sdks/unity.md index 8d60e604d7..bf6067a46f 100644 --- a/pages/docs/tracking-methods/sdks/unity.md +++ b/pages/docs/tracking-methods/sdks/unity.md @@ -59,7 +59,9 @@ Mixpanel.Track("Image Upload"); It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the **user** rather than about a specific event—for example, the user's age, gender, or source. -To make things easier, you can register these properties as **super properties**. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference). +To make things easier, you can register these properties as **super properties**. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app. Super properties are indistinguishable from other event properties once ingested in your project. + +Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties [here](/docs/data-structure/property-reference). To set super properties, call [`Mixpanel.Register.`](http://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel.html#acf2fccd7625dfb2a15ef54fcaf8ddfe4) @@ -150,28 +152,3 @@ Mixpanel.People.Increment("point count", 500); #### Other Types of Profile Updates There are a few other types of profile updates. To learn more, please see the [full API reference](http://mixpanel.github.io/mixpanel-unity/api-reference/annotated.html). - -## Tracking Revenue - -Mixpanel makes it easy to analyze the revenue you earn from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value. - -You can track a single transaction with [`Mixpanel.people.TrackCharge`](http://mixpanel.github.io/mixpanel-unity/api-reference/classmixpanel_1_1_mixpanel_1_1_people.html#ae0f80a6831618f591542f230f821e665). This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report. - -```csharp -// Make sure identify has been called before making revenue -// updates -Mixpanel.Identify("13793"); - -// Tracks $100 in revenue for user 13793 -Mixpanel.People.TrackCharge(100); - -// Refund this user 50 dollars -Mixpanel.People.TrackCharge(-50); - -// Tracks $25 in revenue for user 13793 on the 2nd of -// January -var props = new Value(); -props["time"] = "2012-01-02T00:00:00"; - -Mixpanel.People.TrackCharge(25, props); -``` From d977bf011ba2762cfcdebbe3117ce62df9be5c6a Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Sun, 30 Jun 2024 17:45:56 -0700 Subject: [PATCH 05/12] Myronkaifung content reorg analysis (#1178) * Update server-side-best-practices.md * Update geolocation.md * Update insights.mdx * Update advanced.md * Update overview.md * Rename overview.md to reports.md * Update _meta.json * Rename pages/docs/reports/reports.md to pages/docs/reports.md * Update and rename reports.md to reports.mdx * Update reports.mdx * Update reports.mdx * Update reports.mdx * Create _meta.json * Create metrics.md * Update metrics.md * Create measurements.md * Create visualizations.md * Update _meta.json * Create custom-buckets.md * Update insights.mdx * Update metrics.md * Update reports.mdx * Create query-builder.md * Update _meta.json * Update reports.mdx * Update query-builder.md * Create _meta.json * Create metrics.md * Create measurements.md * Create funnels-conversion-criteria.md * Create funnels-filter.md * Create funnels-breakdown.md * Create visualizations.md * Create _meta.json * Create metrics.md * Create measurements.md * Create visualizations.md * Create retention-frequency.md * Create _meta.json * Create anchor-events.md * Create visualizations.md * Create flows-conversion-criteria.md * Create flows-breakdown.md * Update metrics.md * Rename metrics.md to funnel-behavior.md * Update _meta.json * Update measurements.md * Update measurements.md * Update funnel-behavior.md * Update funnel-behavior.md * Update funnels-conversion-criteria.md * Update funnel-behavior.md * Update and rename funnels-filter.md to breakdowns-and-filters.md * Update _meta.json * Update measurements.md * Update breakdowns-and-filters.md * Delete pages/docs/reports/funnels/funnels-breakdown.md * Update funnels.mdx * Update advanced.md * Update visualizations.md * Update funnels.mdx * Update and rename metrics.md to retention-behavior.md * Update _meta.json * Update funnel-behavior.md * Update measurements.md * Update and rename retention-frequency.md to frequency.md * Update _meta.json * Update retention-behavior.md * Update measurements.md * Update and rename measurements.md to retention-criteria.md * Update _meta.json * Update visualizations.md * Update retention.mdx * Update frequency.md * Update anchor-events.md * Update anchor-events.md * Update visualizations.md * Update flows-conversion-criteria.md * Update anchor-events.md * Update visualizations.md * Update flows-breakdown.md * Update flows.mdx * Update flows-breakdown.md * Update _meta.json * Rename overview.md to users-page.md * Create profile-page.md * Update profile-page.md * Update users-page.md * Update users-page.md * Update _meta.json * Update _meta.json * Rename overview.md to .md * Rename pages/docs/cohort-sync/.md to pages/docs/cohort-syncs.md * Rename cohort-syncs.md to cohort-sync.md * Update cohorts.md * Update _meta.json * Rename pages/docs/boards/overview.mdx to pages/docs/board.mdx * Rename board.mdx to boards.mdx * Create sharing-and-permission.md * Create move-board.md * Update advanced.mdx * Delete pages/docs/boards/advanced.mdx * Update _meta.json * Update boards.mdx * Update _meta.json * Create query-sampling-and-caching.md * Update _meta.json * Create computed-properties.md * Update attribution.mdx * Delete pages/docs/features/attribution.mdx * Update custom-events.md * Update data-type.md * Update query-builder.md * Update _meta.json * Create slack-integration.md * Update visualizations.md * Update advanced.md * Delete pages/docs/features/advanced.md * Update _meta.json * Update sessions.md * Update _meta.json --- pages/docs/_meta.json | 60 +- .../docs/{boards/overview.mdx => boards.mdx} | 49 + pages/docs/boards/_meta.json | 4 +- pages/docs/boards/advanced.mdx | 177 --- pages/docs/boards/move-board.md | 54 + pages/docs/boards/sharing-and-permission.md | 42 + .../overview.md => cohort-sync.md} | 0 pages/docs/cohort-sync/_meta.json | 1 - .../property-reference/data-type.md | 4 +- pages/docs/features/_meta.json | 10 +- pages/docs/features/advanced.md | 1028 ----------------- ...attribution.mdx => computed-properties.md} | 57 +- pages/docs/features/custom-buckets.md | 228 ++++ pages/docs/features/custom-events.md | 5 + .../features/query-sampling-and-caching.md | 75 ++ pages/docs/features/sessions.md | 5 +- pages/docs/features/slack-integration.md | 39 + pages/docs/reports.mdx | 153 +++ pages/docs/reports/_meta.json | 2 +- pages/docs/reports/flows.mdx | 220 ---- pages/docs/reports/flows/_meta.json | 6 + pages/docs/reports/flows/anchor-events.md | 32 + pages/docs/reports/flows/flows-breakdown.md | 44 + .../flows/flows-conversion-criteria.md | 54 + pages/docs/reports/flows/visualizations.md | 102 ++ pages/docs/reports/funnels.mdx | 447 +------ pages/docs/reports/funnels/_meta.json | 7 + .../reports/funnels/breakdowns-and-filters.md | 132 +++ pages/docs/reports/funnels/funnel-behavior.md | 58 + .../funnels/funnels-conversion-criteria.md | 120 ++ pages/docs/reports/funnels/measurements.md | 83 ++ pages/docs/reports/funnels/visualizations.md | 85 ++ pages/docs/reports/insights.mdx | 361 +----- pages/docs/reports/insights/_meta.json | 5 + pages/docs/reports/insights/measurements.md | 141 +++ pages/docs/reports/insights/metrics.md | 77 ++ pages/docs/reports/insights/visualizations.md | 128 ++ .../reports/{overview.md => query-builder.md} | 175 ++- pages/docs/reports/retention.mdx | 185 --- pages/docs/reports/retention/_meta.json | 6 + pages/docs/reports/retention/frequency.md | 32 + .../reports/retention/retention-behavior.md | 37 + .../reports/retention/retention-criteria.md | 127 ++ .../docs/reports/retention/visualizations.md | 75 ++ .../tracking-best-practices/geolocation.md | 6 + .../server-side-best-practices.md | 102 +- pages/docs/users/_meta.json | 3 +- pages/docs/users/cohorts.md | 43 +- pages/docs/users/profile-page.md | 29 + .../docs/users/{overview.md => users-page.md} | 33 +- 50 files changed, 2268 insertions(+), 2680 deletions(-) rename pages/docs/{boards/overview.mdx => boards.mdx} (67%) delete mode 100644 pages/docs/boards/advanced.mdx create mode 100644 pages/docs/boards/move-board.md create mode 100644 pages/docs/boards/sharing-and-permission.md rename pages/docs/{cohort-sync/overview.md => cohort-sync.md} (100%) delete mode 100644 pages/docs/features/advanced.md rename pages/docs/features/{attribution.mdx => computed-properties.md} (75%) create mode 100644 pages/docs/features/custom-buckets.md create mode 100644 pages/docs/features/query-sampling-and-caching.md create mode 100644 pages/docs/features/slack-integration.md create mode 100644 pages/docs/reports.mdx create mode 100644 pages/docs/reports/flows/_meta.json create mode 100644 pages/docs/reports/flows/anchor-events.md create mode 100644 pages/docs/reports/flows/flows-breakdown.md create mode 100644 pages/docs/reports/flows/flows-conversion-criteria.md create mode 100644 pages/docs/reports/flows/visualizations.md create mode 100644 pages/docs/reports/funnels/_meta.json create mode 100644 pages/docs/reports/funnels/breakdowns-and-filters.md create mode 100644 pages/docs/reports/funnels/funnel-behavior.md create mode 100644 pages/docs/reports/funnels/funnels-conversion-criteria.md create mode 100644 pages/docs/reports/funnels/measurements.md create mode 100644 pages/docs/reports/funnels/visualizations.md create mode 100644 pages/docs/reports/insights/_meta.json create mode 100644 pages/docs/reports/insights/measurements.md create mode 100644 pages/docs/reports/insights/metrics.md create mode 100644 pages/docs/reports/insights/visualizations.md rename pages/docs/reports/{overview.md => query-builder.md} (58%) create mode 100644 pages/docs/reports/retention/_meta.json create mode 100644 pages/docs/reports/retention/frequency.md create mode 100644 pages/docs/reports/retention/retention-behavior.md create mode 100644 pages/docs/reports/retention/retention-criteria.md create mode 100644 pages/docs/reports/retention/visualizations.md create mode 100644 pages/docs/users/profile-page.md rename pages/docs/users/{overview.md => users-page.md} (64%) diff --git a/pages/docs/_meta.json b/pages/docs/_meta.json index 8aeaf9540f..92272c45b8 100644 --- a/pages/docs/_meta.json +++ b/pages/docs/_meta.json @@ -3,54 +3,54 @@ "type": "separator", "title": "INTRO" }, - "what-is-mixpanel": "What is Mixpanel?", - "what-to-track": "What to Track", - "quickstart": "Quickstart", + "what-is-mixpanel": "What is Mixpanel?", + "what-to-track": "What to Track", + "quickstart": "Quickstart", "data-in": { "type": "separator", "title": "DATA IN" }, - "tracking-methods": "Tracking Methods", - "data-structure": "Data Structure", - "migration": "Migration", - "tracking-best-practices": "Best Practices", + "tracking-methods": "Tracking Methods", + "data-structure": "Data Structure", + "migration": "Migration", + "tracking-best-practices": "Best Practices", "analysis": { "type": "separator", "title": "ANALYSIS" }, - "reports": "Reports", - "boards": "Boards", - "users": "Users", - "features": "Features", + "reports": "Reports", + "boards": "Boards", + "users": "Users", + "features": "Features", "admin": { "type": "separator", "title": "ADMIN" }, - "orgs-and-projects": "Orgs & Projects", - "data-governance": "Data Governance", - "access-security": "Access Security", - "privacy": "Privacy", - "pricing": "Pricing", + "orgs-and-projects": "Orgs & Projects", + "data-governance": "Data Governance", + "access-security": "Access Security", + "privacy": "Privacy", + "pricing": "Pricing", "data-out": { "type": "separator", "title": "DATA OUT" }, - "data-pipelines": "Data Pipelines", - "cohort-sync": "Cohort Sync", + "data-pipelines": "Data Pipelines", + "cohort-sync": "Cohort Sync", "support": { "type": "separator", "title": "SUPPORT" }, - "community": "Community", - "get-help": { - "title": "Get Help ↗", - "newWindow": true, - "href": "https://mixpanel.com/get-support" - }, - "response-times": "Response Times", - "hire-an-expert": { - "title": "Hire an Expert ↗", - "newWindow": true, - "href": "https://mixpanel.com/partners/experts/matchmaking" - } + "community": "Community", + "get-help": { + "title": "Get Help ↗", + "newWindow": true, + "href": "https://mixpanel.com/get-support" + }, + "response-times": "Response Times", + "hire-an-expert": { + "title": "Hire an Expert ↗", + "newWindow": true, + "href": "https://mixpanel.com/partners/experts/matchmaking" + } } diff --git a/pages/docs/boards/overview.mdx b/pages/docs/boards.mdx similarity index 67% rename from pages/docs/boards/overview.mdx rename to pages/docs/boards.mdx index c815102131..e14fe9e526 100644 --- a/pages/docs/boards/overview.mdx +++ b/pages/docs/boards.mdx @@ -114,3 +114,52 @@ Row heights can now be adjusted to either show more report content, or hide empt A row's height is initially determined by the tallest card within that row. Text cards can be very short if they contain only one line of text, or very tall if they contain many lines. Meanwhile, reports always start at their minimum height, but may warrant expansion in order to show more data (more bars on a bar chart, for example). A row will start life at the minimum possible height. + +### Step 5: Board-wide Date Ranges and Filters + +Boards allow you to alter some aspects of the queries within each of the reports on that board, making it simple to ensure every report is showing results from a consistent set of data.  Both date ranges and filters can be added by clicking "Add Filter" at the top right of the board.  This will open a row, shown below, where the date range can be selected, and filters can be applied. + +![/Screen_Shot_2022-01-07_at_2.35.49_PM.png](/Screen_Shot_2022-01-07_at_2.35.49_PM.png) + +By default, date ranges and filters are temporary, allowing you to explore the data without overwriting the board. But, if you wish to save the date range and filter selections you've made to the board, so they'll appear for other users as well, click "Save to Board." + +**Note** +Applying date ranges and filters on a board does not change the queries saved in each individual report; instead, it only changes the data displayed when you view those reports in the current board. If you click into a report from the board, however, Mixpanel will maintain the date range and filters to ensure you see data consistent between the board and report. Navigate to the report on its own, though, and you'll see the report's original saved date range and filters. + +## Board Subscriptions + +Board Subscriptions allow you to receive a snapshot of a board sent as an email or a slack message. Subscriptions allow members to share recent data with both project members and external audiences, providing quick and meaningful insight into a Mixpanel project. + +You must be a Project Owner, Admin, or Analyst to create a subscription. + +Subscriptions will send the board on a recurring schedule. You can choose a daily, weekly or monthly interval. Note that subscriptions only show the 8 reports that are on the top of a board. + +To create a Subscription: + +1. Select **Subscribe** from the header at the top right of the board. You can see a list of existing subscriptions for the board here as well. Select "Create New". + ![/subscribe1.png](/subscribe1.png) + +2. Fill out the resulting form, selecting the desired email recipients or Slack channel, as well as the sending frequency (daily, weekly, or monthly). + ![/subscribe2.png](/subscribe2.png) + - Any email address will receive the email, whether or not they are internal or external to your organization + - Private Slack Channels are not available at this time +3. Click "Subscribe". + +### Seeing All Subscriptions +![/subscribe3.png](/subscribe3.png) + +You can access this by clicking the "Subscribe" button at the top right of the board. Then select "View All". +This gives you a view of all subscriptions across all users. + +### Subscriptions for Private Boards + +It is possible to subscribe to a private board. However, there are some restrictions to what will be visible or accessible. + +1. If you convert a regular board with subscriptions into a private board, existing subscriptions will still work with existing recipients. However, if they click **View Board**, they will not be able to access your private board. Creating new subscriptions or editing existing subscriptions within the private board will force you to limit recipients to yourself. +2. You cannot edit subscriptions of someone else’s private board without selecting a different board that you have access to (regardless of your permissions or role). You can still delete the subscription or select a different board. + +## TV Mode + +The **Enter TV Mode** option enables displaying a Board on a big screen (such as a TV in the office) where top-level company metrics / KPIs can be constantly monitored. The Board will auto-refresh every 10 minutes when in TV mode. + +![image](/boards-tv-mode.png "Enter TV Mode") diff --git a/pages/docs/boards/_meta.json b/pages/docs/boards/_meta.json index ba860ad061..721de478b1 100644 --- a/pages/docs/boards/_meta.json +++ b/pages/docs/boards/_meta.json @@ -1,7 +1,7 @@ { - "overview": "Overview", + "sharing-and-permission", "Sharing and Permission", "templates": "Templates", "boards-on-boards": "Boards on Boards", "public-boards": "Public Boards", - "advanced": "Advanced" + "move-board": "Move Board" } diff --git a/pages/docs/boards/advanced.mdx b/pages/docs/boards/advanced.mdx deleted file mode 100644 index 80777b11ad..0000000000 --- a/pages/docs/boards/advanced.mdx +++ /dev/null @@ -1,177 +0,0 @@ -# Advanced - -## Board-wide Date Ranges and Filters - -Boards allow you to alter some aspects of the queries within each of the reports on that board, making it simple to ensure every report is showing results from a consistent set of data.  Both date ranges and filters can be added by clicking "Add Filter" at the top right of the board.  This will open a row, shown below, where the date range can be selected, and filters can be applied. - -![/Screen_Shot_2022-01-07_at_2.35.49_PM.png](/Screen_Shot_2022-01-07_at_2.35.49_PM.png) - -By default, date ranges and filters are temporary, allowing you to explore the data without overwriting the board. But, if you wish to save the date range and filter selections you've made to the board, so they'll appear for other users as well, click "Save to Board." - -**Note** -Applying date ranges and filters on a board does not change the queries saved in each individual report; instead, it only changes the data displayed when you view those reports in the current board. If you click into a report from the board, however, Mixpanel will maintain the date range and filters to ensure you see data consistent between the board and report. Navigate to the report on its own, though, and you'll see the report's original saved date range and filters. - -## Board Subscriptions - -Board Subscriptions allow you to receive a snapshot of a board sent as an email or a slack message. Subscriptions allow members to share recent data with both project members and external audiences, providing quick and meaningful insight into a Mixpanel project. - -You must be a Project Owner, Admin, or Analyst to create a subscription. - -Subscriptions will send the board on a recurring schedule. You can choose a daily, weekly or monthly interval. Note that subscriptions only show the 8 reports that are on the top of a board. - -To create a Subscription: - -1. Select **Subscribe** from the header at the top right of the board. You can see a list of existing subscriptions for the board here as well. Select "Create New". - ![/subscribe1.png](/subscribe1.png) - -2. Fill out the resulting form, selecting the desired email recipients or Slack channel, as well as the sending frequency (daily, weekly, or monthly). - ![/subscribe2.png](/subscribe2.png) - - Any email address will receive the email, whether or not they are internal or external to your organization - - Private Slack Channels are not available at this time -3. Click "Subscribe". - -### Seeing All Subscriptions -![/subscribe3.png](/subscribe3.png) - -You can access this by clicking the "Subscribe" button at the top right of the board. Then select "View All". -This gives you a view of all subscriptions across all users. - -### Subscriptions for Private Boards - -It is possible to subscribe to a private board. However, there are some restrictions to what will be visible or accessible. - -1. If you convert a regular board with subscriptions into a private board, existing subscriptions will still work with existing recipients. However, if they click **View Board**, they will not be able to access your private board. Creating new subscriptions or editing existing subscriptions within the private board will force you to limit recipients to yourself. -2. You cannot edit subscriptions of someone else’s private board without selecting a different board that you have access to (regardless of your permissions or role). You can still delete the subscription or select a different board. - -## Sharing - -Sharing and permissions are set at the board level, and all reports saved on a board inherit the same set of sharing and permissions settings of that board. - -To share a board, and therefore all reports contained within it, click the Share button at the top right of the board. From here, sharing works as before, but remember, sharing a board now shares all of that board's reports as well.  - -![/GIF3__light_.gif](/GIF3__light_.gif) - -Both reports and boards can also be shared via the "Copy URL" button at the top right. Clicking this button will immediately copy the short link to the report or board, so you can quickly paste it into your application of choice. - -![/Screen_Shot_2021-11-08_at_11.01.00_AM.png](/Screen_Shot_2021-11-08_at_11.01.00_AM.png) - -So long as the recipient has access to the project, they will be able to see the shared report or board. However, unless they have specifically given Editor permissions, they will only be able to view it, not edit it. - -## Permissions - -Sharing and permissions are set at the board level, and all reports saved on a board inherit the same set of sharing and permissions settings of that board. - -In the sharing process, you can choose the permissions level granted to the individual with whom you're sharing the board. Teammates with access to a board can either be Viewers (any changes made will not be saved) or Editors (changes made will be saved).  - -As with sharing, setting a user's permission level on a board will give them the same permission level for all reports on that board. - -## Move Board - -Move helps teams organize their work and easily replicate Boards across projects and organizations. Using Move, you can find a Board you want to copy, duplicate it, and move it to a different project. - -Let’s take an example situation: - -1. An organization has Project A and Project B that support different products and teams within the organization. -2. Team A has some fantastic Boards that have been well received by leadership, executives, and investors. -3. Team B would like to replicate these reports without having to build them all from scratch. - -This is where Move comes in. With the right permissions, Team A can move copies of their Boards to Team B’s project, allowing Team B to fill in their events and be up and running quickly. - -*Please note: Moving boards from projects based in the US -> EU as well as EU -> US is unavailable at this time. - -### Turning Move Off and On - -1. Go to Project Settings -2. Select Moving Boards from the left hand menu -3. If you are an organization admin, you will be able to select the how freely you want boards to be able to be moved: not at all, within the organization, or between organizations. - - Not at all: no Board can be moved to any other project, no matter the organization - - Within organization: a Board can be moved to any other project in the same organization - - Any organization: a Board can be moved to any other project, even one in a different organization - This setting does not affect whether you can move a Board into a project, only whether you can move a Board out of a project. - -4. On this page, you can also see who last updated the permissions and when. - -![Move-screenshot.png](/Move-screenshot.png) - -### Using Move - -![Demo_mv_x_proj.gif](/Demo_mv_x_proj.gif) - -Step 1: Go to the Board you wish to move. - -Step 2: Hover over the `Move to` option. - -Step 3a: Enterprise users: select ‘projects’, then select the specific project that you want to move the board to. Once you’ve selected a project, then list will populate with Boards you can place the current Board in if you wish. - -Step 3b: Non-enterprise users: hover over the "Move To" option, and the project menu will appear immediately. From there, you can choose “Move to your Boards” or another location and select your choice. - -Step 3c: You can also use Move to use Boards from a demo project in your own. Get your free Mixpanel demo account and click [here](https://mixpanel.com/api/app/demo_project?show-demo-dataset-modal=true) to access the demo datasets. Once you're in, you can set up a new Board easily using a [template](/docs/boards/templates), or you can build a report from scratch. If you like what you see and want to use the analysis in your own project, you can click the button that says "Use this Board." You'll then select the project to which you want to move the board. - -Step 4: If there are events and properties used in the old project but not the new project, the affected reports will remain empty or say “no data” until new events and properties are selected. - -When a report can’t populate, it will display one of two states: a faded out sample report or a “no data” status. - -- Charts that show "no data" occur when an event has been tracked in the last 30 days, but a filter or date range result in no data for the report. -- For the sample report to appear, the report would have to be configured with an event that hasn't existed or at least hasn't been tracked in past 30 days. - -For example: a join membership club event happened 100 times yesterday, but 0 so far today. If you create a report for today, it will show “no data”. But if this is day one of the program and it has never been tracked before, it will show a dummy sample report. From this empty state, you can set up your new reports like any other report. - -👉🏽 NOTE: If you would like a version of the Board to stay in the parent project, duplicate it and move the new duplicate Board. - -## FAQ - -### Where are reports saved to? - -Reports are always saved to boards. Previously, reports were separately saved and added to boards. In boards now, when you save a report, you'll be prompted to save it to a specific board. In essence, the board now acts as a folder, with many potential purposes, including: - -- A centralized place to track numerous metrics related to a product launch -- A chain of analyses digging into a particular behaviour or issue -- A set of draft reports you're working on - -This will make it easy to keep reports organized, and reduce time wasted recreating the same reports again and again. - -Note: This change only applies to the reports that can be added to boards—Mixpanel's core reports: Insights, Flows, Funnels, and Retention. Advanced reports like Signal, Experiments, and Impact have been moved to the Applications folder at the top right of the page. - -![/Screen_Shot_2022-01-05_at_9.18.06_PM.png](/Screen_Shot_2022-01-05_at_9.18.06_PM.png) - -### Where are sharing and permissions set? - -Previously, sharing and permissions were editable at both the report and board levels. This made managing sharing and permissions tedious due to the sheer number of items requiring individual settings. - -Now, all reports saved on the same board will have the same sharing and permissions settings. This means sharing multiple reports with your team is a simple matter of sharing the board. As before, however, any report or board can be shared by simply clicking the "Copy URL" button, and sharing the resulting short link. - -![/Screen_Shot_2022-01-05_at_9.20.44_PM.png](/Screen_Shot_2022-01-05_at_9.20.44_PM.png) - -### What happens to reports on multiple boards? - -All copies of reports have a source location. This can be seen when looking at the report details. - -![/Screen_Shot_2022-07-11_at_6.06.58_PM.png](/Screen_Shot_2022-07-11_at_6.06.58_PM.png) - -However, the same report can be viewed from multiple different boards. - -![/Screen_Shot_2022-07-11_at_6.06.20_PM.png](/Screen_Shot_2022-07-11_at_6.06.20_PM.png) - -On boards, the arrow icon on the top left indicates of the report lives on this board, or is a linked view. - -### What is a linked report? - -Every report in Mixpanel has a board where it was originally saved to. This is called the original board. However, in the interest of being able to use the same report across a variety of boards and sharing the same insight across your team and company, Mixpanel has introduced the concept of a "linked report". A linked report is denoted by the arrow in the icon of the report. Any time an existing report is added to a board or a copy is made, a linked report is made. Any changes to the report will get reflected in all of the linked reports associated with the report. - -![/Screen_Shot_2022-07-11_at_6.06.58_PM.png](/Screen_Shot_2022-07-11_at_6.06.58_PM.png) - -### What is TV Mode? - -The **Enter TV Mode** option enables displaying a Board on a big screen (such as a TV in the office) where top-level company metrics / KPIs can be constantly monitored. The Board will auto-refresh every 10 minutes when in TV mode. - -![image](/boards-tv-mode.png "Enter TV Mode") - -### How do I standardize the color of segments across reports on the same dashboard? - -1. On the report, de-select all segments. -2. Click the down arrow button next to segment name in the table below and select "Segment A->Z" for each report. -3. Select all segments. -In all reports, the segments colors should match. - -This should allow you to standardize across your reports as long as they have the same segment names. - diff --git a/pages/docs/boards/move-board.md b/pages/docs/boards/move-board.md new file mode 100644 index 0000000000..c2a369b991 --- /dev/null +++ b/pages/docs/boards/move-board.md @@ -0,0 +1,54 @@ +# Move Board + +## Overview + +Move helps teams organize their work and easily replicate Boards across projects and organizations. Using Move, you can find a Board you want to copy, duplicate it, and move it to a different project. + +Let’s take an example situation: + +1. An organization has Project A and Project B that support different products and teams within the organization. +2. Team A has some fantastic Boards that have been well received by leadership, executives, and investors. +3. Team B would like to replicate these reports without having to build them all from scratch. + +This is where Move comes in. With the right permissions, Team A can move copies of their Boards to Team B’s project, allowing Team B to fill in their events and be up and running quickly. + +*Please note: Moving boards from projects based in the US -> EU as well as EU -> US is unavailable at this time. + +### Turning Move Off and On + +1. Go to Project Settings +2. Select Moving Boards from the left hand menu +3. If you are an organization admin, you will be able to select the how freely you want boards to be able to be moved: not at all, within the organization, or between organizations. + - Not at all: no Board can be moved to any other project, no matter the organization + - Within organization: a Board can be moved to any other project in the same organization + - Any organization: a Board can be moved to any other project, even one in a different organization + This setting does not affect whether you can move a Board into a project, only whether you can move a Board out of a project. + +4. On this page, you can also see who last updated the permissions and when. + +![Move-screenshot.png](/Move-screenshot.png) + +### Using Move + +![Demo_mv_x_proj.gif](/Demo_mv_x_proj.gif) + +Step 1: Go to the Board you wish to move. + +Step 2: Hover over the `Move to` option. + +Step 3a: Enterprise users: select ‘projects’, then select the specific project that you want to move the board to. Once you’ve selected a project, then list will populate with Boards you can place the current Board in if you wish. + +Step 3b: Non-enterprise users: hover over the "Move To" option, and the project menu will appear immediately. From there, you can choose “Move to your Boards” or another location and select your choice. + +Step 3c: You can also use Move to use Boards from a demo project in your own. Get your free Mixpanel demo account and click [here](https://mixpanel.com/api/app/demo_project?show-demo-dataset-modal=true) to access the demo datasets. Once you're in, you can set up a new Board easily using a [template](/docs/boards/templates), or you can build a report from scratch. If you like what you see and want to use the analysis in your own project, you can click the button that says "Use this Board." You'll then select the project to which you want to move the board. + +Step 4: If there are events and properties used in the old project but not the new project, the affected reports will remain empty or say “no data” until new events and properties are selected. + +When a report can’t populate, it will display one of two states: a faded out sample report or a “no data” status. + +- Charts that show "no data" occur when an event has been tracked in the last 30 days, but a filter or date range result in no data for the report. +- For the sample report to appear, the report would have to be configured with an event that hasn't existed or at least hasn't been tracked in past 30 days. + +For example: a join membership club event happened 100 times yesterday, but 0 so far today. If you create a report for today, it will show “no data”. But if this is day one of the program and it has never been tracked before, it will show a dummy sample report. From this empty state, you can set up your new reports like any other report. + +👉🏽 NOTE: If you would like a version of the Board to stay in the parent project, duplicate it and move the new duplicate Board. diff --git a/pages/docs/boards/sharing-and-permission.md b/pages/docs/boards/sharing-and-permission.md new file mode 100644 index 0000000000..46f9e036c5 --- /dev/null +++ b/pages/docs/boards/sharing-and-permission.md @@ -0,0 +1,42 @@ +# Sharing and Permission + +## Overview +Reports are always saved to boards. When you save a report, you'll be prompted to save it to a specific board. In essence, the board now acts as a folder, with many potential purposes, including: + +- A centralized place to track numerous metrics related to a product launch +- A chain of analyses digging into a particular behaviour or issue +- A set of draft reports you're working on + +This will make it easy to keep reports organized, and reduce time wasted recreating the same reports again and again. + +Note: This only applies to the Mixpanel's core reports (Insights, Flows, Funnels, and Retention). Advanced reports like Signal, Experiments, and Impact lives in the Applications folder at the top right of the page. + +![/Screen_Shot_2022-01-05_at_9.18.06_PM.png](/Screen_Shot_2022-01-05_at_9.18.06_PM.png) + +## Sharing + +Sharing and permissions are set at the board level, and all reports saved on a board inherit the same set of sharing and permissions settings of that board. + +To share a board, and therefore all reports contained within it, click the Share button at the top right of the board. From here, sharing works as before, but remember, sharing a board shares all of that board's other reports as well.  + +![/GIF3__light_.gif](/GIF3__light_.gif) + +Both reports and boards can also be shared via the "Copy URL" button at the top right. Clicking this button will immediately copy the short link to the report or board, so you can quickly paste it into your application of choice. + +![/Screen_Shot_2021-11-08_at_11.01.00_AM.png](/Screen_Shot_2021-11-08_at_11.01.00_AM.png) + +So long as the recipient has access to the project, they will be able to see the shared report or board. However, unless they have specifically given Editor permissions, they will only be able to view it, not edit it. + +## Permissions + +Sharing and permissions are set at the board level, and all reports saved on a board inherit the same set of sharing and permissions settings of that board. + +In the sharing process, you can choose the permissions level granted to the individual with whom you're sharing the board. Teammates with access to a board can either be Viewers (any changes made will not be saved) or Editors (changes made will be saved).  + +As with sharing, setting a user's permission level on a board will give them the same permission level for all reports on that board. + +## Linked Reports + +Every report in Mixpanel has a board where it was originally saved to. This is called the original board. However, in the interest of being able to use the same report across a variety of boards and sharing the same insight across your team and company, Mixpanel has introduced the concept of a "linked report". A linked report is denoted by the arrow in the icon of the report. Any time an existing report is added to a board or a copy is made, a linked report is made. Any changes to the report will get reflected in all of the linked reports associated with the report. + +![/Screen_Shot_2022-07-11_at_6.06.58_PM.png](/Screen_Shot_2022-07-11_at_6.06.58_PM.png) diff --git a/pages/docs/cohort-sync/overview.md b/pages/docs/cohort-sync.md similarity index 100% rename from pages/docs/cohort-sync/overview.md rename to pages/docs/cohort-sync.md diff --git a/pages/docs/cohort-sync/_meta.json b/pages/docs/cohort-sync/_meta.json index 3cb33b0d0c..13c9e96be4 100644 --- a/pages/docs/cohort-sync/_meta.json +++ b/pages/docs/cohort-sync/_meta.json @@ -1,5 +1,4 @@ { - "overview": "Overview", "webhooks": "Webhooks", "build-an-integration": "Build an Integration", "integrations": "Integrations" diff --git a/pages/docs/data-structure/property-reference/data-type.md b/pages/docs/data-structure/property-reference/data-type.md index 60ecc7644d..6d1e02a06a 100644 --- a/pages/docs/data-structure/property-reference/data-type.md +++ b/pages/docs/data-structure/property-reference/data-type.md @@ -275,9 +275,9 @@ In each case, the object will have multiple properties, such as "price" and "bra ### Breakdown and Filter List of objects can be used like other properties in Mixpanel. Upon selecting a list of objects property, you will be prompted to select another property common to the objects in the list. Usage in measurements, filters, and breakdowns follows the same behavior as other [list properties](/docs/data-structure/property-reference/data-type#list-property-support). -### Computed Properties +### Property Computation -We provide a few convenient computed properties after a list of objects property is selected. This does a computation on the property, and works similarly to [custom properties](/docs/features/custom-properties). +We provide a few convenient property computation after a list of objects property is selected. This does a computation on the property, and works similarly to [custom properties](/docs/features/custom-properties). ![list computed properties](/list-computed-properties.png) diff --git a/pages/docs/features/_meta.json b/pages/docs/features/_meta.json index e43bdb13b7..5119f02cc3 100644 --- a/pages/docs/features/_meta.json +++ b/pages/docs/features/_meta.json @@ -1,12 +1,14 @@ { - "alerts": "Alerts", - "attribution": "Attribution", "embeds": "Embeds", + "alerts": "Custom Alerts", "custom-events": "Custom Events", + "custom-buckets": "Custom Buckets", "custom-properties": "Custom Properties", + "computed-properties": "Computed Properties", + "query-sampling-and-caching": "Query Sampling and Caching", "saved-behaviors": "Saved Behaviors", "session-replay": "Session Replay", "sessions": "Sessions", - "spark": "Spark", - "advanced": "Advanced" + "spark": "Spark AI", + "slack-integration": "Slack Integration" } diff --git a/pages/docs/features/advanced.md b/pages/docs/features/advanced.md deleted file mode 100644 index 550aaa3535..0000000000 --- a/pages/docs/features/advanced.md +++ /dev/null @@ -1,1028 +0,0 @@ -# Advanced - -## Query Builder Features - -### Session Metric Analysis - -![/Screen_Shot_2022-07-11_at_3.53.47_PM.png](/Screen_Shot_2022-07-11_at_3.53.47_PM.png) - -Analyze session metrics by selecting "Session Start" or "Session End" from the events list. Learn more about using Sessions in Insights, Funnels and Flows [here](/docs/features/sessions). - -### Inline Filtering - -Filter this event by clicking the **inline action menu** and selecting **Add filter** from the drop-down. Choose an event property, user profile property, group profile property, or cohort to filter the event by. - -![image](https://github.com/mixpanel/docs/assets/2077899/9307d6c1-025c-4bb4-9ab3-12f9ab1c7ce3) - -You can select whether you would like your query to match any or all of the filters by clicking on **and/or** beside the filters. - -![image](https://github.com/mixpanel/docs/assets/2077899/1b8cdb9d-2479-404c-b10a-f82373d03e34) - -### Duplicating Events - -To duplicate any events or properties in your query, select the inline action menu and choose **Duplicate**. Delete any events or properties by clicking the **trash** icon. - -![image](https://github.com/mixpanel/docs/assets/2077899/f496b609-47a3-4287-95f8-e9e6f2ac915d) - -### Advanced Date and Time Selectors - -You can also choose how Mixpanel buckets the time range in Insights, Funnel Trends and Retention Trend reports (granularity may vary). To view a range in hours, you can select **Hour** as the view: - -![image](https://github.com/mixpanel/docs/assets/2077899/991a0f0f-b297-4b94-8d41-7323fe6666f6) - -To zoom in, click on the graph and drag to highlight a specific window of time in your report. Click **Reset zoom** to return to the previous view. - -![zoom (1)](https://github.com/mixpanel/docs/assets/2077899/3add64ad-3fea-4d74-a3bf-303fcc1f4d9d) - -### Advanced Filter & Breakdown Usage - -To filter the results of your report by any property or cohort, click the **Filter** button. - -To break down your results of your report by any property or cohort, click the **Breakdown**. - -You can break down your results by the "Time" event property and breakdown by Hour, Day, Week, Month, Quarter, Year, Hour of Day, or Day of Week. - -![/breakdown_by_date.gif](/breakdown_by_date.gif) - -If you are analyzing any custom events, you can breakdown by the property "Event Name". - -![image](https://github.com/mixpanel/docs/assets/2077899/dafe97ca-35a3-4dee-8285-41a115f0417d) - -The drop-down menus only show events/event properties that were ingested within the last 30 days. To select events/event properties that have not been ingested in the last 30 days, type the name of the event/event property in the Filter or Breakdown search bar. You must know the exact name of the event/event property you want to select because event names are case sensitive. - -![/query_old_event.gif](/query_old_event.gif) - -To create a temporary cohort for the current report, click **Create Custom...** in the dropdown menu and select "Cohort. A window will pop up where you can specify the restrictions of your cohort. Learn more about building a cohort [here](/docs/users/cohorts#creating-cohorts). - -![/create_cohort_from_report.gif](/create_cohort_from_report.gif) - -## Slack Integration - -Connect Mixpanel to your Slack workspace to help share reports with your colleagues faster. You can (1) set up an alert to send a message to a Slack channel, (2) set up a Board Subscription to send a message to a Slack channel, or (3) share previews of any Mixpanel report in Slack. - -To send an alert to a Slack Channel, see [Custom Alerts](/docs/features/alerts). To set up a board subscription to a Slack Channel, see [Advanced Board Functionality - Subscriptions](/docs/boards/advanced#board-subscriptions). - -The Mixpanel application for Slack will also automatically unfurl a preview of any Mixpanel link, including chart images for certain reports, making it easy for anyone in your Slack workspace to learn from your Mixpanel analyses. - -### Enable the Integration - -To enable the integration, log in to both Mixpanel and Slack, then click [here](https://mixpanel.com/slack/oauth?slack_v2=true) to authorize the slack workspace: - -![/Screen_Shot_2020-06-15_at_10.41.00_PM.png](/Screen_Shot_2020-06-15_at_10.41.00_PM.png) - -After clicking allow, you'll return to Mixpanel, where you'll see a success banner: - -![/Screen_Shot_2020-06-15_at_10.42.06_PM.png](/Screen_Shot_2020-06-15_at_10.42.06_PM.png) - -At this point, Mixpanel is a part of your Slack workspace, and any Mixpanel links you send in Slack will unfurl with metadata, and if applicable a chart preview. - -Once at least one member of your Mixpanel organization has set up the Mixpanel Integration for Slack for their account, any other members of the Slack workspace will see a prompt the next time they paste a Mixpanel link. The prompt will ask them to connect their own Mixpanel account to Slack as well. If they choose to do so, Slack will guide them through the authentication flow. Once they have successfully connected Mixpanel to Slack, any further links they paste in Slack will unfurl. - -### Using the Integration - -Once you've set up the integration, Mixpanel links pasted in Slack will unfurl. Most links will provide some basic link metadata, and links to Insights, Flows, Funnels, or Retention reports will also include a chart preview, for example: - -![/slack_app_demo.png](/slack_app_demo.png) - -### Permissions - -Mixpanel does not restrict who can enable the Mixpanel integration for Slack. However, your Slack workspace may limit who can perform the connection. - -After Mixpanel is connected to Slack, any Slack user who posts a Mixpanel link will be prompted to connect their own account, in order to unfurl report previews. By performing this integration at the user level, it ensures that only reports the user has access to will unfurl in Slack. - -### Privacy - -The Mixpanel app for Slack adheres to Mixpanel's overall privacy policy, available in full here: [https://mixpanel.com/legal/privacy-policy/](https://mixpanel.com/legal/privacy-policy/). - -## Custom Buckets - -Custom buckets lets you group existing properties into meaningful segments on the fly. This is focused on enabling every person to answer common segmentation questions easily, quickly and in a low friction way. - -Example use-cases include: - -- Compare how the core markets are performing between US vs UK vs China vs all others -- Compare how many sign-ups are brought in by organic search vs Google ads vs social media channels together (Facebook, Twitter, LinkedIn) -- Compare # videos watched for users between ages 18-30 vs 30-40 or 40+ -- Compare # users based on duration of video watched: < 30, 30-60, 60-90 mins - -### Creating Custom Buckets - -Add a property in Breakdown, then select the **Customize Buckets** option from the overflow menu - -![/14342458665748](/14342458665748.png) - -Depending on your added property data type - string vs numeric, you will see a different custom buckets modal, designed based on the data-type use-cases **(more detail below)** - -Once you define your segment buckets, click **Apply.** Only then will the custom buckets reflect in the visualization. You will also see the custom buckets as an under-item on the property - -![/14342458667924](/14342458667924.png) - -To modify the segment buckets, click on the **under-item** and the custom buckets model will open. Once you’ve made the changes, click **Apply** - -To remove all grouping and revert to the default, open the custom buckets modal and click **Reset** - -### String property Use Cases - -**Use Case:** You want to compare # videos watched between core markets - North America, Europe & China - -Current: You have a property “Country” - -Goal: You want to group the countries into meaningful segments - -- Segment 1: North America: US & Canada -- Segment 2: Europe: UK, Germany, France, Netherlands, Italy -- Segment 3: China -- Segment 4: Rest of the World (everything but those above) - -Steps - -1. Add a breakdown - Country. Below is the default you’ll see - - ![/12828869626644](/12828869626644.png) - -2. Choose to bucket segments, by opening the custom buckets model and click Apply - - For each segment, choose the operator “is” and select one or more values - - “Rest of the World” is auto generated as **remaining values** - - To note — if two segments have the same value, the first segment will consider the value. Custom buckets are non-overlapping and sum up to 100% by definition - -![/14342715436052](/14342715436052.png) - -![/12828860042132](/12828860042132.png) - -**You can also re-name these segments to make them meaningful to you** - -1. On the same line of the segment, choose to rename it using the pencil icon -2. Click Apply after creating and naming your segments as desired - -![/14342752741140](/14342752741140.png) - -![/12828869956628](/12828869956628.png) - -### Numeric property Use Cases - -**Use Case:** You want to compare #users based on duration of video watched - -Current: You have a property “watch time (mins)” - -Goal: You want to distribute this in various ways - -- Use Case A: Evenly in 10 min groups for the range 50-100 mins -- Use Case B: Specific groups <10, 10-20, 20-50, 50-100, ≥100 -- Use Case C: Want to see all the durations as-is (No grouping) - -**Deep Dive: Use Case A**: Evenly in 10 min buckets for the range 50-100 mins - -1. Add a breakdown - “watch time (mins)” - - To note — every numeric property is **auto-bucketed into even sized buckets as the default** - - Here the default seems to be even buckets of 10 mins across the range - - ![/14342489051028](/14342489051028.png) - - ![/12828860268692](/12828860268692.png) - -2. Go to the overflow and open the custom buckets modal -3. Since looking for even buckets of “30 mins”, choose **Even Bucketing** -4. Modify the min and max values of the desired range, and the bucket size, and click apply - - To note — both a lower end and upper end bucket will be auto-generated to ensure your breakdown always adds up to 100% - - Here these buckets are <50 mins and ≥ 100 mins - - ![/14342575096724](/14342575096724.png) - - ![/12828860573204](/12828860573204.png) - - -**Deep Dive: Use Case B**: Specific groups <10, 10-20, 20-50, 50-100, ≥100 - -1. Open the custom buckets modal -2. Since looking for specific buckets with varied bucket ranges, choose **Varied Bucketing** -3. Enter the ‘segment’ break point values in each row and click apply. You can preview the bucket as you enter values in the line-item below - - To note — both a lower end and upper end bucket will be auto-generated to ensure your buckets always adds up to a 100% - -![/14342546138516](/14342546138516.png) - -![/12828860758676](/12828860758676.png) - -**Deep Dive: Use Case C:** Want to see all the durations as-is (No bucketing) - -1. Open the custom buckets modal -2. Since looking for “No bucketing”, choose **None —** This lays out all the numeric property values as-is - -![/14342547991956](/14342547991956.png) - -![/12833587659028](/12833587659028.png) - -### Typecasting property Use Cases - -**Use Case:** You want to identify #users of age 18 and age 60 since these are user ages where they change subscription plans (upgrade and downgrade respectively) - -Current: You have a property age (years) - -Goal: You want to group this in a meaningful way - -- Segment 1: Age 18 (potential to upgrade) -- Segment 2: Age 60 (potential to downgrade) -- Segment 3: Every other age - -Steps - -1. Add a breakdown age(years). By default this will add as a numeric property -2. Since you are looking for pin-pointed years and not creating number-ranges, this is a question more common to string property data type -3. Change **Data Type** of age(years) to String. Once changed you will see the type-casted property type as an under-item - - To note - only type-casted data types show as an under-item. If the data-type was the same as ingested, no under-item for data type will be seen - - ![/14342634016660](/14342634016660.png) - - ![/12833644608148](/12833644608148.png) - -4. Post changing data-type, open the custom buckets modal. This will now open a modal meant for string property data type -5. Follow steps as elaborated for String property use-case above, and achieve the goal - - ![/14342637801748](/14342637801748.png) - - ![/14342707763604](/14342707763604.png) - - ![/12833899595284](/12833899595284.png) - - -### FAQ - -- **Which reports does Custom Buckets work on?** - - This feature is available in the Insights, Funnels and Retention reports. - -- **Which property types does this support?** - - Custom Buckets work on String, Numeric and List data type - -- **Can I save a Custom Bucket**? - - No, you can’t save a custom bucket. If your custom bucket is something you or your team would like to re-use, we encourage you to instead create a [custom property](/docs/features/custom-properties#creating-a-custom-property). - -- **How is custom buckets different from [custom property](/docs/features/custom-properties)?** - - Custom buckets only supports the most common custom-property use-case of **`if else`** to create meaningful segments in a more simplistic UI, and a low lift way to enable quick ad-hoc exploration. You could get this same answer using custom property too, it would just be more effort and not as intuitive - -- **Can I create over-lapping segments like (US & UK) vs (US & Australia)?** - - No, breakdowns are fundamentally designed to sum up to 100%. To ensure your analysis is accurate, please create non-overlapping segments. - - If you really need to answer a question like this, the right way here is to create these as two metrics leveraging [inline filters](/docs/reports/overview) and NOT use breakdowns. - - ![/12834111393684](/12834111393684.png) - -- **What happens if I change data-type, can I still use custom buckets?** - - Yes you can as long as the data-type you’ve changed the property to is supported. - -- **Understanding the details:** - - **In Numeric: Can I change the operators on the upper and lower bound?** - - No, the operators have been fixed. The lower bound is always strictly greater than (≥) and the upper bound is just lesser than (<). If you are looking for more control on the operators, please create a [custom property](/docs/features/custom-properties#creating-a-custom-property). - - - **In String: Is (not set) included in (remaining values)?** - - No, (not set) is not included in remaining values - - - (remaining values): refers to ‘set’ values that just don’t fall into any of your defined segments - - (not set) refers to the events where a property value has not been set at tracking/ ingestion. For example a new video (MixFun) is has been added. But during tracking, you forget to send the name of this video. So the count of this video is being tracked, but it’s being associated to a property value (not set) vs (MixFun) - - More details can be found in [this help doc](/docs/features/advanced#undefined-and-null-properties) - - - **In Numeric: What is the difference between (not set) and (non-numeric values)?** - - (not set) as explained above for string refers to property values that have not been associated to any specific property value - - (non numeric values) refers to set values that have just been sent in as non-numeric data type. For example, you’re looking to track time spent and have coded that as a numeric property, but for some reason some values are tracked as “a”, or “b” which are not-numeric. -- **Some Common How-do-I(s)** - - **How do I know is set, (not set)?** - - (not set) is automatically computed and will always show up in the UI. You don’t have to select (not set) as a segment to know how many events fall in there. So only figure how would you like to segment your (set) values. - - ![/12834113971348](/12834113971348.png) - - - **How do I get "not contains" or "not equal to"?** - - These values will auto-generate under (remaining values). So just select what should be included - - For example — the (remaining values) below is not equal to US or India - - ![/12834082079380](/12834082079380.png) - - - **In Number: how do I get a bucket of just 0?** - - If you’re purely looking for just how many people have value “0”, we would encourage you to typecast this to a string property and get that. - - If you’re looking to get the count of 0, in reference to the other numeric buckets, go ahead and create a **Varied Bucketing** custom buckets modal - - - If the numeric values are integers: - - Choose Varied bucket values 0, 1, 2… - - This would generate buckets: <0, ≥0 & <1, ≥1 & <2, ≥2. - - ≥0 & <1 would be equal to bucket 0 - - If the numeric values are decimals: - - Choose Varied bucket values 0, 0.0001, 1, … - - This would generate buckets: <0, ≥0 & <0.0001, ≥0.0001 & <1, ≥1. - - ≥0 & <0.0001 would approximate to bucket 0 - - -## View Users - -View Users is a streamlined process for exploring the users contributing to a specific metric or point on a chart. By interacting with the chart, you can view a group of users experiencing friction or dig deep into which users are driving feature adoption. - -View Users can help you: - -- See the users contributing to any metric and view their recent activities & properties. -- Save these users as a cohort. -- Export these users to a CSV file. - -### Insights - -![/View_Users_Insights_gif.gif](/View_Users_Insights_gif.gif) - -- To learn more about your users who recently **Signed Up** at a specific point in time, you can click any point on a chart or line to access View Users. The View Users overlay **displays the list of users contributing to your chosen point on the chart**. -- By clicking on one of these users, you can further **explore their User Properties** like experiment group, purchase count, last event and many more. -- While viewing a specific user, you can also **discover their recent activities** (\*Like, Comment, Message Sent, Ad Conversion,\* etc) after **Sign Up** through the Activities menu. - -### Funnels - -![/View_Users_Funnels_gif.gif](/View_Users_Funnels_gif.gif) - -- Finding the **exact group of users who dropped off** after **Sign Up** is possible through View Users in Funnels. While in a Funnels report, click on the section of the chart that displays non-converting users and select View Users - this displays the list of those who didn’t convert after signup. -- **Save this group as a cohort** by clicking the Create Cohort button. Now, you can learn more about their product usage or find the root cause of why they didn’t convert after Sign Up. - -### Retention - -![/View_Users_Retention_gif.gif](/View_Users_Retention_gif.gif) - -- View Users in Retention report presents you with two options - view retained users and view dropped off users. This is helpful to **find the specific group of users who were engaged or dropped off** after **Sign Up** over a period of time. -- **Export your group of choice to a CSV with one click**. This data can guide meaningful actions, like emailing your user group a note that helps them get unstuck and engaged. - -## Keyboard Shortcuts - -### Undo / Redo Shortcuts - -Undo / redo shortcuts allow for fast adjustments to your analysis. `Cmd + Z` to undo; `Cmd + Shift + Z` to redo. Change filters, date ranges, line vs bar chart, and go back in one second to compare before and after, or fix the view. - -![/Undo_Redo_gif.gif](/Undo_Redo_gif.gif) - -- **Navigate different report versions**: add a new event, filter or breakdown and undo that change with `Cmd + Z` . This makes iterating between different versions of your report quick and easy. -- **Compare visualizations**: go from a bar chart, to a line chart, to a pie chart and all the way back while only using the undo / redo keyboard shortcuts. - -## Comparison: Time, Baseline and Overall - -Once you have visualized a metric you are interested in, you want want to compare it against related metrics to gain further insight. Previously, only comparing against past values was supported, but there are now 3 different ways to compare your metrics. The ability to do and show comparisons across segments is also supported in Boards, so any report saved will also reflect in Boards. - -### Time Comparisons - -![/Screen_Shot_2021-09-22_at_4.38.05_PM.png](/Screen_Shot_2021-09-22_at_4.38.05_PM.png) - -The compare to past menu has been modified to include the new comparison options, but users can continue to find the same time comparison options that existed before under the new "Compare" menu. - -### Time Comparison - Absolute Values - -![/Screen_Shot_2021-09-22_at_4.40.26_PM.png](/Screen_Shot_2021-09-22_at_4.40.26_PM.png) - -This is the same default behavior that existed previously. When you compare to a time period users will see a solid line for the present data, and a dashed line for data in the time comparison period. - -### Time Comparison - Percentage change over Baseline - -This can be activated by selecting the "Percent change over Baseline" option in the controller next to the comparison menu. - -![/Screen_Shot_2021-09-22_at_4.40.41_PM.png](/Screen_Shot_2021-09-22_at_4.40.41_PM.png) - -When this view is activated, users will see the percentage difference from the one time period to another. This is the same value that was shown in the tooltip, but now users are able to show how segments are shrinking and growing over time. This also makes it easier to see relative performance between different segments. - -![/Screen_Shot_2021-09-22_at_4.50.52_PM.png](/Screen_Shot_2021-09-22_at_4.50.52_PM.png) - -These values are also reflected into the segmentation table below the chart. - -### Increase over Baseline - -Another comparison type that is now natively supported in Mixpanel is the ability to set a segment as a baseline from which other segments are compared against. This allows users to compare different segments across the same time period. - -![/Screen_Shot_2021-09-22_at_4.50.28_PM.png](/Screen_Shot_2021-09-22_at_4.50.28_PM.png) - -![/Screen_Shot_2021-09-22_at_4.50.36_PM.png](/Screen_Shot_2021-09-22_at_4.50.36_PM.png) - -To enable, choose the "Increase over Baseline" option in the compare menu, then choose the segment that you wish to be the baseline. - -![/Screen_Shot_2021-09-22_at_4.53.21_PM.png](/Screen_Shot_2021-09-22_at_4.53.21_PM.png) - -Notice that because "Home supplies" is chosen at the baseline, it appears on the chart as a flat 0 line - this is because "Home supplies" always has a 0% difference against itself in the same time period. - -Also note that the y axis can go below 0, because segments can perform better or worse than the selected baseline, like "Entertainment" above. - -### Percentage of Overall - -This option allows users to see how segments perform as a percentage of the total. Mixpanel will proactively disable this option when this comparison option won't give meaningful results. - -![/Screen_Shot_2021-09-22_at_5.10.53_PM.png](/Screen_Shot_2021-09-22_at_5.10.53_PM.png) - -To enable, open the Compare menu and select "Percentage of Overall" - -![/Screen_Shot_2021-09-22_at_5.17.27_PM.png](/Screen_Shot_2021-09-22_at_5.17.27_PM.png) - -### Why do the values in Compare to Overall not add up to 100%? - -Depending on the type of metric, the percentages may not add up to 100%. This is because the value is being compared to the unsegmented value. For example, if you were you segment Total "Add Item to Cart" events by "Category", then the values should sum up to 100%, since an item might not be a part of different categories. - -However, if the metric was "average price", then the average price across all categories might be $10. Within individual categories, the average price might be lower or higher, and that is the comparison being done by "Compare to Overall". In this case the percentage values would not add up to 100%. - -More generally, if the metric is summable, and the groups are mutually exclusive, then the percentages will add up to 100%. if the metric is a non counting metric like uniques, or percentile aggregation, the percentages will not add up to 100%. Another example is if the breakdown is by cohorts, where users can be members of multiple cohorts, the percentages will not sum to 100%. - -### Supported Charts - -Comparisons are supported across all insights chart types. Depending on the exact configuration chosen, certain comparison operations may be disabled. - -| Chart Type | Time Comparison Supported | Percentage change over Baseline Supported | Percentage of Overall Supported | -| --- | --- | --- | --- | -| Insights Line | Yes | Yes | Yes | -| Insights Stacked Line | No | No | Yes | -| Insights Bar | Yes | Yes | Yes | -| Insights Stacked Bar | Yes | No | No | -| Insights Pie | No | No | Yes | -| Insights Metric | Yes | Yes | Yes | -| Funnels Steps | Yes | Yes | No | -| Funnel Trends | Yes | Yes | No | -| Retention Curve | No | Yes | No | -| Retention Trends | Yes | Yes | No | - -## Limits and Ordering - -### Summary - -In order to keep the interactive analysis experience snappy for projects of all sizes, we've made 2 changes: - -- Added maximum limits to how many segments are returned when breaking down a metric by properties -- Changed the logic for the top segments that are returned - -### Limits - -### UI - -We're changing how many segments are returned back to the report (**visible limit**), how many segments can be selected at a time for visualization (**selection limit**) as well as the number of segments selected by default (**default selection**). - -Here's the breakdown per report + visualization type: - -| Report Viz | Default Selection | Selection Limit | Visible Limit | -| --- | --- | --- | --- | -| Insights (bar) | 12 | 300 | 3000 | -| Insights (line) | 12 | 50 | 3000 | -| Retention | 6 | 12 | 200 | -| Funnels | 6 | 12 | 200 | - -### Downloaded CSV and API - -When downloading results as CSV or when querying our APIs, the limits remain unchanged. - -### Top Segments logic - -The way we pick the top segments differs according to the type of query. We choose the top segments based on the value shown in the second column. - -| Query type | How we select top segments | -| --- | --- | -| Total | Total number of occurrences of the chosen event | -| Unique | Number of unique users who performed the chosen event | -| Sum of property values | Sum of the chosen property | -| Min/max of property values | Lowest/highest value of the chosen property | -| Average | Number of events (or users) that contribute to the average | -| Median/Percentile/Distribution | Number of events (or users) that contribute to the distribution | -| Distinct count | Number of distinct values of the chosen property | -| DAU/WAU/MAU | Number of unique users | -| Sessions | Number of sessions that contain the chosen event | -| Funnels | Total number of times the first funnel step was completed | -| Retention | Total number of times the first event was completed | - -### FAQ - -**How will I know if my results are being pruned?** - -You will see an indication like this: - -![image](https://github.com/mixpanel/docs/assets/2077899/3935993c-0410-46e4-a9d6-2d2dfb5313cd) - -**Does this mean the downloaded CSV has lower limits?** - -No, limits for CSV downloads remain unchanged across Insights, Funnels and Retention. - -## List Property Support - -### Introduction - -This article walks through a few scenarios of how list properties behave within Mixpanel. The examples used here are from the Insights report, but the principles of how filter and breakdowns work with list properties remain the same across reports. - -### Data - -Let's assume an e-commerce platform has these 3 events: - -- Event 1: *PurchaseCompleted* - - *List of ProductIDs* = ["P1", "P2", "P4"] -- Event 2: *PurchaseCompleted* - - *List of ProductIDs* = ["P2", "P3", "P4"] -- Event 3: *PurchaseCompleted* - - *List of ProductIDs* = ["P3", "P4"] - -Now let's assume that *"List of ProductIDs"* is mapped to a [lookup table](/docs/data-structure/lookup-tables) called *Products* which looks like this: - -| ProductID | Category | Price | -| --- | --- | --- | -| P1 | Clothing - pants | 100 | -| P2 | Clothing - shirt | 54 | -| P3 | Shoes | 109 | -| P4 | Electronics - music | 199 | - -**** - -### Use Cases - -### Breakdown - -- Breakdown a list property - - **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* - - **Answer:** - - - | List of ProductIDs | Total | - | --- | --- | - | P1 | 1 | - | P2 | 2 | - | P3 | 2 | - | P4 | 3 | - - **What's going on here?** When breaking down, each of the list's contents is evaluated as a single item. So for example, P2 is present in Event 1 and Event 2, so the TOTAL (of the *PurchaseCompleted* event) where "P2" is present is 2. -- Breakdown by [lookup profile property](/docs/data-structure/lookup-tables) that's joined to a list property - - **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* → *Category* - - **Answer:** - - - | List of ProductIDs | Total | - | --- | --- | - | Clothing - pants | 1 | - | Clothing - shirt | 2 | - | Shoes | 2 | - | Electronics - music | 3 | - - **What's going on here?** When breaking down, each of the list's contents is evaluated as a single item after being mapped to the lookup table. So for example, P2 is present in Event 1 and Event 2, and P2 mapped to the lookup table which gets us *Category* = "Clothing - shirt", so the TOTAL (of *PurchaseCompleted* events) where "Clothing - shirt" is present is 2. The thing to note here is that the results are identical to when *PurchaseCompleted* was broken down by *"List of ProductDs"*, except the *ProductIDs* are replaced by *Category*. -- Breakdown by lookup profile property that's joined to a list property AND by the list property itself - - **Question:** TOTAL of *PurchaseCompleted* broken down by *"List of ProductIDs"* → *Category* AND *"List of ProductIDs"* (2 breakdowns applied) - - **Answer:** - - - | List of ProductIDs.Category | List of ProductIDs | Total | - | --- | --- | --- | - | Clothing - pants | P1 | 1 | - | | P2 | 1 | - | | P4 | 1 | - | Clothing - shirt | P1 | 1 | - | | P2 | 2 | - | | P3 | 1 | - | | P4 | 2 | - | Shoes | P2 | 1 | - | | P3 | 2 | - | | P4 | 2 | - | Electronics - music | P1 | 1 | - | | P2 | 2 | - | | P3 | 2 | - | | P4 | 3 | - - **What's going on here?** For each breakdown value, Mixpanel recomputes the list breakdown. So for example, TOTAL (*PurchaseCompleted*) with "*List of ProductIDs*" → *Category* = "Shoes" should get us Event 2 and Event 3:When these 2 events are broken down by *"List of ProductIDs"*, we get these results for "Shoes"(*ProductID* = "P3"): - - Event 2: *PurchaseCompleted* - - *List of ProductIDs* = ["P2", "P3", "P4"] - - Event 3: PurchaseCompleted - - *List of ProductIDs* = ["P3", "P4"] - - P2: 1 - - P3: 2 - - P4: 2 - -### Filter - -- Filter by any element of a list property - - **Question:** TOTAL of *PurchaseCompleted* filtered by - - - | "List of ProductIDs" | Any | = (equals) | "P1" | - | --- | --- | --- | --- | - - **Answer:** *PurchaseCompleted - TOTAL*: 1 - - **What's going on here?** The "Any" operator filters down events when the filtered value matches ANY item in the list property. So in this example, the only event in which "List of ProductIDs" has "P1" present even once is Event 1, so the total event count for this filter is 1. -- Filter by all elements of a list property - - **Question**: TOTAL of *PurchaseCompleted* filtered by - - - | "List of ProductIDs" | All | = (equals) | "P1" | - | --- | --- | --- | --- | - - **Answer:** *PurchaseCompleted - TOTAL*: 0 - - **What's going on here?** The "All" operator filters down events when the filtered value matches ALL of the items in the list property. So in this example, there is no event in which "List of ProductIDs" has all the elements equal to "P1", so the total event count for this filter is 0. -- Filter by list property and broken down by list property - - **Question:** TOTAL of PurchaseCompleted filtered byBroken down by "List of ProductIDs" - - - | "List of ProductIDs" | Any | = (equals) | "P1" | - | --- | --- | --- | --- | - - **Answer:** - - - | List of ProductIDs | Total | - | --- | --- | - | P1 | 1 | - | P2 | 1 | - | P4 | 1 | - - **What's going on here?** There is only 1 event that contains "P1" (Event 1, *"List of ProductIDs"* = ["P1", "P2", "P4"]), so when that one event is broken down by *"List of ProductIDs"*, Mixpanel evaluates each list item individually, thereby getting us: - - P1: 1 (1 event) - - P2: 1 (1 event) - - P4: 1 (1 event) -- Filter by lookup profile property that's joined to a list property and then broken down by list property - - **Question:** TOTAL of *PurchaseCompleted* filtered byBroken down by "List of ProductIDs" - - - | "List of ProductIDs" → Category | Any | = (equals) | "Shoes" | - | --- | --- | --- | --- | - - **Answer:** - - - | List of ProductIDs | Total | - | --- | --- | - | P2 | 1 | - | P3 | 2 | - | P4 | 2 | - - **What's going on here?** There are 2 events that contain where the *Category* mapping for at least one of the *ProductIDs* in "*List of ProductIDs*" is equal to "Shoes" (i.e. *ProductID* = P3).When these two events are broken down by *"List of ProductIDs"*, Mixpanel evaluates each list item individually, thereby getting us: - - Event 2: PurchaseCompleted - - List of ProductIDs = ["P2", "P3", "P4"] - - Event 3: PurchaseCompleted - - List of ProductIDs = ["P3", "P4"] - - P2: 1 (1 event) - - P3: 2(2 events) - - P4: 2 (2 events) -- Filter by lookup profile property that's joined to a list property (with multiple matching values) and then broken down by list property - - **Question**: TOTAL of *PurchaseCompleted* filtered byBroken down by "List of ProductIDs" - - - | "List of ProductIDs" → Category | Any | ∋ (contains) | "Clothing" | - | --- | --- | --- | --- | - - **Answer:** - - - | List of ProductIDs | Total | - | --- | --- | - | P1 | 1 | - | P2 | 2 | - | P3 | 1 | - | P4 | 2 | - - **What's going on here?** This filter can be read as "for any of the items in *'List of ProductIDs'* , the lookup property *Category* contains the string 'Clothing'". This operation is filtering down to all the events that contain the *Category* mapping for the *ProductID* contains EITHER "Clothing - pants" or "Clothing - shirt", and that gives us 2 events: - - Event 1: PurchaseCompleted - - List of ProductIDs ["P1","P2","P4"] - - Event 2: PurchaseCompleted - - List of ProductIDs ["P2","P3","P4"] - - Therefore, when those two events are broken down by "List of ProductIDs", Mixpanel evaluates each item of the list individually and we end up getting: - - P1: 1 - - P2: 2 - - P3: 1 - - P4: 2 -- Filter by lookup profile property that's joined to a list property (numeric filter) and then broken down by list property - - **Question**: TOTAL of *PurchaseCompleted* filtered byBroken down by *"List of ProductIDs"* - - - | "List of ProductIDs" → Price (number) | Any | < (less than) | 100 | - | --- | --- | --- | --- | - - **Answer:** - - - | List of ProductIDs | Total | - | --- | --- | - | P1 | 1 | - | P2 | 2 | - | P3 | 1 | - | P4 | 2 | - - **What's going on here?** The filter can be read as "for any item in *'List of ProductIDs',* the lookup property *Price* is less than 100" and it only matches 1 product, and that is P2. Therefore, what this operation is doing is filtering down to all the events that contain P2 as ANY of the values in "List of ProductDs", and that gives us 2 events:Therefore, when those two events are broken down by *"List of ProductIDs"*, Mixpanel evaluates each item of the list individually and we end up getting: - - Event 1: *PurchaseCompleted* - - *List of ProductIDs* = ["P1", "P2", "P4"] - - Event 2: PurchaseCompleted - - *List of ProductIDs* = ["P2", "P3", "P4"] - - P1: 1 - - P2: 2 - - P3: 1 - - P4: 2 - - -## List of Objects Property Support - -### Use Cases - -List of objects are generally useful when tracking a list of complex things. Some examples: - -- items in a cart -- search results -- images in a slideshow - -In each case, the object will have multiple properties, such as "price" and "brand" for items in a cart. - -``` -"event": "Product Added", -"properties": { - "cart": [ - { - "brand": "Puma", - "category": "Jacket", - "price": 30 - }, - { - "brand": "Adidas", - "category": "Hats", - "price": 15 - } - ] -} -``` - -### Usage - -List of objects can be used like other properties in Mixpanel. Upon selecting a list of objects property, you will be prompted to select another property, which is is common to the objects in the list. Usage in measurements, filters and breakdowns follows the same behavior as [other list properties](/docs/features/advanced#list-property-support). - -### Computed Properties - -We provide a few convenient computed properties after a list of objects property is selected. This does a computation on the property, and works similarly to [custom properties](/docs/features/custom-properties). - -![list computed properties](/list-computed-properties.png) - -#### Size - -The size, or length of the list as a numeric property. - -#### Sum - -Prompts a selection of a numeric property contained within the objects of the list. This will give the total for the whole list for that property. - -#### Distinct Count - -Prompts a selection of a property contained within the objects of the list. This will give the number of unique values for that property in the list. - -### Limits - -The list of objects property support will be limited to the first 5 objects within the list property. More details on [Object and List of Objects Data Types](/docs/data-structure/property-reference#object-and-list-of-objects-data-types) support in our docs. - -For customer's on a paid plan, you may submit a request for approval to have this limit increased by opening a support ticket within the UI (or by sending an email to [support@mixpanel.com](mailto:support@mixpanel.com)) with the subject line: “Request for List of Objects Limit Increase”. An increase will not be guaranteed, but your project will be reviewed for feasibility of increasing this limit. - - -## Analyzing First Time Users - -Sometimes, you might want to filter an event to only the first time that it's performed by a user. This helps answer the following questions: - -* How many users sign up or perform another key event for the first time each week? -* Which referrers do most first time users come from? -* How quickly do users make a purchase after their first time engaging with the app? -* How well do users retain after performing a key event for the first time? -* What events do users perform before and after doing their first purchase? - -You can do this by adding a First Time Filter to any event in Mixpanel. This filters the event down to only the first instance of the event performed by a user: - -![233894752-93851682-9d83-4c87-937d-8fd90db465c6.png](https://user-images.githubusercontent.com/2077899/233894752-93851682-9d83-4c87-937d-8fd90db465c6.png) - -Mixpanel computes this on-the-fly by scanning each user's history to determine if this was the first instance of the event performed by the user, based on timestamp. - -### Nth Time -You can analyze the Nth time an event was performed by using a First Time Filter in funnels. For example, this shows you the number of users that do Tutorial Complete 3 times: - -![233895123-bc2dd00f-5dde-4e43-82fe-081173abf0e4.png](https://user-images.githubusercontent.com/2077899/233895123-bc2dd00f-5dde-4e43-82fe-081173abf0e4.png) - -## Behavioral Properties - -Behavioral properties allow you to use your user's activity and use it as a property in your other analysis. A behavioral property is a virtual property, meaning it's not a property that you are explicitly tracking, but a property that Mixpanel can compute and allow you to use in analysis. - -Behavioral properties can be used anywhere, most typically in filters and breakdowns. - -### Frequency per User - -After selecting this option, you must select an event to compute the frequency of. You can use this to segment your users by how many times they did an event, or use it to filter out users to only those who did an event a certain number of times. - -### Aggregate Property per User - -After select this option, you must select an event, and then a property on that event. Finally, you can choose an aggregation type for this property. You can use this to segment your users by this property aggregation. For example, you may want to filter only for users who have greater than 100 minutes of video watch time, or you may want to segment users by their watch time. - -### Time Range - -#### Per Interval - -In insights, the time in which this computation is done is on a per interval basis. For a line chart, that will be for each individual interval plotted on the chart. For bar, table and pie, this interval is the entire date range selected in the date picker. - -#### Between Steps - -In funnels, the behavioral property is computed in the time range between 2 steps in your funnel. You can specify which steps in the funnel this applies to. In the case of doing "Frequency per User", the event count does not include the events that make up the funnel itself, and **only** the events between the funnel steps. - -#### After Step 1 - -In retention, the behavioral property is computed in the chosen time range after the entry event, up until the retaining action. For example, there may be a 7 day window in which we're looking for an event, but if the retaining action happens before the 7 days are up, we no longer count an additional events. - - -## Find Interesting Segments - -Determine which users are either driving conversion and retention or behaving as outliers by using the built in “Find Interesting Segments” feature. - -Find Interesting Segments can help you discover: - -- Whether certain property segments outperform the overall funnel conversion or retention rates. -- Which cohorts perform the best to get ideas on optimizing cohort behavior. -- Which segments are under-performing. -- Changes in the conversion or retention rates of segments. -- Change in population over time in funnels. - -User properties are not yet supported. - -### Interesting Segments in Funnels - -View the top and bottom converting segments in your funnel by clicking the **Find interesting segments** button at the bottom of the segmentation chart. - -![/10038188905364](/10038188905364.png) - -Rather than searching through multiple property breakdowns to find significant data, this feature automatically identifies this data for you. Mixpanel combs through your event properties and cohorts to show you which of those segments convert higher or lower than average, and are therefore statistically significant. - -There are two reports you will receive in your email: segment analysis and time comparison. - -### Segment Analysis - -An email that breaks down the top and bottom converting segments of your funnel based on statistical significance and other factors is automatically sent after you click the button. If no statistically significant segments are found, then the email shows non-statistically significant segments. - -Segment Analysis helps answer questions such as: - -- Which groups of users are driving my conversion rate? -- Which are groups of users are decreasing my conversion rate? - -This is done by examining which segments of users are converting at a high rate and have a large enough population size, or which segments are converting at a low rate and have a large enough population size. In the first scenario, this segment would raise the overall conversion rate, while in the second scenario this segment would be lowering the overall conversion rate. - -### Time Comparison - -A time comparison chart is also included in the email. This chart shows a segments behavior over time (in terms of both conversion rate change and population size change) as it relates to the overall population trend (population and conversion rate change). - -Time comparison answers questions such as: - -- Which groups of users are trending in a way that is different from the overall behavior? -- Which groups of users are driving the overall behavior? - -Mixpanel automatically compares the currently selected date period to the previous one. For example, if you are viewing the current week, the email will compare to the week before. - -### Interesting Segments in Retention - -View the top and bottom converting segments in your retention report by clicking the **Find interesting segments** button at the bottom of the retention chart. This feature is not currently available for Frequency Retention. - -![/10037069627156](/10037069627156.png) - -Rather than searching through multiple segment breakdowns to find significant data, this feature automatically identifies that data for you. Mixpanel combs through your event properties and cohorts, and show you which of those segments retain at a higher or lower rate than average. - -An email that breaks down the top and bottom retaining segments of your Retention report based on changes on retention rates is automatically sent after you click the button. - -### Interpret Email Results - -When your analysis email says “no interesting segments”, this means that none of the segments you analyzed were behaving significantly differently from the overall population at a large enough volume. To resolve this issue, try extending the date range of the report or try a different report. - -If the analysis request included dates in the past five days, and is sent from mobile SDK, data may be delayed and therefore not included at the time of the analysis. Likewise, the date window selected might still fall under conversion window, and more conversions have yet to come through. - -Results are sorted by taking into consideration the property, the number of users in the report, as well as the deviation from overall conversion or retention behavior to surface the most meaningful segments to you. - -## Query Time Sampling - -Query-time sampling allows you to query a subset of users and shorten the time it takes for a report to load results. The Insights, Funnels, Retention and Flows reports all support sampling at query time. - -This feature is available to enterprise customers with over 5 million [MTUs](/docs/admin/pricing-plans#mtu-calculation) or over 2 billion monthly events. - -### Enable or Disable Query Time Sampling - -Navigate to the report where you would like to enable or disable sampling at time of query. - -### Enable Sampling - -From the report in which you would like to use sampling, click the **lightning bolt** in the upper right corner of the query builder. - -![/13109650264596](/13109650264596.png) - -This will enable sampling on the report, and will be indicated by the lightning bolt symbol turning blue. The percentage of the total that is included in the query calculations will be indicated in the top right corner of the query builder. - -### Disable Sampling - -To turn off sampling, click the lightning bolt symbol in the upper right corner of the query builder again. - -The lightning bolt symbol will turn grey to indicate that sampling is disabled. - -### Query Time Sampling Calculation and Presentation - -Mixpanel will not sample, or drop, events at ingestion. Instead, Mixpanel will ingest all event data and sample at query time. This prevents the loss of important data, and therefore allows you to toggle sampling on and off depending on need. - -For example, if you have a need for iterative querying, then sampling will greatly speed up this process. When you build the proper query, you can turn off sampling and query the entire dataset. - -The following occurs when sampling is enabled: - -1. Mixpanel selects a uniformly random sample of users on which to run the analysis. -2. The sample size is 10% of the total population. -3. The report is generated using that subset of users. -4. Mixpanel up-samples the data by multiplying by the inverse of the sampling factor. This is done for [functions](/docs/reports/insights) such as totals and uniques. Functions that do not scale with users (average, min, max) will not be up-sampled. -5. The effect is that numbers should closely approximate results seen without sampling enabled. This works better as the number of users increases, particularly for customers with more than 5 million users. -6. Mixpanel adds an annotation to reports. - -### Saved Reports with Query Time Sampling - -If you save a report that uses query time sampling, then a version of the report *without* sampling is saved. This ensures that Boards and saved reports are computed on the entire dataset for high fidelity. - -## Query Result Caching - -Mixpanel stores the results from a report query in cache, and presents these results from cache when appropriate. This saves time when running a complicated query multiple times, and allows you to surface previously calculated results near-instantaneously. The date range of the query will adjust how Mixpanel presents results from the cache. - -- If the query date range is over 30 days, then the query results are cached for up to 24 hours. -- If the query date range is 30 days or under, then the query results are cached for up to 3 hours. -- If the query date range is 1 day, then the query results are cached for up to 15 minutes. - -You can see While this highlights the default cache behavior, you can always refresh a report to include the most current data. - -![/Cache_Update.png](/Cache_Update.png) - -You can also view when the most recent update was in Boards by hovering over report cards. - -![/Dashboard_Cache.png](/Dashboard_Cache.png) - -### Refreshing the Query Results Cache - -To refresh the query results cache, navigate to an Insights report and click the **Refresh** button at the top of the query builder. - -![/Refresh_Cache.png](/Refresh_Cache.png) - -To refresh query results cache in a Board, click the three dots in the top of the Board, and then click the **Refresh all cards** button. - -![/Dashboard_Refresh.png](/Dashboard_Refresh.png) - -If the cached result is less than 1 min old, we always serve from cache without running a new background query. - -## Event and Property Limitations - -While all reports in Mixpanel utilize your event data and properties to deliver insight into your business, not all reports can use all event types or properties. - -Reports use events and properties to target users, segment data, and filter data. This guide will clarify which reports can use which event types and properties. - -**Insights:** All event types and properties are available in Insights to break down and filter data. - -**Funnels:** Funnels can be calculated by unique or total events. All event types and properties are available to break down and filter data. - -**Retention:** Retention only counts total users, not unique. However, all event types and properties are available to filter data. - -**Signal:** Signal uses only event properties, not user profile properties. However, all event types are available to filter data. - -**Users:** All event types and properties are available in Users. - -## Downloading Reports from Mixpanel - -Users can download reports in three formats: - -- CSV -- PNG -- PDF - -### Breakdown Limits in Report Downloads - -Mixpanel maintains breakdown limits for CSV, PNG, and PDF report downloads. - -### CSV - -For property values that exceed 10,000, Mixpanel only returns the top 10,000 breakdowns of that property. Here’s an example CSV export of an Insights report. The first column contains the date of when each event was sent. The columns contain the event name and the rows contain the number of each event sent to Mixpanel. - -![/CSV-download.png](/CSV-download.png) - -### PNG and PDF - -PNG and PDF downloads display up to 30 segments in the Insights table, Insights bar, Retention table, and Retention line; and up to 12 segments for the Insights line. Here’s an example of a chart in PNG format. - -![/PNG-example.png](/PNG-example.png) - -### Downloading Reports - -To download Insights, Funnels, and Retention reports, click the "..." icon on the upper right corner of each report. - -#### Insights Download Menu - -![/Screen_Shot_2020-02-14_at_10.31.33_AM.png](/Screen_Shot_2020-02-14_at_10.31.33_AM.png) - -#### Funnels Download Menu - -![/Screen_Shot_2020-02-14_at_10.32.18_AM.png](/Screen_Shot_2020-02-14_at_10.32.18_AM.png) - -It is possible (only in the Funnels report) to download "CSV Trends", which downloads funnels by date. - -#### Retention Download Menu - -![/Screen_Shot_2020-02-14_at_10.32.36_AM.png](/Screen_Shot_2020-02-14_at_10.32.36_AM.png) - -## Undefined and Null Properties - -There are several reasons why you might see "undefined" in your properties list throughout Mixpanel reports when segmenting: - -- ***The specific property you’re segmenting by isn’t always sent along with the event you’re analyzing.*** For example, let’s say you’re segmenting the event “App Open” by the property “Account type” If there are instances where App Open fires without the Account type property getting sent with it, these will be categorized as “undefined” when you segment by Account type. Another common example is UTM parameters - “undefined” represents users who fired an event without any UTM in the URL that brought the user to your site. -- When segmenting an event by a User Profile property, ***you’ll see “undefined” if there are User Profile profiles that don’t contain that property or if the event was triggered by a user without a User Profile at all.*** For example, let’s say you’re segmenting the event “Song Play” by the User Profile property “Favorite Genre.” If there are profiles that have triggered Song Play but don’t have the Favorite Genre property, that value will be “undefined.” Triggers of Song Play by users without a User Profile will also show up under “undefined.” -- ***For geolocation data (City, Region, Country), the user’s IP couldn’t be mapped to a location, or their IP was not included with the request.*** For JavaScript implementations, City, Region, and Country are [default properties](https://help.mixpanel.com/hc/en-us/articles/115004613766-What-properties-do-Mixpanel-s-libraries-store-by-default-). However, if the IP address of the user is not in Mixpanel’s geolocation database and can’t be mapped to a city, region, or country, they will be “undefined” in reports. For server-side implementations, City, Region, and Country can be “undefined” if the IP address is not included with the request. [Read more about how Mixpanel maps IP to location.](/docs/privacy/protecting-user-data#disabling-geolocation) - -### Remove “undefined” & "null" values from reports - -If you don’t want to see “undefined” or "null" values in your report, you can remove them by: - -1. Unchecking the “undefined/null” box in the visualization legend. -2. Looking only at instances where the property in question “is set" - this will exclude values where you see "undefined" or "null": - -![image](https://github.com/mixpanel/docs/assets/2077899/1a2465e1-da8d-4fe4-937a-5753716129b3) - -3. Directly exclude undefined or null values from an Insights visualization by hitting the exclude action: - -![image](https://github.com/mixpanel/docs/assets/2077899/4d010827-cc4e-4a11-9716-cd3bfbaebadd) - - -### Troubleshooting Tips - -If you’re getting “undefined” property values but think you should not be, troubleshoot the issue using the Events page. Click on "Filter" in the top left to look at events coming in where the property in question “is not set.” You can then use this data to look at your code and figure out why some events are being fired without that property. - -![image](https://github.com/mixpanel/docs/assets/2077899/c028c2b1-160d-4c0b-ba9a-87b74aba9c42) diff --git a/pages/docs/features/attribution.mdx b/pages/docs/features/computed-properties.md similarity index 75% rename from pages/docs/features/attribution.mdx rename to pages/docs/features/computed-properties.md index 18a6a433ef..13f7faa3df 100644 --- a/pages/docs/features/attribution.mdx +++ b/pages/docs/features/computed-properties.md @@ -1,6 +1,41 @@ -# Attribution +# Computed Properties ## Overview +- Can see them easily in properties menu under "Computed" tag +- behavioral +- attribution +- duration +- reference funnels specific ones briefly + +## Behavioral Properties + +Behavioral properties allow you to use your user's activity and use it as a property in your other analysis. A behavioral property is a virtual property, meaning it's not a property that you are explicitly tracking, but a property that Mixpanel can compute and allow you to use in analysis. + +Behavioral properties can be used anywhere, most typically in filters and breakdowns. + +### Frequency per User + +After selecting this option, you must select an event to compute the frequency of. You can use this to segment your users by how many times they did an event, or use it to filter out users to only those who did an event a certain number of times. + +### Aggregate Property per User + +After select this option, you must select an event, and then a property on that event. Finally, you can choose an aggregation type for this property. You can use this to segment your users by this property aggregation. For example, you may want to filter only for users who have greater than 100 minutes of video watch time, or you may want to segment users by their watch time. + +### Time Range + +#### Per Interval + +In insights, the time in which this computation is done is on a per interval basis. For a line chart, that will be for each individual interval plotted on the chart. For bar, table and pie, this interval is the entire date range selected in the date picker. + +#### Between Steps + +In funnels, the behavioral property is computed in the time range between 2 steps in your funnel. You can specify which steps in the funnel this applies to. In the case of doing "Frequency per User", the event count does not include the events that make up the funnel itself, and **only** the events between the funnel steps. + +#### After Step 1 + +In retention, the behavioral property is computed in the chosen time range after the entry event, up until the retaining action. For example, there may be a 7 day window in which we're looking for an event, but if the retaining action happens before the 7 days are up, we no longer count an additional events. + +## Attribution Attribution helps teams attribute conversion credit to the touchpoints in a user journey, whether it's to the first or last touch (single-touch attribution models) or to multiple touchpoints using a multi-touch attribution model like U-shape or Linear. Let’s consider an example user journey: @@ -18,7 +53,7 @@ In this example, two touchpoints contribute to the successful conversion: the Fa - Using last touch model, the complete conversion can be attributed to the Instagram ad - Using first touch model, the complete conversion can be attributed to the Facebook ad -## Usage +### Usage ![Attribution.gif](/attribution.gif) @@ -35,7 +70,7 @@ Step 5 - If you want to include only certain channels or touchpoints in your att 👉🏽 NOTE: if you are running attribution predominantly on UTM_medium, UTM_source, UTM_campaign, make sure you’re tracking UTM parameters as event properties on every user touchpoint. If you use a Mixpanel js-sdk, we’ve updated our sdk to track utm parameters more effectively to support multi-touch attribution models. -## Attribution Models +### Attribution Models - First Touch - Gives 100% credit to the first touchpoint within the attribution lookback window - Last Touch - Gives 100% credit to the last touchpoint within the attribution lookback window @@ -47,7 +82,7 @@ If you use a Mixpanel js-sdk, we’ve updated our sdk to track utm parameters mo - Inverse J-shaped - Gives 60% credit to the first touchpoint, 20% credit to the last touchpoint, and divides the remaining 20% to any touch points in between. With 2 touchpoints, the credit is normalized (75%, 25%). With 6 touch points the middle 4 touch points would share the 20% (60%, 5%, 5%, 5%, 5%, 20%). - Custom - Customize the weightage to be given to the first and last touchpoint, and all other touchpoints in between based on your use-case. -## Glossary +### Attribution Glossary - **User journey:** Consists of touchpoints and the conversion event. It is possible for a conversion event to have no corresponding touchpoints (eg. utm parameters). In this case we consider it a ‘direct’ conversion - **Conversion**: The primary event you’re interested in analyzing with multi-touch attribution models. Typically some final value generating interaction such as “Signup” or “Upgrade” or “Payment”. @@ -55,9 +90,9 @@ If you use a Mixpanel js-sdk, we’ve updated our sdk to track utm parameters mo - **Attributed by property:** This is the property on a touchpoint event that we use for the attribution model. The canonical example is utm_source - **Lookback window:** The time window where a user's events with this attribution property are counted towards the calculation. The window ends when the conversion metric happens. -## Frequently Asked Questions +### Attribution FAQ -### How does Mixpanel compute attribution under the hood? +**How does Mixpanel compute attribution under the hood?** Please watch this video to better understand. @@ -69,7 +104,7 @@ Please watch this video to better understand. -### What does attribution on ‘unique users’ mean? +**What does attribution on ‘unique users’ mean?** We need one single conversion event which we can use to “qualify” a user unique. @@ -98,7 +133,7 @@ Some nuances to note ![image](/Attribution_uniques_2.png) -### What does filtering do in attribution? +**What does filtering do in attribution?** Once attribution is computed, filtering narrows total conversion events to only include/exclude those with the associated attribution property. @@ -137,3 +172,9 @@ NOTE: You can apply a filter on an attribution property only after an attributio - Step 1: Turn on Attribution analysis by going to the breakdown section and choosing `Attributed by..` and property `XYZ` - Step 2 (a): Once attribution model has been applied, go to the filter section and choose the computed property `Attributed by XXX`. You can apply an attribution filter only on the property used in the attribution breakdown - Step 2 (b): Once attribution model has been applied, click on the chart bar and filter/exclude the segments as needed + +## Duration +The duration property returns the duration between 2 instances of an event. This works best for events that occur continuously during a session such as Page View or Screen View. Users that did not track the same event again will appear in the "Did not convert" segment. + +#### Funnels-specific Computed Properties +The Funnel reports support two unique computed properties. The [Time to Convert](/docs/reports/funnels/measurements#time-to-convert) property returns the time in seconds needed to convert between funnels steps, and the [Property Sum](/docs/reports/funnels/measurements#property-sum) property allows you to sum up a numeric property as a user moves through funnel steps. diff --git a/pages/docs/features/custom-buckets.md b/pages/docs/features/custom-buckets.md new file mode 100644 index 0000000000..458361ccf4 --- /dev/null +++ b/pages/docs/features/custom-buckets.md @@ -0,0 +1,228 @@ +# Custom Buckets + +# Overview + +Custom buckets lets you group existing properties into meaningful segments on the fly. This is focused on enabling every person to answer common segmentation questions easily, quickly and in a low friction way. + +Example use-cases include: + +- Compare how the core markets are performing between US vs UK vs China vs all others +- Compare how many sign-ups are brought in by organic search vs Google ads vs social media channels together (Facebook, Twitter, LinkedIn) +- Compare # videos watched for users between ages 18-30 vs 30-40 or 40+ +- Compare # users based on duration of video watched: < 30, 30-60, 60-90 mins + +## Creating Custom Buckets + +Add a property in Breakdown, then select the **Customize Buckets** option from the overflow menu + +![/14342458665748](/14342458665748.png) + +Depending on your added property data type - string vs numeric, you will see a different custom buckets modal, designed based on the data-type use-cases **(more detail below)** + +Once you define your segment buckets, click **Apply.** Only then will the custom buckets reflect in the visualization. You will also see the custom buckets as an under-item on the property + +![/14342458667924](/14342458667924.png) + +To modify the segment buckets, click on the **under-item** and the custom buckets model will open. Once you’ve made the changes, click **Apply** + +To remove all grouping and revert to the default, open the custom buckets modal and click **Reset** + +### String property Use Cases + +**Use Case:** You want to compare # videos watched between core markets - North America, Europe & China + +Current: You have a property “Country” + +Goal: You want to group the countries into meaningful segments + +- Segment 1: North America: US & Canada +- Segment 2: Europe: UK, Germany, France, Netherlands, Italy +- Segment 3: China +- Segment 4: Rest of the World (everything but those above) + +Steps + +1. Add a breakdown - Country. Below is the default you’ll see + + ![/12828869626644](/12828869626644.png) + +2. Choose to bucket segments, by opening the custom buckets model and click Apply + - For each segment, choose the operator “is” and select one or more values + - “Rest of the World” is auto generated as **remaining values** + - To note — if two segments have the same value, the first segment will consider the value. Custom buckets are non-overlapping and sum up to 100% by definition + +![/14342715436052](/14342715436052.png) + +![/12828860042132](/12828860042132.png) + +**You can also re-name these segments to make them meaningful to you** + +1. On the same line of the segment, choose to rename it using the pencil icon +2. Click Apply after creating and naming your segments as desired + +![/14342752741140](/14342752741140.png) + +![/12828869956628](/12828869956628.png) + +### Numeric property Use Cases + +**Use Case:** You want to compare #users based on duration of video watched + +Current: You have a property “watch time (mins)” + +Goal: You want to distribute this in various ways + +- Use Case A: Evenly in 10 min groups for the range 50-100 mins +- Use Case B: Specific groups <10, 10-20, 20-50, 50-100, ≥100 +- Use Case C: Want to see all the durations as-is (No grouping) + +**Deep Dive: Use Case A**: Evenly in 10 min buckets for the range 50-100 mins + +1. Add a breakdown - “watch time (mins)” + - To note — every numeric property is **auto-bucketed into even sized buckets as the default** + - Here the default seems to be even buckets of 10 mins across the range + + ![/14342489051028](/14342489051028.png) + + ![/12828860268692](/12828860268692.png) + +2. Go to the overflow and open the custom buckets modal +3. Since looking for even buckets of “30 mins”, choose **Even Bucketing** +4. Modify the min and max values of the desired range, and the bucket size, and click apply + - To note — both a lower end and upper end bucket will be auto-generated to ensure your breakdown always adds up to 100% + - Here these buckets are <50 mins and ≥ 100 mins + + ![/14342575096724](/14342575096724.png) + + ![/12828860573204](/12828860573204.png) + + +**Deep Dive: Use Case B**: Specific groups <10, 10-20, 20-50, 50-100, ≥100 + +1. Open the custom buckets modal +2. Since looking for specific buckets with varied bucket ranges, choose **Varied Bucketing** +3. Enter the ‘segment’ break point values in each row and click apply. You can preview the bucket as you enter values in the line-item below + - To note — both a lower end and upper end bucket will be auto-generated to ensure your buckets always adds up to a 100% + +![/14342546138516](/14342546138516.png) + +![/12828860758676](/12828860758676.png) + +**Deep Dive: Use Case C:** Want to see all the durations as-is (No bucketing) + +1. Open the custom buckets modal +2. Since looking for “No bucketing”, choose **None —** This lays out all the numeric property values as-is + +![/14342547991956](/14342547991956.png) + +![/12833587659028](/12833587659028.png) + +### Typecasting property Use Cases + +**Use Case:** You want to identify #users of age 18 and age 60 since these are user ages where they change subscription plans (upgrade and downgrade respectively) + +Current: You have a property age (years) + +Goal: You want to group this in a meaningful way + +- Segment 1: Age 18 (potential to upgrade) +- Segment 2: Age 60 (potential to downgrade) +- Segment 3: Every other age + +Steps + +1. Add a breakdown age(years). By default this will add as a numeric property +2. Since you are looking for pin-pointed years and not creating number-ranges, this is a question more common to string property data type +3. Change **Data Type** of age(years) to String. Once changed you will see the type-casted property type as an under-item + - To note - only type-casted data types show as an under-item. If the data-type was the same as ingested, no under-item for data type will be seen + + ![/14342634016660](/14342634016660.png) + + ![/12833644608148](/12833644608148.png) + +4. Post changing data-type, open the custom buckets modal. This will now open a modal meant for string property data type +5. Follow steps as elaborated for String property use-case above, and achieve the goal + + ![/14342637801748](/14342637801748.png) + + ![/14342707763604](/14342707763604.png) + + ![/12833899595284](/12833899595284.png) + + +## FAQ + +- **Which reports does Custom Buckets work on?** + + This feature is available in the Insights, Funnels and Retention reports. + +- **Which property types does this support?** + + Custom Buckets work on String, Numeric and List data type + +- **Can I save a Custom Bucket**? + + No, you can’t save a custom bucket. If your custom bucket is something you or your team would like to re-use, we encourage you to instead create a [custom property](/docs/features/custom-properties#creating-a-custom-property). + +- **How is custom buckets different from [custom property](/docs/features/custom-properties)?** + + Custom buckets only supports the most common custom-property use-case of **`if else`** to create meaningful segments in a more simplistic UI, and a low lift way to enable quick ad-hoc exploration. You could get this same answer using custom property too, it would just be more effort and not as intuitive + +- **Can I create over-lapping segments like (US & UK) vs (US & Australia)?** + + No, breakdowns are fundamentally designed to sum up to 100%. To ensure your analysis is accurate, please create non-overlapping segments. + + If you really need to answer a question like this, the right way here is to create these as two metrics leveraging [inline filters](/docs/reports/overview) and NOT use breakdowns. + + ![/12834111393684](/12834111393684.png) + +- **What happens if I change data-type, can I still use custom buckets?** + + Yes you can as long as the data-type you’ve changed the property to is supported. + +- **Understanding the details:** + - **In Numeric: Can I change the operators on the upper and lower bound?** + + No, the operators have been fixed. The lower bound is always strictly greater than (≥) and the upper bound is just lesser than (<). If you are looking for more control on the operators, please create a [custom property](/docs/features/custom-properties#creating-a-custom-property). + + - **In String: Is (not set) included in (remaining values)?** + + No, (not set) is not included in remaining values + + - (remaining values): refers to ‘set’ values that just don’t fall into any of your defined segments + - (not set) refers to the events where a property value has not been set at tracking/ ingestion. For example a new video (MixFun) is has been added. But during tracking, you forget to send the name of this video. So the count of this video is being tracked, but it’s being associated to a property value (not set) vs (MixFun) + + More details can be found in [this help doc](/docs/features/advanced#undefined-and-null-properties) + + - **In Numeric: What is the difference between (not set) and (non-numeric values)?** + - (not set) as explained above for string refers to property values that have not been associated to any specific property value + - (non numeric values) refers to set values that have just been sent in as non-numeric data type. For example, you’re looking to track time spent and have coded that as a numeric property, but for some reason some values are tracked as “a”, or “b” which are not-numeric. +- **Some Common How-do-I(s)** + - **How do I know is set, (not set)?** + + (not set) is automatically computed and will always show up in the UI. You don’t have to select (not set) as a segment to know how many events fall in there. So only figure how would you like to segment your (set) values. + + ![/12834113971348](/12834113971348.png) + + - **How do I get "not contains" or "not equal to"?** + + These values will auto-generate under (remaining values). So just select what should be included + + For example — the (remaining values) below is not equal to US or India + + ![/12834082079380](/12834082079380.png) + + - **In Number: how do I get a bucket of just 0?** + + If you’re purely looking for just how many people have value “0”, we would encourage you to typecast this to a string property and get that. + + If you’re looking to get the count of 0, in reference to the other numeric buckets, go ahead and create a **Varied Bucketing** custom buckets modal + + - If the numeric values are integers: + - Choose Varied bucket values 0, 1, 2… + - This would generate buckets: <0, ≥0 & <1, ≥1 & <2, ≥2. + - ≥0 & <1 would be equal to bucket 0 + - If the numeric values are decimals: + - Choose Varied bucket values 0, 0.0001, 1, … + - This would generate buckets: <0, ≥0 & <0.0001, ≥0.0001 & <1, ≥1. + - ≥0 & <0.0001 would approximate to bucket 0 diff --git a/pages/docs/features/custom-events.md b/pages/docs/features/custom-events.md index f65f06eabf..05b8b167a8 100644 --- a/pages/docs/features/custom-events.md +++ b/pages/docs/features/custom-events.md @@ -20,6 +20,11 @@ You can create a custom event containing "Ad Conversion" and "Ad Impression," an 3. Select the events and properties you’d like to include. 4. Name your custom event, and click **Save**. +## Breakdown by Event Name +If you are analyzing any custom events, you can breakdown by the property "Event Name" to better understand which events inside of your Custom Event is contributing to your metrics. + +![image](https://github.com/mixpanel/docs/assets/2077899/dafe97ca-35a3-4dee-8285-41a115f0417d) + ## Edit and Delete Custom Events To view, edit, or delete any custom event, navigate to [Lexicon](/docs/data-governance/lexicon). diff --git a/pages/docs/features/query-sampling-and-caching.md b/pages/docs/features/query-sampling-and-caching.md new file mode 100644 index 0000000000..4859216ecd --- /dev/null +++ b/pages/docs/features/query-sampling-and-caching.md @@ -0,0 +1,75 @@ +# Query Sampling and Caching + +## Overview +Mixpanel has built-in features to improve the query performance of your project. This includes query-time sampling to shorten the querying duration and query result caching to pre-render results from a previous query. + +## Query Time Sampling + +Query-time sampling allows you to query a subset of users and shorten the time it takes for a report to load results. The Insights, Funnels, Retention and Flows reports all support sampling at query time. + +This feature is available to enterprise customers with over 5 million [MTUs](/docs/admin/pricing-plans#mtu-calculation) or over 2 billion monthly events. + +### Enable or Disable Query Time Sampling + +Navigate to the report where you would like to enable or disable sampling at time of query. + +### Enable Sampling + +From the report in which you would like to use sampling, click the **lightning bolt** in the upper right corner of the query builder. + +![/13109650264596](/13109650264596.png) + +This will enable sampling on the report, and will be indicated by the lightning bolt symbol turning blue. The percentage of the total that is included in the query calculations will be indicated in the top right corner of the query builder. + +### Disable Sampling + +To turn off sampling, click the lightning bolt symbol in the upper right corner of the query builder again. + +The lightning bolt symbol will turn grey to indicate that sampling is disabled. + +### Query Time Sampling Calculation and Presentation + +Mixpanel will not sample, or drop, events at ingestion. Instead, Mixpanel will ingest all event data and sample at query time. This prevents the loss of important data, and therefore allows you to toggle sampling on and off depending on need. + +For example, if you have a need for iterative querying, then sampling will greatly speed up this process. When you build the proper query, you can turn off sampling and query the entire dataset. + +The following occurs when sampling is enabled: + +1. Mixpanel selects a uniformly random sample of users on which to run the analysis. +2. The sample size is 10% of the total population. +3. The report is generated using that subset of users. +4. Mixpanel up-samples the data by multiplying by the inverse of the sampling factor. This is done for [functions](/docs/reports/insights) such as totals and uniques. Functions that do not scale with users (average, min, max) will not be up-sampled. +5. The effect is that numbers should closely approximate results seen without sampling enabled. This works better as the number of users increases, particularly for customers with more than 5 million users. +6. Mixpanel adds an annotation to reports. + +### Saved Reports with Query Time Sampling + +If you save a report that uses query time sampling, then a version of the report *without* sampling is saved. This ensures that Boards and saved reports are computed on the entire dataset for high fidelity. + +## Query Result Caching + +Mixpanel stores the results from a report query in cache, and presents these results from cache when appropriate. This saves time when running a complicated query multiple times, and allows you to surface previously calculated results near-instantaneously. The date range of the query will adjust how Mixpanel presents results from the cache. + +- If the query date range is over 30 days, then the query results are cached for up to 24 hours. +- If the query date range is 30 days or under, then the query results are cached for up to 3 hours. +- If the query date range is 1 day, then the query results are cached for up to 15 minutes. + +You can see While this highlights the default cache behavior, you can always refresh a report to include the most current data. + +![/Cache_Update.png](/Cache_Update.png) + +You can also view when the most recent update was in Boards by hovering over report cards. + +![/Dashboard_Cache.png](/Dashboard_Cache.png) + +### Refreshing the Query Results Cache + +To refresh the query results cache, navigate to an Insights report and click the **Refresh** button at the top of the query builder. + +![/Refresh_Cache.png](/Refresh_Cache.png) + +To refresh query results cache in a Board, click the three dots in the top of the Board, and then click the **Refresh all cards** button. + +![/Dashboard_Refresh.png](/Dashboard_Refresh.png) + +If the cached result is less than 1 min old, we always serve from cache without running a new background query. diff --git a/pages/docs/features/sessions.md b/pages/docs/features/sessions.md index 14e98c0c77..1b174d9a4c 100644 --- a/pages/docs/features/sessions.md +++ b/pages/docs/features/sessions.md @@ -1,5 +1,7 @@ # Sessions +> The Session feature in this page is not about the legacy autotrack events (App Sessions, $ae_session, etc.) sent by older versions of Mixpanel's mobile SDKs. + Use Sessions in Mixpanel to answer questions like: * How much time do users spend on my site per session? * What are the average number of pages visited per session? @@ -21,7 +23,8 @@ The way sessions are computed, and thus how the Session Start and Session End ev * **Property Based**: Provide a `session_id` property. All events that a user performs which have the same value for `session_id` are considered part of the same session. Project Admins or Owners can choose between one of these configurations in [Project Settings](https://mixpanel.com/settings/project). -Since Mixpanel computes sessions on the fly, you can change this definition at any time and it will apply historically. Read more [below](#session-computation-deep-dive). + +These virtual Session events are dynamically computed in the front end based on your provided session definition, so any reports that include these events will reflect the latest definition at the time of query. Note that these are not raw events that are stored in your project, meaning that they will not appear in your raw event export payload. ## Use Cases These use cases assume that you're tracking an event for each page a user views. You can do this automatically with our [Javascript SDK](/docs/quickstart/connect-your-data?sdk=javascript) or using a CDP like Segment. diff --git a/pages/docs/features/slack-integration.md b/pages/docs/features/slack-integration.md new file mode 100644 index 0000000000..686bacbd39 --- /dev/null +++ b/pages/docs/features/slack-integration.md @@ -0,0 +1,39 @@ +# Slack Integration + +## Overview + +Connect Mixpanel to your Slack workspace to help share reports with your colleagues faster. You can (1) set up an alert to send a message to a Slack channel, (2) set up a Board Subscription to send a message to a Slack channel, or (3) share previews of any Mixpanel report in Slack. + +To send an alert to a Slack Channel, see [Custom Alerts](/docs/features/alerts). To set up a board subscription to a Slack Channel, see [Advanced Board Functionality - Subscriptions](/docs/boards/advanced#board-subscriptions). + +The Mixpanel application for Slack will also automatically unfurl a preview of any Mixpanel link, including chart images for certain reports, making it easy for anyone in your Slack workspace to learn from your Mixpanel analyses. + +## Enable the Integration + +To enable the integration, log in to both Mixpanel and Slack, then click [here](https://mixpanel.com/slack/oauth?slack_v2=true) to authorize the slack workspace: + +![/Screen_Shot_2020-06-15_at_10.41.00_PM.png](/Screen_Shot_2020-06-15_at_10.41.00_PM.png) + +After clicking allow, you'll return to Mixpanel, where you'll see a success banner: + +![/Screen_Shot_2020-06-15_at_10.42.06_PM.png](/Screen_Shot_2020-06-15_at_10.42.06_PM.png) + +At this point, Mixpanel is a part of your Slack workspace, and any Mixpanel links you send in Slack will unfurl with metadata, and if applicable a chart preview. + +Once at least one member of your Mixpanel organization has set up the Mixpanel Integration for Slack for their account, any other members of the Slack workspace will see a prompt the next time they paste a Mixpanel link. The prompt will ask them to connect their own Mixpanel account to Slack as well. If they choose to do so, Slack will guide them through the authentication flow. Once they have successfully connected Mixpanel to Slack, any further links they paste in Slack will unfurl. + +## Using the Integration + +Once you've set up the integration, Mixpanel links pasted in Slack will unfurl. Most links will provide some basic link metadata, and links to Insights, Flows, Funnels, or Retention reports will also include a chart preview, for example: + +![/slack_app_demo.png](/slack_app_demo.png) + +## Slack Integration Permissions + +Mixpanel does not restrict who can enable the Mixpanel integration for Slack. However, your Slack workspace may limit who can perform the connection. + +After Mixpanel is connected to Slack, any Slack user who posts a Mixpanel link will be prompted to connect their own account, in order to unfurl report previews. By performing this integration at the user level, it ensures that only reports the user has access to will unfurl in Slack. + +## Slack Integration Privacy + +The Mixpanel app for Slack adheres to Mixpanel's overall privacy policy, available in full here: [https://mixpanel.com/legal/privacy-policy/](https://mixpanel.com/legal/privacy-policy/). diff --git a/pages/docs/reports.mdx b/pages/docs/reports.mdx new file mode 100644 index 0000000000..29c52ca5a5 --- /dev/null +++ b/pages/docs/reports.mdx @@ -0,0 +1,153 @@ +# Reports + +import { Card, Cards } from 'nextra/components' + +## Overview + +Reports are the basic unit of performing an analysis in Mixpanel. A report can be saved to a [Board](docs/boards/), and a board can contain many reports. Each report consists of one or more **metric** displayed using a **visualization**. + +Mixpanel has four core reports. + + + + + + + + +This article focuses on the common concepts across the core reports. Learn more about the [Query Builder here](/docs/reports/query-builder). + +## Metrics + +A metric is a some sort of **measurement** on a **behavior**. An example of a metric is "Unique Users" doing "Sign up", which is the measurement of unique users, on the behavior of "Sign up". + +## Behaviors + +A behavior is an event or a sequence of events performed within some criteria. A behavior can be something simple like a single event, or it can be something more complex like doing a multi step funnel. + +## Measurements + +A measurement is a selection on how to summarize behaviors. Depending on the behavior, certain measurements may be not be possible. For example, for a single event, you cannot measure the conversion rate of it. Some examples of measurements are: total events, unique users, total sessions, conversion rate, retention rate and aggregate property. The measurement is chosen at the bottom left area of the metric. + +![measurement](/report-measurement.png) + +## Visualizations + +In the top right, you can change the type of visualization for your report. The options available will depend on the type of report that you started with. In this case, we switched to a bar view, allowing us to see the total number of "Log In" across the entire time range, allowing us a summarized view that is easily scanned. + +![/Screen_Shot_2022-07-11_at_3.07.02_PM.png](/Screen_Shot_2022-07-11_at_3.07.02_PM.png) + +## Filters + +Filters are used to narrow events or behaviors that qualify for analysis. For example, you may want to only consider "Sign Up" events that came from Android. In this case you would you be filtering the "Sign Up" event to only include the "Sign Up" events where the property "Device" is equal to "Android". + +### Global Filters + +A global filter applies to the entire report. by properties or cohorts by clicking the **Filter** button. This will filter the results of the entire report to show only data with that property or cohort. + +![image](/global-filter.png) + +### Inline Filters + +An inline filter applies to one particular event in the report. + +Add a filter to your query by clicking on the **…** icon beside an event, profile, cohort, or step. + +![image](https://github.com/mixpanel/docs/assets/2077899/3e36bd7e-f5b8-462a-890c-bf396ff98f69) + +Then, select a property from the drop down list that appears and specify which values to filter. + +![image](https://github.com/mixpanel/docs/assets/2077899/c7cce429-3c9c-4759-8ea1-b09345fa0b4e) + +In Funnels, filtering a step by a particular property will limit the data you see in the funnel to events with that property value. + +You can choose multiple property filters for each item in your query. + +You can select whether you would like the query to match any of these filters, or all of the filters by clicking on **and/or** beside the filters. + +![image](https://github.com/mixpanel/docs/assets/2077899/9e3bcd31-2b12-48d1-b04f-cdda85dd2584) + +## Breakdowns + +Breakdown groups the results of your metrics in Insights, Funnels, Flows, or Retention reports by a property or cohort, allowing you to examine which properties or cohorts have a significant impact on your query. + +This feature is useful for determining if a group factor, such as browser type, is having an impact on the way users interact with your product. Breakdown will display counts, such as the number of events performed or the conversion rates with that property value. + +Select the **Breakdown** button, and select the property or cohort you want to breakdown your results by. + +![image](/report-breakdown.png) + +For cohorts, you will be shown groups of users both in and not in the cohort in your results. + +It is only possible to either group by properties or group by cohorts, but not both. + +## View Users + +View Users is a streamlined process for exploring the users contributing to a specific metric or point on a chart. By interacting with the chart, you can view a group of users experiencing friction or dig deep into which users are driving feature adoption. + +View Users can help you: + +- See the users contributing to any metric and view their recent activities & properties. +- Save these users as a cohort. +- Export these users to a CSV file. + +![/View_Users_Insights_gif.gif](/View_Users_Insights_gif.gif) + + +## Downloading Reports + +You can download reports in four formats: +- CSV +- PNG +- PDF +- Formatted API + +To download Insights, Funnels, and Retention reports, click the "..." icon on the upper right corner of each report. Note the [limitations on downloads](/docs/reports#report-exports). + +## Limits and Ordering + +### UI +In order to keep the interactive analysis experience snappy for projects of all sizes, we imposed limits on how many segments are returned back to the report (**visible limit**) and how many segments can be selected at a time for visualization (**selection limit**), as well as the number of segments selected by default (**default selection**). + +Here's the breakdown per report + visualization type: + +| Report Viz | Default Selection | Selection Limit | Visible Limit | +| --- | --- | --- | --- | +| Insights (bar) | 12 | 300 | 3000 | +| Insights (line) | 12 | 50 | 3000 | +| Retention | 6 | 12 | 200 | +| Funnels | 6 | 12 | 200 | + +Hover over your table of visible segments to check if your report has reached the segmentation limit. + +![image](https://github.com/mixpanel/docs/assets/2077899/3935993c-0410-46e4-a9d6-2d2dfb5313cd) + +### Report Exports +**CSV** - CSV export supports up to 50,000 breakdown segments. +**API** - The Query API supports up to 10,000 breakdown segments. +**PNG and PDF** - PNG and PDF export supports up to 30 segments in the Insights table, Insights bar, Retention table, and Retention line; and up to 12 segments for the Insights line. + +### Top Segments logic + +The way we pick the top segments differs according to the type of query. We choose the top segments based on the value shown in the second column. + +| Query type | How we select top segments | +| --- | --- | +| Total | Total number of occurrences of the chosen event | +| Unique | Number of unique users who performed the chosen event | +| Sum of property values | Sum of the chosen property | +| Min/max of property values | Lowest/highest value of the chosen property | +| Average | Number of events (or users) that contribute to the average | +| Median/Percentile/Distribution | Number of events (or users) that contribute to the distribution | +| Distinct count | Number of distinct values of the chosen property | +| DAU/WAU/MAU | Number of unique users | +| Sessions | Number of sessions that contain the chosen event | +| Funnels | Total number of times the first funnel step was completed | +| Retention | Total number of times the first event was completed | + + +## Saving to a Board + +When you are satisfied with the analysis, and decide that this is something that you are likely to revisit, Mixpanel recommends that you save the report to a [Board](/docs/boards/overview). You can do this by pressing "Save" in the top right and selecting the Board you would like to save to, or creating a new Board. Sharing and permissions are set at the Board level. Learn more about [Sharing and Permissions](/docs/boards/sharing-and-permission). + +![/Screen_Shot_2022-07-08_at_5.40.30_PM.png](/Screen_Shot_2022-07-08_at_5.40.30_PM.png) diff --git a/pages/docs/reports/_meta.json b/pages/docs/reports/_meta.json index b3c2b9c4ec..979c148a04 100644 --- a/pages/docs/reports/_meta.json +++ b/pages/docs/reports/_meta.json @@ -1,5 +1,5 @@ { - "overview": "Overview", + "query-builder": "Query Builder", "insights": "Insights", "funnels": "Funnels", "retention": "Retention", diff --git a/pages/docs/reports/flows.mdx b/pages/docs/reports/flows.mdx index 83b8699443..4f5eee1b25 100644 --- a/pages/docs/reports/flows.mdx +++ b/pages/docs/reports/flows.mdx @@ -64,223 +64,3 @@ Hover over a stage of the diagram to highlight it and see details of that sectio Select any blue node representing an event on the Sankey chart to highlight the most popular paths that led to or from that node. The selected node is indicated in a lighter blue. ![/Screen_Shot_2021-07-20_at_7.16.15_PM.png](/Screen_Shot_2021-07-20_at_7.16.15_PM.png) - -## Basic Features - -### Viewing More Steps - -By default, flows shows you the first 3 events performed by users after the selected event. If you wish to see what users did further along in the path, you can adjust the number of steps directly in the Sankey visualization as shown below. - -Use the "+" on the right of the visualization to add steps after your selected events of interest to see what paths your users took following these key events. - -![/Screen_Shot_2021-07-20_at_7.34.41_PM.png](/Screen_Shot_2021-07-20_at_7.34.41_PM.png) - -The "+" on the left of the visualization will add steps before the events you've added in the query builder. This will allow you to see what paths your users took that led up to these events of interest. - -![/Screen_Shot_2021-07-20_at_7.35.06_PM.png](/Screen_Shot_2021-07-20_at_7.35.06_PM.png) - -To add steps in larger quantities, you can adjust the number of steps directly in the query builder section as well. - -![/Screen_Shot_2021-07-20_at_7.40.10_PM.png](/Screen_Shot_2021-07-20_at_7.40.10_PM.png) - -### Multiple Anchor Steps - -You can add multiple steps in the query builder. - -![/Screen_Shot_2021-07-20_at_7.51.32_PM.png](/Screen_Shot_2021-07-20_at_7.51.32_PM.png) - -This allows you to examine flows between targeted events. The "+" on the left of the breakpoint line (marked with ≈) will show you the events that happened directly after the first anchored event. - -In the following example, Flows is showing the event that happened right after App Open before the made a Purchase. - -![/Screen_Shot_2021-07-20_at_7.52.07_PM.png](/Screen_Shot_2021-07-20_at_7.52.07_PM.png) - -Use the "+" on the right of the breakpoint line (marked with ≈) will show you the events that happened right before the later anchored event. - -For example, below Flows is showing the event that happened directly before a Purchase, but only after the user did App Open. - -![/Screen_Shot_2021-07-20_at_7.53.04_PM.png](/Screen_Shot_2021-07-20_at_7.53.04_PM.png) - -### Viewing More Event Flows - -By default, flows only shows you the top 3 events performed by users ordered by the number of users who performed them. Less common events performed by fewer users are combined into an "Other events" section. ([Click here](/docs/reports/flows). To view more events, simply right click the other events node and `Add a row of events`. - -![/Screen_Shot_2021-07-20_at_7.46.45_PM.png](/Screen_Shot_2021-07-20_at_7.46.45_PM.png) - -To expand a large number of steps at the same time, you can select the number of rows you want directly in the advanced settings - -![/Screen_Shot_2021-07-20_at_7.47.31_PM.png](/Screen_Shot_2021-07-20_at_7.47.31_PM.png) - -### Sankey Chart - -#### Selected Events - -These are significant moments in a users lifecycle around which you would like to explore user behavior (for example, you may wish to view what users do after a Sign Up event).  Selected events are picked in the query builder and are annotated with an alphabetical label (A, B, C) that is shown in the query builder and the sankey diagram. - -![/Screen_Shot_2021-07-20_at_7.20.39_PM.png](/Screen_Shot_2021-07-20_at_7.20.39_PM.png) - -In the above example, we picked two anchor events "Exit Tutorial" and "Experiment Started", and are viewing the events that were performed by users between them. - -#### Intermediate Events - -Once an event is selected, Mixpanel calculates the most common events performed by users immediately before or after the selected events. These intermediate events can match either regularly tracked events OR the most used custom events in your project. The icon will let you know at a glance the type of event being displayed. - -![/Screen_Shot_2021-07-20_at_7.27.00_PM.png](/Screen_Shot_2021-07-20_at_7.27.00_PM.png) - -In the above example, Install or Open is a custom event, while Experiment Started is a regular event. - -[Click here](/docs/reports/flows#custom-events-in-flows) to learn more about custom events in flows. - -#### Other Events - -At each step in the flow, Mixpanel by default displays the top 3 intermediate events performed by users ordered by the number of users who performed them at that step. The rest of the events performed are grouped into a single bar called "Other events". - -![/Screen_Shot_2021-07-20_at_7.28.39_PM.png](/Screen_Shot_2021-07-20_at_7.28.39_PM.png) - -#### Drop off - -“Drop-off” represents users who did not do any further events in the next step during the time period specified in the report, and therefore dropped out of the flow. Users are considered dropped off at future anchor steps selected in the query builder if they do not perform that particular anchor in the time period. - -![/Screen_Shot_2021-07-20_at_7.28.54_PM.png](/Screen_Shot_2021-07-20_at_7.28.54_PM.png) - -### Conversion Criteria - -#### Counting Method - -Your selected counting method determines how many times Mixpanel will count a particular user's activity. Mixpanel Flows can be calculated by uniques, totals, or sessions, the same as the Funnels report. - -By default, Flows calculations are based on **uniques**. To change to a different counting method, click on the word **Uniques** in the conversion criteria, and select between **totals or sessions** from the drop-down list. - -![/Screen_Shot_2021-12-15_at_10.16.00_AM.png](/Screen_Shot_2021-12-15_at_10.16.00_AM.png) - -**Uniques** -Unique flows count a single entry per user (determined by distinct_id). Each can do the first step only once, and this is on the first time they perform the Step A event in the date range. Even if a particular user completes the funnel multiple times in the date range, they will only be counted towards conversion once, and on the first time they entered in the span of the funnel. - -**Totals** -Totals flows count multiple entries per user.  Users can re-start the flow and every time a user starts the flow they are counted. Users may re-enter a totals flows only after they have exited their previous attempt. Users exit a flow in 3 ways: - -1. They complete the last required step in the flow -2. They fail to get to the last required step in the conversion window and time out, -3. They are excluded from the current flow by an exclusion step. - -**Sessions** -Sessions ensure every step in the flow is performed in the same session. Like totals flows, users will be allowed to re-start the flow in subsequent sessions. Learn more about Sessions [here](/docs/features/sessions). - -#### Conversion Window - -The Conversion Window determines how much time a user has to finish the last required step in the flow. By default, all customers have 30 days to complete a flow from the timestamp they perform the Step A event. To adjust this conversion window, click on the words **30 days** in the conversion criteria. You will be able to adjust both the unit of time and the amount. - -![/Screen_Shot_2021-12-15_at_11.12.25_AM.png](/Screen_Shot_2021-12-15_at_11.12.25_AM.png) - -The maximum amount of time you can choose for the conversion window is 366 days, or otherwise equivalent (12 months, 52 weeks, etc). - -#### Hold Property Constant - -Holding a property constant in flows requires that a user retain the same value of a given event property for an event to be considered part of the flow. - -For example, let's say your product is an e-commerce retail site, and you want to see flows between Add to Cart > Purchase as long as they purchased the same item - meaning they must be interacting with the same item in every step of the flow - you would hold the Item Name property constant. - -The way this is calculated depends on whether you have selected a counting method that does not allow users to re-enter the flow ("Uniques") or allows re-entry ("Totals" or "Sessions). - -- **Uniques:** When you select "Uniques" and hold a property constant, because users of this counting method only enter the flow once and on the first time they do the Step A event, Mixpanel will hold constant the property value from the first Step A event. -- **Totals or Sessions:** When you select "Totals" or "Sessions" and hold a property constant, since these counting methods allow users to re-enter the flow, Mixpanel will hold the property constant that is set with each new re-entry at the Step A event. - -To add a property constant to your flows, select the **Holding property constant** button in the conversion criteria section. - -![/Screen_Shot_2021-12-15_at_11.10.42_AM.png](/Screen_Shot_2021-12-15_at_11.10.42_AM.png) - -Some things to keep in mind are that you are only able to select event properties that apply to all of the required steps. Also, you can select multiple properties, but when you do ALL must be kept constant. - -## Advanced - -### Top Paths - -Another way to visualize your user flows is by "Top Paths", which condenses the flows down to unique paths on each row. This visualization is great for understanding the most common paths users take, though they may not be similar. In this case, since we want to understand the most common paths, choose Top Paths. Your report should look like this: - -In the top bar of the visualization, you will see the option to toggle between User Flows and Top Paths. - -![/Screen_Shot_2022-07-12_at_4.31.17_PM.png](/Screen_Shot_2022-07-12_at_4.31.17_PM.png) - -Top paths will show the 50 most common event sequences of up to the number of steps you had selected in the User Flow sankey visualization. - -![/Screen_Shot_2022-07-12_at_4.32.15_PM.png](/Screen_Shot_2022-07-12_at_4.32.15_PM.png) - -The total percentage of users who reached the ultimate destination of a flow is indicated on the top left, while the total users that reached a given step and the percentage of users who converted from the previous step are indicated on the bottom of each step. - -![image](https://github.com/mixpanel/docs/assets/2077899/c36fcfb5-edbb-4374-86fc-6e3d3f5aa316) - -### Expand Event by Property - -You can choose to expand the results of your report by a particular property to see how that property may impact user flows. You can select multiple properties. For instance, what if I wanted to understand how the specific Purchase Type changes the most common flow that leads to a Purchase event? - -Click the **Expand** button, select an event, and then select a property under that event. - -![/psAq6XYr2B.gif](/psAq6XYr2B.gif) - -You can also expand on a specific event in the chart below by right clicking on an event and selecting **Expand by property**. - -![/6.png](/6.png) - -### Breakdown and Compare by Cohorts - -Beside the **Filter** button, select the **Breakdown** button to select one or more cohorts from the drop-down list. You will be shown both users in and not in the cohort. - -![/Screen_Shot_2021-07-20_at_5.42.21_PM.png](/Screen_Shot_2021-07-20_at_5.42.21_PM.png) - -If you have selected multiple cohorts, the chart below will be broken down by those cohorts. Cohorts will appear in the chart in different colors, making it easy to follow the paths the cohorts took in your flows. - -In the following example, the cohorts “Android Users” and “iPhone Users” are being compared. As shown in the Legend on the left of the chart, “iPhone Users” are indicated in purple, “Android Users” in orange. - -![/Screen_Shot_2021-07-20_at_5.42.31_PM.png](/Screen_Shot_2021-07-20_at_5.42.31_PM.png) - -To see the percentage breakdowns of these cohorts in more detail, click on a node to highlight the strongest path to that node. The box that pops up shows the percentage of each cohort that followed that path. - -In the following example, of the users that reached this Exit Tutorial event, 22.2% of users are iPhone users, 77.8% of users are Android users. - -![/Screen_Shot_2021-07-20_at_5.42.41_PM.png](/Screen_Shot_2021-07-20_at_5.42.41_PM.png) - -### Hide Events - -You can choose to hide events from the flows report to simplify and clarify the results. This is useful if you have common events that add noise because they are not relevant to the workflow you are examining. - -Click the **Hide Events** button at the top of the chart and check any events you want to hide from the query, then click **Apply**. - -![/Screen_Shot_2021-07-20_at_5.45.22_PM.png](/Screen_Shot_2021-07-20_at_5.45.22_PM.png) - -You can also choose to hide a specific event from the flow by right clicking on it in the Flows chart. - -![/Screen_Shot_2021-07-20_at_5.45.58_PM.png](/Screen_Shot_2021-07-20_at_5.45.58_PM.png) - -### Custom Events in Flows - -#### Custom events as start/end events - -You may pick custom events as the starting or ending events directly in the query. For custom events that are composed of multiple events, paths consisting of either event are combined into a single flow. - -#### Custom events as intermediate events - -Mixpanel automatically considers the most used and common custom events in your project, displaying them in intermediate steps instead of showing the underlying events. When a custom event is shown instead of the underlying event, it is annotated with the custom event icon to indicate that the event displayed is a custom event. - -![/Screen_Shot_2021-07-20_at_7.04.29_PM.png](/Screen_Shot_2021-07-20_at_7.04.29_PM.png) - -Mixpanel uses the following criteria to decide which custom events are shown in user flows: - -1. Custom events that are shared with all users in the projects are the only ones picked to be shown in flows right now -2. Only the 50 most frequently queried custom events in the project are used in flows analysis. -3. If custom events have overlapping definitions (e.g. both custom events operate on the same event), we will choose the more frequently queried custom event to show in the report. - -#### Expanding custom events - -You may also expand custom events by event name to view the underlying events if required. - -![/Screen_Shot_2021-07-30_at_1.21.26_PM.png](/Screen_Shot_2021-07-30_at_1.21.26_PM.png) - -#### Disabling custom events - -You can disable custom events for flows by toggling the Show Custom Events in the dropdown menu below. Custom events that have been manually chosen as steps in the flow will continue to show up, but no other other custom events will be shown. - -![/Screen_Shot_2021-10-29_at_10.48.22_AM__1_.png](/Screen_Shot_2021-10-29_at_10.48.22_AM__1_.png) - -### Exclusion Steps - -You can add exclusion steps, which exclude users who did a particular step. This is useful digging into a particular view, for example to explore the 2nd most popular path taken. diff --git a/pages/docs/reports/flows/_meta.json b/pages/docs/reports/flows/_meta.json new file mode 100644 index 0000000000..d4518b4e28 --- /dev/null +++ b/pages/docs/reports/flows/_meta.json @@ -0,0 +1,6 @@ +{ + "anchor-events": "Anchor Events", + "visualizations": "Visualizations", + "flows-conversion-crietria": "Flows Conversion Criteria", + "flows-breakdown": "Flows Breakdown" +} diff --git a/pages/docs/reports/flows/anchor-events.md b/pages/docs/reports/flows/anchor-events.md new file mode 100644 index 0000000000..19f1b191dc --- /dev/null +++ b/pages/docs/reports/flows/anchor-events.md @@ -0,0 +1,32 @@ +# Anchor Events + +## Overview +Events are the basic building block of a Flows report. Place an anchor event into your Flows report to learn what actions your users take before/after the event. + +## Multiple Anchor Events + +You can add multiple anchor events in the query builder. + +![/Screen_Shot_2021-07-20_at_7.51.32_PM.png](/Screen_Shot_2021-07-20_at_7.51.32_PM.png) + +This allows you to examine flows between targeted events. The "+" on the left of the breakpoint line (marked with ≈) will show you the events that happened directly after the first anchored event. + +In the following example, Flows is showing the event that happened right after App Open before the made a Purchase. + +![/Screen_Shot_2021-07-20_at_7.52.07_PM.png](/Screen_Shot_2021-07-20_at_7.52.07_PM.png) + +Use the "+" on the right of the breakpoint line (marked with ≈) will show you the events that happened right before the later anchored event. + +For example, below Flows is showing the event that happened directly before a Purchase, but only after the user did App Open. + +![/Screen_Shot_2021-07-20_at_7.53.04_PM.png](/Screen_Shot_2021-07-20_at_7.53.04_PM.png) + +## Custom Events in Flows + +You may pick [custom events](/docs/features/custom-events) as the starting or ending anchor events directly in the query. For custom events that are composed of multiple events, paths consisting of either event are combined into a single flow. + +### Disabling custom events + +You can disable custom events for flows by toggling the Show Custom Events in the dropdown menu below. Custom events that have been manually chosen as steps in the flow will continue to show up, but no other other custom events will be shown. + +![/Screen_Shot_2021-10-29_at_10.48.22_AM__1_.png](/Screen_Shot_2021-10-29_at_10.48.22_AM__1_.png) diff --git a/pages/docs/reports/flows/flows-breakdown.md b/pages/docs/reports/flows/flows-breakdown.md new file mode 100644 index 0000000000..ee5a487953 --- /dev/null +++ b/pages/docs/reports/flows/flows-breakdown.md @@ -0,0 +1,44 @@ +# Flows Breakdown + +## Overview +Flows report is an exploratory report where the events that are returned in the flows are often unpredictable. For this reason, standard property breakdown is not used for this report, but there are other ways to segment your flows. + +## Breakdown by Cohorts + +Beside the **Filter** button, select the **Breakdown** button to select one or more cohorts from the drop-down list. You will be shown both users in and not in the cohort. + +![/Screen_Shot_2021-07-20_at_5.42.21_PM.png](/Screen_Shot_2021-07-20_at_5.42.21_PM.png) + +If you have selected multiple cohorts, the chart below will be broken down by those cohorts. Cohorts will appear in the chart in different colors, making it easy to follow the paths the cohorts took in your flows. + +In the following example, the cohorts “Android Users” and “iPhone Users” are being compared. As shown in the Legend on the left of the chart, “iPhone Users” are indicated in purple, “Android Users” in orange. + +![/Screen_Shot_2021-07-20_at_5.42.31_PM.png](/Screen_Shot_2021-07-20_at_5.42.31_PM.png) + +To see the percentage breakdowns of these cohorts in more detail, click on a node to highlight the strongest path to that node. The box that pops up shows the percentage of each cohort that followed that path. + +In the following example, of the users that reached this Exit Tutorial event, 22.2% of users are iPhone users, 77.8% of users are Android users. + +![/Screen_Shot_2021-07-20_at_5.42.41_PM.png](/Screen_Shot_2021-07-20_at_5.42.41_PM.png) + +## Breakdown by Conversion + +If your flows have multiple anchor events, you can breakdown by Conversion as a computed property to segment your user event flows based on whether they converted or dropped off between the anchor events. + +## Expand Event by Property + +You can choose to expand the results of your report by a particular property to see how that property may impact user flows. You can select multiple properties. For instance, what if I wanted to understand how the specific Purchase Type changes the most common flow that leads to a Purchase event? + +Click the **Expand** button, select an event, and then select a property under that event. + +![/psAq6XYr2B.gif](/psAq6XYr2B.gif) + +You can also expand on a specific event in the chart below by right clicking on an event and selecting **Expand by property**. + +![/6.png](/6.png) + +### Expanding custom events + +If your report includes [custom events](/docs/features/custom-events/), you may expand custom events by event name to view the underlying events if required. + +![/Screen_Shot_2021-07-30_at_1.21.26_PM.png](/Screen_Shot_2021-07-30_at_1.21.26_PM.png) diff --git a/pages/docs/reports/flows/flows-conversion-criteria.md b/pages/docs/reports/flows/flows-conversion-criteria.md new file mode 100644 index 0000000000..b76715bd2b --- /dev/null +++ b/pages/docs/reports/flows/flows-conversion-criteria.md @@ -0,0 +1,54 @@ +# Flows Conversion Criteria + +## Overview +You can configure your Flows report conversion criteria to determine how your users will enter your flows. + +## Counting Method + +Your selected counting method determines how many times Mixpanel will count a particular user's activity. Mixpanel Flows can be calculated by uniques, totals, or sessions, the same as the Funnels report. + +By default, Flows calculations are based on **uniques**. To change to a different counting method, click on the word **Uniques** in the conversion criteria, and select between **totals or sessions** from the drop-down list. + +![/Screen_Shot_2021-12-15_at_10.16.00_AM.png](/Screen_Shot_2021-12-15_at_10.16.00_AM.png) + +**Uniques** +Unique flows count a single entry per user (determined by distinct_id). Each can do the first step only once, and this is on the first time they perform the Step A event in the date range. Even if a particular user completes the funnel multiple times in the date range, they will only be counted towards conversion once, and on the first time they entered in the span of the funnel. + +**Totals** +Totals flows count multiple entries per user.  Users can re-start the flow and every time a user starts the flow they are counted. Users may re-enter a totals flows only after they have exited their previous attempt. Users exit a flow in 3 ways: + +1. They complete the last required step in the flow +2. They fail to get to the last required step in the conversion window and time out, +3. They are excluded from the current flow by an exclusion step. + +**Sessions** +Sessions ensure every step in the flow is performed in the same session. Like totals flows, users will be allowed to re-start the flow in subsequent sessions. Learn more about Sessions [here](/docs/features/sessions). + +## Conversion Window + +The Conversion Window determines how much time a user has to finish the last required step in the flow. By default, all customers have 30 days to complete a flow from the timestamp they perform the Step A event. To adjust this conversion window, click on the words **30 days** in the conversion criteria. You will be able to adjust both the unit of time and the amount. + +![/Screen_Shot_2021-12-15_at_11.12.25_AM.png](/Screen_Shot_2021-12-15_at_11.12.25_AM.png) + +The maximum amount of time you can choose for the conversion window is 366 days, or otherwise equivalent (12 months, 52 weeks, etc). + +## Hold Property Constant + +Holding a property constant in flows requires that a user retain the same value of a given event property for an event to be considered part of the flow. + +For example, let's say your product is an e-commerce retail site, and you want to see flows between Add to Cart > Purchase as long as they purchased the same item - meaning they must be interacting with the same item in every step of the flow - you would hold the Item Name property constant. + +The way this is calculated depends on whether you have selected a counting method that does not allow users to re-enter the flow ("Uniques") or allows re-entry ("Totals" or "Sessions). + +- **Uniques:** When you select "Uniques" and hold a property constant, because users of this counting method only enter the flow once and on the first time they do the Step A event, Mixpanel will hold constant the property value from the first Step A event. +- **Totals or Sessions:** When you select "Totals" or "Sessions" and hold a property constant, since these counting methods allow users to re-enter the flow, Mixpanel will hold the property constant that is set with each new re-entry at the Step A event. + +To add a property constant to your flows, select the **Holding property constant** button in the conversion criteria section. + +![/Screen_Shot_2021-12-15_at_11.10.42_AM.png](/Screen_Shot_2021-12-15_at_11.10.42_AM.png) + +Some things to keep in mind are that you are only able to select event properties that apply to all of the required steps. Also, you can select multiple properties, but when you do ALL must be kept constant. + +## Exclusion Steps + +You can add exclusion steps, which exclude users who did a particular step. This is useful digging into a particular view, for example to explore the 2nd most popular path taken. diff --git a/pages/docs/reports/flows/visualizations.md b/pages/docs/reports/flows/visualizations.md new file mode 100644 index 0000000000..cd225cb383 --- /dev/null +++ b/pages/docs/reports/flows/visualizations.md @@ -0,0 +1,102 @@ +# Visualizations + +## Overview + +The Flows report provides a User Flows sankey chart and a Top Path chart to help you understand the events flow of your users. + +## Sankey Chart + +### Selected Events + +These are significant moments in a users lifecycle around which you would like to explore user behavior (for example, you may wish to view what users do after a Sign Up event).  Selected events are picked in the query builder and are annotated with an alphabetical label (A, B, C) that is shown in the query builder and the sankey diagram. + +![/Screen_Shot_2021-07-20_at_7.20.39_PM.png](/Screen_Shot_2021-07-20_at_7.20.39_PM.png) + +In the above example, we picked two anchor events "Exit Tutorial" and "Experiment Started", and are viewing the events that were performed by users between them. + +### Intermediate Events + +Once an event is selected, Mixpanel calculates the most common events performed by users immediately before or after the selected events. These intermediate events can match either regularly tracked events OR the most used custom events in your project. The icon will let you know at a glance the type of event being displayed. + +![/Screen_Shot_2021-07-20_at_7.27.00_PM.png](/Screen_Shot_2021-07-20_at_7.27.00_PM.png) + +In the above example, Install or Open is a [custom event](/docs/features/custom-events/), while Experiment Started is a regular event. + +### Custom events as intermediate events + +Mixpanel automatically considers the most used and common custom events in your project, displaying them in intermediate steps instead of showing the underlying events. When a custom event is shown instead of the underlying event, it is annotated with the custom event icon to indicate that the event displayed is a custom event. + +![/Screen_Shot_2021-07-20_at_7.04.29_PM.png](/Screen_Shot_2021-07-20_at_7.04.29_PM.png) + +Mixpanel uses the following criteria to decide which custom events are shown in user flows: + +1. Custom events that are shared with all users in the projects are the only ones picked to be shown in flows right now +2. Only the 50 most frequently queried custom events in the project are used in flows analysis. +3. If custom events have overlapping definitions (e.g. both custom events operate on the same event), we will choose the more frequently queried custom event to show in the report. + +### Other Events + +At each step in the flow, Mixpanel by default displays the top 3 intermediate events performed by users ordered by the number of users who performed them at that step. The rest of the events performed are grouped into a single bar called "Other events". + +![/Screen_Shot_2021-07-20_at_7.28.39_PM.png](/Screen_Shot_2021-07-20_at_7.28.39_PM.png) + +### Drop off + +“Drop-off” represents users who did not do any further events in the next step during the time period specified in the report, and therefore dropped out of the flow. Users are considered dropped off at future anchor steps selected in the query builder if they do not perform that particular anchor in the time period. + +![/Screen_Shot_2021-07-20_at_7.28.54_PM.png](/Screen_Shot_2021-07-20_at_7.28.54_PM.png) + +### View More Events + +By default, flows only shows you the top 3 events performed by users ordered by the number of users who performed them. Less common events performed by fewer users are combined into an "Other events" section. ([Click here](/docs/reports/flows). To view more events, simply right click the other events node and `Add a row of events`. + +![/Screen_Shot_2021-07-20_at_7.46.45_PM.png](/Screen_Shot_2021-07-20_at_7.46.45_PM.png) + +To expand a large number of steps at the same time, you can select the number of rows you want directly in the advanced settings + +![/Screen_Shot_2021-07-20_at_7.47.31_PM.png](/Screen_Shot_2021-07-20_at_7.47.31_PM.png) + + +## Top Paths + +Another way to visualize your user flows is by "Top Paths", which condenses the flows down to unique paths on each row. This visualization is great for understanding the most common paths users take, though they may not be similar. In this case, since we want to understand the most common paths, choose Top Paths. Your report should look like this: + +In the top bar of the visualization, you will see the option to toggle between User Flows and Top Paths. + +![/Screen_Shot_2022-07-12_at_4.31.17_PM.png](/Screen_Shot_2022-07-12_at_4.31.17_PM.png) + +Top paths will show the 50 most common event sequences of up to the number of steps you had selected in the User Flow sankey visualization. + +![/Screen_Shot_2022-07-12_at_4.32.15_PM.png](/Screen_Shot_2022-07-12_at_4.32.15_PM.png) + +The total percentage of users who reached the ultimate destination of a flow is indicated on the top left, while the total users that reached a given step and the percentage of users who converted from the previous step are indicated on the bottom of each step. + +![image](https://github.com/mixpanel/docs/assets/2077899/c36fcfb5-edbb-4374-86fc-6e3d3f5aa316) + +## View More Steps + +By default, flows shows you the first 3 events performed by users after the selected event. If you wish to see what users did further along in the path, you can adjust the number of steps directly in the Sankey visualization as shown below. + +Use the "+" on the right of the visualization to add steps after your selected events of interest to see what paths your users took following these key events. + +![/Screen_Shot_2021-07-20_at_7.34.41_PM.png](/Screen_Shot_2021-07-20_at_7.34.41_PM.png) + +The "+" on the left of the visualization will add steps before the events you've added in the query builder. This will allow you to see what paths your users took that led up to these events of interest. + +![/Screen_Shot_2021-07-20_at_7.35.06_PM.png](/Screen_Shot_2021-07-20_at_7.35.06_PM.png) + +To add steps in larger quantities, you can adjust the number of steps directly in the query builder section as well. + +![/Screen_Shot_2022-07-11_at_3.19.59_PM.png](/Screen_Shot_2022-07-11_at_3.19.59_PM.png) + +## Hide Events + +You can choose to hide events from the flows report to simplify and clarify the results. This is useful if you have common events that add noise because they are not relevant to the workflow you are examining. + +Click the **Hide Events** button at the top of the chart and check any events you want to hide from the query, then click **Apply**. + +![/Screen_Shot_2021-07-20_at_5.45.22_PM.png](/Screen_Shot_2021-07-20_at_5.45.22_PM.png) + +You can also choose to hide a specific event from the flow by right clicking on it in the Flows chart. + +![/Screen_Shot_2021-07-20_at_5.45.58_PM.png](/Screen_Shot_2021-07-20_at_5.45.58_PM.png) diff --git a/pages/docs/reports/funnels.mdx b/pages/docs/reports/funnels.mdx index bf46e80b78..35616bbbd8 100644 --- a/pages/docs/reports/funnels.mdx +++ b/pages/docs/reports/funnels.mdx @@ -63,402 +63,6 @@ You can visualize your metric in a variety of ways. Mixpanel allows you to choos ![/funnels_beta_5.png](/funnels_beta_5.png) -## Advanced - -### Conversion Criteria - -

- -

- -#### Conversion Window - -The Conversion Window determines how much time a user has to convert through all steps of the funnel after entering it. - -By default, all customers have 30 days to complete a funnel from the timestamp they perform the Step 1 event. To adjust this conversion window, click on the words **30 days** in the conversion criteria. You will be able to adjust both the unit of time and the amount. - -![/Screen_Shot_2021-12-15_at_11.12.25_AM.png](/Screen_Shot_2021-12-15_at_11.12.25_AM.png) - -The maximum amount of time you can choose for the conversion window is 366 days, or otherwise equivalent (12 months, 52 weeks, etc). For session-based conversion windows, the maximum is 1 session. - -Keep in mind that the conversion window starts on the first instance of the Step 1 event per funnel entry, and will not be updated by later instances of the same event in the same funnel trial. - -For example, let's assume a funnel with the following criteria: A → B → C, conversion window of one hour - -If the user does A at 1pm and then A again at 1:30pm, before doing B at 1:45pm and C at 2:15pm, they would count as converting to B, but will not be counted as completing the entire funnel to C. This is because 1pm to 2:15pm is greater than one hour. The conversion window for a given funnel trial starts with the first instance of A and is not reset by later instances of A in the same trial. B and C need to be completed within the conversion window from the first instance of A to be counted as conversions. - -#### Ordering - -The order control determines how much flexibility there can be to the sequence of your user's actions to be counted as a conversion. - -By default, funnels are based on a **specific order**. To change order designation, click on the words **Advanced** next to Conversion Criteria, and toggle on **Any Order** from the drop-down list. - -![/Screen_Shot_2021-12-15_at_10.20.13_AM.png](/Screen_Shot_2021-12-15_at_10.20.13_AM.png) - -**Specific Order** - -Specific Order Funnels require the user to complete each of the funnel steps in the order laid out to be counted as a conversion from one step to another. In other words, Step 1 must be completed before Step 2, which must be completed before Step 3, and so on. The user can engage in other actions in between funnel steps - including additional occurrences of the actions listed as funnels steps - but they will only be counted as converted if they complete all the funnel steps in order. - -To illustrate with an example, let's say a specific order funnel has steps: A, B, C, D, E - -1. The customer does steps A -> B -> C -> D -> E in exact order. Mixpanel counts this as a conversion. -2. The customer does steps A -> B -> ***F*** -> C -> D -> E. Mixpanel counts this as a conversion. Users can do additional actions in between funnels steps and still convert. -3. The customer does steps A -> B -> ***D*** -> C -> D -> E. Mixpanel counts this as a conversion. Even though the customer did D before the first time they did C, they will continue to convert because they eventually did a D after C. -4. The customer does steps A -> B -> C -> E. Mixpanel will not count this as a full conversion, and the customer will drop off after step C. The customer's completion of step E is excluded from the funnel because step D did not occur. - -**Any Order** - -In Any Order Funnels, users can complete unanchored funnel steps in any particular sequence and still convert. This type of funnel is most useful in situations where a user must complete all actions to be considered converted, but the exact order is not important. - -A good example of this could be a job application flow, where a user must input multiple pieces of information (their name, email address, current job title, credentials, references, cover letter, resume, etc.) in order to complete the form and submit their application, but they can provide all this information in any order they'd like and still proceed towards converting. - -To switch to **Any Order**, expand the "Advanced" menu in the Conversion Criteria and toggle on "Any Order". - -![/Screen_Shot_2022-07-12_at_3.35.33_PM.png](/Screen_Shot_2022-07-12_at_3.35.33_PM.png) - -When you switch to **Any Order,** you have the option to anchor specific steps in your funnel by clicking on the step number. - -![/CleanShot_2021-12-15_at_11.03.46.gif](/CleanShot_2021-12-15_at_11.03.46.gif) - -A step will either appear with a number beside it, indicating where it must fall in the funnel, or with an asterix (\*), indicating that it can be performed in any order before the next anchored step. - -**Example**: - -![/Untitled_Diagram.jpg](/Untitled_Diagram.jpg) - -In the above example, Steps 1, 4, and 6 must occur as the 1st, 4th, and 6th steps the user performs.Any of the * steps can occur at any time within those boundaries. - -#### Hold Property Constant - -Holding a property constant in a funnel requires that a user retains the same value for a given event property for each step in order to convert. In other words, a user must not only perform the funnel events in the order you specified, but also perform these events with the same property value. - -For example, let's say your product is an e-commerce retail site, and you have a three-step funnel of Browse > Add to Cart > Purchase. If you want to examine the conversion of users through this funnel that browse, add to cart, and purchase the same item - meaning that they cannot convert if they don't complete each step with the same item - you would hold the Item Name property constant. - -The way this is counted depends on whether you have selected a counting method that does not allow users to re-enter the funnel ("Uniques") or allows re-entry ("Totals" or "Sessions). - -- **Uniques:** When you select "Uniques" and hold a property constant, because users of this counting method only enter the funnel once and on the first time they do the Step 1 event, Mixpanel will hold constant the property value from the first Step 1 event. -- **Totals or Sessions:** When you select "Totals" or "Sessions" and hold a property constant, since these counting methods allow users to re-enter the funnel, Mixpanel will hold the property constant that is set with each new re-entry at the Step 1 event. - -To add a property constant to your funnel, expand the "Advanced" menu in the Conversion Criteria and click on "Holding property constant". - -![/Screen_Shot_2021-12-15_at_11.10.42_AM.png](/Screen_Shot_2021-12-15_at_11.10.42_AM.png) - -Some things to keep in mind are that you are only able to select event properties that apply to all of the events in your funnel. Also, you can select multiple properties, but when you do ALL must be kept constant. A maximum of 3 properties can be held constant at the same time. - -### Exclusion Steps (Exclude users who did...) - -Exclusion steps operate as a "did not do" filter for funnels. This provides the ability to create a funnel where, for example, you look for users that did event A, then event B, did not do event C, but then continue to do D. Note that the users are excluded at that point in the funnel. So in the previous example a user that did event C would still be counted in the funnel as having A and B, but they would not qualify in the funnel for event D, by virtue of having done event C. - -At the "Conversion Criteria" section, click on "Advanced" and then on "Exclude users who did...". A dropdown will appear to exclude a step from your funnel. - -![image](https://github.com/mixpanel/docs/assets/2077899/fc146839-6feb-4a40-a7b7-c17217bf6c7a) - -Select an event from the list and choose whether you would like the event to be excluded between all steps, or between specific steps. - -![image](https://github.com/mixpanel/docs/assets/2077899/d1c95913-42ca-45ba-9605-5cce51534e48) - -Click the **Filter icon** beside the step to filter that event by an event or user profile property. - -![image](https://github.com/mixpanel/docs/assets/2077899/ab63bef8-3d64-4b4b-97ed-392811e185ac) - -For example, if your product was an e-commerce retail company and you want to understand if users who browse for additional products between adding something to their cart and checking out are less likely to complete a purchase. To answer this question, you could create a funnel with three steps: - -Event 1: Browse product - -Event 2: Add to Cart - -Event 3: Purchase - -You can exclude users who did another “Browse product” event between Event 2 and Event 3 to and see how that affects your funnel's conversion rate. - -Further example use cases: - -1. Evaluate whether a certain step done alone is beneficial to your flow. -2. Ensure that a conversion was NOT the result of another detour step being taken in between two key steps. - -Note: -1. An exclusion step can be placed between any steps in the funnel. It cannot be the first or last step. -2. An exclusion step does not prevent users for qualifying into the funnel up until the exclusion step. If you want users who did a particular event at any point excluded, use a cohort filter. -3. There may be any number of exclusion events between steps. -4. Exclusion steps have the same [two second grace period](/docs/reports/funnels#how-does-mixpanel-handle-simultaneous-events) as other steps in the funnel. - -### Saved Funnel Behaviors - -You can define a funnel behavior and save and share it. Press "Save as New" button to save your funnel behavior definition. You can change the name and add a description. - -![save funnel](/save-funnel-1.png) - -You can also load existing funnel definitions by clicking the name of funnel. - -![save funnel](/save-funnel-2.png) - -See more about saved behaviors [here](/docs/features/saved-behaviors). - -### Measurements - -You have a variety of options to measure your funnel behavior. - -| Measurement | Description | -| --- | --- | -| Conversion Rate | The rate at which funnels are completed for the selected steps of the funnel. The conversion rate can be based off of unique users, total funnel entries or sessions. | -| Unique Users | The number of users who completed the selected steps of the funnel; based on their first attempt at entering the funnel within the timeframe of the report. | -| Total Conversions | The total number of funnels that have reached the selected step of the funnel. This measurement allows for users to re-enter the funnel multiple times, if they exit the funnel by either fully converting or dropping out. | -| Total Sessions | The total number of unique users sessions that reached the selected step of the funnel | -| Time to Convert | Allows for selection of an aggregation: Average, Median, Percentile, Min and Max. Measures the aggregated time to convert for the selected steps of the funnel. [See more](#time-to-convert-measurement) | -| Property Sum | Sums up a chosen property value for each step of the funnel, and measures the total amount of the property converted for the selected step of the funnel. [See more](#property-sum) | - -#### Step Selection - -You can select which step of the funnel you would like to measure. By default this is set to All Steps. To change your step selection, press "All Steps" and choose the desired range. - -![step selection](/step-selection.png) - -When measuring "Unique Users", "Total Conversions" or "Total Sessions", you can select "Entering Funnel" in order to get a top of funnel count. Similarly, if you would like to get the bottom of funnel count, you choose "All Steps" or any other step range to get the bottom of funnel count for that step. - -### Time to Convert -#### Time to Convert Measurement - -![Time to Convert Measurements](/ttc-measurements.png) - -You can select a Time to Convert aggregation to see how quickly or slowly your funnel converts. You can see this as a summarized value by selecting "Metric" or "Bar" visualizations, or you can see it as a trend using the "Line" visualization. You can also see the time to convert for a particular chosen step selection. - -#### Time to Convert Breakdown - -Use the Time to Convert breakdown to see a distribution of time users took between any two steps in the funnel or all steps. The steps selected in the breakdown are independent of the step of the metric you are measuring, for example you can measure overall conversion rate broken down by Time to Convert between Steps 1 and 2. - -![/funnels_ttc_selection.png](/funnels_ttc_selection.png) - -![/funnels_ttc_step_selection.png](/funnels_ttc_step_selection.png) - -Time to Convert works like any other property in that you can filter to specific range of times or customize the bucketing of the breakdown. You cannot use it as a step filter as it is used to filter funnels which have been measured rather than changing the per step conversion window. - -![/funnels_ttc_filter.png](/funnels_ttc_filter.png) - -![/funnels_ttc_custom_buckets.png](/funnels_ttc_custom_buckets.png) - -You can can use this in combination with measuring total conversion to get a distribution of conversions, based on how long they took to convert. You can also use this to see how other metrics such as conversion rate are affected based on how quickly users convert on a particular step range. - -### Frequency - -Use the Frequency per User breakdown to see the number of times users performed an event between any two funnel steps. For example, see the number of times a user listened to a song between sign up and purchasing the song. - -![/funnels_frequency_per_user_selection.png](/funnels_frequency_per_user_selection.png) - -You can select the steps between which you want to measure frequency from the breakdown, this is different from the step you are deriving the metric from, for example you can measure overall conversion rate but breakdown by frequency of an event between Step 1 and 2. - -![/funnels_frequency_per_user_finished.png](/funnels_frequency_per_user_finished.png) - -Frequency per user works like any other numeric property in that you are able to filter to a specific range of frequencies or customize how it is bucketed. - -![/funnels_frquency_per_user_filter.png](/funnels_frquency_per_user_filter.png) - -![/frequency_per_user_custom_buckets.png](/frequency_per_user_custom_buckets.png) - -To measure the frequency of a particular funnel step between that step and the next one, use *Selected Step* from the event selection in the Frequency per user breakdown. If the user does not do the step again before the next one the frequency will be 0. - -![/funnels_frequency_per_user_selected_step.png](/funnels_frequency_per_user_selected_step.png) - -Similar to Frequency per User if you want to instead breakdown by an aggregation on an event property between steps, like the sum of video watched time between sign up and purchase you can use Aggregate Property per user. - -![/funnels_aggregate_property_per_user_select_aggregation.png](/funnels_aggregate_property_per_user_select_aggregation.png) - -![/funnels_aggregate_property_per_user_finished.png](/funnels_aggregate_property_per_user_finished.png) - -Note: The frequency breakdown will only count the events in between the chosen range. The event that original satisfied the funnel definition does not count towards the frequency between steps. If you get 0 in your breakdown, it means that that event did not occur again before the next step in the funnel. - -For example, if a user performs "Step 1 -> Step 2": -- Frequency: "0 times" --- there is no extra "Step 1" event, so it will be "0 times" - -For example, if a user performs "Step 1 -> Step 1 -> Step 2": -- Frequency: "1 time" --- we will count "Step 1 -> *Step 1* -> Step 2" - -### Property Sum - -This measurement type allows you to visualize revenue through a funnel. Instead of seeing how many users move through your flow, you can select an event property that exists on each step of the funnel. Mixpanel will sum up the total value of this property at each stage of the funnel and visualize the total ammount converted, or the dropoff at each step if "Funnel Steps" visualization is selected. - -**Note**: For many e-commerce flows, you will want to pair property sum with [hold property constant](/docs/reports/funnels#hold-property-constant) on item ID so you can track each individual item. - -To use property sum, select property sum from the measurement menu, and select a numeric property. In this case, we're seeing our 5 step purchase funnel, and we can see that our biggest dropoff is between viewing an item and adding it to cart. - -![Revenue Funnel](/funnels_property_sum.png) - -### Top Paths - -If you have selected **any order** for your funnels steps, you have the option to select **Top paths** from the drop-down list to view a Sankey visualization of how your users are performing the steps in your funnel. - -![/Screen_Shot_2022-07-12_at_3.30.32_PM.png](/Screen_Shot_2022-07-12_at_3.30.32_PM.png) - -### Comparison Events - -You can select multiple events at a particular step in a funnel, and Mixpanel will compute a segmented funnel that shows what percent of users reached each of these comparison events. - -To do this, click on the "..." and select "add event comparison" - -![/xvjcq1dbb2_1_.png](/xvjcq1dbb2_1_.png) - -### Advanced Breakdown Functionality - -#### User Count in Breakdown - -When grouping or filtering the results of your funnel, user count will be determined by the number of unique users for each property combination. - -For example, if you are an e-commerce site grouping by the property “item” to determine what users are searching for and purchasing, users will appear in the table once for each property they use. In a funnel where Event A is “Search”, Event B is “Add to Cart”, and Event C is “Purchase”, a user may complete the funnel twice, once with the property “hat”, and once with the property “shirt”. This user would convert through the funnel, and be counted in the Group By table for both “hat” and “shirt” when grouping by property “item”. They would be counted in the “overall” row as completing the funnel once. - -This behavior matches how users are counted when filtering by property: if a user goes through the entire funnel X times with Y distinct event property values, the user will be counted Y times. - -#### Statistical Significance - -Statistical significance in funnels validates an increase or decrease in conversion rate for a property or cohort segment. It attempts to identify random chance with respect to overall conversion. A p-value indicating statistical significance is calculated in the overview table when you choose a property or cohort to group by. - -In statistical hypothesis testing, the p-value or probability value is the probability that the variation in a segment’s conversion rate, compared to the overall conversion rate, is not driven by a random chance. This value is shown for every segment by default. To learn more about how this is calculated, click [here](/docs/reports/funnels#how-does-mixpanel-calculate-statistical-significance). - -In order to clarify this statistical significance, the segmentation chart shows the confidence level of each segment. Confidence level is defined as 1 - p. - -- > 0.95 = statistically significant, indicated in green. This variation in conversion rate is likely **not** driven by random chance. -- < 0.95 = not statistically significant, indicated in red. This variation in conversion rate is likely driven by random chance. - -![/Screen_Shot_2019-10-28_at_2.28.54_PM.png](/Screen_Shot_2019-10-28_at_2.28.54_PM.png) - -Scrolling further down the table takes you to the statistically insignificant segments. If a segment has less than 30 samples, p-value is not shown, as the sample size is too low to detect difference from overall population. This is indicated by “Insufficient samples”. - -The number of samples is the same as the count of entries into the funnel. If the funnel is looking at the unique count, this is the number of unique users who entered the funnel in that segment. If the funnel is looking at total count, this is the total number of entries into the funnel in that segment. - -You can choose to sort by any of the columns of the overall table in descending or ascending order by clicking on the header. If you sort by statistical significance, values with confidence level of > 0.95 are shown first, and then values with confidence level < 0.95. The secondary sorting is determined by the overall conversion rate for the funnel. - -Click on the **dot** beside the statistical significance number to make that property value the Control value that the other property values are compared to. To return to the default view, click the **dot** beside “Overall”. - -![/Oct-28-2019_10-35-23.gif](/Oct-28-2019_10-35-23.gif) - -### Property Attribution - -#### First Step Defined vs Last Step Defined - -Event property values can vary from step to step in your funnel. For example, a user may select a blue shirt in step 1, but put a red shirt in their cart in step 3. If you want to control when the property value is locked in for all steps of your funnel, you can use property attribution. - -To access this feature, filter or breakdown by a property in the funnel chart below the query builder. Click on **Step 1** to select either “Last Step Defined”, “First Step Defined”, or a specific step number. - -![/Screen_Shot_2022-07-12_at_3.33.03_PM.png](/Screen_Shot_2022-07-12_at_3.33.03_PM.png) - -Your selected choice will determine which step of your funnel determines the property value for the whole funnel. - -#### First Step Defined Attribution and Forwardfilling - -By default, Mixpanel “forwardfills” [event properties](/docs/data-structure/events-and-properties) in instances where properties are sent in earlier steps of a Funnel but not sent in subsequent steps of the same funnel. This means that the property that is present in early steps of a funnel is appended to the later steps of the funnel where it was previously absent. - -Select **First Step Defined** to attribute the first property value to the whole funnel, regardless of whether the property value changes in subsequent steps. First Step Defined is not the same as the first step of the funnel, rather it is the first time the property is given a non-null defined value. - -For example, say that the user is shopping on your website and you want to track a funnel from Log In to Purchase. There are three events in this journey: Log In, Item View, and Purchase. Each event has its own properties, and the “Name” property is only sent with the “Log In” event. This property will be added to the subsequent events, where it was previously absent: - -![/ForwardfillingDiagram.png](/ForwardfillingDiagram.png) - -As you can see in the diagram above, the property of “Name” is only a property for the event “Log In”, but that property is forwardfilled to the subsequent events. - -#### Last Step Defined Attribution and Backfilling - -By default, Mixpanel “backfills” [event properties](/docs/data-structure/events-and-properties) in instances where properties are sent in later steps of a Funnel but not sent in the earlier steps of the same funnel. This means that the property that is present in later steps of a funnel is appended to the earlier steps of the funnel where it was previously absent. - -Select **Last Step Defined** to attribute the last property value to the whole funnel, regardless of the property value in previous steps. Last Step Defined is not the same as the last step of the funnel, rather it is the last time the property is given a non-null defined value. - -For example, the user shopping on your website chooses to buy a shirt that costs $5. In this instance, properties of the item that is purchased are not sent until the “Purchase” event, so the property is backfilled and added to the “Item View” and “Log In” events: - -![/11544922524820.png](/11544922524820.png) - -As you can see, the property of “Item Price” is only a property of the event “Purchase”, but that property backfilled to the previous two steps. Also, the properties sent with the event “Item View” are backfilled to “Log In”. - -If an event property is sent with all steps of a funnel but the value of the property changes across steps, then the most recent value is applied to all steps of the Funnel. - -For example, the user shopping on your website views a blue shirt and adds it to their cart. However, when they make their purchase, they have changed their mind and decided to get a red shirt instead: - -![/BackfillingReplaceDiagram.png](/BackfillingReplaceDiagram.png) - -As you can see, the property of “Item Color” is Blue for Event 2, but changes to Red for Event 3. As a result of backfilling, the property of “Item Color” will be appended to Red in the “Item View” event, and further backfilled to “Log In”  as well. - -#### Per-Step Attribution - -You can choose to attribute a property value from any step to the whole funnel by selecting the step number. Note that with this option you may see an "undefined" null value for the property, as this option is not tied to when the property value was defined. - -For example, the user viewing your website encounters an error and sends in a support ticket to your business. On First Step Defined they may have been using Safari as their browser, and used Safari to send in the support ticket at Last Step Defined, but they were using Chrome when they triggered an error-state. It is relevant for your business to know that they triggered an error on the Chrome browser and not Safari, in order to assist them in fixing the error. - -## Conversion & drop-off Flows -You can click into any funnel step and select "View as Flow". This takes you to the [flows](/docs/reports/flows) report and lets you see: -* What events did users do before or after converting? -* What events did the users who dropped off do instead? - -For example, you might use this to discover that most users who dropped off are hitting a specific bug in your platform. You can then fix the bug and revisit your funnel to see if there's been an improvement. - -

- -

- -### Rename a Step - -Click on the "three dots" icon beside a step and click **Rename** to rename it. - -![image](https://github.com/mixpanel/docs/assets/2077899/2e2e844b-a9f6-4eb1-8532-345c7e8613e3) - -### View as Flow - -In order to learn more about the behavior users take between funnel steps, use "View as Flow". You can see what user flows and behaviors that can increase the likelihood of conversion or drop-off. This helps to answer questions like: - -- What flows do users take between opening an app and making a purchase? -- Why did the successful users purchase? -- What flows do users take that don’t lead to a purchase? -- How do these two paths differ? What actions should I nudge towards or against? -- What did the users that dropped-off do instead? - -![image](https://github.com/mixpanel/docs/assets/2077899/b37e48d4-d9c8-42b7-9e79-72e7e71e47eb) - -#### Using Conversion and Drop-off Flows - -First, go to the Mixpanel Funnels Report, and create any funnel you like by selecting 2 or more events steps. - -Next, click on the conversion or drop-off population you wish to examine further and select View As Flow. - -![/cr8695o49k.png](/cr8695o49k.png) - -In this example, I want to see what events lead to better conversion or more drop-off between Step 1 Browse and Step 2 Add To Cart. This will send me to the Sankey visualization to see these event streams in a Flows report. - -I can see that all of the Funnel's criteria is still maintained. In my example, I still am counting a Unique funnel, within 30 days, holding the Item Name property constant, and excluding users that Abandon Cart at any stage. I can also go back to the Funnel to change my criteria at any time. - -The Sankey is automatically broken down by users that eventually converted or did not convert to Add to Cart (Users may not convert because of hitting exclusion steps, or failing to complete the funnel within the conversion window). - -![/Screen_Shot_2021-05-26_at_7.13.34_AM.png](/Screen_Shot_2021-05-26_at_7.13.34_AM.png) - -Hovering over any path I can see the size of the population and the percent converted to this action from the previous one. - -![/rjgjxun5bz.png](/rjgjxun5bz.png) - -In the example, I can see here that 10.6% converted immediately to Adding to their Cart. - -#### Lift Actions: What paths are performed more often by users who convert compared those who drop off? - -With the recently added lift actions feature, we have made it possible to quickly tell which actions and paths had a higher or lower conversion rate compared to the funnel as a whole. - -![/Screen_Shot_2021-05-26_at_7.38.50_AM.png](/Screen_Shot_2021-05-26_at_7.38.50_AM.png) - -In this example, I can see that Users who performed Search Results, had a +24% higher conversion rate compared to overall (51.1% vs. 41.2%). Whereas, users who performed Experiment Started had a -82.4% reduction in conversion rate compared to overall (7.2% vs. 41.2%).By looking at the positive (green) and negative (red) lift actions, you should be able to quickly form hypothesis on which paths and events are likely to result in more or less conversions. - -#### Filter by Conversion: What are the common paths taken by users who convert? - -If you want to do an isolated analysis of conversions, I can apply a filter so that the report will include only conversions.  This is done by clicking on Filter in the query builder and selecting the Conversion property. Setting it to Converted, will filter only to users who have converted. - -![/l387g5uhw1_1_.png](/l387g5uhw1_1_.png) - -![/Screen_Shot_2021-05-26_at_7.55.31_AM.png](/Screen_Shot_2021-05-26_at_7.55.31_AM.png) - -In this example, we can see that 35.6% of conversions happened in the first step. - -#### Filter by drop off: What do users do right before dropping off? - -To view what users did before dropping off, change the filter to "Did not Convert", and add more steps before the drop off step - -![/Screen_Shot_2021-05-26_at_7.58.29_AM.png](/Screen_Shot_2021-05-26_at_7.58.29_AM.png) - -![/Screen_Shot_2021-05-26_at_7.59.51_AM.png](/Screen_Shot_2021-05-26_at_7.59.51_AM.png) - -Now, I can see that 33.7% of users who did not convert, did the "Join Loyalty Program" before dropping off. I can use this hypothesis to evaluate the business impact of the loyalty program, and perhaps make some changes to the product. ## FAQ @@ -466,6 +70,8 @@ Now, I can see that 33.7% of users who did not convert, did the "Join Loyalty Pr Assuming that the user performed all actions in the funnel, on their first try, in the right sequence, within the conversion window, the user should be counted as converted. However, if you are looking at the Funnel report for today, they might be shown as dropped off. This is because there may be up to a 24 hour delay on our reports (except for Activity Feed), as we work towards linking anonymous user activity to known profiles. This would explain why the funnel displays the user as not converted, soon after ingestion. Once we account for the delay, the funnel should display the conversion, especially if the user performs the steps in the funnel in the specified sequence. +This can also happen due to identity management issues. Mixpanel uses distinct_id to keep track of user events throughout their conversion journeys, and if the distinct ID on events tracked by a single user is not consistent, they are misattributed and appear as a drop off. + ### Can users do other actions during the funnel? Users can complete the steps you designate in your funnel in loose order. Loose order means that a customer can engage in other actions in between funnel steps, as long as they complete all the funnel steps in order. Let's start with an example where the funnel has steps: A, B, C, D, E and go through a few cases: @@ -494,55 +100,6 @@ Mixpanel Funnels include a built-in two second grace period. This means any cons What does this mean in terms of your funnel? In a funnel with step A -> B, if a user completes event B first and then performs event A within two seconds, Mixpanel counts this as a conversion from A -> B or B -> A. -### What is the difference between Per-Step Filtering and Global Filtering? - -You can use both per-step and global filters to decide which users and events to include in a funnel. While per-step filters only apply to a single step and global filters apply to all steps in a funnel, there is more to the distinction than just that. - -Next, let's expand on the differences between per-step (pre-query) and global (post-query) filtering and how it can affect your results. - -#### Per-Step Filtering (Pre-Query) - -Per-step filters allow you to apply event or user property filters to each step of your funnel. This adds granularity and specificity to your conversion criteria. In selecting a per-step filter, you are tightening the parameters of events that qualify for conversion. - -Per-step filters are performed pre-query. Thus, these filters will impact your funnel’s conversion by removing events that don’t qualify from consideration of being included in a funnel calculation. - -Let's illustrate this with some examples. - -Consider a four-step funnel where a user must Search > Item Detail Page > Add to Cart > Complete Purchase, all within a one-day conversion window. - -As you can see in the below activity feed, this user's first Search event happens more than one day before any Item Detail Pages, and as such, they would not convert in this funnel. - -![image](https://github.com/mixpanel/docs/assets/2077899/5d671e0b-5666-4ec5-971a-cfaf3734929a) - -![image](https://github.com/mixpanel/docs/assets/2077899/eb848af7-4cef-4eb5-8a60-36c88a6fd64f) - -However, if I put a per step filter on the Search event and require a user to use a Brower = Safari, then I will restrict entry into the funnel to only Search events on Safari browsers. - -Below we see the same user's activity stream where their first Search event is with the Chrome browser, and thus this user’s first Search event **is not** included in a funnels calculation. However they have a second Search that is using Safari, and this event qualifies them to enter into the funnel. Unlike before when we did not filter, now each of their subsequent steps happens within the conversion window, and this user reaches full conversion to the end of the funnel. - -![image](https://github.com/mixpanel/docs/assets/2077899/6daf8f38-afaf-48dd-994e-7f7be682cc92) - -![image](https://github.com/mixpanel/docs/assets/2077899/a025b018-cecc-4798-9b95-b907ad157b5e) - -If we were to take it further and place a per-step filter on each and every step in this funnel, so that all steps must be completed with events where Browser = Safari, then this user would only convert to the second step of the Item Detail. - -This is because, as we can see below, the first Search/Safari step is followed by two steps that aren’t tracked in the funnel: *Item Detail Page/Chrome* that is filtered out of this funnel because it does not fulfill the Browser= Safari criteria, and *Add to Cart/Safari* that is not considered because it is not preceded by an Item Detail Page/Safari. The next step that is tracked in the funnel (Item Detail Page/Safari) converts the user to Step 2, but then *Add to Cart/Chrome* is filtered out of the funnel. Since there is not another Add to Cart/Safari before the Purchase event or before the 1 day conversion window runs out, this user times out of the funnel after Step 2. - -![image](https://github.com/mixpanel/docs/assets/2077899/d2425bf0-5d61-4bf3-ad2f-861fa65f3563) - -![image](https://github.com/mixpanel/docs/assets/2077899/c91178bc-f358-44fd-ada8-ca786d690354) - -#### Global Filtering (Post-Query) - -Global filters apply your selected filters to the entire report after the Funnels query has been run. Since Funnels will calculate conversions first and then apply your global filters, entire conversions with any part that does not meet these filter requirements will be excluded from the report's results. - -For example, let's use the same four-step funnel where a user must Seach > Item Detail Page > Add to Cart > Complete Purchase, all within a one-day conversion window. - -In the below example, the Funnels query will calculate a conversion because the user moves from Search, then Item Detail Page, then Add to Cart and lastly to Purchase within the 1 day conversion window. However, after the query is calculated, the global filter of Browser = Safari is applied. Since there are steps of this calculated funnel that have Browser = Chrome, the entire funnel will be filtered out of the aggregate results. - -![image](https://github.com/mixpanel/docs/assets/2077899/ef83cca5-5108-4d06-a111-5c2b7e93a492) - -![image](https://github.com/mixpanel/docs/assets/2077899/2335dc77-4dac-48d8-a56d-66deefadbc11) ### How does Mixpanel calculate statistical significance? diff --git a/pages/docs/reports/funnels/_meta.json b/pages/docs/reports/funnels/_meta.json new file mode 100644 index 0000000000..263adffc2f --- /dev/null +++ b/pages/docs/reports/funnels/_meta.json @@ -0,0 +1,7 @@ +{ + "funnel-behavior": "Funnel Behavior", + "measurements": "Measurements", + "funnels-conversion-critera": "Funnels Conversion Criteria", + "breakdowns-and-filters": "Breakdowns and Filters", + "visualizations": "Visualizations" +} diff --git a/pages/docs/reports/funnels/breakdowns-and-filters.md b/pages/docs/reports/funnels/breakdowns-and-filters.md new file mode 100644 index 0000000000..fc241bb9c4 --- /dev/null +++ b/pages/docs/reports/funnels/breakdowns-and-filters.md @@ -0,0 +1,132 @@ +# Breakdowns and Filters + +## Overview +Funnels measure sequences of events as a behavior, which adds complexity when filters and breakdowns are applied. This article will go over the Funnels property attribution mechanism, as well as the impact of filters and breakdowns on your funnel results. + +## Funnels Property Attribution +A funnel measures multiple events in sequence, and in many cases, event property values can vary from step to step in your funnel. For example, a user may select a blue shirt in step 1, but put a red shirt in their cart in step 3. When you apply an event property filter or breakdown in a Funnels report, we select one of the steps in the funnel entry and use the event property value in that step to represent the entire funnel entry through a property attribution mechanism. + +To configure your property attribution model, add an event property filter or breakdown. The option to choose which step to segment and filter your funnels on will appear in the bottom left corner of the Conversion Criteria module below your measurement selection. + +Screenshot 2024-06-24 at 10 33 45 PM + +Your selected choice will determine which step of your funnel determines the property value segment for that entire funnel. + +## First Step Defined Attribution and Forwardfilling + +By default, Mixpanel “forwardfills” [event properties](/docs/data-structure/events-and-properties) in instances where properties are sent in earlier steps of a Funnel but not sent in subsequent steps of the same funnel. This means that the property that is present in early steps of a funnel is appended to the later steps of the funnel where it was previously absent. + +Select **First Step Defined** to attribute the first property value to the whole funnel, regardless of whether the property value changes in subsequent steps. First Step Defined is not the same as the first step of the funnel, rather it is the first time the property is given a non-null defined value. + +For example, say that the user is shopping on your website and you want to track a funnel from Log In to Purchase. There are three events in this journey: Log In, Item View, and Purchase. Each event has its own properties, and the “Name” property is only sent with the “Log In” event. This property will be added to the subsequent events, where it was previously absent: + +![/ForwardfillingDiagram.png](/ForwardfillingDiagram.png) + +As you can see in the diagram above, the property of “Name” is only a property for the event “Log In”, but that property is forwardfilled to the subsequent events. + +## Last Step Defined Attribution and Backfilling + +By default, Mixpanel “backfills” [event properties](/docs/data-structure/events-and-properties) in instances where properties are sent in later steps of a Funnel but not sent in the earlier steps of the same funnel. This means that the property that is present in later steps of a funnel is appended to the earlier steps of the funnel where it was previously absent. + +Select **Last Step Defined** to attribute the last property value to the whole funnel, regardless of the property value in previous steps. Last Step Defined is not the same as the last step of the funnel, rather it is the last time the property is given a non-null defined value. + +For example, the user shopping on your website chooses to buy a shirt that costs $5. In this instance, properties of the item that is purchased are not sent until the “Purchase” event, so the property is backfilled and added to the “Item View” and “Log In” events: + +![/11544922524820.png](/11544922524820.png) + +As you can see, the property of “Item Price” is only a property of the event “Purchase”, but that property backfilled to the previous two steps. Also, the properties sent with the event “Item View” are backfilled to “Log In”. + +If an event property is sent with all steps of a funnel but the value of the property changes across steps, then the most recent value is applied to all steps of the Funnel. + +For example, the user shopping on your website views a blue shirt and adds it to their cart. However, when they make their purchase, they have changed their mind and decided to get a red shirt instead: + +![/BackfillingReplaceDiagram.png](/BackfillingReplaceDiagram.png) + +As you can see, the property of “Item Color” is Blue for Event 2, but changes to Red for Event 3. As a result of backfilling, the property of “Item Color” will be appended to Red in the “Item View” event, and further backfilled to “Log In”  as well. + +## Per-Step Attribution + +You can choose to attribute a property value from any step to the whole funnel by selecting the step number. Note that with this option you may see an "undefined" null value for the property, as this option is not tied to when the property value was defined. + +For example, the user viewing your website encounters an error and sends in a support ticket to your business. On First Step Defined they may have been using Safari as their browser, and used Safari to send in the support ticket at Last Step Defined, but they were using Chrome when they triggered an error-state. It is relevant for your business to know that they triggered an error on the Chrome browser and not Safari, in order to assist them in fixing the error. + +## Filters + +You can use both in-line filters and global filters to decide which users and events to include in a funnel. While in-line filters only apply to a single step and global filters apply to all steps in a funnel, property attribution leads to some additional distinctions to highlight. + +Let's expand on the differences between in-line (pre-query) and global (post-query) filtering and how it can affect your Funnels result. + +### In-line Filtering (Pre-Query) + +In-line filters allow you to apply event or user property filters to each step of your funnel. This adds granularity and specificity to your conversion criteria. In selecting an In-line filter, you are tightening the parameters of events that qualify for conversion. + +In-line filters are performed pre-query. Thus, these filters will impact your funnel’s conversion by removing events that don’t qualify for consideration of being included in a funnel calculation. + +In-line filters are not affected by + +Let's illustrate this with some examples. + +Consider a four-step funnel where a user must Search > Item Detail Page > Add to Cart > Complete Purchase, all within a one-day conversion window. + +As you can see in the below activity feed, this user's first Search event happens more than one day before any Item Detail Pages, and as such, they would not convert in this funnel. + +![image](https://github.com/mixpanel/docs/assets/2077899/5d671e0b-5666-4ec5-971a-cfaf3734929a) + +![image](https://github.com/mixpanel/docs/assets/2077899/eb848af7-4cef-4eb5-8a60-36c88a6fd64f) + +However, if I put an in-line filter on the Search event and require a user to use a Brower = Safari, then I will restrict entry into the funnel to only Search events on Safari browsers. + +Below we see the same user's activity stream where their first Search event is with the Chrome browser, and thus this user’s first Search event **is not** included in a funnels calculation. However they have a second Search that is using Safari, and this event qualifies them to enter into the funnel. Unlike before when we did not filter, now each of their subsequent steps happens within the conversion window, and this user reaches full conversion to the end of the funnel. + +![image](https://github.com/mixpanel/docs/assets/2077899/6daf8f38-afaf-48dd-994e-7f7be682cc92) + +![image](https://github.com/mixpanel/docs/assets/2077899/a025b018-cecc-4798-9b95-b907ad157b5e) + +If we were to take it further and place an in-line filter on each and every step in this funnel, so that all steps must be completed with events where Browser = Safari, then this user would only convert to the second step of the Item Detail. + +This is because, as we can see below, the first Search/Safari step is followed by two steps that aren’t tracked in the funnel: *Item Detail Page/Chrome* that is filtered out of this funnel because it does not fulfill the Browser= Safari criteria, and *Add to Cart/Safari* that is not considered because it is not preceded by an Item Detail Page/Safari. The next step that is tracked in the funnel (Item Detail Page/Safari) converts the user to Step 2, but then *Add to Cart/Chrome* is filtered out of the funnel. Since there is not another Add to Cart/Safari before the Purchase event or before the 1 day conversion window runs out, this user times out of the funnel after Step 2. + +![image](https://github.com/mixpanel/docs/assets/2077899/d2425bf0-5d61-4bf3-ad2f-861fa65f3563) + +![image](https://github.com/mixpanel/docs/assets/2077899/c91178bc-f358-44fd-ada8-ca786d690354) + +### Global Filtering (Post-Query) + +Global filters apply your selected filters to the entire report after the Funnels query has been run. Since Funnels will calculate conversions first and then apply your global filters, entire conversions with any part that does not meet these filter requirements will be excluded from the report's results. + +For example, let's use the same four-step funnel where a user must Seach > Item Detail Page > Add to Cart > Complete Purchase, all within a one-day conversion window. + +In the below example, the Funnels query will calculate a conversion because the user moves from Search, then Item Detail Page, then Add to Cart and lastly to Purchase within the 1 day conversion window. However, after the query is calculated, the global filter of Browser = Safari is applied. Since there are steps of this calculated funnel that have Browser = Chrome, the entire funnel will be filtered out of the aggregate results. + +![image](https://github.com/mixpanel/docs/assets/2077899/ef83cca5-5108-4d06-a111-5c2b7e93a492) + +![image](https://github.com/mixpanel/docs/assets/2077899/2335dc77-4dac-48d8-a56d-66deefadbc11) + +## Breakdowns +When grouping or filtering the results of your funnel, the user count will be determined by the number of unique users for each property combination. + +For example, if you are an e-commerce site grouping by the property “item” to determine what users are searching for and purchasing, users will appear in the table once for each property they use. In a funnel where Event A is “Search”, Event B is “Add to Cart”, and Event C is “Purchase”, a user may complete the funnel twice, once with the property “hat”, and once with the property “shirt”. This user would convert through the funnel, and be counted in the Group By table for both “hat” and “shirt” when grouping by property “item”. They would be counted in the “overall” row as completing the funnel once. + +This behavior matches how users are counted when filtering by property: if a user goes through the entire funnel X times with Y distinct event property values, the user will be counted Y times. + +### Statistical Significance +Statistical significance in funnels validates an increase or decrease in conversion rate for a breakdown segment. It attempts to identify random chance with respect to overall conversion. A p-value indicating statistical significance is calculated in the overview table when you choose a property or cohort to group by. + +In statistical hypothesis testing, the p-value or probability value is the probability that the variation in a segment’s conversion rate, compared to the overall conversion rate, is not driven by a random chance. This value is shown for every segment by default. To learn more about how this is calculated, click [here](/docs/reports/funnels#how-does-mixpanel-calculate-statistical-significance). + +In order to clarify this statistical significance, the segmentation chart shows the confidence level of each segment. Confidence level is defined as 1 - p. + +- > 0.95 = statistically significant, indicated in green. This variation in conversion rate is likely **not** driven by random chance. +- < 0.95 = not statistically significant, indicated in red. This variation in conversion rate is likely driven by random chance. + +![/Screen_Shot_2019-10-28_at_2.28.54_PM.png](/Screen_Shot_2019-10-28_at_2.28.54_PM.png) + +Scrolling further down the table takes you to the statistically insignificant segments. If a segment has less than 30 samples, p-value is not shown, as the sample size is too low to detect difference from overall population. This is indicated by “Insufficient samples”. + +The number of samples is the same as the count of entries into the funnel. If the funnel is looking at the unique count, this is the number of unique users who entered the funnel in that segment. If the funnel is looking at total count, this is the total number of entries into the funnel in that segment. + +You can choose to sort by any of the columns of the overall table in descending or ascending order by clicking on the header. If you sort by statistical significance, values with confidence level of > 0.95 are shown first, and then values with confidence level < 0.95. The secondary sorting is determined by the overall conversion rate for the funnel. + +Click on the **dot** beside the statistical significance number to make that property value the Control value that the other property values are compared to. To return to the default view, click the **dot** beside “Overall”. + +![/Oct-28-2019_10-35-23.gif](/Oct-28-2019_10-35-23.gif) diff --git a/pages/docs/reports/funnels/funnel-behavior.md b/pages/docs/reports/funnels/funnel-behavior.md new file mode 100644 index 0000000000..ecbf080c01 --- /dev/null +++ b/pages/docs/reports/funnels/funnel-behavior.md @@ -0,0 +1,58 @@ +# Funnel Behavior + +## Overview + +A funnel is a sequence of events performed within a certain time period and is the basic building block of the Funnels report. Unlike standard metrics such as Events or Users, funnels is a behavioral measurement focused on calculating how users convert (or drop-off) from one event to another. + +## Funnel Events + +A funnel consists of multiple steps anchored by events. Each funnel requires at least 2 events; an entry event and a conversion event. + +**Entry Event** + +An entry event lives at the top of the funnel in the first step. Any users who track this event within your date range will be included in your enter your funnel and included in your report. + +Users who did not track the entry event will be excluded from the report even if they tracked other events defined in your funnel. + +**Conversion Event** + +A conversion event is any event that follows the entry event, defined after the first step of the funnel. A funnel with multiple steps will have multiple conversion events. + +## Building a Funnel + +### Define an Entry Event +- Start by adding an entry event. +- Visit Website + +### Define a Conversion Event +- Add any event as a conversion event. +- Click Purchase + +### Multistep Funnel +- Add additional conversion events +- Visit Website, Add Payment Information, Click Purchase to learn about dropoff + +### Comparison Events + +You can select multiple events at a particular step in a funnel, and Mixpanel will compute a segmented funnel that shows what percent of users reached each of these comparison events. + +For example, you may be interested in whether showing one ad banner leads to more purchase than another ad banner. In this case, you can build a funnel using "Visit Website" at the first step, "Advertisement A" at the second step, and "Purchase" at the third step, then add "Advertisement B" as a comparison event in the second step to see whether their is a significant difference in conversion to "Purchase" between the two ad banners. + +To do this, click on the "..." at the desired step and select "add event comparison". + +![/xvjcq1dbb2_1_.png](/xvjcq1dbb2_1_.png) + +### Order of Events +By default, funnels require the users to complete each of the funnel steps in the order laid out to be counted as a conversion from one step to another. It is possible to create flexible ordering by configuring your [Conversion Criteria](/docs/reports/funnels/funnels-conversion-criteria). Learn more about step ordering [here](/docs/reports/funnels/funnels-conversion-criteria#ordering). + +## Saved Funnel Behaviors + +You can define a funnel behavior and save and share it. Press "Save as New" button to save your funnel behavior definition. You can change the name and add a description. + +![save funnel](/save-funnel-1.png) + +You can also load existing funnel definitions by clicking the name of funnel. + +![save funnel](/save-funnel-2.png) + +See more about saved behaviors [here](/docs/features/saved-behaviors). diff --git a/pages/docs/reports/funnels/funnels-conversion-criteria.md b/pages/docs/reports/funnels/funnels-conversion-criteria.md new file mode 100644 index 0000000000..b3235a3df8 --- /dev/null +++ b/pages/docs/reports/funnels/funnels-conversion-criteria.md @@ -0,0 +1,120 @@ +# Funnels Conversion Criteria + +## Overview + +You can toggle the conversion criteria in your Funnels report to customize the definition of conversion in the report. + +

+ +

+ +## Conversion Window + +The Conversion Window determines how much time a user has to convert through all steps of the funnel after entering it. + +By default, all customers have 30 days to complete a funnel from the timestamp they perform the Step 1 event. To adjust this conversion window, click on the words **30 days** in the conversion criteria. You will be able to adjust both the unit of time and the amount. + +![/Screen_Shot_2021-12-15_at_11.12.25_AM.png](/Screen_Shot_2021-12-15_at_11.12.25_AM.png) + +The maximum amount of time you can choose for the conversion window is 366 days, or otherwise equivalent (12 months, 52 weeks, etc). For session-based conversion windows, the maximum is 1 session. + +Keep in mind that the conversion window starts on the first instance of the Step 1 event per funnel entry, and will not be updated by later instances of the same event in the same funnel trial. + +For example, let's assume a funnel with the following criteria: A → B → C, conversion window of one hour + +If the user does A at 1pm and then A again at 1:30pm, before doing B at 1:45pm and C at 2:15pm, they would count as converting to B, but will not be counted as completing the entire funnel to C. This is because 1pm to 2:15pm is greater than one hour. The conversion window for a given funnel trial starts with the first instance of A and is not reset by later instances of A in the same trial. B and C need to be completed within the conversion window from the first instance of A to be counted as conversions. + +## Ordering + +The order control determines how much flexibility there can be to the sequence of your user's actions to be counted as a conversion. + +By default, funnels are based on a **specific order**. To change order designation, click on the words **Advanced** next to Conversion Criteria, and toggle on **Any Order** from the drop-down list. + +![/Screen_Shot_2021-12-15_at_10.20.13_AM.png](/Screen_Shot_2021-12-15_at_10.20.13_AM.png) + +### Specific Order + +Specific Order Funnels require the user to complete each of the funnel steps in the order laid out to be counted as a conversion from one step to another. In other words, Step 1 must be completed before Step 2, which must be completed before Step 3, and so on. The user can engage in other actions in between funnel steps - including additional occurrences of the actions listed as funnels steps - but they will only be counted as converted if they complete all the funnel steps in order. + +To illustrate with an example, let's say a specific order funnel has steps: A, B, C, D, E + +1. The customer does steps A -> B -> C -> D -> E in exact order. Mixpanel counts this as a conversion. +2. The customer does steps A -> B -> ***F*** -> C -> D -> E. Mixpanel counts this as a conversion. Users can do additional actions in between funnels steps and still convert. +3. The customer does steps A -> B -> ***D*** -> C -> D -> E. Mixpanel counts this as a conversion. Even though the customer did D before the first time they did C, they will continue to convert because they eventually did a D after C. +4. The customer does steps A -> B -> C -> E. Mixpanel will not count this as a full conversion, and the customer will drop off after step C. The customer's completion of step E is excluded from the funnel because step D did not occur. + +### Any Order + +In Any Order Funnels, users can complete unanchored funnel steps in any particular sequence and still convert. This type of funnel is most useful in situations where a user must complete all actions to be considered converted, but the exact order is not important. + +A good example of this could be a job application flow, where a user must input multiple pieces of information (their name, email address, current job title, credentials, references, cover letter, resume, etc.) in order to complete the form and submit their application, but they can provide all this information in any order they'd like and still proceed towards converting. + +To switch to **Any Order**, expand the "Advanced" menu in the Conversion Criteria and toggle on "Any Order". + +![/Screen_Shot_2022-07-12_at_3.35.33_PM.png](/Screen_Shot_2022-07-12_at_3.35.33_PM.png) + +When you switch to **Any Order,** you have the option to anchor specific steps in your funnel by clicking on the step number. + +![/CleanShot_2021-12-15_at_11.03.46.gif](/CleanShot_2021-12-15_at_11.03.46.gif) + +A step will either appear with a number beside it, indicating where it must fall in the funnel, or with an asterix (\*), indicating that it can be performed in any order before the next anchored step. + +**Example**: + +![/Untitled_Diagram.jpg](/Untitled_Diagram.jpg) + +In the above example, Steps 1, 4, and 6 must occur as the 1st, 4th, and 6th steps the user performs.Any of the * steps can occur at any time within those boundaries. + +## Hold Property Constant + +Holding a property constant in a funnel requires that a user retains the same value for a given event property for each step in order to convert. In other words, a user must not only perform the funnel events in the order you specified, but also perform these events with the same property value. + +For example, let's say your product is an e-commerce retail site, and you have a three-step funnel of Browse > Add to Cart > Purchase. If you want to examine the conversion of users through this funnel that browse, add to cart, and purchase the same item - meaning that they cannot convert if they don't complete each step with the same item - you would hold the Item Name property constant. + +The way this is counted depends on whether you have selected a counting method that does not allow users to re-enter the funnel ("Uniques") or allows re-entry ("Totals" or "Sessions). + +- **Uniques:** When you select "Uniques" and hold a property constant, because users of this counting method only enter the funnel once and on the first time they do the Step 1 event, Mixpanel will hold constant the property value from the first Step 1 event. +- **Totals or Sessions:** When you select "Totals" or "Sessions" and hold a property constant, since these counting methods allow users to re-enter the funnel, Mixpanel will hold the property constant that is set with each new re-entry at the Step 1 event. + +To add a property constant to your funnel, expand the "Advanced" menu in the Conversion Criteria and click on "Holding property constant". + +![/Screen_Shot_2021-12-15_at_11.10.42_AM.png](/Screen_Shot_2021-12-15_at_11.10.42_AM.png) + +Some things to keep in mind are that you are only able to select event properties that apply to all of the events in your funnel. Also, you can select multiple properties, but when you do ALL must be kept constant. A maximum of 3 properties can be held constant at the same time. + +## Exclusion Steps (Exclude users who did...) + +Exclusion steps operate as a "did not do" filter for funnels. This provides the ability to create a funnel where, for example, you look for users that did event A, then event B, did not do event C, but then continue to do D. Note that the users are excluded at that point in the funnel. So in the previous example a user that did event C would still be counted in the funnel as having A and B, but they would not qualify in the funnel for event D, by virtue of having done event C. + +At the "Conversion Criteria" section, click on "Advanced" and then on "Exclude users who did...". A dropdown will appear to exclude a step from your funnel. + +![image](https://github.com/mixpanel/docs/assets/2077899/fc146839-6feb-4a40-a7b7-c17217bf6c7a) + +Select an event from the list and choose whether you would like the event to be excluded between all steps, or between specific steps. + +![image](https://github.com/mixpanel/docs/assets/2077899/d1c95913-42ca-45ba-9605-5cce51534e48) + +Click the **Filter icon** beside the step to filter that event by an event or user profile property. + +![image](https://github.com/mixpanel/docs/assets/2077899/ab63bef8-3d64-4b4b-97ed-392811e185ac) + +For example, if your product was an e-commerce retail company and you want to understand if users who browse for additional products between adding something to their cart and checking out are less likely to complete a purchase. To answer this question, you could create a funnel with three steps: + +Event 1: Browse product + +Event 2: Add to Cart + +Event 3: Purchase + +You can exclude users who did another “Browse product” event between Event 2 and Event 3 to and see how that affects your funnel's conversion rate. + +Further example use cases: + +1. Evaluate whether a certain step done alone is beneficial to your flow. +2. Ensure that a conversion was NOT the result of another detour step being taken in between two key steps. + +Note: +1. An exclusion step can be placed between any steps in the funnel. It cannot be the first or last step. +2. An exclusion step does not prevent users for qualifying into the funnel up until the exclusion step. If you want users who did a particular event at any point excluded, use a cohort filter. +3. There may be any number of exclusion events between steps. +4. Exclusion steps have the same [two second grace period](/docs/reports/funnels#how-does-mixpanel-handle-simultaneous-events) as other steps in the funnel. diff --git a/pages/docs/reports/funnels/measurements.md b/pages/docs/reports/funnels/measurements.md new file mode 100644 index 0000000000..ddda5ec11e --- /dev/null +++ b/pages/docs/reports/funnels/measurements.md @@ -0,0 +1,83 @@ +# Measurements + +## Overview +Funnels report supports a variety of measurements. You can configure your funnel measurement using one of the options in the table below. + +| Measurement | Description | +| --- | --- | +| Conversion Rate | The rate at which funnels are completed for the selected steps of the funnel. The conversion rate can be based off of [unique users](/docs/reports/funnels/measurements#uniques-count), [total](/docs/reports/funnels/measurements#totals-count) funnel entries or [sessions](/docs/reports/funnels/measurements#sessions-count). | +| Unique Users | The number of users who completed the selected steps of the funnel; based on their first attempt at entering the funnel within the timeframe of the report using [Uniques](/docs/reports/funnels/measurements#uniques-count) counting method.| +| Total Conversions | The total number of funnels that have reached the selected step of the funnel using the [Totals counting method](/docs/reports/funnels/measurements#totals-count). This measurement allows for users to re-enter the funnel multiple times, if they exit the funnel by either fully converting or dropping out. | +| Total Sessions | The total number of unique users sessions that reached the selected step of the funnel using the [Sessions counting method](/docs/reports/funnels/measurements#sessions-count). | +| Time to Convert | Allows for selection of an aggregation: Average, Median, Percentile, Min and Max. Measures the aggregated time to convert for the selected steps of the funnel. [See more](#time-to-convert-measurement) | +| Property Sum | Sums up a chosen property value for each step of the funnel, and measures the total amount of the property converted for the selected step of the funnel. [See more](#property-sum) | + +## Conversion Measurements +You can configure your Funnels report to calculate your conversions as a percentage using **Conversion Rate** measurements or return the number of users/entries using **Total Conversion**/**Unique Users**/**Total Session** measurements. + +Regardless of your selection, the conversions are measured using one of these counting methods. + +### Counting Methods +#### Uniques count +Uniques conversion includes a single entry per user (determined by distinct_id). Each user enters the funnel only once, and this is on the first time they perform the entry event (step 1) in the date range. Even if a particular user completes the funnel multiple times in the date range, they will only be counted towards conversion once, on the first time they entered in the span of the date range. + +This counting method is used for **Conversion Rate > Uniques** (default Funnels setting) and **Unique Users** measurements. + +#### Totals count +Totals conversion rate includes multiple entries per user. Users can re-enter the funnel and every time a user enters the funnel they are counted towards conversion. Users may re-enter a totals funnel only after they have exited their previous attempt through the funnel. Users exit a funnel in 3 ways: + +1. They complete the funnel and convert to the last step, +2. They fail to complete the funnel in the conversion window and time out, +3. They are excluded from conversion by an exclusion step. + +This counting method is used for **Conversion Rate > Totals** and **Total Conversions** measurements. + +#### Sessions count +Sessions conversion includes the number of sessions that contain a conversion. Like totals funnels, users will be allowed to re-enter the funnel in subsequent sessions; however, in sessions funnels users must convert through the funnel within the same session they entered the funnel to be counted as converted. If the session ends before they have converted, the user will time out and drop out of the funnel after the last step they reached. Learn more about [Sessions](/docs/features/sessions). + +This countng method is used for **Conversion Rate > Sessions** and **Total Sessions** measurements. + + +### Conversion Rate Toggle +By default your Funnels is set to measure Conversion Rate using the Uniques counting method. You can switch the counting method to Totals or Sessions by clicking the gear icon when selecting your measurement. + +## Time to Convert + +![Time to Convert Measurements](/ttc-measurements.png) + +You can select a Time to Convert aggregation to see how quickly or slowly your funnel converts. You can see this as a summarized value by selecting "Metric" or "Bar" visualizations, or you can see it as a trend using the "Line" visualization. You can also see the time to convert for a particular chosen step selection. + +#### Time to Convert Breakdown and Filter + +Use the Time to Convert breakdown to see a distribution of time users took between any two steps in the funnel or all steps. The steps selected in the breakdown are independent of the step of the metric you are measuring, for example you can measure overall conversion rate broken down by Time to Convert between Steps 1 and 2. + +![/funnels_ttc_selection.png](/funnels_ttc_selection.png) + +![/funnels_ttc_step_selection.png](/funnels_ttc_step_selection.png) + +Time to Convert works like any other property in that you can filter to specific range of times or customize the bucketing of the breakdown. You cannot use it as a step filter as it is used to filter funnels which have been measured rather than changing the per step conversion window. + +![/funnels_ttc_filter.png](/funnels_ttc_filter.png) + +![/funnels_ttc_custom_buckets.png](/funnels_ttc_custom_buckets.png) + +You can can use this in combination with measuring total conversion to get a distribution of conversions, based on how long they took to convert. You can also use this to see how other metrics such as conversion rate are affected based on how quickly users convert on a particular step range. + +## Property Sum + +This measurement type allows you to visualize revenue through a funnel. Instead of seeing how many users move through your flow, you can select an event property that exists on each step of the funnel. Mixpanel will sum up the total value of this property at each stage of the funnel and visualize the total ammount converted, or the dropoff at each step if "Funnel Steps" visualization is selected. + +**Note**: For many e-commerce flows, you will want to pair property sum with [hold property constant](/docs/reports/funnels#hold-property-constant) on item ID so you can track each individual item. + +To use property sum, select property sum from the measurement menu, and select a numeric property. In this case, we're seeing our 5 step purchase funnel, and we can see that our biggest dropoff is between viewing an item and adding it to cart. + +![Revenue Funnel](/funnels_property_sum.png) + + +## Step Selection + +You can select which step of the funnel you would like to measure. By default this is set to All Steps. To change your step selection, press "All Steps" and choose the desired range. + +![step selection](/step-selection.png) + +When measuring "Unique Users", "Total Conversions" or "Total Sessions", you can select "Entering Funnel" in order to get a top of funnel count. Similarly, if you would like to get the bottom of funnel count, you choose "All Steps" or any other step range to get the bottom of funnel count for that step. diff --git a/pages/docs/reports/funnels/visualizations.md b/pages/docs/reports/funnels/visualizations.md new file mode 100644 index 0000000000..a39ad44dd7 --- /dev/null +++ b/pages/docs/reports/funnels/visualizations.md @@ -0,0 +1,85 @@ +# Visualizations + +## Overview + +Funnels feature multiple visualizations to help you understand how your users convert from one event to the next. + +## Funnel Steps + +Funnel Steps is the default visualization for the Funnels Report and lets you see how your users are progressing through the steps of your funnel. Each bar represents a funnel step showing you both the conversion rate percentage and the raw number of funnel entries at each step. Click on each bar to view users who converted/dropped off or use the View as Flow feature to learn more about behaviors between the steps. + +### View as Flow + +In order to learn more about the behavior users take between funnel steps, use "View as Flow". You can see what user flows and behaviors that can increase the likelihood of conversion or drop-off. This helps to answer questions like: + +- What flows do users take between opening an app and making a purchase? +- Why did the successful users purchase? +- What flows do users take that don’t lead to a purchase? +- How do these two paths differ? What actions should I nudge towards or against? +- What did the users that dropped-off do instead? + +![image](https://github.com/mixpanel/docs/assets/2077899/b37e48d4-d9c8-42b7-9e79-72e7e71e47eb) + +#### Using Conversion and Drop-off Flows + +First, go to the Mixpanel Funnels Report, and create any funnel you like by selecting 2 or more events steps. + +Next, click on the conversion or drop-off population you wish to examine further and select View As Flow. + +![/cr8695o49k.png](/cr8695o49k.png) + +In this example, I want to see what events lead to better conversion or more drop-off between Step 1 Browse and Step 2 Add To Cart. This will send me to the Sankey visualization to see these event streams in a Flows report. + +I can see that all of the Funnel's criteria is still maintained. In my example, I still am counting a Unique funnel, within 30 days, holding the Item Name property constant, and excluding users that Abandon Cart at any stage. I can also go back to the Funnel to change my criteria at any time. + +The Sankey is automatically broken down by users that eventually converted or did not convert to Add to Cart (Users may not convert because of hitting exclusion steps, or failing to complete the funnel within the conversion window). + +![/Screen_Shot_2021-05-26_at_7.13.34_AM.png](/Screen_Shot_2021-05-26_at_7.13.34_AM.png) + +Hovering over any path I can see the size of the population and the percent converted to this action from the previous one. + +![/rjgjxun5bz.png](/rjgjxun5bz.png) + +In the example, I can see here that 10.6% converted immediately to Adding to their Cart. + +**Lift Actions: What paths are performed more often by users who convert compared those who drop off?** + +With the recently added lift actions feature, we have made it possible to quickly tell which actions and paths had a higher or lower conversion rate compared to the funnel as a whole. + +![/Screen_Shot_2021-05-26_at_7.38.50_AM.png](/Screen_Shot_2021-05-26_at_7.38.50_AM.png) + +In this example, I can see that Users who performed Search Results, had a +24% higher conversion rate compared to overall (51.1% vs. 41.2%). Whereas, users who performed Experiment Started had a -82.4% reduction in conversion rate compared to overall (7.2% vs. 41.2%).By looking at the positive (green) and negative (red) lift actions, you should be able to quickly form hypothesis on which paths and events are likely to result in more or less conversions. + +**Filter by Conversion: What are the common paths taken by users who convert?** + +If you want to do an isolated analysis of conversions, I can apply a filter so that the report will include only conversions.  This is done by clicking on Filter in the query builder and selecting the Conversion property. Setting it to Converted, will filter only to users who have converted. + +![/l387g5uhw1_1_.png](/l387g5uhw1_1_.png) + +![/Screen_Shot_2021-05-26_at_7.55.31_AM.png](/Screen_Shot_2021-05-26_at_7.55.31_AM.png) + +In this example, we can see that 35.6% of conversions happened in the first step. + +**Filter by drop off: What do users do right before dropping off?** + +To view what users did before dropping off, change the filter to "Did not Convert", and add more steps before the drop off step + +![/Screen_Shot_2021-05-26_at_7.58.29_AM.png](/Screen_Shot_2021-05-26_at_7.58.29_AM.png) + +![/Screen_Shot_2021-05-26_at_7.59.51_AM.png](/Screen_Shot_2021-05-26_at_7.59.51_AM.png) + +Now, I can see that 33.7% of users who did not convert, did the "Join Loyalty Program" before dropping off. I can use this hypothesis to evaluate the business impact of the loyalty program, and perhaps make some changes to the product. + +## Line Chart + +The line chart in Funnels allows you to visualize your measurement as a trend over time. You can toggle between evaluating the performance of your [entire funnel across all steps or between specific steps](/docs/reports/funnels/measurements#step-selection). Please note that the line chart is a time-segmented visualization, meaning that your measurement is taking place for each selected interval (daily, weekly, etc.). Each interval represents the time-period when your user enters the funnel. + +## Bar Chart + +The bar in Funnels allow you to visualize your measurement as an aggregate across the entire date range of the report. You can toggle between evaluating the performance of your [entire funnel across all steps or between specific steps](/docs/reports/funnels/measurements#step-selection). The metric view behaves in the same way as a bar chart, but optimizes the visualization for viewing as a KPI. + +## Top Paths + +If you have selected **any order** for your funnels steps, you have the option to select **Top paths** from the drop-down list to view a Sankey visualization of how your users are performing the steps in your funnel. + +![/Screen_Shot_2022-07-12_at_3.30.32_PM.png](/Screen_Shot_2022-07-12_at_3.30.32_PM.png) diff --git a/pages/docs/reports/insights.mdx b/pages/docs/reports/insights.mdx index 609489b938..00ff768ed0 100644 --- a/pages/docs/reports/insights.mdx +++ b/pages/docs/reports/insights.mdx @@ -76,364 +76,9 @@ Choosing a different chart can help you visualize data better. Line charts help You now have a full analysis that you can use and add onto a Board, or use as a starting point to dig in further. This might mean adding more filters or breakdowns, or adding another metric and seeing if there's an interesting comparison to be made. You could also change the counting type or the chart type. -## Basic Features -### Metric Types +### FAQ -| Metric Type | Description | -| --- | --- | -| Event | A metric based off of a single event. The metric could measure the total number of occurences, unique users, or aggregates a property of this event. | -| Profile | A metric based off of the user or group profiles. You can measure the number of profiles, or an aggregate on properties of the profiles. | -| Formula | A metric that is a function of other metrics. You can select a saved formula, or create a new formula based on the existing metrics in the report. | -| Funnel | A metric based off a funnel behavior. You can select a saved funnel behavior or define a new funnel, then choose a measurement on that funnel to form a funnel metric. By default measures conversion rate on all steps of the funnel. | -| Retention | A metric based off a retention behavior. You can select a saved retention behavior or define a new retention, then choose a measurement to form a retention metric. By default, measures retention rate. | -| Cohort | A metric based off of a defined cohort. Measures the number of users who are part of that cohort. | +#### +- Some content about users in multiple segments, events not present, cardinality, null values -If choosing Formula, Funnel, Retention or Cohort, you will be prompted first to selected a saved definition. If you wish to start by defining your own behavior, press "Create" in the top right of the menu. - -### Chart Types - -Insights feature multiple visualizations to help you view the query results in the clearest chart type. By default, Insights displays the results on the line chart, which helps you understand how metrics trend over time. However, another chart type might present the results with more clarity. In Insights, you can choose to get a metric calculated either across the entire time period selected in the date picker or on a time-segmented view of the metric (e.g. daily breakdown). - -- Metric calculated across the entire time period - - Bar chart - - Stacked bar chart - - Pie chart - - Metric chart - - Table chart -- Metric time-segmented - - Line chart - - Stacked line chart - - Column chart - - Stacked Column chart - -### Rename an Event within a Report - -Click on the "three dots" icon beside an event and click Rename to rename it. This will only affect the current report, and will not change the event's name in other reports. - -### Sorting - -#### Bar chart - -When you view a bar chart, you have four different sorting options: A-Z Ascending, Z-A Descending, Value Ascending, or Value Descending. To switch the sorting view, select the **Events** or **property name** column header in the upper left hand of the results and then select which sorting order you would like to see. - -![Sorting Bar Chart](/sorting-bar-chart.png) - -#### Line chart - -Line charts in Insights are accompanied by a table of values that gives users another way to consume the trends information. This data table can also be sorted by clicking the column headers. - -Click on a column header to sort by that column. Click the header again to reverse the sorting order. For example, the table below is sorted by event counts on August 2nd: - -![Sorting Line Chart](/sorting-line-chart-1.png) - -Results that are segmented (from one or more "group by" clauses in your query) have four different sorting options when you click on the "segment column" headers: - -- Segment A-Z Ascending: sort by segment name in ascending order -- Segment Z-A Descending: sort by segment name in descending order -- Value Ascending: sort by segment value in ascending order -- Value Descending. sort by segment value in descending order - -When sorting by segments, the sort is carried out from left to right. - -![Sorting Line Chart](/sorting-line-chart-2.gif) - -Clicking on the "Average" data column performs a flat sort across all segments: - -![Sorting Line Chart](/sorting-line-chart-3.png) - -#### Table chart -Tables are useful to see the precise values of your data and to quickly scan multiple metrics per segment. In general, tables work similarly to the rest of Insights, with a few extra features. - -##### Sort Order -You can configure how you want rows in the table to be sorted, with our global sorting control. -![Sorting.gif](https://github.com/mixpanel/docs/assets/2077899/a61948a6-3e4a-4e5d-9b75-3f4b14cb1450) - -###### Grouped View vs Ungrouped View -The Ungrouped View removes all hierarchy and makes the table flat. Each combination of segment values is treated as a row, independently of the other rows. - -![image](https://github.com/mixpanel/docs/assets/2077899/e57400a1-a86c-4d46-9ffb-379306586d8d) - -The Grouped View preserves the hierarchy of breakdowns. It shows you segments within a breakdown as displayed below. This view is only applicable when you have 2 or more breakdowns - -![image](https://github.com/mixpanel/docs/assets/2077899/2a72e93c-c332-4418-83e1-91bb24e2d271) - -###### Alphabetical vs Value-Based Sorting -You can sort segments alphabetically or by the value of a particular metric. In the grouped view, sorting is configured on a per-breakdown level and respects the breakdown hierarchy. - -In the below image, we sort Country *within* Item Category, which respects the hierarchy. -![image](https://github.com/mixpanel/docs/assets/2077899/4697ce00-d394-46ce-b538-66ec91ccd6e7) - -Hierarchy is defined by the breakdown order in the query panel: -![image](https://github.com/mixpanel/docs/assets/2077899/ff2f72b3-89bc-459e-b8b7-e81655d04bb7) - -###### View “N” segments - -The View “N” control lets you decide how many rows to display per breakdown in your table. -![View_N_gif](https://github.com/mixpanel/docs/assets/2077899/4fb0fd18-2ef7-416b-adaa-c7299da0f7b3) - -In the ungrouped view, choose the number of rows to display: -![image](https://github.com/mixpanel/docs/assets/2077899/b1b25b19-51be-4934-bbfd-7562e0f98d4a) - -In the grouped view, you can choose the number of rows you want to display for each breakdown: -![image](https://github.com/mixpanel/docs/assets/2077899/f9f8c83c-34ed-44bd-b4e7-f60b70255a6f) - -![image](https://github.com/mixpanel/docs/assets/2077899/b09c1ad1-1392-4ec0-9358-361f677c600d) - -**Notes** -- View N only controls how many segments to display. To decide which segments to display i.e if it’s the top segments by value or bottom segments by value or alphabetical, please change the “Sort Order”. -- View N will show the minimum of N and how many segments are in your report. For example, if you set N=10 but you only have 7 segments, we will only show 7 rows. -- When selecting “Show All”, the maximum number of segments displayed in the UI will be 3000 given cardinality limits. If your breakdown has more than 3000 segments, you'll only see the top 3000, dictated by the sort order. - -##### Overall and Segment Sub-Totals - -**Overall:** This refers to the value considering all the segments, independent of whether displayed or not based on your View N control; i.e changes to View N will not affect Overall numbers -![image](https://github.com/mixpanel/docs/assets/2077899/3d6556a4-9468-4d1f-8979-4fdb512f2aaa) - -**Sub-Totals:** In the grouped view, in addition to the Overall, segment sub-totals are also displayed. Similar to “Overall”, these values are independent of the View N control - -![image](https://github.com/mixpanel/docs/assets/2077899/ee7d8c9b-f738-4a5b-8967-300cf8322f76) - -### Visualization Settings - -The visualization options allow you to choose how the data is visualized. The options are: - -- **Linear:** This is the standard view for the chart. -- **Logarithmic:** A nonlinear scale based on orders of magnitude, rather than a standard linear scale, so the value represented by each equidistant mark on the scale is the value at the previous mark multiplied by a constant. - -## Advanced - -### Formulas - -Use Formulas to make calculations using simple arithmetic operators. - -Mixpanel supports the following operators: - -- \+ : Add -- \- : Subtract -- \* : Multiply -- / : Divide -- () : Use parentheses to influence the order of operations - -You can also use numbers as constants in a formula. Multiply a ratio by 100 to display as a percentage, for example. Divide a property value tracked in seconds by 3,600 to display the value in hours. You can rename a formula by selecting Rename in the overflow menu of the formula. - -Click the **Metrics** button, then select Formula.. Each event in the query shows a letter next to it, which indicates its variable name. Use these letters in combination with the operators to calculate a more advanced query. For example, you can use the DAU, WAU, and MAU functions in Formulas to calculate the stickiness of your product: - -![Formulas 1](/advanced-formulas-1.png) - -To note, you cannot nest a formula metric when constructing another formula. - -#### Save formulas for re-use - -Use existing events to create calculated formulas, like Bounce Rate & % Active Users, that can be saved and reused by others within the project. - -![saveformula.gif](/saveformula.gif) - -Some nuances to note: -- Once you save a formula, A,B,C refer to what’s **within** the saved formula modal -- To edit a saved formula, expand the metric and edit inline, and then save -- When a saved metric is updated, it will update across all reports it’s being used in -- A saved formula can’t reference another formula - -To access and re-use saved formulas, click on “+Formula”, and then see the list of saved formulas. You can also look at all the saved formulas in the Lexicon tab “Formulas”. Some callouts regarding permissions: -- All roles can create a saved formula, but only some roles can share them with the whole project for re-use -- You can only look at saved formulas created by you or shared with you - -![reuseformula.gif](/reuseformula.gif) - -### Custom Bucketing - -Insights will automatically group your high-cardinality segments into buckets. Buckets can be edited by using the "Custom Buckets" option in the overflow menu: -You can choose "Even" to get buckets of uniform size, and you can choose "Varied" to get buckets of different sizes. This helps with organizing outliers, or with drilling deeper into particular ranges. - -![Bucketing](/advanced-bucketing.png) - -### Time Period Comparisons - -Compare the current period of time to previous periods to track trends and growth in your product’s use. Compare traffic from a specific campaign period or event from one year to the next, or compare the success of that campaign to your normal traffic. - -Note that if a data point for a previous year falls on a weekend, the data point is automatically moved to the next Monday to give a clearer picture of the data change from one year to the next. - -Click on the **Compare to past** button at the top of your Insights graph and select the time period you wish to compare to. You can also select a custom date range. - -![Time Period Comparison](/advanced-time-period-comparison.gif) - -### Value Comparisons - -When you have multiple metrics, or have broken down a metric by a property, you can compare them against each and the relative value. Click on **Compare** -> **Overall**. This works for all measurements. For a "totals" measurement, you can see the percentage that a particular segment makes up. For non-sumable aggregations, it compares the segment value to the whole, unsegmented value. - -![Value Setting](/advanced-value-comparison.png) - -### Profile Analysis - -Profile metrics allow you to access profile data and visualize your users with filters and breakdowns based on their profile properties. When exploring Profiles, you are always analyzing all user profiles. Select the [Measurement](/docs/reports/insights#measurements) you want to use to calculate results by clicking on **Total** and selecting an option from the drop-down. You can calculate based on users or profile property value. - -

- -

- -### Annotations - -To clarify the results in your Insights report, add detailed annotations directly to the line chart. Annotations are tied to a specific date on the chart, rather than a specific data point on the chart. - -To add an annotation, hover your mouse over the point on the chart you want to annotate, and click the blue **+** button that appears. Enter a description for the annotation, such as a holiday that occurred on that day or the end date of your fiscal year, then click **Save**. If you accidentally selected the incorrect date on the chart, you can edit the date and time of the annotation in this window. - -![Annotations 1](/advanced-annotations-1.png) - -View an existing annotation by clicking on the number found at the bottom of a report. You will be able to see who submitted the annotation. - -![Annotations 2](/advanced-annotations-2.png) - -Hover the cursor over the annotation to edit or delete it. Click on the **pencil icon** to edit an annotation, or the **trash icon** to delete an annotation. Add additional annotations to the same date by clicking **Add annotation**. - -![Annotations 3](/advanced-annotations-3.png) - -### Measurements - -

- -

- -Measurements in Mixpanel reports allow you to perform more complex calculations on your queries - this includes computing aggregate values of your event and property data, including totals, uniques, and averages. - -The following measurements are only available in Insights, and are separated into groups based on what is being calculated: Total, Unique, Count users, aggregate property values, aggregate property values per user, and count sessions. - -Select the measurement you want to use to calculate results by clicking on **Unique Users** and selecting an option from the drop-down. You can calculate based on events, users, event property value, event property value per user, and sessions. - -![Measurements 1](/advanced-data-functions-1.png) - -The following functions have additional aggregation options which you will be prompted to select: - -| Function | Aggregation options | -| --- | --- | -| Frequency per User | Total Per User | -| Aggregate Property | Sum
Average
Median
[Distinct Count](https://www.loom.com/share/7d0e42f847c24b3c8720d5b6a6bedeb4)
Percentiles (P25,P75,P90,P99)
Minimum
Maximum | -| Aggregate Property per User | Sum
Average
Distinct value count
Minimum
Maximum | - -These functions provide additional aggregation options following the initial calculation because they are “per user” calculations. “Per user” calculations first calculate the value per user, which is an unhelpful query in its raw form, but becomes useful when you perform an aggregation on that calculation. - -Selecting any of these functions gives you the option to choose different ways to aggregate this data. The default aggregation is **Average**, which you can click on to select a different option such as distribution, median, 25/75/90th percentiles, minimum, and maximum. - -![Measurements 2](/advanced-data-functions-2.png) - -If the measurement you select calculates based on property (“Event Property Values” or “Event Property Values Per User”), you will be prompted to select an event property. You can find more information about each measurement and how they are calculated below: - -#### Events - -| Function Name | Events Calculation | Profiles Calculation | -| --- | --- | --- | -| Total Events | Total count of [event] performed.
Example: How many times did my users watch a video? | N/A | -| Frequency per User | The number of events performed per user.
Example: How many videos were watched per user?
Aggregation options: Average, distribution, median, percentiles, minimum, maximum | N/A | - -#### Users - -This can refer to measuring the total number of user profiles, as well as the number of unique users that performed an event. -DAU, WAU, and MAU are accessed through the advanced settings of unique users. Select the > arrow to choose any XAU options. - -If you select the DAU, WAU, or MAU function for a date range that includes the current day, the query will take the end of the current day as the end of the query’s time segment (even though it’s in the future). For example, today is April 25th, and it’s 4:22 PM. If you make a query to show WAU and you select “current day” as your date range, the query will return the count of unique users between April 19 at 12:00:00 AM and April 25 at 11:59:59. - -![Measurements 3](/advanced-data-functions-3.png) - -| Function Name | Events Calculation | Profiles Calculation | -| --- | --- | --- | -| Total | N/A | Total count of user profiles.

**Example**: What's my total number of users? | -| Unique Users | The number of users who performed [event] or are a part of the cohort.

**Example**: What's the count of users who watched a video? | N/A | -| Daily Active Users (DAU) | The number of users who performed [event] within the last 24 hours.

**Example**: What's the count of users who watched a video on the last day? | N/A | -| Weekly Active Users (WAU) | The number of users who performed [event] within the last 7 days.

**Example**: What's the count of users who watched a video in the week? | N/A | -| Monthly Active Users (MAU) | The number of users who performed [event] within the last 30 days.

**Example**: What's the count of users who watched a video in the last month? | N/A | - -**How do breakdowns work with Uniques?** - -When you apply a breakdown to a metric, by default, Mixpanel tells you how many unique users contributed to each segment. For example, in the image below, you can see there were a total of 2441 unique users, while the sum of individual segments is more than 3000. This is correct. That is because one user could have seen both a Home Page and a Shop Page, so they get counted as a user towards both segments. - -By default, Mixpanel answers the question: per segment, tell me the number of unique users, DON'T tell me how the 2441 users are distributed across the various pages with a user being counted only towards one segment, which will require assigning a user to one segment even if they contributed towards multiple segments. - -![image](/uniques_default.png) - -There are some cases though, where you want to know how the 2441 users are distributed, generally either by their first or last action. For example, based on the last page (segment) a user saw, tell me the distribution of users. You can enable this now via the advanced control for Uniques, by choosing which segment to associate a user to: either the first segment or the last segment in the chart date range (7D in the below image) - -![image](/uniques_count_once.png) - -To note - in a line chart, there are two concepts of time period: chart date range (3M below) and time interval (weekly interval below). When advanced controls are used in a line chart, it assigns a segment based on the first/last segment for each time interval, NOT across all time intervals in the chart range. For eg. user Joey could count towards Contact Page Wk of Feb 27 and Shop Page Wk of March 6. But in the same time interval, they would count only towards one segment. - -![image](/uniques_count_once_line.png) - -#### Aggregate Property - -| Function Name | Events Calculation | Profiles Calculation | -| --- | --- | --- | -| Sum | The total of a numeric property value across all instances of [event].

**Example**: What's the total number of minutes of videos watched? | The total of a numeric property value across all user profiles.
Example: What's the total revenue across all users? | -| Average | Average of a numeric property value across all instances of [event].

**Example**: What's the average number of minutes per video watched? | Average of a numeric property value across all user profiles.
Example: What's the average revenue across all users? | -| Distinct count | Calculates the unique count of property values across all instances of [event].

**Example**: How many unique songs were played in the last 30 days? | Calculates the unique count of property values across all profiles.
Example: How many unique countries were our video watchers from? | -| Median | Median of a numeric property value across all instances of [event].

**Example**: What's the median number of minutes per video watched? | Median of a numeric property value across all user profiles.
Example: What's the median revenue across all users? | -| Percentiles (25/75/90/99) | The 25/75/90/99th percentile of a numeric property value across all instances of [event].

**Example**: What's the 25th percentile number of minutes of videos watched? | The 25/75/90/99th percentile of a numeric property value across all user profiles.
Example: What's the 25th percentile revenue across all users? | -| Minimum | Minimum of a numeric property value across all instances of [event].

**Example**: What's the minimum number of minutes per video watched? | Minimum of a numeric property value across all user profiles.
Example: What's the minimum revenue across all users? | -| Maximum | Maximum of a numeric property value across all instances of [event].

**Example**: What's the maximum number of minutes per video watched? | Maximum of a numeric property value across all user profiles.
Example: What's the maximum revenue across all users? | - -#### Aggregate Property per User - -| Function Name | Events Calculation | Profiles Calculation | -| --- | --- | --- | -| Sum | The total of a numeric property value across all instances of [event] per user.

**Example**: What's the total number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | -| Average | Average of a numeric property value across all instances of [event] per user.

**Example**: What's the average number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | -| Distinct count | The number of distinct property values per user.

**Example**: How many different videos did each user watch?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | -| Minimum | Minimum of a numeric property value across all instances of [event] per user.

**Example**: What's the minimum number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | -| Maximum | Maximum of a numeric property value across all instances of [event] per user.

**Example**: What's the maximum number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | - -#### Total Sessions - -| Function Name | Events Calculation | Profiles Calculation | -| --- | --- | --- | -| Sessions with event | The number of sessions that contain [event].

**Example**: What's the total number of sessions in which users watched a video? | N/A | - -#### Additional Aggregation Option Examples - -| Measurement | Average | Distribution | Median | Percentiles (25/75/90) | Minimum/Maximum | -| --- | --- | --- | --- | --- | --- | -| Total per user | What's the average number of songs played per user? | What is the distribution of my users by the number of songs played? | What's the median number of songs played per user? | How many songs did the 90th percentile user listen to? | How many songs did my least/most active user listen to? | -| Sum of property value count per user | What's the average cumulative watch time per user? | What's the distribution of my users by the cumulative minutes of content watched? | What's the median of the cumulative watch time per user? | How many cumulative minutes has the 90th percentile user watched? | How much has the lowest/highest spender spent? | -| Average of property value count per user | What's the average of the average cart value for each rider? | What's the distribution of my users by the average cart value per user? | What's the median of the average cart value per user? | What's the average cart value for the 90th percentile user? | What's the minimum/maximum average cart value? | -| Distinct property value count per user | What's the average number of unique song titles heard by my users? | What's the distribution of my users by the number of unique song titles listened to? | How many unique songs does the median user listen to? | How many unique songs does the 90th percentile user listen to? | What's the minimum/maximum number of unique songs my users listen to? | -| Minimum property value count per user | What's the average of the minimum ratings provided per user? | What's the distribution of my users by the minimum rating provided? | What's the median of the minimum ratings provided by users? | What's the minimum rating provided by the 90th percentile user? | What's the minimum rating across all ratings?? | -| Maximum property value count per user | What's the average of the maximum gaming session length per user? | What's the distribution of my users by the maximum gaming session length? | What's the median of the maximum gaming session length per user? | What's the maximum gaming session length provided by the 90th percentile user? | How long has the longest gaming session lasted across our users? | - -Here's a quick overview on "Distinct count" of property values, and how that differs from "Distinct count" of property values per user: - -Here are some use cases that are now possible with "Distinct count" of property values: - -- How many **unique items** were added to cart yesterday? -- How many **unique songs/videos** were played in the last 30 days? -- How many **unique files** were worked on in the last week? - -### Analysis Settings - -Allows you to change the metric being measured. Access by going into the advanced section of the measurement menu. - -![Rolling and Cumulative](/rolling-cumulative.png) - -- **Rolling Average:** Rolling analysis calculates the rolling average of the data set. A rolling average curve is a series of averages from subsets of data. Use rolling average analysis to remove noise or spikes from data and smooth out trends over time. Mixpanel calculates the rolling average based on the selected time interval (hour, day, week, month, or quarter) for each data point in the graph.
-For example, if you make a rolling analysis query for the past 30 days, Mixpanel calculates the rolling 7-day average by default. The value reported on each day in the line graph is the average of the values from the 7 days leading to that day. In the case of the first 6 days in your selected time period, the 7-day-average calculation will include days before the selected time period. -- **Cumulative:** Adds up the values of each point on the graph as it goes along, so the height of the line will increase over time. - -

- -

- -### View Users - -Click a segment in an Insights report to see the list of users that underlie that data point. This helps see a representative sample of users from any analysis, so you can drill into anomalies or simply get to know your users. You can also save this user list as a cohort to either export or use for message targeting. - -See this [video walkthrough](https://www.loom.com/embed/5568e266532b4804a1c2d36d678eb1a2) for examples of how View Users can help you understand users contributing to a specific metric. - -### View Events - -Click on a chart segment in Insights and view the raw events that made up that metric. You will be redirected to the Events page. - -![View Events](/advanced-view-events.gif) - -### View Sample Events - -You can hover over any event and in the context panel, you now have the ability to "View Sample Events", which redirects you to the Events page with the 100 most recent samples of that hovered event: -You can see a few samples of an event to help you decide whether that's the right event you want for your analysis or which property you should use for filters/breakdowns. - -![View Sample Events](/advanced-view-sample-events.gif) diff --git a/pages/docs/reports/insights/_meta.json b/pages/docs/reports/insights/_meta.json new file mode 100644 index 0000000000..7606d545a1 --- /dev/null +++ b/pages/docs/reports/insights/_meta.json @@ -0,0 +1,5 @@ +{ + "metrics": "Metrics", + "measurements": "Measurements", + "visualizations": "Visualizations" +} diff --git a/pages/docs/reports/insights/measurements.md b/pages/docs/reports/insights/measurements.md new file mode 100644 index 0000000000..a69496abe6 --- /dev/null +++ b/pages/docs/reports/insights/measurements.md @@ -0,0 +1,141 @@ +# Measurements + + +## Overview + +Measurements in Mixpanel reports allow you to perform more complex calculations on your queries - this includes computing aggregate values of your event and property data, including totals, uniques, and averages. + +

+ +

+ +## Insights Measurements + +The following measurements are only available in Insights, and are separated into groups based on what is being calculated: Total, Unique, Count users, aggregate property values, aggregate property values per user, and count sessions. + +Select the measurement you want to use to calculate results by clicking on **Unique Users** and selecting an option from the drop-down. You can calculate based on events, users, event property value, event property value per user, and sessions. + +![Measurements 1](/advanced-data-functions-1.png) + +### Aggregations + +The following measurements have additional aggregation options which you will be prompted to select: + +| Function | Aggregation options | +| --- | --- | +| Frequency per User | Distribution
Average
Median
Percentile
Minimum
Maximum | +| Aggregate Property | Sum
Average
Median
[Distinct Count](https://www.loom.com/share/7d0e42f847c24b3c8720d5b6a6bedeb4)
Percentiles (P25,P75,P90,P99)
Minimum
Maximum | +| Aggregate Property per User | Sum
Average
Distinct value count
Minimum
Maximum | + +These functions provide additional aggregation options following the initial calculation because they are aggregates on all your users. The Aggregate Property measurement calculates property values across all your users using the selected aggregation method. The “Per user” calculations first calculate the value per user, which is an unhelpful query in its raw form, but becomes useful when you perform an aggregation on that calculation. + +Selecting any of these functions gives you the option to choose different ways to aggregate this data. The default aggregation is **Average**, which you can click on to select a different option such as distribution, median, 25/75/90th percentiles, minimum, and maximum. + +![Measurements 2](/advanced-data-functions-2.png) + +If the measurement you select calculates based on property (“Event Property Values” or “Event Property Values Per User”), you will be prompted to select an event property. You can find more information about each measurement and how they are calculated below. + +## Measurements Reference + +#### Event Measurement + +| Function Name | Events Calculation | Profiles Calculation | +| --- | --- | --- | +| Total Events | Total count of [event] performed.
Example: How many times did my users watch a video? | N/A | +| Frequency per User | The number of events performed per user.
Example: How many videos were watched per user?
Aggregation options: Average, distribution, median, percentiles, minimum, maximum | N/A | + +#### Users + +This can refer to measuring the total number of user profiles, as well as the number of unique users that performed an event. +DAU, WAU, and MAU are accessed through the advanced settings of unique users. Select the > arrow to choose any XAU options. + +If you select the DAU, WAU, or MAU function for a date range that includes the current day, the query will take the end of the current day as the end of the query’s time segment (even though it’s in the future). For example, today is April 25th, and it’s 4:22 PM. If you make a query to show WAU and you select “current day” as your date range, the query will return the count of unique users between April 19 at 12:00:00 AM and April 25 at 11:59:59. + +![Measurements 3](/advanced-data-functions-3.png) + +| Function Name | Events Calculation | Profiles Calculation | +| --- | --- | --- | +| Total | N/A | Total count of user profiles.

**Example**: What's my total number of users? | +| Unique Users | The number of users who performed [event] or are a part of the cohort.

**Example**: What's the count of users who watched a video? | N/A | +| Daily Active Users (DAU) | The number of users who performed [event] within the last 24 hours.

**Example**: What's the count of users who watched a video on the last day? | N/A | +| Weekly Active Users (WAU) | The number of users who performed [event] within the last 7 days.

**Example**: What's the count of users who watched a video in the week? | N/A | +| Monthly Active Users (MAU) | The number of users who performed [event] within the last 30 days.

**Example**: What's the count of users who watched a video in the last month? | N/A | + +##### Uniques and Breakdowns + +When you apply a breakdown to a metric, by default, Mixpanel tells you how many unique users contributed to each segment. For example, in the image below, you can see there were a total of 2441 unique users, while the sum of individual segments is more than 3000. This is correct. That is because one user could have seen both a Home Page and a Shop Page, so they get counted as a user towards both segments. + +By default, Mixpanel answers the question: per segment, tell me the number of unique users, DON'T tell me how the 2441 users are distributed across the various pages with a user being counted only towards one segment, which will require assigning a user to one segment even if they contributed towards multiple segments. + +![image](/uniques_default.png) + +There are some cases though, where you want to know how the 2441 users are distributed, generally either by their first or last action. For example, based on the last page (segment) a user saw, tell me the distribution of users. You can enable this now via the advanced control for Uniques, by choosing which segment to associate a user to: either the first segment or the last segment in the chart date range (7D in the below image) + +![image](/uniques_count_once.png) + +To note - in a line chart, there are two concepts of time period: chart date range (3M below) and time interval (weekly interval below). When advanced controls are used in a line chart, it assigns a segment based on the first/last segment for each time interval, NOT across all time intervals in the chart range. For eg. user Joey could count towards Contact Page Wk of Feb 27 and Shop Page Wk of March 6. But in the same time interval, they would count only towards one segment. + +![image](/uniques_count_once_line.png) + +#### Aggregate Property + +| Function Name | Events Calculation | Profiles Calculation | +| --- | --- | --- | +| Sum | The total of a numeric property value across all instances of [event].

**Example**: What's the total number of minutes of videos watched? | The total of a numeric property value across all user profiles.
Example: What's the total revenue across all users? | +| Average | Average of a numeric property value across all instances of [event].

**Example**: What's the average number of minutes per video watched? | Average of a numeric property value across all user profiles.
Example: What's the average revenue across all users? | +| Distinct count | Calculates the unique count of property values across all instances of [event].

**Example**: How many unique songs were played in the last 30 days? | Calculates the unique count of property values across all profiles.
Example: How many unique countries were our video watchers from? | +| Median | Median of a numeric property value across all instances of [event].

**Example**: What's the median number of minutes per video watched? | Median of a numeric property value across all user profiles.
Example: What's the median revenue across all users? | +| Percentiles (25/75/90/99) | The 25/75/90/99th percentile of a numeric property value across all instances of [event].

**Example**: What's the 25th percentile number of minutes of videos watched? | The 25/75/90/99th percentile of a numeric property value across all user profiles.
Example: What's the 25th percentile revenue across all users? | +| Minimum | Minimum of a numeric property value across all instances of [event].

**Example**: What's the minimum number of minutes per video watched? | Minimum of a numeric property value across all user profiles.
Example: What's the minimum revenue across all users? | +| Maximum | Maximum of a numeric property value across all instances of [event].

**Example**: What's the maximum number of minutes per video watched? | Maximum of a numeric property value across all user profiles.
Example: What's the maximum revenue across all users? | + +#### Aggregate Property per User + +| Function Name | Events Calculation | Profiles Calculation | +| --- | --- | --- | +| Sum | The total of a numeric property value across all instances of [event] per user.

**Example**: What's the total number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | +| Average | Average of a numeric property value across all instances of [event] per user.

**Example**: What's the average number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | +| Distinct count | The number of distinct property values per user.

**Example**: How many different videos did each user watch?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | +| Minimum | Minimum of a numeric property value across all instances of [event] per user.

**Example**: What's the minimum number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | +| Maximum | Maximum of a numeric property value across all instances of [event] per user.

**Example**: What's the maximum number of hours of videos watched per user?
**Aggregation options**: Average, distribution, median, percentiles, minimum, maximum | N/A | + +#### Total Sessions + +| Function Name | Events Calculation | Profiles Calculation | +| --- | --- | --- | +| Sessions with event | The number of sessions that contain [event].

**Example**: What's the total number of sessions in which users watched a video? | N/A | + +Learn more about [Sessions](/docs/features/sessions). + +##### Additional Aggregation Option Examples + +| Measurement | Average | Distribution | Median | Percentiles (25/75/90) | Minimum/Maximum | +| --- | --- | --- | --- | --- | --- | +| Total per user | What's the average number of songs played per user? | What is the distribution of my users by the number of songs played? | What's the median number of songs played per user? | How many songs did the 90th percentile user listen to? | How many songs did my least/most active user listen to? | +| Sum of property value count per user | What's the average cumulative watch time per user? | What's the distribution of my users by the cumulative minutes of content watched? | What's the median of the cumulative watch time per user? | How many cumulative minutes has the 90th percentile user watched? | How much has the lowest/highest spender spent? | +| Average of property value count per user | What's the average of the average cart value for each rider? | What's the distribution of my users by the average cart value per user? | What's the median of the average cart value per user? | What's the average cart value for the 90th percentile user? | What's the minimum/maximum average cart value? | +| Distinct property value count per user | What's the average number of unique song titles heard by my users? | What's the distribution of my users by the number of unique song titles listened to? | How many unique songs does the median user listen to? | How many unique songs does the 90th percentile user listen to? | What's the minimum/maximum number of unique songs my users listen to? | +| Minimum property value count per user | What's the average of the minimum ratings provided per user? | What's the distribution of my users by the minimum rating provided? | What's the median of the minimum ratings provided by users? | What's the minimum rating provided by the 90th percentile user? | What's the minimum rating across all ratings?? | +| Maximum property value count per user | What's the average of the maximum gaming session length per user? | What's the distribution of my users by the maximum gaming session length? | What's the median of the maximum gaming session length per user? | What's the maximum gaming session length provided by the 90th percentile user? | How long has the longest gaming session lasted across our users? | + +Here's a quick overview on "Distinct count" of property values, and how that differs from "Distinct count" of property values per user: + +Here are some use cases that are now possible with "Distinct count" of property values: + +- How many **unique items** were added to cart yesterday? +- How many **unique songs/videos** were played in the last 30 days? +- How many **unique files** were worked on in the last week? + +## Analysis Settings + +Allows you to change the metric being measured. Access by going into the advanced section of the measurement menu. + +![Rolling and Cumulative](/rolling-cumulative.png) + +- **Rolling Average:** Rolling analysis calculates the rolling average of the data set. A rolling average curve is a series of averages from subsets of data. Use rolling average analysis to remove noise or spikes from data and smooth out trends over time. Mixpanel calculates the rolling average based on the selected time interval (hour, day, week, month, or quarter) for each data point in the graph.
+For example, if you make a rolling analysis query for the past 30 days, Mixpanel calculates the rolling 7-day average by default. The value reported on each day in the line graph is the average of the values from the 7 days leading to that day. In the case of the first 6 days in your selected time period, the 7-day-average calculation will include days before the selected time period. +- **Cumulative:** Adds up the values of each point on the graph as it goes along, so the height of the line will increase over time. + +

+ +

diff --git a/pages/docs/reports/insights/metrics.md b/pages/docs/reports/insights/metrics.md new file mode 100644 index 0000000000..079b91b9ed --- /dev/null +++ b/pages/docs/reports/insights/metrics.md @@ -0,0 +1,77 @@ +# Metrics + +## Overview +The Insights Report supports 6 different metric types, which you can combine under a single report for your analysis. + +## Metric Types + +| Metric Type | Description | +| --- | --- | +| Event | A metric based off of a single event. The metric could measure the total number of occurences, unique users, or aggregates a property of this event. | +| Profile | A metric based off of the user or group profiles. You can measure the number of profiles, or an aggregate on properties of the profiles. | +| Formula | A metric that is a function of other metrics. You can select a saved formula, or create a new formula based on the existing metrics in the report. | +| Funnel | A metric based off a funnel behavior. You can select a saved funnel behavior or define a new funnel, then choose a measurement on that funnel to form a funnel metric. By default measures conversion rate on all steps of the funnel. | +| Retention | A metric based off a retention behavior. You can select a saved retention behavior or define a new retention, then choose a measurement to form a retention metric. By default, measures retention rate. | +| Cohort | A metric based off of a defined cohort. Measures the number of users who are part of that cohort. | + +If choosing [Formula](/docs/reports/insights/metrics#formulas), Funnel, Retention or Cohort, you will be prompted first to select a saved definition. If you wish to start by defining your own behavior, press "Create" in the top right of the menu. + +Learn more about [Saved Behaviors](/docs/features/saved-behaviors) and [Cohorts](/docs/users/cohorts). + +### Event + +Event metrics allow you to measure a single event. You can aggregate multiple events using a single event metric by using a custom event [custom events](/docs/features/custom-events). + +### Profile + +Profile metrics allow you to access profile data and visualize your users with filters and breakdowns based on their profile properties. When exploring Profiles, you are always analyzing all user profiles. Select the [Measurement](/docs/reports/insights#measurements) you want to use to calculate results by clicking on **Total** and selecting an option from the drop-down. You can calculate based on users or profile property value. + +

+ +

+ +### Formulas + +Use Formulas to make calculations between multiple metrics. + +Mixpanel supports the following operators: + +- \+ : Add +- \- : Subtract +- \* : Multiply +- / : Divide +- () : Use parentheses to influence the order of operations + +You can also use numbers as constants in a formula. Multiply a ratio by 100 to display as a percentage, for example. Divide a property value tracked in seconds by 3,600 to display the value in hours. You can rename a formula by selecting Rename in the overflow menu of the formula. + +Click the **Metrics** button, then select Formula.. Each event in the query shows a letter next to it, which indicates its variable name. Use these letters in combination with the operators to calculate a more advanced query. For example, you can use the DAU, WAU, and MAU functions in Formulas to calculate the stickiness of your product: + +![Formulas 1](/advanced-formulas-1.png) + +To note, you cannot nest a formula metric when constructing another formula. + +#### Save formulas for re-use + +Use existing events to create calculated formulas, like Bounce Rate & % Active Users, that can be saved and reused by others within the project. + +![saveformula.gif](/saveformula.gif) + +Some nuances to note: +- Once you save a formula, A,B,C refer to what’s **within** the saved formula modal +- To edit a saved formula, expand the metric and edit inline, and then save +- When a saved metric is updated, it will update across all reports it’s being used in +- A saved formula can’t reference another formula + +To access and re-use saved formulas, click on “+Formula”, and then see the list of saved formulas. You can also look at all the saved formulas in the Lexicon tab “Formulas”. Some callouts regarding permissions: +- All roles can create a saved formula, but only some roles can share them with the whole project for re-use +- You can only look at saved formulas created by you or shared with you + +![reuseformula.gif](/reuseformula.gif) + +### Funnel and Retention Metric + +You can use a saved funnel or retention definition as a metric in your report. Learn more about [Funnels](docs/reports/funnels), [Retention](docs/reports/retention), and [Saved Behaviors](/docs/features/saved-behaviors). + +## Cohorts + +Cohort metrics allow you to measure the size of your cohort and how it changes over time. Learn more about [Cohorts](/docs/users/cohorts). diff --git a/pages/docs/reports/insights/visualizations.md b/pages/docs/reports/insights/visualizations.md new file mode 100644 index 0000000000..b4188d4a30 --- /dev/null +++ b/pages/docs/reports/insights/visualizations.md @@ -0,0 +1,128 @@ +# Visualizations + +## Overview + +Insights feature multiple visualizations to help you view the query results in the clearest chart type. + +## Chart Types + +By default, Insights displays the results on the line chart, which visualize how metrics trend over time. However, another chart type might present the results with more clarity. In Insights, you can choose visualizations that aggregate your metric across an entire date range or per time interval (e.g. hour, day, week, etc.). + +These visualizations aggregate your metric across the entire date range: + - Bar chart + - Stacked Bar chart + - Pie chart + - Metric chart + - Table chart + +These visualizations aggregate your metric per each selected time interval: + - Line chart + - Stacked line chart + - Column chart + - Stacked Column chart + +## Sorting + +### Bar chart + +When you view a bar chart, you have four different sorting options: A-Z Ascending, Z-A Descending, Value Ascending, or Value Descending. To switch the sorting view, select the **Events** or **property name** column header in the upper left hand of the results and then select which sorting order you would like to see. + +![Sorting Bar Chart](/sorting-bar-chart.png) + +### Line chart + +Line charts in Insights are accompanied by a table of values that gives users another way to consume the trends information. This data table can also be sorted by clicking the column headers. + +Click on a column header to sort by that column. Click the header again to reverse the sorting order. For example, the table below is sorted by event counts on August 2nd: + +![Sorting Line Chart](/sorting-line-chart-1.png) + +Results that are segmented (from one or more "group by" clauses in your query) have four different sorting options when you click on the "segment column" headers: + +- Segment A-Z Ascending: sort by segment name in ascending order +- Segment Z-A Descending: sort by segment name in descending order +- Value Ascending: sort by segment value in ascending order +- Value Descending. sort by segment value in descending order + +When sorting by segments, the sort is carried out from left to right. + +![Sorting Line Chart](/sorting-line-chart-2.gif) + +Clicking on the "Average" data column performs a flat sort across all segments: + +![Sorting Line Chart](/sorting-line-chart-3.png) + +### Table chart +Tables are useful to see the precise values of your data and to quickly scan multiple metrics per segment. In general, tables work similarly to the rest of Insights, with a few extra features. + +#### Sort Order +You can configure how you want rows in the table to be sorted, with our global sorting control. +![Sorting.gif](https://github.com/mixpanel/docs/assets/2077899/a61948a6-3e4a-4e5d-9b75-3f4b14cb1450) + +##### Grouped View vs Ungrouped View +The Ungrouped View removes all hierarchy and makes the table flat. Each combination of segment values is treated as a row, independently of the other rows. + +![image](https://github.com/mixpanel/docs/assets/2077899/e57400a1-a86c-4d46-9ffb-379306586d8d) + +The Grouped View preserves the hierarchy of breakdowns. It shows you segments within a breakdown as displayed below. This view is only applicable when you have 2 or more breakdowns + +![image](https://github.com/mixpanel/docs/assets/2077899/2a72e93c-c332-4418-83e1-91bb24e2d271) + +##### Alphabetical vs Value-Based Sorting +You can sort segments alphabetically or by the value of a particular metric. In the grouped view, sorting is configured on a per-breakdown level and respects the breakdown hierarchy. + +In the below image, we sort Country *within* Item Category, which respects the hierarchy. +![image](https://github.com/mixpanel/docs/assets/2077899/4697ce00-d394-46ce-b538-66ec91ccd6e7) + +Hierarchy is defined by the breakdown order in the query panel: +![image](https://github.com/mixpanel/docs/assets/2077899/ff2f72b3-89bc-459e-b8b7-e81655d04bb7) + +##### View “N” segments + +The View “N” control lets you decide how many rows to display per breakdown in your table. +![View_N_gif](https://github.com/mixpanel/docs/assets/2077899/4fb0fd18-2ef7-416b-adaa-c7299da0f7b3) + +In the ungrouped view, choose the number of rows to display: +![image](https://github.com/mixpanel/docs/assets/2077899/b1b25b19-51be-4934-bbfd-7562e0f98d4a) + +In the grouped view, you can choose the number of rows you want to display for each breakdown: +![image](https://github.com/mixpanel/docs/assets/2077899/f9f8c83c-34ed-44bd-b4e7-f60b70255a6f) + +![image](https://github.com/mixpanel/docs/assets/2077899/b09c1ad1-1392-4ec0-9358-361f677c600d) + +**Notes** +- View N only controls how many segments to display. To decide which segments to display i.e if it’s the top segments by value or bottom segments by value or alphabetical, please change the “Sort Order”. +- View N will show the minimum of N and how many segments are in your report. For example, if you set N=10 but you only have 7 segments, we will only show 7 rows. +- When selecting “Show All”, the maximum number of segments displayed in the UI will be 3000 given cardinality limits. If your breakdown has more than 3000 segments, you'll only see the top 3000, dictated by the sort order. + +##### Overall and Segment Sub-Totals + +**Overall:** This refers to the value considering all the segments, independent of whether displayed or not based on your View N control; i.e changes to View N will not affect Overall numbers +![image](https://github.com/mixpanel/docs/assets/2077899/3d6556a4-9468-4d1f-8979-4fdb512f2aaa) + +**Sub-Totals:** In the grouped view, in addition to the Overall, segment sub-totals are also displayed. Similar to “Overall”, these values are independent of the View N control + +![image](https://github.com/mixpanel/docs/assets/2077899/ee7d8c9b-f738-4a5b-8967-300cf8322f76) + +### Visualization Settings (Chart Visualization content would go here) + +The visualization options allow you to choose how the data is visualized. The options are: + +- **Linear:** This is the standard view for the chart. +- **Logarithmic:** A nonlinear scale based on orders of magnitude, rather than a standard linear scale, so the value represented by each equidistant mark on the scale is the value at the previous mark multiplied by a constant. + +### Annotations + +To clarify the results in your Insights report, add detailed annotations directly to the line chart. Annotations are tied to a specific date on the chart, rather than a specific data point on the chart. + +To add an annotation, hover your mouse over the point on the chart you want to annotate, and click the blue **+** button that appears. Enter a description for the annotation, such as a holiday that occurred on that day or the end date of your fiscal year, then click **Save**. If you accidentally selected the incorrect date on the chart, you can edit the date and time of the annotation in this window. + +![Annotations 1](/advanced-annotations-1.png) + +View an existing annotation by clicking on the number found at the bottom of a report. You will be able to see who submitted the annotation. + +![Annotations 2](/advanced-annotations-2.png) + +Hover the cursor over the annotation to edit or delete it. Click on the **pencil icon** to edit an annotation, or the **trash icon** to delete an annotation. Add additional annotations to the same date by clicking **Add annotation**. + +![Annotations 3](/advanced-annotations-3.png) diff --git a/pages/docs/reports/overview.md b/pages/docs/reports/query-builder.md similarity index 58% rename from pages/docs/reports/overview.md rename to pages/docs/reports/query-builder.md index 0805e50c73..f45626f886 100644 --- a/pages/docs/reports/overview.md +++ b/pages/docs/reports/query-builder.md @@ -1,90 +1,46 @@ -# Reports +# Query Builder ## Overview -A report is the basic unit of performing an analysis in Mixpanel. +The Query Builder allows you to build complex queries using a simple drag-and-drop interface. This article goes over the query builder features common across our [core reports](/docs/reports). -Mixpanel has several types of reports: [Insights](/docs/reports/insights), [Funnels](/docs/reports/funnels), [Flows](/docs/reports/flows), [Retention](/docs/reports/retention) and other advanced reports, each with their specialized use. - -This article focuses on the common concepts across each report. - -## Report - -A report is the basic unit of performing an analysis in Mixpanel. A report can be saved to a board, and a board can contain many reports. Each report is made up of at least one **metric** and is displayed using the chosen **visualization**. - -## Metrics - -A metric is a some sort of **measurement** on a **behavior**. An example of a metric is "Unique Users" doing "Sign up", which is the measurement of unique users, on the behavior of "Sign up". - -## Behaviors - -A behavior is an event or a sequence of events performed within some criteria. A behavior can be something simple like a single event, or it can be something more complex like doing a multi step funnel. - -## Measurements - -A measurement is a selection on how to summarize behaviors. Depending on the behavior, certain measurements may be not be possible. For example, for a single event, you cannot measure the conversion rate of it. Some examples of measurements are: total events, unique users, total sessions, conversion rate, retention rate and aggregate property. The measurement is chosen at the bottom left area of the metric. - -![measurement](/report-measurement.png) - -## Visualizations - -In the top right, you can change the type of visualization for your report. The options available will depend on the type of report that you started with. In this case, we switched to a bar view, allowing us to see the total number of "Log In" across the entire time range, allowing us a summarized view that is easily scanned. - -![/Screen_Shot_2022-07-11_at_3.07.02_PM.png](/Screen_Shot_2022-07-11_at_3.07.02_PM.png) - -## Filters - -Filters are used to narrow events or behaviors that qualify for analysis. For example, you may want to only consider "Sign Up" events that came from Android. In this case you would you be filtering the "Sign Up" event to only include the "Sign Up" events where the property "Device" is equal to "Android". - -### Global Filters - -A global filter applies to the entire report. by properties or cohorts by clicking the **Filter** button. This will filter the results of the entire report to show only data with that property or cohort. - -![image](/global-filter.png) - -### Inline Filters - -An inline filter applies to one particular event in the report. - -Add a filter to your query by clicking on the **…** icon beside an event, profile, cohort, or step. - -![image](https://github.com/mixpanel/docs/assets/2077899/3e36bd7e-f5b8-462a-890c-bf396ff98f69) - -Then, select a property from the drop down list that appears and specify which values to filter. - -![image](https://github.com/mixpanel/docs/assets/2077899/c7cce429-3c9c-4759-8ea1-b09345fa0b4e) +## Events Menu -In Funnels, filtering a step by a particular property will limit the data you see in the funnel to events with that property value. +This is the menu that appears under "Add Metric" or "Select Step". -You can choose multiple property filters for each item in your query. +By default, the event menu shows all events, except for [hidden events](/docs/data-governance/lexicon#hide-events-and-properties). -You can select whether you would like the query to match any of these filters, or all of the filters by clicking on **and/or** beside the filters. +If you organize your events using [tags](/docs/data-governance/lexicon) in Lexicon, the tags will show up as filtering options in the event menu. When you select a tag, a list of events that share the same tag appears: -![image](https://github.com/mixpanel/docs/assets/2077899/9e3bcd31-2b12-48d1-b04f-cdda85dd2584) +![/Untitled__1_.png](/Untitled__1_.png) -## Breakdowns +**View Sample Events** -Breakdown groups the results of your metrics in Insights, Funnels, Flows, or Retention reports by a property or cohort, allowing you to examine which properties or cohorts have a significant impact on your query. +You can hover over any event and in the context panel, you now have the ability to "View Sample Events", which redirects you to the Events page with the 100 most recent samples of that hovered event: +You can see a few samples of an event to help you decide whether that's the right event you want for your analysis or which property you should use for filters/breakdowns. -This feature is useful for determining if a group factor, such as browser type, is having an impact on the way users interact with your product. Breakdown will display counts, such as the number of events performed or the conversion rates with that property value. +![View Sample Events](/advanced-view-sample-events.gif) -Select the **Breakdown** button, and select the property or cohort you want to breakdown your results by. +### Rename an Event within a Report -![image](/report-breakdown.png) +Click on the "three dots" icon beside an event and click Rename to rename it. This will only affect the current report, and will not change the event's name in other reports. -For cohorts, you will be shown groups of users both in and not in the cohort in your results. +### First Time Ever Filter -It is only possible to either group by properties or group by cohorts, but not both. +Sometimes, you might want to filter an event to only the first time that it's performed by a user. This helps answer the following questions: -## Events Menu +* How many users sign up or perform another key event for the first time each week? +* Which referrers do most first time users come from? +* How quickly do users make a purchase after their first time engaging with the app? +* How well do users retain after performing a key event for the first time? +* What events do users perform before and after doing their first purchase? -This is the menu that appears under "Add Metric" or "Select Step". +You can do this by adding a First Time Filter to any event in Mixpanel. This filters the event down to only the first instance of the event in a **user's entire history**. (not the first time they tracked the event inside the report date range) -By default, the event menu shows all events, except for [hidden events](/docs/data-governance/lexicon#hide-events-and-properties). +![233894752-93851682-9d83-4c87-937d-8fd90db465c6.png](https://user-images.githubusercontent.com/2077899/233894752-93851682-9d83-4c87-937d-8fd90db465c6.png) -If you organize your events using [tags](/docs/data-governance/lexicon) in Lexicon, the tags will show up as filtering options in the event menu. When you select a tag, a list of events that share the same tag appears: +Mixpanel computes this on-the-fly by scanning each user's history to determine if this was the first instance of the event performed by the user, based on timestamp. -![/Untitled__1_.png](/Untitled__1_.png) ## Properties Menu @@ -129,7 +85,26 @@ The events and properties in the menu are prefixed to provide additional context ![/Screen_Shot_2021-11-18_at_12.29.06_PM.png](/Screen_Shot_2021-11-18_at_12.29.06_PM.png) -## Date Range +### Typecasting + +Mixpanel allows you to force Properties into another [data type](https://help.mixpanel.com/hc/en-us/articles/115004547063) by using the **"Data Type"** option in the overflow menu for property filters and breakdowns. + +![/Kapture_2022-01-04_at_11.38.41.gif](/Kapture_2022-01-04_at_11.38.41.gif) + +Typecasting is helpful when one of your properties is a number but is sent to Mixpanel as a string and you want to see histogram data for that property. Or if one of your properties is a unix timestamp and got sent as a number, and you want it to be treated as a date Property instead. + +### Duplicating Query Elements + +To duplicate any events or properties in your query, select the inline action menu and choose **Duplicate**. Delete any events or properties by clicking the **trash** icon. + +![image](https://github.com/mixpanel/docs/assets/2077899/f496b609-47a3-4287-95f8-e9e6f2ac915d) + +### Event and Properties Indexing +The drop-down menus only show events/event properties that were ingested within the last 30 days. To select events/event properties that have not been ingested in the last 30 days, type the name of the event/event property in the Filter or Breakdown search bar. You must know the exact name of the event/event property you want to select because event names are case-sensitive. + +![/query_old_event.gif](/query_old_event.gif) + +## Date and Time Selector Determine the time range of a query by clicking on the date range selector. The date range selector is common across all reports. @@ -157,7 +132,7 @@ For these date ranges, the output shows results from the last complete 30 days, Selecting **Custom** on the date range selector opens up some additional options, "Last", "Fixed" and "Since". -### Last +**Last** “In the last” allows you to select a rolling time range similar to the default “last 30 days” but you have the flexibility to choose the time value and scale, either days, weeks, or months. @@ -167,71 +142,67 @@ If you need to, you can click on the **+ Ending** button and shift back the de ![/Screen_Shot_2022-07-11_at_3.18.03_PM.png](/Screen_Shot_2022-07-11_at_3.18.03_PM.png) -### Fixed +**Fixed** “Fixed” allows you to select two dates to query between or a select particular day to query by entering the same start & end date. If you save this report as a bookmark or add it to the dashboard, the date range selection will always persist. ![/Screen_Shot_2022-07-11_at_3.21.03_PM.png](/Screen_Shot_2022-07-11_at_3.21.03_PM.png) -### Since +**Since** “Since” allows you to select a specific date to query for all data since that start date. -### To Date +**To Date** "To Date" allows you select a date rnge that will update dynamically to fit the current internval. You can choose Week to Date, Month to Date, Quarter to Date and Year to Date. When the boundary of interval is passed, the date range will automatically update to include only the current interval. For example, if "Month to Date" was selected, and the date was February 27, the date range would include Feb 1 - Feb 27. The next week, after the month boundary has passed the date range would include Mar 1 - Mar 4. To Date respects start of week and start of quarter settings under project settings. -## Comparisons - -Comparisons allow you to compare metrics, or broken down segments of metrics against each other. Depending on the type of comparison type, you are also able see the lift of a segment or metric against another. - -### Compare to Past - -Compare to past allows for comparing a metric against itself on a different time period. You are able to compare against the previous day, week, month, quarter and year. You are also able choose a custom time comparison window. +### Line Chart Time Selector -![/compare_to_past.png](/compare_to_past.png) +**Line Chart Intervals** +You can also choose how Mixpanel buckets the time range in Insights, Funnel Trends and Retention Trend reports (granularity may vary). To view a range in hours, you can select **Hour** as the view: -By default, Mixpanel will visualize the values for both time periods. If you wish to see the lift of the current time period against the past time period, you can select the "Percent Change over Baseline" option to see the lift of your metric over time. +![image](https://github.com/mixpanel/docs/assets/2077899/991a0f0f-b297-4b94-8d41-7323fe6666f6) -![/compare_to_past_lift.png](/compare_to_past_lift.png) +**Line Chart Zoom** +To zoom in, click on the graph and drag to highlight a specific window of time in your report. Click **Reset zoom** to return to the previous view. -### Compare to Segment +![zoom (1)](https://github.com/mixpanel/docs/assets/2077899/3add64ad-3fea-4d74-a3bf-303fcc1f4d9d) -Compare to segment allows you to set a property value as a baseline and see how every other property compares. -![/compare_to_segment.png](/compare_to_segment.png) +## Comparisons -### Compare to Overall +Comparisons allow you to compare metrics, or broken down segments of metrics against each other. Depending on the type of comparison type, you are also able see the lift of a segment or metric against another. -Compare to overall allows you compare each segment value and see what proportion it makes of the overall value. +### Time Period Comparison -![/compare_to_overall.png](/compare_to_overall.png) +Compare to past allows for comparing a metric against itself on a different time period. You are able to compare against the previous day, week, month, quarter and year. You are also able choose a custom time comparison window. -## Saving to a Board +> Note that if a data point for a previous year falls on a weekend, the data point is automatically moved to the next Monday to give a clearer picture of the data change from one year to the next. -When you are satisfied with the analysis, and decide that this is something that you are likely to revisit, Mixpanel recommends that you save the report to a [Board](/docs/boards/overview). You can do this by pressing "Save" in the top right and selecting the Board you would like to save to, or creating a new Board. +Hover over a segment to see the details on the time-period selected. -![/Screen_Shot_2022-07-08_at_5.40.30_PM.png](/Screen_Shot_2022-07-08_at_5.40.30_PM.png) +![/compare_to_past.png](/compare_to_past.png) -## Typecasting +By default, Mixpanel will visualize the values for both time periods. If you wish to see the lift of the current time period against the past time period, you can select the "Percent Change over Baseline" option to see the lift of your metric over time. -Mixpanel allows you to force Properties into another [data type](https://help.mixpanel.com/hc/en-us/articles/115004547063) by using the **"Data Type"** option in the overflow menu for property filters and breakdowns. +![/compare_to_past_lift.png](/compare_to_past_lift.png) -![/Kapture_2022-01-04_at_11.38.41.gif](/Kapture_2022-01-04_at_11.38.41.gif) +### Value Comparison -Typecasting is helpful when one of your properties is a number but is sent to Mixpanel as a string and you want to see histogram data for that property. Or if one of your properties is a unix timestamp and got sent as a number, and you want it to be treated as a date Property instead. +**Compare to segment** allows you to set a property value as a baseline and see how every other property compares. -**How do I see the exact numeric values when applying a breakdown to a number data type in Insights?** +![/compare_to_segment.png](/compare_to_segment.png) -Insights will automatically bucket high-cardinality segments of number data types into ranges. +**Compare to overall** allows you compare each segment value and see what proportion it makes of the overall value. -You can either customize the ranges by clicking "[Customize Range](/docs/features/advanced#custom-buckets)". +![/compare_to_overall.png](/compare_to_overall.png) -Or alternatively, if you'd like to see the exact numeric values you can typecast the Number property to a String to remove the range bucketing. +## Undo and Redo -## Sessions +The undo/redo keyboard shortcuts allow for fast adjustments to your analysis. `Cmd + Z` to undo; `Cmd + Shift + Z` to redo. Change filters, date ranges, line vs bar chart, and go back in one second to compare before and after, or fix the view. -This is a period of continuous user activity. Use Sessions in Mixpanel to track which events users perform within a session, how many sessions contained a key action or how many sessions it takes for a user to convert in a funnel. [Learn more](/docs/features/sessions). +![/Undo_Redo_gif.gif](/Undo_Redo_gif.gif) -![/Screen_Shot_2022-07-11_at_3.27.25_PM.png](/Screen_Shot_2022-07-11_at_3.27.25_PM.png) +- **Navigate different report versions**: add a new event, filter or breakdown and undo that change with `Cmd + Z` . This makes iterating between different versions of your report quick and easy. +- **Compare visualizations**: go from a bar chart, to a line chart, to a pie chart and all the way back while only using the undo / redo keyboard shortcuts. diff --git a/pages/docs/reports/retention.mdx b/pages/docs/reports/retention.mdx index dc5819565f..c951d047c2 100644 --- a/pages/docs/reports/retention.mdx +++ b/pages/docs/reports/retention.mdx @@ -58,191 +58,6 @@ You can visualize your metric in a variety of ways. Mixpanel allows you to choos ![/retention_beta_5.png](/retention_beta_5.png) -## Basic Features - -### Retention Curve - -

- -

- -The retention curve chart displays retention data as both a line chart and a table. Data is identical between the two. The line chart provides a visual representation of users becoming inactive over time, while the table provides a heat map to show which groups have the best retention. - -![/Screen_Shot_2021-05-27_at_7.49.12_AM.png](/Screen_Shot_2021-05-27_at_7.49.12_AM.png) - -**Incomplete Buckets** -Boxes with an asterisk (\*) indicate that the data is still in flux and not set yet because the time is still ongoing. Hover over a box to see when the last qualifying date for that bucket will occur. - -**Color Mapping** -Each box within a row is assigned a shade of purple. The shading gets darker the higher the retention percentage. It's important to note that the scale is relative to each cohort row. - -### Line chart - -![/Retention Line Chart](/Retention_Trend.png) - -Select **Line** from the visualization drop-down list to see how your retention metrics are changing over time. You can see how your retention rate or number of users retained is trending. You can see this trend for any of the retention time unit buckets. You can change between the different time unit buckets (i.e. < 1 Day, Day 1, Day 2, ...) to see if your retention metrics are improving or declining along your retention curve. - -### User Cohort Buckets - -Retention counts users, not event totals. In other words, each of the user cohort buckets will include every unique user that did the "A event" criteria in that time window, starting at 0:00 of the first day of the bucket and ending midnight of the last day. A customer can only be counted once per bucket, but can be included in more than one bucket. - -The first column (Date) indicates the day/week/month when the user performed the "A event". The Size column indicates the number of users that performed the "A event" within the time period. - -For example, if you are bucketing based on your "Item Purchased" event and creating weekly buckets, a customer who purchased at least one item each week will be in every bucket, not just the bucket of their first purchase. - -## Advanced - -### Retention Criteria - -

- -

- -#### Retention Criteria - On time interval - -"On" Retention calculates the percentage of users who come back on a specific time unit (e.g. day, week, month). - -After a user completes the “A criteria”, they will belong to a time unit cohort that corresponds with when they did the "A event" and the Retention report will start the clock counting from the time that particular user performed that "A event". When using "On" Retention, that same user must return to fulfill the “came back and did B criteria” on a specific and exact time unit relative to when they did the A criteria to be counted as retained. - -For example, day 5 retention is the percentage of users who “came back and did B” exactly on the fifth day after they did the A event. - -"On" retention is useful to understand high-level usage patterns.  We also recommend using "on" retention when your product relies on users returning in each and every time unit. - -#### Retention Criteria - On or After time interval - -![/Retention_Criteria](/Retention_Criteria.png) - -"On or After" Retention calculates the percentage of users who come back on a specific time unit (e.g. day, week, month) **or any time unit afterward**. A user can fulfill the "came back and did B criteria" on a specific time unit or any time in the future to be counted as retained in "On or After" Retention. - -"On or After" Retention gives you a better sense of how long you are holding on to your users in an absolute sense. It will tell you how many users used your app and then ever returned to find more value. In other words, it's the opposite of the overall churn of your user base. - -We think "On or After" retention is a better fit for most businesses and it is the default calculation for the Retention report. This is because it’s more common that a product doesn’t require users to come back in each time unit to achieve the product’s value proposition, and more often than not when doing retention analysis we don’t only value the user coming back in a specific time unit as long as they eventually do. However, if this is important to you and your business, please utilize "On" Retention. - -### Custom Retention Brackets - -Not all retention analysis can be done with a set, repeated cadence and it is not always important to measure how a user came back relative to each and every particular time unit. - -Custom bracket retention gives you the flexibility to split up your retention buckets into customized intervals of multiple days, weeks, or months to create meaningful touchpoints as you see fit. - -#### Use Cases - -For example, let's answer an important mobile gaming question: How often do my users came back and play a game between 15 and 30 days after sign up to represent mid-term players? - -In mobile gaming, industry-standard intervals typically examine retention for users that came back and play a game on Day < 1, Days 1-3, Days 4-7, Days 8-14, and Day 15-30. - -Typical "exact day" retention buckets don't quite solve for this use case because users should be able to play a game on any day between day 15 and 30 and be counted in a single bucket to understand how many users were retained in that entire period. Exact day retention will log users in each individual day bucket (15, 16, 17, ..., 30) which, while more granular, doesn't give a retention percentage for the entire interval. Instead, we want to know how many users played a game at all in any of the days 15-30. - -**Free trials:** If you want to understand how many users come back to use the product during a 7-day free trial and also who came back and kept using the product in the 30 days after the free trial is up, you could do something like this: - -![Retention 7 30](/Retention_7_30.png) - -**In between cadences:** Are you somewhere in between a DAU or WAU product? You can group daily buckets to understand how your users retain every 3 days (bi-weekly). - -![Retention 3 3](/Retention_3_3.png) - -#### Setting Custom Brackets - -First, go into the time unit drop-down in the Retention query builder and select **Custom** - -![Setting Custom Buckets](/Retention_Setting_Custom.png) - -Then, select the size of each bracket for the given time unit. In this example, we are selecting the number of days that are in each custom bracket. Apply. - -![Retention 3 3](/Retention_3_3.png) - -Each of these intervals is its own retention bucket, and if the user does the "come back and did B" event anytime inside that bucket they are counted as retained. Now I will be able to understand what percent of users come back to play at least one game in any day between day 15 and day 30 from signing up. - -#### Calendar Retention Mode - -You can go into advanced menu under Retention Criteria to switch the retention mode from the default rolling time windows to calendar defined time windows. This aligns the retention calculation so that all users entering within a time bucket get calculated together. - -![/13599603833876.png](/13599603833876.png) - -This may be useful in scenarios where you want to check engagement on a strict day basis, OR if you want to check retention of your user base for the entire month and when they return, regardless of when in the month they first entered or when in the next month they returned. - -![/13599765981076.png](/13599765981076.png) - -In the above example, we're looking at retention on a calendar week basis. - -- In the < Week 1 bucket, there were 6 users who did "Sign Up" at any point of the week of Dec 23 - Dec 30, and returned to do "Post Content" in that same week of Dec 23 - Dec 30. -- In the Week 1 bucket, there were 10 users who did "Sign Up" in the same Dec 23 - Dec 30 interval, but returned to do "Post Content" only some time between Dec 30 - Jan 6. - -##### How is this different than the basic retention mode? - -This [loom video](https://www.loom.com/share/5484c7bdd61a4332818ceef20f475176) should provide an overview of what is calendar interval retention and how it works vs the default rolling window retention - -![/5484c7bdd61a4332818ceef20f475176-with-play.gif](/5484c7bdd61a4332818ceef20f475176-with-play.gif) - -**[Basic] Rolling interval retention** - Considers time intervals based on user’s time of birth; i.e - -- Day 1 retention = 24-48 hrs since person’s birth -- Week 1 retention = 7-14 days since person’s birth -- Month 1 retention = 30-60 days since person’s birth - -**[Advanced] Calendar interval retention** - Considers time intervals based on ‘calendar’ time; i.e - -- Day 1 retention = next ‘calendar’ day since person’s birth. If a person did an activity at 8pm on Monday and then 6am on Tuesday, person is counted under Day 1 retention even though it’s just 10 hrs later -- Week 1 retention = next ‘calendar’ week since person’s birth. If a person did an activity on Friday and then Monday, person is counted under Week 1 retention even though it’s just 3 days, since the ‘calendar’ week changed -- Month 1 retention = next ‘calendar’ month since person’s birth. Similarly, if a person made a purchase on 25th Feb and then again on 3rd March, person will be counted under Month 1 retention metrics - -NOTE — All the above cases would NOT qualify under Day 1 or Week 1 or Month 1 rolling interval retention - -**When should you the calendar vs rolling interval retention mode? - -Both the modes are extremely useful. It totally depends on the use-case you’re trying to answer. Some examples - - -| Use-Case | Which mode to use? | -| --- | --- | -| Day 1 retention for apps focused on “daily engagement” like music, meditation or workout apps | Calendar-interval | -| How many users come back after month 1 (30 days)? How many comes back after 3 months (90 days)? | Rolling-interval | -| Understanding the effect of a marketing promotion, how many people came back the week after the promotion ended? | Calendar-interval | -| What’s Mixpanel's quarterly revenue retention? How was gross and net retention in Q4 vs Q3? | Calendar-interval | -| How many users renewed their Netflix subscription? To note, renewals happen 30 days after last payment | Rolling-interval | - -Above said, general expectation is product use-cases which focus on user stickiness are likely to use rolling interval mode. Marketing & Revenue teams which focus on calendar dates for their activities, are likely to use calendar interval model - -### Saved Retention Behaviors - -You can define a retention behavior and save and share it. Press "Save as New" button to save your retention behavior definition. You can change the name and add a description. - -![save retention](/save-retention-1.png) - -You can also load existing retention behavior definitions by clicking the name of retention behavior. - -![save retention](/save-retention-2.png) - -See more about saved behaviors [here](/docs/features/saved-behaviors). - -### Frequency View - -

- -

- -You can use the Frequency report to learn how frequently users return to use your product or service. - -To generate Frequency reports, click **Reports**, **Retention,** and select the **Frequency** option under the toggle for retention. - -![/Screen_Shot_2022-07-05_at_4.41.04_PM.png](/Screen_Shot_2022-07-05_at_4.41.04_PM.png) - -Mixpanel groups unique users in time-incremented buckets when they first complete an action, and then groups those same users in subsequent buckets when they return and perform the same or different actions. - -The buckets measure the number of unique time buckets a user was active. Depending on the interval chosen, this will one of: - -- unique hours in a day -- unique days in a week -- unique months in a year - -This will show how engaged users are with an action. In the example below, you can see how many users did the event "Complete Purchase" on unique days in a week. For users who did "Complete Purchase" on the week of Jan 9, 2020, 13.04% of them did "Complete Purchase" on 4 unique days that week. - -![/Screen_Shot_2022-07-05_at_4.49.46_PM.png](/Screen_Shot_2022-07-05_at_4.49.46_PM.png) - -#### Frequency Criteria - -**Cumulative Frequency**: calculates the number of users who did the event **in at least** X unique intervals. This shows overall engagement up to that up to each frequency interval. - -**Non-cumulative Frequency**: calculates the number of users who did the event in **exactly** X unique intervals. This is useful for determining exact engagement and for further investigating specific groups of engaged users. - ## FAQ ### Retention reports do not extend beyond 60 days. How can I look beyond the 60 day mark? diff --git a/pages/docs/reports/retention/_meta.json b/pages/docs/reports/retention/_meta.json new file mode 100644 index 0000000000..91cbca33f7 --- /dev/null +++ b/pages/docs/reports/retention/_meta.json @@ -0,0 +1,6 @@ +{ + "retention-behavior": "Retention Behavior", + "retention-criteria": "Retention Criteria", + "visualizations": "Visualizations", + "frequency": "Frequency", +} diff --git a/pages/docs/reports/retention/frequency.md b/pages/docs/reports/retention/frequency.md new file mode 100644 index 0000000000..8159192df0 --- /dev/null +++ b/pages/docs/reports/retention/frequency.md @@ -0,0 +1,32 @@ +# Frequency Retention + +## Overview + +Frequency is a specific type of retention that measures whether your users who track an event return to track the same event again and again. Frequency retention is helpful for measuring how engaged your users are with a specific action. + +

+ +

+ +## Frequency Report +To generate Frequency reports, click **Reports**, **Retention,** and select the **Frequency** option under the toggle for retention. + +![/Screen_Shot_2022-07-05_at_4.41.04_PM.png](/Screen_Shot_2022-07-05_at_4.41.04_PM.png) + +Mixpanel groups unique users in time-incremented buckets when they first complete an action, and then groups those same users in subsequent buckets when they return and perform the same or different actions. + +The buckets measure the number of unique time buckets a user was active. Depending on the interval chosen, this will be one of: + +- unique hours in a day +- unique days in a week +- unique months in a year + +This will show how engaged users are with an action. In the example below, you can see how many users did the event "Complete Purchase" on unique days in a week. For users who did "Complete Purchase" on the week of Jan 9, 2020, 13.04% of them did "Complete Purchase" on 4 unique days that week. + +![/Screen_Shot_2022-07-05_at_4.49.46_PM.png](/Screen_Shot_2022-07-05_at_4.49.46_PM.png) + +#### Frequency Criteria + +**Cumulative Frequency**: calculates the number of users who did the event **in at least** X unique intervals. This shows overall engagement up to that up to each frequency interval. + +**Non-cumulative Frequency**: calculates the number of users who did the event in **exactly** X unique intervals. This is useful for determining exact engagement and for further investigating specific groups of engaged users. diff --git a/pages/docs/reports/retention/retention-behavior.md b/pages/docs/reports/retention/retention-behavior.md new file mode 100644 index 0000000000..4852a184b4 --- /dev/null +++ b/pages/docs/reports/retention/retention-behavior.md @@ -0,0 +1,37 @@ +# Retention Behavior + +## Overview + +The retention behavior is the basic building block of a Retention report. Unlike a standard metric such as Event or Users, retention is a behavioral measurement that evaluates whether a user who does an event returns to do another event. + +## Define Retention Events + +Retention is defined by two events; an **Entry Event** and a **Retention Event**. + +**Entry Event** + +This event serves as the entry point for your retention analysis. Any users who track this event within your report date range will be included in your retention analysis. + +For example, you might use an event like " Ad Campaign" here if you want to evaluate the retention of your users who have seen a particular ad campaign in your product. + +** Retention Event** + +This event is used to measure your retention and is used to determine whether your users are returning after tracking your entry event. + +For example, you may want to use an event like "Browse Catalog" to see if the ad campaign from your entry event is effective at keeping your users interested in shopping with your product. + +## Saved Retention Behaviors + +You can define a retention behavior and save and share it. Press "Save as New" button to save your retention behavior definition. You can change the name and add a description. + +![save retention](/save-retention-1.png) + +You can also load existing retention behavior definitions by clicking the name of the retention behavior. + +![save retention](/save-retention-2.png) + +See more about saved behaviors [here](/docs/features/saved-behaviors). + +## Frequency Retention + +Frequency is a type of retention that evaluates whether your users who do an event return to do the same event again. Learn more about Frequency retention [here](/docs/reports/retention/frequency/). diff --git a/pages/docs/reports/retention/retention-criteria.md b/pages/docs/reports/retention/retention-criteria.md new file mode 100644 index 0000000000..54e37e357d --- /dev/null +++ b/pages/docs/reports/retention/retention-criteria.md @@ -0,0 +1,127 @@ +# Retention Criteria + +## Overview + +The Retention report provides a variety of configurations to fine-tune how your retention is measured. + +## Retention Measurement +You can toggle your report to return your retention as a percentage via **Retention Rate** or as a raw number of users via **Unique Users**. Click the "Retention Rate" button beneath the Retention Criteria module to switch between the two options. + + + +## Retention Groups + +When using the line chart or metric visualization, you can select which retention group to target for your report. Click the button in the bottom right corner of the Retention Criteria module showing the default retention group time unit to choose another retention group. + + + +## Retention Criteria + +You can configure the definition of a retained user using the Retention Criteria module. + +

+ +

+ +### Retention Criteria - On time interval + +"On" Retention calculates the percentage of users who come back on a specific time bracket (e.g. day, week, month). + +After a user completes the “A criteria”, they will belong to a time unit cohort that corresponds with when they did the "A event" and the Retention report will start the clock counting from the time that particular user performed that "A event". When using "On" Retention, that same user must return to fulfill the “came back and did B criteria” on a specific and exact time unit relative to when they did the A criteria to be counted as retained. + +For example, day 5 retention is the percentage of users who “came back and did B” exactly on the fifth day after they did the A event. + +"On" retention is useful to understand high-level usage patterns.  We also recommend using "on" retention when your product relies on users returning in each and every time unit. + +### Retention Criteria - On or After time interval + +![/Retention_Criteria](/Retention_Criteria.png) + +"On or After" Retention calculates the percentage of users who come back on a specific time unit (e.g. day, week, month) **or any time unit afterward**. A user can fulfill the "came back and did B criteria" on a specific time unit or any time in the future to be counted as retained in "On or After" Retention. + +"On or After" Retention gives you a better sense of how long you are holding on to your users in an absolute sense. It will tell you how many users used your app and then ever returned to find more value. In other words, it's the opposite of the overall churn of your user base. + +We think "On or After" retention is a better fit for most businesses and it is the default calculation for the Retention report. This is because it’s more common that a product doesn’t require users to come back in each time unit to achieve the product’s value proposition, and more often than not when doing retention analysis we don’t only value the user coming back in a specific time unit as long as they eventually do. However, if this is important to you and your business, please utilize "On" Retention. + +#### Custom Retention Brackets + +Not all retention analysis can be done with a set, repeated cadence and it is not always important to measure how a user came back relative to each and every particular time unit. + +Custom bracket retention gives you the flexibility to split up your retention buckets into customized intervals of multiple days, weeks, or months to create meaningful touchpoints as you see fit. + +**Use Cases** + +For example, let's answer an important mobile gaming question: How often do my users came back and play a game between 15 and 30 days after sign up to represent mid-term players? + +In mobile gaming, industry-standard intervals typically examine retention for users that came back and play a game on Day < 1, Days 1-3, Days 4-7, Days 8-14, and Day 15-30. + +Typical "exact day" retention buckets don't quite solve for this use case because users should be able to play a game on any day between day 15 and 30 and be counted in a single bucket to understand how many users were retained in that entire period. Exact day retention will log users in each individual day bucket (15, 16, 17, ..., 30) which, while more granular, doesn't give a retention percentage for the entire interval. Instead, we want to know how many users played a game at all in any of the days 15-30. + +**Free trials:** If you want to understand how many users come back to use the product during a 7-day free trial and also who came back and kept using the product in the 30 days after the free trial is up, you could do something like this: + +![Retention 7 30](/Retention_7_30.png) + +**In between cadences:** Are you somewhere in between a DAU or WAU product? You can group daily buckets to understand how your users retain every 3 days (bi-weekly). + +![Retention 3 3](/Retention_3_3.png) + +##### Setting Custom Brackets + +First, go into the time unit drop-down in the Retention query builder and select **Custom** + +![Setting Custom Buckets](/Retention_Setting_Custom.png) + +Then, select the size of each bracket for the given time unit. In this example, we are selecting the number of days that are in each custom bracket. Apply. + +![Retention 3 3](/Retention_3_3.png) + +Each of these intervals is its own retention bucket, and if the user does the "come back and did B" event anytime inside that bucket they are counted as retained. Now I will be able to understand what percent of users come back to play at least one game in any day between day 15 and day 30 from signing up. + +### Calendar Retention Mode + +You can go into advanced menu under Retention Criteria to switch the retention mode from the default rolling time windows to calendar defined time windows. This aligns the retention calculation so that all users entering within a time bucket get calculated together. + +![/13599603833876.png](/13599603833876.png) + +This may be useful in scenarios where you want to check engagement on a strict day basis, OR if you want to check retention of your user base for the entire month and when they return, regardless of when in the month they first entered or when in the next month they returned. + +![/13599765981076.png](/13599765981076.png) + +In the above example, we're looking at retention on a calendar week basis. + +- In the < Week 1 bucket, there were 6 users who did "Sign Up" at any point of the week of Dec 23 - Dec 30, and returned to do "Post Content" in that same week of Dec 23 - Dec 30. +- In the Week 1 bucket, there were 10 users who did "Sign Up" in the same Dec 23 - Dec 30 interval, but returned to do "Post Content" only some time between Dec 30 - Jan 6. + +##### How is this different than the basic retention mode? + +This [loom video](https://www.loom.com/share/5484c7bdd61a4332818ceef20f475176) should provide an overview of what is calendar interval retention and how it works vs the default rolling window retention + +![/5484c7bdd61a4332818ceef20f475176-with-play.gif](/5484c7bdd61a4332818ceef20f475176-with-play.gif) + +**[Basic] Rolling interval retention** - Considers time intervals based on user’s time of birth; i.e + +- Day 1 retention = 24-48 hrs since person’s birth +- Week 1 retention = 7-14 days since person’s birth +- Month 1 retention = 30-60 days since person’s birth + +**[Advanced] Calendar interval retention** - Considers time intervals based on ‘calendar’ time; i.e + +- Day 1 retention = next ‘calendar’ day since person’s birth. If a person did an activity at 8pm on Monday and then 6am on Tuesday, person is counted under Day 1 retention even though it’s just 10 hrs later +- Week 1 retention = next ‘calendar’ week since person’s birth. If a person did an activity on Friday and then Monday, person is counted under Week 1 retention even though it’s just 3 days, since the ‘calendar’ week changed +- Month 1 retention = next ‘calendar’ month since person’s birth. Similarly, if a person made a purchase on 25th Feb and then again on 3rd March, person will be counted under Month 1 retention metrics + +NOTE — All the above cases would NOT qualify under Day 1 or Week 1 or Month 1 rolling interval retention + +**When should you the calendar vs rolling interval retention mode? + +Both the modes are extremely useful. It totally depends on the use-case you’re trying to answer. Some examples - + +| Use-Case | Which mode to use? | +| --- | --- | +| Day 1 retention for apps focused on “daily engagement” like music, meditation or workout apps | Calendar-interval | +| How many users come back after month 1 (30 days)? How many comes back after 3 months (90 days)? | Rolling-interval | +| Understanding the effect of a marketing promotion, how many people came back the week after the promotion ended? | Calendar-interval | +| What’s Mixpanel's quarterly revenue retention? How was gross and net retention in Q4 vs Q3? | Calendar-interval | +| How many users renewed their Netflix subscription? To note, renewals happen 30 days after last payment | Rolling-interval | + +Above said, general expectation is product use-cases which focus on user stickiness are likely to use rolling interval mode. Marketing & Revenue teams which focus on calendar dates for their activities, are likely to use calendar interval model diff --git a/pages/docs/reports/retention/visualizations.md b/pages/docs/reports/retention/visualizations.md new file mode 100644 index 0000000000..15abbdfb80 --- /dev/null +++ b/pages/docs/reports/retention/visualizations.md @@ -0,0 +1,75 @@ +# Visualizations + +## Overview + +The Retention report feature multiple visualizations to help you understand how your users are retained over time. + + +## Retention Curve + +

+ +

+ +The retention curve chart displays retention data as both a line chart and a table. Data is identical between the two. The line chart provides a visual representation of users becoming inactive over time, while the table provides a heat map to show which groups have the best retention. + +![/Screen_Shot_2021-05-27_at_7.49.12_AM.png](/Screen_Shot_2021-05-27_at_7.49.12_AM.png) + +###Incomplete Buckets +Boxes with an asterisk (\*) indicate that the data is still in flux and not set yet because the time is still ongoing. Hover over a box to see when the last qualifying date for that bucket will occur. + +###Color Mapping +Each box within a row is assigned a shade of purple. The shading gets darker the higher the retention percentage. It's important to note that the scale is relative to each cohort row. + +#### User Cohort Buckets + +Retention counts users, not event totals. In other words, each of the user cohort buckets will include every unique user that did the "A event" criteria in that time window, starting at 0:00 of the first day of the bucket and ending midnight of the last day. A customer can only be counted once per bucket, but can be included in more than one bucket. + +The first column (Date) indicates the day/week/month when the user performed the "A event". The Size column indicates the number of users that performed the "A event" within the time period. + +For example, if you are bucketing based on your "Item Purchased" event and creating weekly buckets, a customer who purchased at least one item each week will be in every bucket, not just the bucket of their first purchase. + +#### Retention Time Unit Buckets + +Retention Time Unit buckets correlate to the time interval defined in your [Retention Criteria](/docs/reports/retention/retention-criteria/). This is dynamically calculated, based on when your users entered the User Cohort Bucket. + +For example, if 2 users are in the same April 1st User Cohort Bucket, but user A entered at 2AM and user B entered at 6PM, the < 1 Day retention time unit bucket for user A is between April 1st 2AM to April 2nd 1:59AM, while the < 1 Day retention time unit bucket for user B is April 1st 6PM to April 2nd 5:59PM. + +## Line chart + +![/Retention Line Chart](/Retention_Trend.png) + +Select **Line** from the visualization drop-down list to see how your retention metrics are changing over time. You can see how your retention rate or number of users retained is trending. You can see this trend for any of the retention time unit buckets and change between the different time unit buckets (i.e. < 1 Day, Day 1, Day 2, ...) to see if your retention metrics are improving or declining along your retention curve. Learn how to select your retention group [here](/docs/reports/retention/retention-criteria#retention-groups). + +## Metric chart + +Select **Metric** from the visualization drop-down list to see the performance of your retention metric aggregated across the entire date range. You can target a specific retention time unit bucket by [selecting a retention group]((/docs/reports/retention/retention-criteria#retention-groups)). + +## Find Interesting Segments + +Determine which users are either driving retention or behaving as outliers by using the built-in “Find Interesting Segments” feature. + +Find Interesting Segments can help you discover: + +- Whether certain property segments outperform the overall retention rates. +- Which cohorts perform the best to get ideas on optimizing cohort behavior. +- Which segments are under-performing. +- Changes in the retention rates of segments. + +User properties are not yet supported. + +View the top and bottom converting segments in your retention report by clicking the **Find interesting segments** button at the bottom of the retention chart. This feature is not currently available for Frequency Retention. + +![/10037069627156](/10037069627156.png) + +Rather than searching through multiple segment breakdowns to find significant data, this feature automatically identifies that data for you. Mixpanel combs through your event properties and cohorts, and show you which of those segments retain at a higher or lower rate than average. + +An email that breaks down the top and bottom retaining segments of your Retention report based on changes on retention rates is automatically sent after you click the button. + +### Interpret Email Results + +When your analysis email says “no interesting segments”, this means that none of the segments you analyzed were behaving significantly differently from the overall population at a large enough volume. To resolve this issue, try extending the date range of the report or try a different report. + +If the analysis request included dates in the past five days, and is sent from mobile SDK, data may be delayed and therefore not included at the time of the analysis. Likewise, the date window selected might still fall under conversion window, and more conversions have yet to come through. + +Results are sorted by taking into consideration the property, the number of users in the report, as well as the deviation from overall retention behavior to surface the most meaningful segments to you. diff --git a/pages/docs/tracking-best-practices/geolocation.md b/pages/docs/tracking-best-practices/geolocation.md index ab0c81bcd8..1f66c0d605 100644 --- a/pages/docs/tracking-best-practices/geolocation.md +++ b/pages/docs/tracking-best-practices/geolocation.md @@ -100,6 +100,12 @@ Do note: Reverse geocoding for user profiles is not supported via client-side SD - Mixpanel drops IP address at ingestion. If you want to store it, name the property something else - Events uses "ip", engage uses "$ip" +If you're tracking from your servers, you need to set the `ip` property of the events to the _client's_ IP address. Most server frameworks provide this out of the box. +* [Django](https://docs.djangoproject.com/en/4.1/ref/request-response/#django.http.HttpRequest.META) exposes this in the request object with `request.META['REMOTE_ADDR']`. +* [Flask](https://flask.palletsprojects.com/en/2.2.x/api/?highlight=remote_addr#flask.Request.remote_addr) exposes this as `request.remote_addr`. +* [Go](https://pkg.go.dev/net/http#Request) exposes this as the `RemoteAddr` field on the http.Request struct. +* [Nginx](http://nginx.org/en/docs/http/ngx_http_log_module.html) exposes this as `$remote_addr`. + **Events** - Events use "ip" inside properties object ``` diff --git a/pages/docs/tracking-best-practices/server-side-best-practices.md b/pages/docs/tracking-best-practices/server-side-best-practices.md index aaa0648afa..98cb60f04c 100644 --- a/pages/docs/tracking-best-practices/server-side-best-practices.md +++ b/pages/docs/tracking-best-practices/server-side-best-practices.md @@ -70,96 +70,6 @@ def track_to_mp(request, event_name, properties): mp.track(request.user_id, event_name, properties) ``` -## Tracking Geolocation (Server-side) -If you supply the `ip` property on an event, Mixpanel will enrich the event with `$city`, `$country`, and `$region` properties. Mixpanel's Web and Mobile SDKs automatically set `ip` to the IP address of the device that they're installed on. - -Note: Mixpanel drops the `ip` address at ingestion and does not store it at rest, to protect a user's privacy. - -If you're tracking from your servers, you need to set the `ip` property of the events to the _client's_ IP address. Most server frameworks provide this out of the box. -* [Django](https://docs.djangoproject.com/en/4.1/ref/request-response/#django.http.HttpRequest.META) exposes this in the request object with `request.META['REMOTE_ADDR']`. -* [Flask](https://flask.palletsprojects.com/en/2.2.x/api/?highlight=remote_addr#flask.Request.remote_addr) exposes this as `request.remote_addr`. -* [Go](https://pkg.go.dev/net/http#Request) exposes this as the `RemoteAddr` field on the http.Request struct. -* [Nginx](http://nginx.org/en/docs/http/ngx_http_log_module.html) exposes this as `$remote_addr`. - -We recommend creating a helper function that does this for all tracking calls: -```python -from mixpanel import Mixpanel -mp = mixpanel.init("YOUR_TOKEN") - -def track_to_mp(request, event_name, properties): - properties["ip"] = request.remote_addr - mp.track(request.user_id, "Signed Up", properties) - -def handle_signup(request): - # ... logic to process the signup ... - - track_to_mp(request, "Signed Up", {"Signup Type": request.form["type"]}) - - return "Signup successful!" -``` - -## Tracking Geolocation (HTTP API) - -As all server-side calls originate from the same IP, such as the IP of your server, it can have the unintended effect of setting the location of all of your users to the location of your datacenter. -To prevent Ingestion API `/engage` endpoint from taking the IP of the incoming request for geolocation, you can specify the `ip=0` parameter. -``` -api.mixpanel.com/engage?verbose=1&ip=0 -``` - -If you want to pass in your own IP address using our [HTTP API](https://developer.mixpanel.com/reference/profile-set) (`/engage#profile-set` endpoint) similar to the way you can with `track()`, pass in a property called `$ip` to the message payload. -``` -{ - "$token": "e3bc4100330c35722740fb8c6f5abddc", - "$distinct_id": "13793", - "$ip": "72.229.28.185", - "$set": { - "Address": "1313 Mockingbird Lane" - } -} -``` -Notice that you need to set `$ip` outside of the $set dictionary. This action overwrites the geographic data on the profile with `distinct_id = 13793` with New York, NY. - -> **Note:** default geolocation tracking is based on IP addresses, which are meant to be approximations and **should not be considered fully accurate**, especially at the Region and City level. For use cases in which a high degree of location accuracy is required, you'll want to review the possibility of leveraging latitude and longitude coordinates as specified below. - -## Tracking Geolocation (Latitude and Longitude) - -If you have access to Latitude and Longitude information, you can specify `$latitude` and `$longitude` in the payload so that Mixpanel will use these properties (instead of the IP address) to infer the closest city. - -**Events** - -On events, the event properties must be named `$latitude` and `$longitude` and the values should be in floating point decimal degrees. -``` -{ - "event": "Signed Up", - "properties": { - "distinct_id": "13793", - "token": "mytoken", - "$latitude": 37.77, - "$longitude": -122.42 - } -} -``` - -**User Profiles** - -On user profile updates, the data must be named `$latitude` and `$longitude` and the values should be in floating point decimal degrees. - -You would also need to set `$latitude` and `$longitude` outside of the `$set` dictionary. - -You will see profile property `$geo_source=reverse_geocoding` in the Profile UI if location properties were determined through `$latitude` and `$longitude`. - -Do note: Reverse geocoding for user profiles is not supported via client-side SDKs. -``` -{ - "$token": "mytoken", - "$distinct_id": "13793", - "$latitude": 37.77, - "$longitude": -122.42, - "$set": { - "My_property": "my_value" - } -} -``` ## Tracking Page Views Page view tracking must be done manually for server-side implementations. Here are some general guidelines for tracking page views. @@ -171,3 +81,15 @@ Page view tracking must be done manually for server-side implementations. Here a - Fire page view events only on successful responses to the client - Parse headers and the request URL for common web analytics properties such as referrer and UTM parameters - See above for [parsing user agent](#tracking-browser-device-and-os) and [marketing attribution properties](#tracking-utms-and-referrer) + + +## Tracking Geolocation +By default, Mixpanel uses the IP address of the request to set geolocation properties. If you're tracking from your servers, you need to override the IP property of your events and profile updates from your server's IP address to the client's IP address. + +[Read our full guide](docs/tracking-best-practices/geolocation) on managing geolocation properties. + +## Identifying Users + +Mixpanel's server-side SDKs and HTTP API do not generate IDs automatically, meaning your server is responsible for generating IDs and maintaining ID persistence. + +[Read our full guide](/docs/tracking-methods/id-management/server-side-id-management) on Server-side ID Management. diff --git a/pages/docs/users/_meta.json b/pages/docs/users/_meta.json index 2c93de3c29..8b990fade7 100644 --- a/pages/docs/users/_meta.json +++ b/pages/docs/users/_meta.json @@ -1,4 +1,5 @@ { - "overview": "Overview", + "users-page": "Users Page", + "profile-page": "Profile Page", "cohorts": "Cohorts" } diff --git a/pages/docs/users/cohorts.md b/pages/docs/users/cohorts.md index dac5310a8d..d23ff2bfb9 100644 --- a/pages/docs/users/cohorts.md +++ b/pages/docs/users/cohorts.md @@ -1,5 +1,6 @@ # Cohorts +## Overview Cohorts are groups of users that share a certain set of properties or who perform a similar sequence of events. Mixpanel lets you visually define cohorts, view the list of users that comprise them, compare them in your analysis, and share them with the rest of your company. Here are some examples of cohorts you can create in Mixpanel: @@ -15,53 +16,67 @@ You can create cohorts via any of our report visualizations or explicitly using ### Creating a Cohort via a Report Click any bar or point in an Insights, Funnels, or Retention report and select "View Users". The side panel will show the list of users that belong to that bar or point you selected. You can save that group of users as a cohort. -### Creating a Cohort via the Cohort Builder -The [Cohort Builder](https://mixpanel.com/report/users) lets you define cohorts based on a precise set of conditions. These conditions are either of the form "Users who did `` more/less than ``" or "Users where `` is equal to/more/less than ``". +### Creating a Cohort via the Users page +The [Cohort Builder in the Users page](/docs/users/users-page#cohort-builder) lets you define cohorts based on a precise set of conditions. These conditions are either of the form "Users who did `` more/less than ``" or "Users where `` is equal to/more/less than ``". Let's walk through some of cohorts you can create with the builder. -#### Filter by users who watched more than 10 videos in the last 7 days +**Filter by users who watched more than 10 videos in the last 7 days** ![/Kapture_2021-04-06_at_13.43.06.gif](/Kapture_2021-04-06_at_13.43.06.gif) -#### Filter to only users who watched a video for the very first time in the past 30 days +**Filter to only users who watched a video for the very first time in the past 30 days** ![/Kapture_2021-04-06_at_13.52.43.gif](/Kapture_2021-04-06_at_13.52.43.gif) -#### Filter to users that watched more than 300 mins of video in the previous 30 days +**Filter to users that watched more than 300 mins of video in the previous 30 days** ![/Kapture_2021-04-06_at_13.54.25.gif](/Kapture_2021-04-06_at_13.54.25.gif) -#### Filter to users whose average video watch time was over 15 minutes in the previous 30 days +**Filter to users whose average video watch time was over 15 minutes in the previous 30 days** ![/Kapture_2021-04-06_at_13.57.34.gif](/Kapture_2021-04-06_at_13.57.34.gif) -#### Filter to users that purchased items in 3 unique categories in the last 30 days +**Filter to users that purchased items in 3 unique categories in the last 30 days** ![/Kapture_2021-04-06_at_14.00.02.gif](/Kapture_2021-04-06_at_14.00.02.gif) -#### Filter to users that watched a video on at least 3 unique days in the previous 30 days +**Filter to users that watched a video on at least 3 unique days in the previous 30 days** ![/Kapture_2021-04-06_at_14.05.11.gif](/Kapture_2021-04-06_at_14.05.11.gif) -#### Filter to users that made a purchase on 4 or more unique weeks in the last 3 months +**Filter to users that made a purchase on 4 or more unique weeks in the last 3 months** ![/Kapture_2021-04-06_at_14.09.03.gif](/Kapture_2021-04-06_at_14.09.03.gif) -#### Filter to users that are above the age of 60 +Filter to users that are above the age of 60 ![/Kapture_2021-04-06_at_14.13.40.gif](/Kapture_2021-04-06_at_14.13.40.gif) -#### Chaining cohorts together using the AND/OR operators +**Chaining cohorts together using the AND/OR operators** ![/Kapture_2021-04-06_at_14.31.41.gif](/Kapture_2021-04-06_at_14.31.41.gif) You can also access the builder directly from the property picker in any of our reports, by clicking Create Custom > Cohort. This will create a temporary cohort that only persists for your analysis session. -### Note on cohorts whose filters contain user properties +#### Multiple Cohort Definitions +Click the "+ group" in the bottom left corner of the cohort builder to add additional definitions to your cohorts. Each group contains a separate cohort definition, and you may toggle between using the AND/OR operator to combine your definitions. + + + +#### Cohorts definitions with user profile properties Because user profile properties only store the most recent value, cohorts involving user profile properties will use the current value for those properties (even if the value changed over time). For example, suppose the cohort’s filter criteria is: users where user[“City”] == “SF” and “Did Event: Order Ride 3 times in Last 7 days”. Mixpanel computes the above over the last 30 days and then groups the set of users who have property user[“City”] == “SF” as of right now and intersect that with the daily cohort of users who did Order Ride 3 times in the last 7 days. +#### Cohort definitions with a long list of unique values +If you have a specific list of users that you want to include in a cohort definition, it is not recommended to manually define them by their unique property values (list of 10K emails, user IDs, etc.). Parsing lists of values may affect your query performance and lead to some queries failing. As a best practice, you should add a profile property that identifies these users cohort membership, and then build a cohort definition using that profile property instead. + +To upload a group of user (or group) profiles and easily sort them into a cohort, add a value to the CSV which sorts the profiles into a cohort as a property. For example, give each profile the unique property of "Cohort = Android Users". Next, go to the [Cohorts](/docs/users/cohorts#creating-cohorts) tab to create a cohort as usual, and filter to user profiles with that property and save. This will create a cohort of users with that matching property. + +Note that when creating cohorts this way, the cohort will remain static, meaning that it will not update over time like other cohorts as the property is unchanging. + ## Using Cohorts in Analysis You can visualize how cohorts size over time, use cohorts to filter your reports, or compare how cohorts perform a metric. ### Visualizing Cohort Size Over Time -In Insights, you can define a metric based on the size of a cohort over time. This is useful to understand how key subsets of your user base (like your Power Users) are trending over time. Select a cohort from the "Events and Cohorts" menu in the Insights report; this will generate a line chart that shows the size of the cohort over time. Each point is the size of the cohort as of the end of that time interval. +In Insights, you can define a metric based on the size of a cohort over time. This is useful to understand how key subsets of your user base (like your Power Users) are trending over time. Select a cohort from the "Events and Cohorts" menu in the Insights report; this will generate a line chart that shows the size of the cohort over time. Each point is the size of the cohort as of the end of that time interval. + +Note that [cohort definitions that only contain user profile properties will appear static](/docs/users/cohorts#cohorts-definitions-with-user-profile-properties). ### Filtering by a Cohort @@ -96,3 +111,5 @@ We recommend sharing a set of key cohorts with your organization, to ensure that ## Exporting Cohorts You can download the list of users in any Cohort as a CSV via the Cohort Builder. You can also push cohorts to 3rd-party destinations like [Segment](/docs/cohort-sync/integrations/segment), [Braze](/docs/cohort-sync/integrations/braze), or a [Custom Webhook](/docs/cohort-sync/webhooks). + +Learn more about [cohort syncs](/docs/cohort-sync/). diff --git a/pages/docs/users/profile-page.md b/pages/docs/users/profile-page.md new file mode 100644 index 0000000000..df79f26b83 --- /dev/null +++ b/pages/docs/users/profile-page.md @@ -0,0 +1,29 @@ +# Profile Page + +## Overview +- profile page lets you learn more about a specific user profile of group profile +- Access it from Users page by clicking into any returned users + + +## Reserved properties on the profile page +- reference a few reserved properties as it relates to profile page (geolocation, email, name, pictures, updated at) +- Show a screenshot that highlights which UI area corresponds with what reserved props + +## Distinct ID cluster +- Canonical distinct_id is shown +- Expand to show all IDs currently in the cluster + +## Activity Feed +- see events for this user +- consecutive events are grouped. Click to expand to see grouped events. +- Click individual events to see properties +- Hide events to narrow in on specific events only +- Default to 30 days, can update date range +- Click View in Insights to see your current activity feed as an Insights report, including all current params like date range, hidden events, distinct_id, etc. + + + +## Editing profile properties +- You can edit profile properties directly in this UI to update the user +- Good for quick fixes, but best practice is to do this in implementation/some other source of truth +- Changes here will reflect in your raw data/exports, not just the UI. Updates from implementation/other sources after will overwrite your changes. diff --git a/pages/docs/users/overview.md b/pages/docs/users/users-page.md similarity index 64% rename from pages/docs/users/overview.md rename to pages/docs/users/users-page.md index a641f7cd5c..a26e9cb454 100644 --- a/pages/docs/users/overview.md +++ b/pages/docs/users/users-page.md @@ -5,7 +5,7 @@ Mixpanel's Users page allows you to filter users and gain a deeper understanding If you want to import User Profiles into Mixpanel, see our [User Profiles guide](/docs/data-structure/user-profiles). -### Use Case +## Use Case Mixpanel’s Users page aggregates and organizes a collection of user profiles. This facilitates a granular view into the behavior of individual users or groups of users. The Users page can be used to: @@ -14,15 +14,20 @@ Mixpanel’s Users page aggregates and organizes a collection of user profiles. - Update user profiles. - Create cohorts of groups of users. -## Basic Features +## Users Toggle You can select **User Profiles** or **All Users** in the Users page. If you select **User Profiles**, the page will only show users that have at least one user profile property set. If you select **All Users**, the page will show all users who have completed any event. ![/Screen_Shot_2022-07-12_at_11.55.17_AM.png](/Screen_Shot_2022-07-12_at_11.55.17_AM.png) -By clicking the name of a user in the User tables, you can explore that user's unique history by examining their user profile. Learn more about the Users Profiles [here](/docs/data-structure/user-profiles). +By clicking the name of a user in the User tables, you can explore that user's unique history by examining their [profile page](/docs/users/profile-page). Learn more about the Users Profiles [here](/docs/data-structure/user-profiles). -### Cohorts +### Analyze Group Profiles +You may analyze group profiles in the Users page by switching the identifier. Click the "Analyze Uniques by" dropdown in the top left corner of the UI, then select your group identifier. You will need to [modify your table columns](/docs/users/users-page#modifying-table-columns) and select group profile properties. + + + +## Cohorts Builder A cohort is a group of users who share a certain set of properties or have performed a particular combination or frequency of events. You can create a cohort on the Users page by generating filtering criteria. Once a cohort is created, you can save it and use it to group and filter data in other Mixpanel reports. @@ -32,23 +37,27 @@ Learn more about Cohorts [here](/docs/users/cohorts).

-### Modifying Table Columns +## Modifying Table Columns You may wish to change what data is displayed in the Users table. You can do so by clicking on **Edit Columns** and selecting / deselecting the profile properties you wish to display on the User table ![/Screen_Shot_2022-07-12_at_2.22.57_PM.png](/Screen_Shot_2022-07-12_at_2.22.57_PM.png) +## Exporting Profiles to CSV -## FAQ +To download your profiles from the Users page, simply click the **Export icon.** This will download all the profile data being displayed in the current report - to download more properties, edit your columns to select more properties. You can choose to filter the list or select individual profiles to download instead of downloading the full list. -### How do I create a cohort out of a list of user emails I have? +This is helpful for quickly creating a CSV template to use for [CSV profile imports](/docs/data-structure/user-profiles#importing-from-csv). -To upload a group of user (or group) profiles and easily sort them into a cohort, add a value to the CSV which sorts the profiles into a cohort as a property. For example, give each profile the unique property of "Cohort = Android Users". Next, go to the [Cohorts](/docs/users/cohorts#creating-cohorts) tab to create a cohort as usual, and filter to user profiles with that property and save. This will create a cohort of users with that matching property. +![/Screen_Shot_2022-07-12_at_2.26.45_PM.png](/Screen_Shot_2022-07-12_at_2.26.45_PM.png) -Note that when creating cohorts this way, the cohort will remain static, meaning that it will not update over time like other cohorts as the property is unchanging. -### How do I download User Profiles in Mixpanel? +## FAQ +#### How do I create a cohort out of a list of user emails I have? -To download your user profiles from the Users page, simply click the **Export icon.** This will download all the profile data being displayed in the current report - to download more properties, edit your columns to select more properties. You can choose to filter the list or select individual profiles to download instead of downloading the full list. +To upload a group of user (or group) profiles and easily sort them into a cohort, add a value to the CSV which sorts the profiles into a cohort as a property. For example, give each profile the unique property of "Cohort = Android Users". Next, go to the [Cohorts](/docs/users/cohorts#creating-cohorts) tab to create a cohort as usual, and filter to user profiles with that property and save. This will create a cohort of users with that matching property. -![/Screen_Shot_2022-07-12_at_2.26.45_PM.png](/Screen_Shot_2022-07-12_at_2.26.45_PM.png) +Note that when creating cohorts this way, the cohort will remain static, meaning that it will not update over time like other cohorts as the property is unchanging. + +#### Why are anonymous users not returned when filtering using the distinct ID user profile property? +Anonymous users do not have any user profile properties, including distinct ID. To search for an anonymous user, please use event properties. For example, you can search for users that tracked any events then add the distinct ID as an inline filter to the event. From b55ae855bc543b9636a16474b38667ddb5d4b265 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Sun, 30 Jun 2024 20:16:16 -0700 Subject: [PATCH 06/12] Myronkaifung content reorg admin (#1192) * Update overview.md * Update overview.md * Update organizations.md * Update managing-projects.md * Update roles-and-permissions.md * Update _meta.json * Update lexicon.mdx * Update _meta.json * Create login.md * Update end-user-data-management.md --- pages/docs/access-security/_meta.json | 1 + pages/docs/access-security/login.md | 30 +++ pages/docs/data-governance/_meta.json | 2 +- pages/docs/data-governance/lexicon.mdx | 53 +++-- .../orgs-and-projects/managing-projects.md | 33 +-- pages/docs/orgs-and-projects/organizations.md | 14 +- pages/docs/orgs-and-projects/overview.md | 4 +- .../roles-and-permissions.md | 4 +- .../docs/privacy/end-user-data-management.md | 211 +----------------- 9 files changed, 94 insertions(+), 258 deletions(-) create mode 100644 pages/docs/access-security/login.md diff --git a/pages/docs/access-security/_meta.json b/pages/docs/access-security/_meta.json index 14b2f9fd68..b854c0859f 100644 --- a/pages/docs/access-security/_meta.json +++ b/pages/docs/access-security/_meta.json @@ -1,4 +1,5 @@ { + "login": "Login", "two-factor-authentication": "Two Factor Authentication", "single-sign-on": "Single Sign-On" } diff --git a/pages/docs/access-security/login.md b/pages/docs/access-security/login.md new file mode 100644 index 0000000000..11e238aa52 --- /dev/null +++ b/pages/docs/access-security/login.md @@ -0,0 +1,30 @@ +# Login + +## Overview + +Mixpanel users access Mixpanel's UI by authenticating through a login process. Mixpanel supports a few different methods for login. + +## Magic Link +- is the default for all users when they sign up for a new account +- Unless domain is claimed or other access security settings (see 2FA and SSO) +- When you click sign in, an email is sent to the email associated with your account. Click the link in the email to login. + +## Password login +- Can override default magic link login by navigating to Personal Settings and defining a password. +- After defining a password, login defaults to password moving forward and magic link option will no longer be used. +- Change password in the same personal settings page + +## Organization Access Security +- org owners/admins can enforce requirements for access security to safeguard data. +- 2FA: Whenever users sign in with a username and password, they also need to enter a security code generated on their mobile device. Users do not need a security code when signing in through the organization's identity provider (SSO). +- SSO: Enable users of your organization to log in with single sign-on. Can also require users to login using SSO and assign roles/permissions via IdP. + +## FAQ + +#### Why am I not receiving the magic login link after I click in? +Check the junk/spam inbox for the email or click the resend the email from the login page. + +If you are not seeing the email even after checking spam and resending the email, it is possible that your account may be associated with a different email. In this case, try signing up for a new account using your provided email. If your account already exists, this is another way to send the magic login link to your email. If your account does not exist, it will create one for you. + +#### Why don't I see my team's data and reports? +If you signed up via an invitation from a teammate, it is possible that the invitation was sent with the incorrect access permission. Reach out to your teammate and have them follow [these instructions to grant you access](/docs/orgs-and-projects/roles-and-permissions#invite-users). diff --git a/pages/docs/data-governance/_meta.json b/pages/docs/data-governance/_meta.json index b35450ee74..597dbc67da 100644 --- a/pages/docs/data-governance/_meta.json +++ b/pages/docs/data-governance/_meta.json @@ -1,7 +1,7 @@ { + "lexicon": "Lexicon", "data-views-and-classification": "Data Views & Classification", "event-approval": "Event Approval", "data-volume-monitoring": "Data Volume Monitoring", - "lexicon": "Lexicon", "data-clean-up": "Data Clean-Up" } diff --git a/pages/docs/data-governance/lexicon.mdx b/pages/docs/data-governance/lexicon.mdx index 296026035d..81ad194251 100644 --- a/pages/docs/data-governance/lexicon.mdx +++ b/pages/docs/data-governance/lexicon.mdx @@ -88,6 +88,13 @@ If you have Group Analytics enabled, you will see a dropdown on the Profile Prop ![Lexicon Profile Properties](/lexicon-group-analytics-GIF.gif) +### Lookup Table Definitions + +[Lookup Tables](/docs/data-structure/lookup-tables) in your project are listed in your Lexicon. Click into a Lookup Table definition to export the underlying CSV, replace the Lookup Table with a new CSV, and see which properties are linked. + +### Formulas and Behaviors Definition +Saved [Formulas](/docs/reports/insights/metrics#formulas) and [Funnels/Retention Behaviors](/docs/features/saved-behaviors) in your project are also documented in your Lexicon. Review here to get an overview of existing definitions in your project that you can quickly leverage in your own analysis. + ## Filtering Events, Custom Events, and Properties Lexicon provides several options for you to filter your events, custom events, event properties, and profile properties. @@ -104,7 +111,7 @@ This data lets you easily discover the parts of your implementation that are mos ![Lexicon Query Volumes](/lexicon-query-volumes.png) -## Dropping and Hiding Data +## Dropping Data In Lexicon, you can intercept and drop incoming events or properties. Mixpanel won’t store any **new data** for the event or property you select to drop. **Warning: You cannot recover event data after you drop it.** @@ -130,6 +137,16 @@ To drop an event in Lexicon: ![Lexicon Drop Events Warning](/lexicon-drop-events-warning.png) 3. Click Drop. The status of the event indicates **Dropped**. +**Undropping Events** + +You can undrop events and properties when you decide you need them again. + +To undrop an event: + +1. Select a dropped event. The “Status” column indicates if an event is dropped. +![Lexicon Undrop Events](/lexicon-undrop-events.png) +2. Click **Undrop**. The “Status” column no longer contains “Dropped”. + ### Dropping Properties By dropping a property, you can intercept and drop incoming property. Mixpanel won’t store any new data for the property you select to drop. @@ -140,25 +157,25 @@ To drop a property in Lexicon: ![Lexicon Drop Properties](/lexicon-drop-properties.png) 2. Click **Drop**. A warning indicates that you cannot recover the data that you choose to drop. Click Drop to confirm. The status of the property will indicate Dropped. -### Undropping Events +**Undropping Properties** -You can undrop events and properties when you decide you need them again. +1. Select a dropped property. The “Status” column indicates if a property is dropped. +![Lexicon Undrop Properties](/lexicon-undrop-properties.png) +2. Click **Undrop**. The “Status” column no longer contains “Dropped”. -To undrop an event: +## Hiding Data -1. Select a dropped event. The “Status” column indicates if an event is dropped. -![Lexicon Undrop Events](/lexicon-undrop-events.png) -2. Click **Undrop**. The “Status” column no longer contains “Dropped”. +In Lexicon, you can hide any events or properties. Unlike [dropping data](/docs/data-governance/lexicon#dropping-data), hiding data does not affect data ingestion; any events/properties that are hidden will continue to be ingested in your project and count toward your data allowance. -### Undropping Properties +A hidden entity will not be indexed in your event/properties menu in the query builder. Any [inactive events and properties](/docs/tracking-best-practices/debugging#inactive-events-and-properties) will also be hidden. -1. Select a dropped property. The “Status” column indicates if a property is dropped. -![Lexicon Undrop Properties](/lexicon-undrop-properties.png) -2. Click **Undrop**. The “Status” column no longer contains “Dropped”. +Hidden events will be excluded from your query results. For example, it will not be included in "All Events" and won't appear as an intermediate step in your [Flows report](/docs/reports/flows). + +Hiding data is useful for preventing not-so-commonly used entities from cluttering your events/properties menu, or to prevent certain events from being considered in your reports. -### Hide Events and Properties +If you wish to use a hidden entity in your report, you may manually select the entity by searching in the events/properties menu and then clicking "Show Hidden Events/Properties" to reveal the hidden entity. -To hide an event or property: +### Hiding Events and Properties 1. Select one or more visible events, event properties, or profile properties. The “Hide” icon appears. You can check the “Status” field to determine whether an event or property is visible or hidden. ![Lexicon Hide Events](/hide-events.png) @@ -188,17 +205,15 @@ Do note however that user profile properties cannot be merged at this time. ### Merging Events -To merge events: +**To merge events:** 1. Select the events to merge. The “Merge” icon appears. 2. Click Merge. The “Merge Events” window appears. It shows the events you selected and explains that merging the selected events combines them into a single event, which does not affect the raw data. ![Lexicon Merge Events](/lexicon-merge-events.png) 3. In the “MERGE SELECTED EVENTS INTO…” section, specify which event Mixpanel should consider as the new unique event. 4. Click **Merge**. The merged event appears and the “Status” column indicates “Merged”. - -### Unmerging Events -To unmerge events: +**To unmerge events:** 1. Select the merged event to unmerge. The “Unmerge” icon appears. ![Lexicon Unmerge Events](/unmerge-events.png) @@ -206,7 +221,7 @@ To unmerge events: ### Merging Properties -To merge properties: +**To merge properties:** 1. Select the properties to merge. The “Merge” icon appears. 2. Click Merge. The “Merge Properties” window appears. It shows the properties you selected and explains that merging the selected properties combines them into a single property, which does not affect the raw data. @@ -216,7 +231,7 @@ To merge properties: ### Unmerging Properties -To unmerge properties: +**To unmerge properties:** 1. Select the merged property to unmerge. The “Unmerge” icon appears. ![Lexicon Unmerge Events](/unmerge-properties.png) diff --git a/pages/docs/orgs-and-projects/managing-projects.md b/pages/docs/orgs-and-projects/managing-projects.md index 71a0f3adf6..86593e2fb8 100644 --- a/pages/docs/orgs-and-projects/managing-projects.md +++ b/pages/docs/orgs-and-projects/managing-projects.md @@ -94,11 +94,11 @@ Then select the Projects tab. ## Manage Timezones for Projects -Mixpanel records all events in [Coordinated Universal Time (UTC)](https://www.worldtimeserver.com/learn/what-is-utc/) at intake. +>Note: For projects created before 11 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. -Mixpanel converts the timezone to your project timezone before writing the event to Mixpanel data stores. Mixpanel sets project timezones by city or region. If a city or region observes Daylight Savings Time, the ingestion offset adjusts appropriately. +Mixpanel records all events in [Coordinated Universal Time (UTC)](https://www.worldtimeserver.com/learn/what-is-utc/) at intake. Changing the timezone for any project under Project Settings only affects the timezone in which Mixpanel outputs results. ->Note: As of 11 Jan 2023, all new projects store their data in UTC. Changing the timezone for any project under Project Settings only affects the timezone in which Mixpanel outputs results. You will no longer see a gap or spike in events after changing the timezone. +Mixpanel sets project timezones by city or region. If a city or region observes Daylight Savings Time, the ingestion offset adjusts appropriately. ### Changing your Timezone @@ -120,17 +120,9 @@ To change the project’s timezone: >Note that changing the timezone will not affect any data, it only affects the timezone in which we output results. -### Understanding How Timezones Affect Data - -After you set your timezone correctly, you should send any dates or times to Mixpanel as Coordinated Universal Time (UTC). - -By default, Mixpanel’s integration libraries work with API ingestion endpoints to automatically convert the UTC timestamp or date to your project timezone before storing your data. - ->If you overwrite the default timestamp, import old data, or set a property that is in date format (e.g. Account Created Date), be sure to send the timestamp or date in UTC. - #### Sending Date Properties to Mixpanel -As mentioned previously, you should send date properties to Mixpanel as UTC. Date properties are one of the five data types Mixpanel accepts. +[Date properties are one of the five data types](/docs/data-structure/property-reference/data-type#date) Mixpanel accepts. Mixpanel events should be ingested with timestamps set to Coordinated Universal Time (UTC). If you overwrite the default timestamp, import old data, or set a property that is in date format (e.g. Account Created Date), be sure to send the timestamp or date in UTC. For this type of property, Mixpanel recommends an iso-formatted date string (YYYY-MM-DDTHH:mm:ss) to use in your Mixpanel reports. @@ -156,28 +148,19 @@ Mixpanel.track("Account Created Date", props); ``` #### Exporting Data from Mixpanel -When you’re exporting raw data from Mixpanel, your request requires the date parameters "from_date" and "to_date" to determine which date range of data to return. +When you’re exporting raw data from Mixpanel, your request requires the date parameters `from_date` and `to_date` to determine which date range of data to return. Mixpanel's raw export machines interpret the "from_date" and "to_date" values to your project’s timezone. As a result, if you request a single day of data, you receive one full day in your project’s timezone, not one full day in UTC. -As mentioned earlier, Mixpanel hardcodes event timestamps to your project’s timezone. However, the "$time" property from a raw export returns with a Unix timestamp, not a UTC timestamp. - -The Unix timestamp represents the number of seconds that have elapsed since 00:00:00 on January 1, 1970 in your project’s timezone. +As mentioned earlier, Mixpanel stores your events in UTC. The "$time" property from a raw export returns with a Unix timestamp, which represents the number of seconds that have elapsed since 00:00:00 on January 1, 1970. -In the example below, if your project’s timezone is US/Pacific, the below parameters return: - - -``` -00:00:00 Aug. 1 to 11:59:59 Aug. 1 PDT, or 07:00:00 Aug. 1 – 06:59:59 Aug. 2 UTC. from_date = "2015-08-01" to_date = "2015-08-01" -``` +In the example below, if your project’s timezone is US/Pacific, and you set both the `from_date` and `to_date` to `2023-08-01`, it will return events between `00:00:00 Aug. 1 to 11:59:59 Aug. 1 PDT`/`07:00:00 Aug. 1 – 06:59:59 Aug. 2 UTC` where the events timestamp are in Unix timestamp format in UTC. #### Importing Data into Mixpanel Always send imported data to Mixpanel in UTC to ensure it displays correctly in your project. -Mixpanel hardcodes timestamps of exported data to your project’s timezone. The exported data can be events and any date properties on events and users. - -As a result, operations such as extract, transform, and load, need a quick timestamp and date property offset to reset the data back to UTC before importing it back to Mixpanel. +Mixpanel stores your data in UTC, then use your project timezone setting to output data in your selected timezone. ## Transfer Project to Another Organization diff --git a/pages/docs/orgs-and-projects/organizations.md b/pages/docs/orgs-and-projects/organizations.md index b4afaf7305..9f5f26ed79 100644 --- a/pages/docs/orgs-and-projects/organizations.md +++ b/pages/docs/orgs-and-projects/organizations.md @@ -2,8 +2,12 @@ ## Overview +An Organization is an entity that links your projects, users, and subscription plan. -As an Organization Admin, you may create and manage security processes that dictate the requirements needed for your users to access your organization. +## Creating an Organization +A user who signs up for a new Mixpanel account without being invited by an existing Mixpanel user will be prompted to create a new organization. This is the only way a new organization is created. + +[Contact the Support team](https://mixpanel.com/get-support) if you need to create a new organization as a member of an existing organization. ## Organization Discoverability Organization Discoverability makes it seamless for new users with a shared work email domain to connect with teammates in an existing organization in Mixpanel, allowing them to access their team’s projects, data, and reports, instead of joining a new, empty org. @@ -28,3 +32,11 @@ The org owner or admin can then designate the level of discoverability of their **Admin Approval:** An organization designated as requiring “admin approval” is discoverable to any new user signing up with a specified email domain, but can only be joined upon request. Admins will receive an email notification to authorize access. **Invite Only:** An organization designated “invite only” is undiscoverable regardless of email domain. New users must be invited by the admin. + +## Deleting an Organization + +Organization Owners may request the closure of the organization under the Overview tab in the Organization Settings, which would delete your organization, all existing projects, and all the data contained inside of the project. Users will maintain access to your organization for 90 days, after which it will be deleted. After 90 days, organization projects will be **permanently** deleted. + +Learn more about [privacy and compliance here](/docs/privacy/overview). + +[Contact the Support team](https://mixpanel.com/get-support) if you have any questions regarding the deletion of your organization/data. diff --git a/pages/docs/orgs-and-projects/overview.md b/pages/docs/orgs-and-projects/overview.md index 62bdcabcff..99effe75ed 100644 --- a/pages/docs/orgs-and-projects/overview.md +++ b/pages/docs/orgs-and-projects/overview.md @@ -1,10 +1,12 @@ # Overview -The Mixpanel administrative system includes organizations and projects. +The Mixpanel administrative system includes organizations, projects, and teams. An **Organization** is the controlling entity that links projects, users, and a plan together. Each organization has a single Mixpanel plan associated with it and that plan is what determines the data volume limits and features available across all projects in the organization. A **Project** is a container for your product's analytics data, including saved entities like custom events, or saved reports. Projects house the events, properties and user profiles sent to them which can then be queried with Mixpanel’s web interface and APIs. A single organization can contain multiple projects and each project’s data tallies are summed together to give the organization-level usage. +A **Team** is a group of users in your organization that shares the same project access permission, which makes it easier to manage roles and permissions for a group of users. A team contains a roster of users, the projects they are assigned to, the role permission in each project, Data View access, and Classified Data access. + ![Organization Overview 1 Image](/organization_overview.png) diff --git a/pages/docs/orgs-and-projects/roles-and-permissions.md b/pages/docs/orgs-and-projects/roles-and-permissions.md index 1ff53e9ab6..2622a84897 100644 --- a/pages/docs/orgs-and-projects/roles-and-permissions.md +++ b/pages/docs/orgs-and-projects/roles-and-permissions.md @@ -44,7 +44,7 @@ If there are projects that you wish for everyone in your organization to have so ### Remove Users -You can remove users from an organization or project. +You can remove users from an organization or project. You can only remove users with role permission below your own. #### Remove User from an Organization @@ -95,6 +95,8 @@ Paid Organizations have four roles: Owner, Admin, Billing Admin and Member. Free #### Owner +>As a best practice, it is recommended to have at least 2 Organization Owners at all times, in case an owner loses access to their account or is no longer working with the company. + Organization Owners have administrative permissions for the organization and all the projects in the organization. Multiple users can be Owners. However, each organization must have at least one Owner. #### Admin diff --git a/pages/docs/privacy/end-user-data-management.md b/pages/docs/privacy/end-user-data-management.md index aebc2586f7..aa5222554d 100644 --- a/pages/docs/privacy/end-user-data-management.md +++ b/pages/docs/privacy/end-user-data-management.md @@ -100,213 +100,4 @@ Mixpanel deletion and retrieval APIs are in place to help Mixpanel implementatio > 📘GDPR Request Rate Limits > You can batch up to 2000 distinct IDs per deletion request and up to 2000 for a retrieval request. Request rates are limited for GDPR API requests. -### GDPR and CCPA API (v3) -The following retrieval and deletion API calls are updated for version 3 and are made for GDPR and CCPA compliance. - -#### Create Retrieval -Request Type: **POST** -Description: Creates a data retrieval job. -Endpoint: `https://mixpanel.com/api/app/data-retrievals/v3.0/?token=` -Parameters: - -| Parameter | Parameter Type | Data Type | Description | -|-----------------|-------------------------|----------------|-------------------| -| Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). | -| distinct_ids | Body. Passed in JSON blob format. | Array of strings | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 2000 distinct IDs. | -| compliance_type | Body. Passed in JSON blob format. | String | Select CCPA or GDPR. Default is GDPR. | -| disclosure_type | Body. Passed in JSON blob format. | String | Only required if compliance_type = CCPA. Can be [Data, Categories, or Sources. Default is Data](/docs/privacy/end-user-data-management#ccpa-requests). | - -Authorization: - -| Authorization Type | Pass As | Description | -|-----------------------------|-------------|-------------------| -| Bearer | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. | - -Example Request: -`curl "https://mixpanel.com/api/app/data-retrievals/v3.0/?token=591b3354bb2bdd96f72f23bf56911673" --H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc" - -Example Return: -`{"status":"ok","results":[{"status":"PENDING", "disclosure_type":"DATA", "date_requested":"2020-03-09T22:28:55.078315", "tracking_id":"1583792934719392965", "project_id":1978118, "compliance_type":"ccpa", "destination_url":null, "requesting_user":"pat.davis@mixpanel.com", "distinct_id_count":1}]}` - -##### Rate Limit - -We place a rate limit in place to ensure the integrity of our system as well as prevent a single project from monopolizing the avaialble resources for other projects. Getting a 429 response code from our GDPR API means that you have reached our rate-limit. We currently have a rate-limit of 1 request per second for GDPR APIs. We also limit maximum number of outstanding scans for a single project to be approximately 5 years. - -GDPR data retrieval process works by dividing the job of extracting the events by the granularity of day, getting the events belonging to each distinct_id in the request for each day going back to the first day for which we have events in Mixpanel. Since user activity can go back several years, this means that even a single data retrieval request might require scans of many hundred days. - -In order to maximize the throughput of data retrievals, we recommend sending the maximum number of distinct-ids per request, now at 2000 distinct-ids, then retrying with exponential backoff. Depending on the amount of data that needs to be scanned, retrying for several hours might sometimes be necessary. - -#### Check Status of Retrieval -Request Type: GET - -Description: Checks the status of a data retrieval job. - -Endpoint: `https://mixpanel.com/api/app/data-retrievals/v3.0/?token=` - -Return Format: -`200 OK -{ - "results": { - "status": oneOf [ - "PENDING", - "STAGING", - "STARTED", - "SUCCESS", - "FAILURE", - "REVOKED", - "NOT_FOUND", - "UNKNOWN", - ], - } -}` - -Return Key: - -| Name | Type | Description | -|----------|---------|-------------------| -| PENDING | String | Task ID returned from POST. | -| STAGING | String | The staging process of the retrieval task has started. The task can still be canceled during staging. | -| STARTED | String | The retrieval task has started, and cannot be canceled. | -| SUCCESS | String | The retrieval task is complete. | -| FAILURE | String | The retrieval task has failed. Check the original task input parameters and create a new task. | -| REVOKED | String | The retrieval task has been canceled through a DELETE operation. | -| NOT_FOUND | String | The retrieval task cannot be found. | -| UNKNOWN | String | An error occurred while locating the retrieval task. | - -Parameters: - -| Parameter | Parameter Type | Type | Description | -|-----------------|-------------------------|---------|------------------| -| Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). | -| Task ID | URL. Passed in request URL. | Query String Parameter | The tracking ID shown in the response. | - -Authorization: - -| Authorization Type | Pass As | Description | -|-----------------------------|-------------|------------------| -| Bearer | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. | - -Example Request: -`curl "https://mixpanel.com/api/app/data-retrievals/v3.0/1583958896131033662/?token=591b3354bb2bdd96f72f23bf56911673" --H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc"` - -Example Return: -`{"status": "ok", "results": {"status": "PENDING", "result": "", "distinct_ids": ["1"]}}` - -#### Create a Deletion Task -Request Type: POST - -Description: Creates a task that specifies a list of users in a particular project to delete. This will schedule a deletion job that will delete all data, including events and user profile data, for the users specified by distinct_ids. This deletion job may be canceled until it reaches the STARTED stage. It may take up to 30 days to complete a deletion task in a customer’s Mixpanel database. Mixpanel may retain records of deletion tasks for legal compliance purposes or for a short time based on our legitimate interest in providing a service continuity. - -Endpoint: `https://mixpanel.com/api/app/data-deletions/v3.0/?token=` - -Parameters: - -| Parameter | Parameter Type | Type | Description | -|-----------------|-------------------------|---------|------------------| -| Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). | -| distinct_ids | Body. Passed in JSON blob format. | Array of strings | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 1999 distinct IDs. | -| compliance_type | Body. Passed in JSON blob format. | String | Select CCPA or GDPR. Default is GDPR. | - -Authorization: - -| Authorization Type | Pass As | Description | -|-----------------------------|-------------|------------------| -| Bearer | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. | - -Example Request: -`curl "https://mixpanel.com/api/app/data-deletions/v3.0/?token=591b3354bb2bdd96f72f23bf56911673" --H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc" -d '{"compliance_type":"CCPA", "distinct_ids":["1"]}'` - -Example Return: -`{"status": "ok", "results": {"task_id": "35bd8477-f71f-4088-af55-c88a6fb4ad4a"}}` - -#### Check Status of a Deletion Task -Request Type: **GET** - -Description: Checks the status of an existing deletion task. - -Endpoint: `https://mixpanel.com/api/app/data-deletions/v3.0/?token=` - -Return Format: -`{ - "status": "ok", - "results": { - "tracking_id": , - "status": oneOf [ "PENDING", "STAGING", "STARTED", "SUCCESS", "FAILURE", "REVOKED", "NOT_FOUND", "UNKNOWN", ], - "requesting_user": , - "compliance_type": oneOf [ "ccpa", "gdpr", ], - "project_id": , - "date_requested": , - "distinct_ids": [,,] - } -}` - -Return Key: - -| Name | Type | Description | -|----------|---------|-------------------| -| PENDING | String | Task ID returned from POST. | -| STAGING | String | The staging process of the deletion task has started. The task can still be canceled during staging. | -| STARTED | String | The deletion task has started, and cannot be canceled. | -| SUCCESS | String | The deletion task is complete. | -| FAILURE | String | The deletion task has failed. Check the original task input parameters and create a new task. | -| REVOKED | String | The deletion task has been canceled through a DELETE operation. | -| NOT_FOUND | String | The deletion task cannot be found. | -| UNKNOWN | String | An error occurred while locating the deletion task. | - -Parameters: - -| Parameter | Parameter Type | Type | Description | -|-----------------|-------------------------|---------|------------------| -| Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). | -| Task ID | URL. Passed in request URL. | Query String Parameter | The tracking ID shown in the response. | - -Authorization: - -| Authorization Type | Pass As | Description | -|-----------------------------|-------------|------------------| -| Bearer | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. | - -Example Request: -`curl "https://mixpanel.com/api/app/data-deletions/v3.0/35bd8477-f71f-4088-af55-c88a6fb4ad4b/?token=591b3354bb2bdd96f72f23bf56911674" -H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc" - -Example Return: -`{"status": "ok", "results": {"tracking_id": "35bd8477-f71f-4088-af55-c88a6fb4ad4a", "status": "PENDING", "requesting_user": "pat.davis@mixpanel.com", "compliance_type": "ccpa", "project_id": 1978118, "date_requested": "2024-01-24T08:00:03.672120", "distinct_ids": ["1"]}}` - -#### Cancel Deletion -Request Type: **DELETE** - -Description: Cancels an existing deletion task. Deletion jobs can be canceled until the STARTED stage initiates. - -Endpoint: `https://mixpanel.com/api/app/data-deletions/v3.0/?token=` - -Return Format: `204 NoContent` or `405 MethodNotAllowed` - -Return Key: - -| Name | Type | Description | -|----------|----------|------------------| -| 204 NoContent | Query String Parameter `required` | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). | -| 405 MethodNotAllowed | Query String Parameter `required` | Task ID returned from POST. | - -Parameters: - -| Parameter | Parameter Type | Type | Description | -|-----------------|-------------------------|---------|------------------| -| Token | URL. Passed in request URL. | Query String Parameter | Your Mixpanel [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens). | -| distinct_ids | Body. Passed in JSON blob format. | Array of strings | A list of distinct IDs associated with the users whose data you would like to export. You can add up to 1999 distinct IDs. | - -Authorization: - -| Authorization Type | Pass As | Description | -|-----------------------------|-------------|------------------| -| Bearer | Body. Passed in JSON blob format. | Your [OAuth token](/docs/privacy/end-user-data-management#generate-oauth-token) for GDPR APIs. | - -Example Request: -`curl "https://mixpanel.com/api/app/data-deletions/v3.0/?token=591b3354bb2bdd96f72f23bf56911673" --H "Authorization: Bearer vZcErNw8JCq42BZUJyWoZmDWCKBxXc" -d '{"distinct_ids":["1"]}'` - -Example Return: -`{"status": "ok", "results": {"task_id": "35bd8477-f71f-4088-af55-c88a6fb4ad4a"}}` +Please [see our GDPR API Reference](https://developer.mixpanel.com/reference/gdpr-api) to learn more about the deletion/retrieval endpoints. From 17c8ac3ab43ae80ebf7528f12a7485abda9958f8 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Sun, 30 Jun 2024 23:00:09 -0700 Subject: [PATCH 07/12] Myronkaifung content reorg data out (#1195) * Update _meta.json * Update and rename pages/docs/data-structure/concepts.md to pages/docs/data-structure.md * Update original-id-merge.md * Update simplified-id-merge.md * Update _meta.json * Rename pages/docs/migration/overview.md to pages/docs/migration.md * Update migration.md * Update _meta.json * Rename pages/docs/orgs-and-projects/overview.md to pages/docs/orgs-and-projects.md * Update and rename pages/docs/access-security/single-sign-on/overview.md to pages/docs/access-security/single-sign-on.md * Update _meta.json * Update _meta.json * Update and rename overview.md to .md * Rename pages/docs/privacy/.md to pages/docs/privacys.md * Rename privacys.md to privacy.md * Update and rename pages/docs/data-pipelines/overview.md to pages/docs/data-pipelines.md * Update _meta.json * Update _meta.json * Update roles-and-permissions.md * Update login.md * Update reports.mdx * Create exporting-methods.md * Update webhooks.md * Create integrations.mdx * Update data-pipelines.md * Update schematized-export-pipeline.md * Update and rename aws-raw-pipeline.md to raw-aws-s3-pipeline.md * Update and rename azure-raw-pipeline.md to raw-azure-pipeline.md * Update and rename google-cloud-storage-raw-pipeline.md to raw-gcs-pipeline.md * Update and rename raw-aws-s3-pipeline.md to raw-aws-pipeline.md * Update and rename bigquery.md to schematized-bigquery-pipeline.md * Update and rename amazon-s3.md to schematized-aws-pipeline.md * Update and rename azure-blob-storage.md to schematized-azure-pipeline.md * Update and rename google-cloud-storage.md to schematized-gcs-pipeline.md * Update and rename snowflake.md to schematized-snowflake-pipeline.md * Update _meta.json * Create integrations.mdx --- pages/docs/_meta.json | 1 + pages/docs/access-security/login.md | 6 +- .../overview.md => single-sign-on.md} | 2 +- .../access-security/single-sign-on/_meta.json | 1 - pages/docs/cohort-sync/integrations.mdx | 35 +++++++++++ pages/docs/cohort-sync/webhooks.md | 63 +++++++++---------- .../overview.md => data-pipelines.md} | 5 +- pages/docs/data-pipelines/_meta.json | 1 - pages/docs/data-pipelines/integrations.mdx | 25 ++++++++ .../data-pipelines/integrations/_meta.json | 16 ++--- ...ws-raw-pipeline.md => raw-aws-pipeline.md} | 2 +- ...-raw-pipeline.md => raw-azure-pipeline.md} | 2 +- ...ge-raw-pipeline.md => raw-gcs-pipeline.md} | 2 +- ...azon-s3.md => schematized-aws-pipeline.md} | 2 +- ...orage.md => schematized-azure-pipeline.md} | 2 +- ...ry.md => schematized-bigquery-pipeline.md} | 2 +- ...storage.md => schematized-gcs-pipeline.md} | 4 +- ...e.md => schematized-snowflake-pipeline.md} | 2 +- .../schematized-export-pipeline.md | 2 +- .../concepts.md => data-structure.md} | 8 +-- pages/docs/data-structure/_meta.json | 1 - pages/docs/exporting-methods.md | 59 +++++++++++++++++ .../{migration/overview.md => migration.md} | 3 +- pages/docs/migration/_meta.json | 1 - .../overview.md => orgs-and-projects.md} | 0 pages/docs/orgs-and-projects/_meta.json | 1 - .../roles-and-permissions.md | 16 ++--- .../docs/{privacy/overview.md => privacy.md} | 4 +- pages/docs/privacy/_meta.json | 1 - pages/docs/reports.mdx | 2 +- .../id-management/original-id-merge.md | 2 +- .../id-management/simplified-id-merge.md | 3 +- 32 files changed, 196 insertions(+), 80 deletions(-) rename pages/docs/access-security/{single-sign-on/overview.md => single-sign-on.md} (99%) create mode 100644 pages/docs/cohort-sync/integrations.mdx rename pages/docs/{data-pipelines/overview.md => data-pipelines.md} (92%) create mode 100644 pages/docs/data-pipelines/integrations.mdx rename pages/docs/data-pipelines/integrations/{aws-raw-pipeline.md => raw-aws-pipeline.md} (99%) rename pages/docs/data-pipelines/integrations/{azure-raw-pipeline.md => raw-azure-pipeline.md} (99%) rename pages/docs/data-pipelines/integrations/{google-cloud-storage-raw-pipeline.md => raw-gcs-pipeline.md} (96%) rename pages/docs/data-pipelines/integrations/{amazon-s3.md => schematized-aws-pipeline.md} (99%) rename pages/docs/data-pipelines/integrations/{azure-blob-storage.md => schematized-azure-pipeline.md} (98%) rename pages/docs/data-pipelines/integrations/{bigquery.md => schematized-bigquery-pipeline.md} (99%) rename pages/docs/data-pipelines/integrations/{google-cloud-storage.md => schematized-gcs-pipeline.md} (81%) rename pages/docs/data-pipelines/integrations/{snowflake.md => schematized-snowflake-pipeline.md} (99%) rename pages/docs/{data-structure/concepts.md => data-structure.md} (94%) create mode 100644 pages/docs/exporting-methods.md rename pages/docs/{migration/overview.md => migration.md} (99%) rename pages/docs/{orgs-and-projects/overview.md => orgs-and-projects.md} (100%) rename pages/docs/{privacy/overview.md => privacy.md} (99%) diff --git a/pages/docs/_meta.json b/pages/docs/_meta.json index 92272c45b8..d460c448f9 100644 --- a/pages/docs/_meta.json +++ b/pages/docs/_meta.json @@ -35,6 +35,7 @@ "type": "separator", "title": "DATA OUT" }, + "exporting-methods": "Exporting Methods", "data-pipelines": "Data Pipelines", "cohort-sync": "Cohort Sync", "support": { diff --git a/pages/docs/access-security/login.md b/pages/docs/access-security/login.md index 11e238aa52..67afeabe1d 100644 --- a/pages/docs/access-security/login.md +++ b/pages/docs/access-security/login.md @@ -4,17 +4,17 @@ Mixpanel users access Mixpanel's UI by authenticating through a login process. Mixpanel supports a few different methods for login. -## Magic Link +## Magic Link Login - is the default for all users when they sign up for a new account - Unless domain is claimed or other access security settings (see 2FA and SSO) - When you click sign in, an email is sent to the email associated with your account. Click the link in the email to login. -## Password login +## Password Login - Can override default magic link login by navigating to Personal Settings and defining a password. - After defining a password, login defaults to password moving forward and magic link option will no longer be used. - Change password in the same personal settings page -## Organization Access Security +## Organization-wide Access Security Settings - org owners/admins can enforce requirements for access security to safeguard data. - 2FA: Whenever users sign in with a username and password, they also need to enter a security code generated on their mobile device. Users do not need a security code when signing in through the organization's identity provider (SSO). - SSO: Enable users of your organization to log in with single sign-on. Can also require users to login using SSO and assign roles/permissions via IdP. diff --git a/pages/docs/access-security/single-sign-on/overview.md b/pages/docs/access-security/single-sign-on.md similarity index 99% rename from pages/docs/access-security/single-sign-on/overview.md rename to pages/docs/access-security/single-sign-on.md index 97708d92c3..160c26fec4 100644 --- a/pages/docs/access-security/single-sign-on/overview.md +++ b/pages/docs/access-security/single-sign-on.md @@ -1,4 +1,4 @@ -# SSO +# Single Sign-On ## Overview diff --git a/pages/docs/access-security/single-sign-on/_meta.json b/pages/docs/access-security/single-sign-on/_meta.json index 1eb0e3e8bc..bfb9bf5955 100644 --- a/pages/docs/access-security/single-sign-on/_meta.json +++ b/pages/docs/access-security/single-sign-on/_meta.json @@ -1,5 +1,4 @@ { - "overview": "Overview", "azure": "Azure", "jumpcloud": "JumpCloud", "okta": "Okta" diff --git a/pages/docs/cohort-sync/integrations.mdx b/pages/docs/cohort-sync/integrations.mdx new file mode 100644 index 0000000000..74561d85c5 --- /dev/null +++ b/pages/docs/cohort-sync/integrations.mdx @@ -0,0 +1,35 @@ +# Cohort Sync Integrations + +import { Card, Cards } from 'nextra/components' + +> This page highlights integrations that sends Mixpanel Cohorts to external destinations. Learn more about [integrations that imports data from other destinations into Mixpanel](/docs/tracking-methods/integrations) and [integrations that exports data from Mixpanel to data warehouses](/docs/data-pipelines/integrations/). + +These integrations allow you to send your [Cohorts](docs/users/cohorts) to other destinations for audience targeting. You may review our complete integrations directory [here](https://mixpanel.com/partners/integrations). If you don't see what you're looking for [reach out to us](https://mixpanel.com/get-support). + +## Featured Integrations + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/pages/docs/cohort-sync/webhooks.md b/pages/docs/cohort-sync/webhooks.md index 0b0300948a..b2c248021f 100644 --- a/pages/docs/cohort-sync/webhooks.md +++ b/pages/docs/cohort-sync/webhooks.md @@ -18,6 +18,9 @@ Optional: Basic Authentication when calling the webhook URL provided From this point onward, you can sync any cohort to this connection from our cohorts page. +### Exported Properties +Mixpanel will automatically include `email`, `mixpanel_distinct_id`, `first_name`, and `last_name` to identify the user. If you need to add extra properties, feel free to add in `Properties to Export` field where we populate some pre-existing fields for you to choose. + ## Webhook Format Our webhook format has the following structure in the body of a `POST` request: * **action**: The action defines the type of message we are sending. It will be one of: @@ -31,7 +34,7 @@ Our webhook format has the following structure in the body of a `POST` request: * **mixpanel_cohort_description**: The cohort description, editable via the Mixpanel UI. * **mixpanel_session_id**: An identifier for this export. Mixpanel sends large cohorts over multiple messages; mixpanel_session_id uniquely identifies a set of requests that correspond to the same export. * **page_info**: An object containing “total_pages”, i.e. the number of total messages for the given session ID, and “page_count”, the index of which page this message is (e.g. message 6 of 10, in the example below). You may use this value to know if/when you’ve collected the full set of messages for an export. - * **members**: The list of users being added or removed from the cohort. We include `email`, `mixpanel_distinct_id`, `first_name`, and `last_name` to help identify the user. + * **members**: The list of users being added or removed from the cohort. We include `email`, `mixpanel_distinct_id`, `first_name`, and `last_name` to help identify the user. You may [specify additional properties](/docs/cohort-sync/webhooks#exported-properties) during setup. You can download the Swagger spec [here](https://mxpnl.notion.site/Cohort-Webhook-Yaml-17d35e8ca78245fdbfa0aa4fcbb56596). @@ -87,61 +90,53 @@ We expect a JSON response of the following shape. } ``` -## Simple Sync Scenario +## Sync +Cohorts are synced once every 30 minutes. The batch size is set to 1000 users per call to `add_members` or `remove_members`. -Consider A, B, C, D, E, F as users. Sync interval is 30 minutes. T is when the sync is created in our UI. -`add_members(...)` indicates a call to the webhook to add members. `remove_members(...)` indicates a call to remove members. +### Full Sync +Full syncs are only performed when: +* We sync the cohort for the first time. +* We store the snapshot of the cohort state for the last successful sync for 3 days. If your webhook server is down (returns a 429 or 5XX error) for more than 3 days, the snapshot expires and we do a full sync. -* **T**: `add_members(A, B, C, D)` | `remove_members()` -* **T+0.1h**: B, D leave the cohort -* **T+0.2h**: E, F join the cohort -* **T+0.5h**: `add_members(E, F)` | `remove_members(B, D)` -* <...No cohort changes...> -* **T+1h**: `add_members()` | `remove_members()` calls are made to the customer webhook +Subsequent syncs include only differences in membership since the previous successful sync in order to preserve bandwidth, through a [diffing](/docs/cohort-sync/webhooks#diffing) mechanism. -## FAQ -### How can we add custom properties? -Mixpanel will automatically include `email`, `mixpanel_distinct_id`, `first_name`, and `last_name` to identify the user. If you need to add extra properties, feel free to add in `Properties to Export` field where we populate some pre-existing fields for you to choose. +### Diffing +Every time we perform a successful sync to your webhook, we store a snapshot of the cohort as of that time. This snapshot is valid for 3 days. Subsequent syncs use the last successful snapshot of the cohort to compute the number of users added and removed (the diff). We send this diff to your webhook via the `add_members` and `remove_members` calls. -### What is the frequency of the syncs? -We sync cohorts once every 30 minutes. +### Example Webhook Sync Scenario -### How many users are in each batch? -The batch size is set at 1000 users per call to `add_members` or `remove_members`. +Consider A, B, C, D, E, and F as users. The sync interval is 30 minutes. T represents the time when the sync is created in our UI. -### How does diffing work? -Every time we perform a successful sync to your webhook, we store a snapshot of the cohort as of that time. This snapshot is valid for 3 days. Subsequent syncs use the last successful snapshot of the cohort to compute the number of users added and removed (the diff). We send this diff to your webhook via the `add_members` and `remove_members` calls. +`add_members(...)` indicates a call to the webhook to add members. `remove_members(...)` indicates a call to remove members. -### When is a full sync of all members in the cohort performed? -Full syncs are only performed when: -* We sync the cohort for the first time. -* We store the snapshot of the cohort state for the last successful sync for 3 days. If your webhook server is down (returns a 429 or 5XX error) for more than 3 days, the snapshot expires and we do a full sync. +* **T**: `add_members(A, B, C, D)` | `remove_members()` +* **T+10mins**: B, D leave the cohort +* **T+20mins**: E, F join the cohort +* **T+30mins**: `add_members(E, F)` | `remove_members(B, D)` +* <...No cohort changes...> +* **T+1h**: `add_members()` | `remove_members()` calls are made to the customer webhook -### How are diffs computed when a sync fails? -When a sync fails, we do not update the cohort snapshot. The next sync performed will recompute the diff based on the last successful snapshot (until 3 days have passed, at which point we will attempt to sync the full cohort). This ensures that the state of the cohort will converge to what Mixpanel has. +### Failed Syncs +We pause syncs when your server returns a non-transient error (400, 401, 403, 404). Please use the appropriate HTTP status code to indicate a non-transient error; this helps avoid added load. We record failed syncs in our UI and display the error message returned in the response from your webhook server (see the `error.message` field in the sample response above). -### When are syncs paused? -We pause syncs on when your server returns a non-transient error (400, 401, 403, 404). Please use the appropriate HTTP status code to indicate a non-transient error; this helps avoid added load. +A notification email is sent to all users who have set up cohort syncs when the syncs pause due to an error. -We record failed syncs in our UI and display the error message returned in the response from your webhook server (see the `error.message` field in the sample response above). +We retry syncs 5 times over 60 secs with exponential backoff in response to 5xx and 429 status codes. After this point, we will wait until the next scheduled sync to retry. -### Do we get notified when the sync is paused? -Yes, an email is sent to all users who have set up cohort syncs when the syncs pause due to an error. +#### Diffs After Failed Syncs +When a sync fails, we do not update the cohort snapshot. The next sync performed will recompute the diff based on the last successful snapshot (until 3 days have passed, at which point we will attempt to sync the full cohort). This ensures that the state of the cohort will converge to what Mixpanel has. +## FAQ ### Does page_count in the requests start from 0 or 1? The page_count starts from 1. -### Do you retry on webhook call failures? -Yes, we retry 5 times over 60 secs with exponential backoff in response to 5xx and 429 status codes. After this point, we will wait until the next scheduled sync to retry. - ### Are users within cohort resynced when webhook calls fail or there is an internal failure? Even though we just sync a diff of users for each cohort there can be failures that occur mid sync. In a case like this, we do not have a mechanism to keep track of users that were already synced for a cohort when the failure occurs in between the sync process. So we start the sync from the top again. This can cause issues like users being synced again. ### What can go wrong for custom webhooks when users are synced again after failure scenarios? For example, If these users are set up for some action upon arrival, this failure and recovery could trigger a duplicate action for the same user. -### How to avoid duplicate actions for the same users? This can be fixed on the custom webhook server-side by keeping track of users who have been already targeted with the action. This way during failure and recovery scenarios of cohort syncs duplicate actions for the same users can be avoided. ### How are actions tracked in Mixpanel? diff --git a/pages/docs/data-pipelines/overview.md b/pages/docs/data-pipelines.md similarity index 92% rename from pages/docs/data-pipelines/overview.md rename to pages/docs/data-pipelines.md index 3c6b8d7344..8e4e8eddd4 100644 --- a/pages/docs/data-pipelines/overview.md +++ b/pages/docs/data-pipelines.md @@ -1,4 +1,4 @@ -# Overview +# Data Pipelines Data Pipelines is a [paid add-on](https://mixpanel.com/pricing) which continuously exports the events in your Mixpanel project to a cloud storage bucket or data warehouse of your choice. It's useful if you want to analyze Mixpanel events using SQL in your own environment. @@ -65,6 +65,9 @@ This can happen for a few reasons: - Data Delay: it can take up to 1 day for late arriving data to be synced from Mixpanel to your destination. - Hidden Events: Mixpanel exports all events to your destination, even ones that are hidden in the UI via Lexicon. We recommend checking whether the count in your destination is mostly due to events that have been hidden in the Mixpanel UI. +### What timezone is used for my event exports? +Pipeline exports raw data from your project so all exported events so it will be whatever timestamp was supplied at the time of ingestion. This means that the timestamp for exported events from your pipeline will be in the UTC timezone, unless your project was created before 11 Jan 2023. Learn more about [managing timezones here](/docs/orgs-and-projects/managing-projects#manage-timezones-for-projects). + ### How can I count events exported by Mixpanel in the warehouse? Counting events can be slightly different for each warehouse, since we use different partitioning methods. Here are examples for [BigQuery](/docs/data-pipelines/integrations/bigquery#getting-the-number-of-events-in-each-day) and [Snowflake](/docs/data-pipelines/integrations/snowflake#getting-the-number-of-events-in-each-day). diff --git a/pages/docs/data-pipelines/_meta.json b/pages/docs/data-pipelines/_meta.json index 0bfe54aa99..f8ee76d0ba 100644 --- a/pages/docs/data-pipelines/_meta.json +++ b/pages/docs/data-pipelines/_meta.json @@ -1,5 +1,4 @@ { - "overview": "Overview", "schematized-export-pipeline": "Schematized Export Pipeline", "integrations": "Integrations" } diff --git a/pages/docs/data-pipelines/integrations.mdx b/pages/docs/data-pipelines/integrations.mdx new file mode 100644 index 0000000000..61fef7c1ec --- /dev/null +++ b/pages/docs/data-pipelines/integrations.mdx @@ -0,0 +1,25 @@ +# Data Pipeline Integrations + +import { Card, Cards } from 'nextra/components' + +> This page highlights integrations that sends Mixpanel data to data warehouses. Learn more about [integrations that imports data from other destinations into Mixpanel](/docs/tracking-methods/integrations) and [integrations that exports cohorts for audience targeting](docs/cohort-sync/integrations). + +These integrations allow you to send your [raw data](/docs/data-pipelines#raw) and [schematized data](/docs/data-pipelines#schematized) to your cloud storage bucket or data warehouse. You may review our complete integrations directory [here](https://mixpanel.com/partners/integrations). If you don't see what you're looking for [reach out to us](https://mixpanel.com/get-support). + +## Raw Pipelines + + + + + + + +## Schematized Pipelines + + + + + + + + diff --git a/pages/docs/data-pipelines/integrations/_meta.json b/pages/docs/data-pipelines/integrations/_meta.json index d734f4c304..c47b993281 100644 --- a/pages/docs/data-pipelines/integrations/_meta.json +++ b/pages/docs/data-pipelines/integrations/_meta.json @@ -1,10 +1,10 @@ { - "aws-raw-pipeline": "AWS Raw Pipeline", - "amazon-s3": "Amazon S3", - "azure-raw-pipeline": "Azure Raw Pipeline", - "azure-blob-storage": "Azure Blob Storage", - "bigquery": "BigQuery", - "google-cloud-storage-raw-pipeline": "Google Cloud Storage Raw Pipeline", - "google-cloud-storage": "Google Cloud Storage", - "snowflake": "Snowflake" + "raw-aws-pipeline": "Raw AWS Pipeline", + "raw-azure-pipeline": "Raw Azure Pipeline", + "raw-gcs-pipeline": "Raw GCS Pipeline", + "schematized-bigquery-pipeline": "Schematized BigQuery Pipeline", + "schematized-aws-pipeline": "Schematized AWS Pipeline", + "schematized-azure-pipeline": "Schematized Azure Pipeline", + "schematized-gcs-pipeline": "Schematized GCS Pipeline", + "schematized-snowflake-pipeline": "Schematized Snowflake Pipeline" } diff --git a/pages/docs/data-pipelines/integrations/aws-raw-pipeline.md b/pages/docs/data-pipelines/integrations/raw-aws-pipeline.md similarity index 99% rename from pages/docs/data-pipelines/integrations/aws-raw-pipeline.md rename to pages/docs/data-pipelines/integrations/raw-aws-pipeline.md index 5e06e0f484..7aaf4c2037 100644 --- a/pages/docs/data-pipelines/integrations/aws-raw-pipeline.md +++ b/pages/docs/data-pipelines/integrations/raw-aws-pipeline.md @@ -1,4 +1,4 @@ -# AWS Raw Pipeline +# Raw AWS Pipeline To set up a raw export pipeline to an S3 bucket from Mixpanel, you must configure S3 to receive the exported data, then [create a pipeline](https://developer.mixpanel.com/reference/create-warehouse-pipeline) to export the data. diff --git a/pages/docs/data-pipelines/integrations/azure-raw-pipeline.md b/pages/docs/data-pipelines/integrations/raw-azure-pipeline.md similarity index 99% rename from pages/docs/data-pipelines/integrations/azure-raw-pipeline.md rename to pages/docs/data-pipelines/integrations/raw-azure-pipeline.md index 7957f2e6d5..2d601fb277 100644 --- a/pages/docs/data-pipelines/integrations/azure-raw-pipeline.md +++ b/pages/docs/data-pipelines/integrations/raw-azure-pipeline.md @@ -1,4 +1,4 @@ -# Azure Raw Pipeline +# Raw Azure Pipeline To set up a raw export pipeline to Azure Blob Storage from Mixpanel, you must first give Mixpanel permission to write to Azure. Next you can [create a pipeline](https://developer.mixpanel.com/reference/create-warehouse-pipeline) to export the data. Mixpanel then uploads the data to Azure Blob Storage on a recurring basis. diff --git a/pages/docs/data-pipelines/integrations/google-cloud-storage-raw-pipeline.md b/pages/docs/data-pipelines/integrations/raw-gcs-pipeline.md similarity index 96% rename from pages/docs/data-pipelines/integrations/google-cloud-storage-raw-pipeline.md rename to pages/docs/data-pipelines/integrations/raw-gcs-pipeline.md index a3ad267c76..a7e453fe19 100644 --- a/pages/docs/data-pipelines/integrations/google-cloud-storage-raw-pipeline.md +++ b/pages/docs/data-pipelines/integrations/raw-gcs-pipeline.md @@ -1,4 +1,4 @@ -# Google Cloud Storage Raw Pipeline +# Raw GCS Pipeline To set up a raw export pipeline to Google Cloud Storage (GCS) from Mixpanel, you must configure GCS to receive the exported data, then [create a pipeline](https://developer.mixpanel.com/reference/create-warehouse-pipeline) to export the data. diff --git a/pages/docs/data-pipelines/integrations/amazon-s3.md b/pages/docs/data-pipelines/integrations/schematized-aws-pipeline.md similarity index 99% rename from pages/docs/data-pipelines/integrations/amazon-s3.md rename to pages/docs/data-pipelines/integrations/schematized-aws-pipeline.md index 804ffc1298..9ec6e78f50 100644 --- a/pages/docs/data-pipelines/integrations/amazon-s3.md +++ b/pages/docs/data-pipelines/integrations/schematized-aws-pipeline.md @@ -1,4 +1,4 @@ -# Amazon S3 +# Schematized AWS Pipeline Mixpanel's [Schematized Export Pipeline](/docs/data-pipelines/schematized-export-pipeline) lets you export your Mixpanel data directly into an S3 bucket, allowing the use of Glue to query it. To set up the Mixpanel AWS pipeline, you must configure AWS to receive the exported data, then [create a pipeline](https://developer.mixpanel.com/reference/create-warehouse-pipeline) to export the data. diff --git a/pages/docs/data-pipelines/integrations/azure-blob-storage.md b/pages/docs/data-pipelines/integrations/schematized-azure-pipeline.md similarity index 98% rename from pages/docs/data-pipelines/integrations/azure-blob-storage.md rename to pages/docs/data-pipelines/integrations/schematized-azure-pipeline.md index 147fc821d3..45edba2a64 100644 --- a/pages/docs/data-pipelines/integrations/azure-blob-storage.md +++ b/pages/docs/data-pipelines/integrations/schematized-azure-pipeline.md @@ -1,4 +1,4 @@ -# Azure Blob Storage +# Schematized Azure Pipeline Mixpanel’s Azure Blob Export is one type of [Schematized Export Pipeline](/docs/data-pipelines/schematized-export-pipeline) that exports Mixpanel events and people data and imports them into an Azure Blob storage instance. diff --git a/pages/docs/data-pipelines/integrations/bigquery.md b/pages/docs/data-pipelines/integrations/schematized-bigquery-pipeline.md similarity index 99% rename from pages/docs/data-pipelines/integrations/bigquery.md rename to pages/docs/data-pipelines/integrations/schematized-bigquery-pipeline.md index a2ce55881e..2c52d9ae50 100644 --- a/pages/docs/data-pipelines/integrations/bigquery.md +++ b/pages/docs/data-pipelines/integrations/schematized-bigquery-pipeline.md @@ -1,4 +1,4 @@ -# BigQuery +# Schematized BigQuery Pipeline This guide describes how Mixpanel exports your data to a [Google BigQuery](https://cloud.google.com/bigquery/) dataset. ## Design diff --git a/pages/docs/data-pipelines/integrations/google-cloud-storage.md b/pages/docs/data-pipelines/integrations/schematized-gcs-pipeline.md similarity index 81% rename from pages/docs/data-pipelines/integrations/google-cloud-storage.md rename to pages/docs/data-pipelines/integrations/schematized-gcs-pipeline.md index 23d3694dda..69f3fd82a4 100644 --- a/pages/docs/data-pipelines/integrations/google-cloud-storage.md +++ b/pages/docs/data-pipelines/integrations/schematized-gcs-pipeline.md @@ -1,6 +1,6 @@ -# Google Cloud Storage +# Schematized GCS Pipeline -The GCS schema pipeline exports [transformed data](/docs/data-pipelines/schematized-export-pipeline#transformation-rules) to a GCS bucket. This can be useful in case you want to export Mixpanel data into your own BigQuery instance. +The Google Cloud Storage schema pipeline exports [transformed data](/docs/data-pipelines/schematized-export-pipeline#transformation-rules) to a GCS bucket. This can be useful in case you want to export Mixpanel data into your own BigQuery instance. To set up a schematized export pipeline to Google Cloud Storage (GCS) from Mixpanel, you must configure GCS to receive the exported data, then [create a pipeline](https://developer.mixpanel.com/reference/create-warehouse-pipeline) to export the data. diff --git a/pages/docs/data-pipelines/integrations/snowflake.md b/pages/docs/data-pipelines/integrations/schematized-snowflake-pipeline.md similarity index 99% rename from pages/docs/data-pipelines/integrations/snowflake.md rename to pages/docs/data-pipelines/integrations/schematized-snowflake-pipeline.md index 672213f863..c4aded4c16 100644 --- a/pages/docs/data-pipelines/integrations/snowflake.md +++ b/pages/docs/data-pipelines/integrations/schematized-snowflake-pipeline.md @@ -1,4 +1,4 @@ -# Snowflake +# Schematized Snowflake Pipeline This guide describes how Mixpanel data is exported into a [Snowflake](https://docs.snowflake.net/manuals/user-guide-getting-started.html) dataset. [Create a pipeline](https://developer.mixpanel.com/reference/create-warehouse-pipeline) to export your Mixpanel data into Snowflake. Once an export job is scheduled, Mixpanel exports data to Snowflake on a recurring basis. diff --git a/pages/docs/data-pipelines/schematized-export-pipeline.md b/pages/docs/data-pipelines/schematized-export-pipeline.md index 291ff11c36..a279224f44 100644 --- a/pages/docs/data-pipelines/schematized-export-pipeline.md +++ b/pages/docs/data-pipelines/schematized-export-pipeline.md @@ -45,7 +45,7 @@ Since user profiles are mutable, the data in the table is replaced every time an ## User Identity Resolution Exports from projects with [ID merge enabled](/docs/tracking-methods/id-management/identifying-users#how-do-i-switch-between-the-simplified-and-original-api) will need to use the identity mapping table to replicate the user counts seen in UI reporting. When ID merge is enabled, Mixpanel assigns multiple identifiers to an individual. Mixpanel resolves these into one identifier, and uses that for reporting unique user counts. Read more about how Mixpanel resolves IDs [here](/docs/tracking-methods/id-management/identifying-users#example-user-flows). -Pipelines export event data as they appear when Mixpanel ingests them. This means exported event data before sending alias event has the original user identifier, **not** the resolved identifier. Use the identity mappings table to accurately count unique users. This will allow you to recreate the identity cluster that Mixpanel creates. +Pipelines export event data as they appear when Mixpanel ingests them. This means exported event data will contain the distinct ID at the time it was exported, **not** the resolved identifier. Use the identity mappings table to accurately count unique users. This will allow you to recreate the identity cluster that Mixpanel creates. For this reason, it is highly recommended to enable [Data Sync](/data-pipelines/schematized-export-pipeline#data-sync). Mixpanel automatically exports the ID mapping table when you create a people export pipeline from a project with ID merge enabled. diff --git a/pages/docs/data-structure/concepts.md b/pages/docs/data-structure.md similarity index 94% rename from pages/docs/data-structure/concepts.md rename to pages/docs/data-structure.md index 7c5317075c..8e179300bf 100644 --- a/pages/docs/data-structure/concepts.md +++ b/pages/docs/data-structure.md @@ -1,6 +1,6 @@ -# Concepts +# Data Structure -## Overview +## Concepts Mixpanel data is stored and isolated within a [project](/docs/orgs-and-projects/managing-projects). At this time, you cannot query data across multiple projects. Mixpanel supports a few different categories of data that can be used for analysis: events, user profiles, group profiles, and lookup tables. In data warehouse parlance, events make up the fact table while user profiles, group profiles, and lookup tables are dimension tables. @@ -10,7 +10,7 @@ Mixpanel data is stored and isolated within a [project](/docs/orgs-and-projects/ |----------|-------------------| | **Events** | Events describe actions that take place within your product. An event contains properties that describe the action. Events can also be joined with user profiles, group profiles, and lookup tables to enrich the data.

[Learn more about event properties](/docs/data-structure/events-and-properties) | | **User Profiles** | A user profile is a key/value store that holds state about a user. User profiles are joined to events on `event.distinct_id = user_profile.distinct_id`.

[Learn more about profile properties](/docs/data-structure/events-and-properties) | -| **Group Profiles** | A group profile is a key/value store that holds state about member of your group. Group profiles are joined to Events on your chosen _group key_. For example, if you create a new group key for `company_id` your events will be joined on `event.company_id = group_profile.company_id`.

[Learn more about group analytics](/docs/data-structure/advanced/group-analytics) | +| **Group Profiles** | A group profile is a key/value store that holds state about member of your group. Group profiles are joined to Events on your chosen _group key_. For example, if you create a new group key for `company_id` your events will be joined on `event.company_id = group_profile.company_id`.

[Learn more about group analytics](/docs/data-structure/group-analytics) | | **Lookup Tables** | A lookup table is a key/value store that holds state about an entity. Lookup tables are joined to events (and other profiles) on your chosen join key. For example, if you create a lookup table for "Songs" and specify the join key as `song_id`, your events will be joined on `event.song_id = lookup_table.song_id`.

[Learn more about lookup tables](/docs/data-structure/lookup-tables) | ### Event Property vs User Profile Property @@ -89,7 +89,7 @@ All three are key/value stores that augment your event data with additional meta **[User profiles](/docs/data-structure/user-profiles)** are joined to events via `distinct_id` which is the default indexing for Events. -**[Group profiles](/docs/data-structure/advanced/group-analytics)** are joined to events via an event property you specify as a group key. Once you create a new group key, we will add an additional index for your events on that property. This allows you to do funnels or retention by that property instead of by `distinct_id`. +**[Group profiles](/docs/data-structure/group-analytics)** are joined to events via an event property you specify as a group key. Once you create a new group key, we will add an additional index for your events on that property. This allows you to do funnels or retention by that property instead of by `distinct_id`. **[Lookup tables](/docs/data-structure/lookup-tables)** are joined to events and user profiles using the join key that you specify. Unlike group profiles, your events are *not* indexed by the join key. You can use lookup table properties to do filtering, breakdowns, etc but you can't do things like funnels analysis using the join key for uniques. Note: Currently, group profile properties cannot be lookup table keys. diff --git a/pages/docs/data-structure/_meta.json b/pages/docs/data-structure/_meta.json index 0074fb8daa..1084db07c3 100644 --- a/pages/docs/data-structure/_meta.json +++ b/pages/docs/data-structure/_meta.json @@ -1,5 +1,4 @@ { - "concepts": "Concepts", "events-and-properties": "Events & Properties", "user-profiles": "User Profiles", "group-analytics": "Group Analytics", diff --git a/pages/docs/exporting-methods.md b/pages/docs/exporting-methods.md new file mode 100644 index 0000000000..acbea5b585 --- /dev/null +++ b/pages/docs/exporting-methods.md @@ -0,0 +1,59 @@ +# Exporting Methods + +## Overview +- Many ways to export data +- Quick and lightweight options via UI for fast analysis +- APIs for raw event/profile data and formatted data for larger exports +- Integrations to other destinations to do even more with your data +- If you need GDPR compliant export/deletion, see stuff on [End User Data Management](/docs/privacy/end-user-data-management). + +## Exporting Events +### Event Export via API +- use API for raw data export +- Link to dev doc +- Event data format +- Timezone callout + +### CSV Events Export +- can navigate to Events page to query specific events +- Modify table to control what properties are returned in the CSV +- Only what is visible in the UI is exported + +## Exporting Profiles +### User Profile Export via API + +- use Engage API for profile data export +- link to dev doc +- Profile data format +- able to control what properties to return +- able to export specific cohort using filter_by_cohort_id +- Profile always returned with canonical distinct_id + +#### Group Profile Export via API +- Can include data_group_id to export group profiles +- How to find data_group_id +- Where to include data_group_id in request + +### CSV Profile Export + +- Can navigate to Users page to query specific Users or Group Profiles +- Modify table column to control what properties are returned in the CSV +- Link to [exporting users to CSV](/docs/users/users-page#exporting-profiles-to-csv) + +## Exporting Reports +### Downloading Reports via the UI +You can download any reports as a CSV, PNG, or PDF by clicking the "..." button in the top right corner of the report UI, and then selecting "Export". Learn more about [the limits of UI exports here](/docs/reports#limits-and-ordering). + +### Exporting Reports via API +You may use our [Query API](https://developer.mixpanel.com/reference/query-api) to export the formatted results that you see in our web app. Learn more about the [Insights API](https://developer.mixpanel.com/reference/insights-query), [Funnels API](https://developer.mixpanel.com/reference/funnels-query), and [Retention API](https://developer.mixpanel.com/reference/retention-query). + + +## Export Integrations +- You can export to your data warehouse using Data Pipelines +- You can also export cohorts of users to various destinations using Cohort Sync integrations + + + + + + diff --git a/pages/docs/migration/overview.md b/pages/docs/migration.md similarity index 99% rename from pages/docs/migration/overview.md rename to pages/docs/migration.md index eca654f8fb..46268c9b25 100644 --- a/pages/docs/migration/overview.md +++ b/pages/docs/migration.md @@ -1,5 +1,6 @@ -# Overview +# Migration +## Overview If you’re reading this, congrats on considering making the switch from another analytics provider to Mixpanel 🎊  Our migration guides are intended to outline how a migration works, what to expect, and how to mitigate the risks and switching costs of a migration whilst accelerate time to value. ## What a migration will solve diff --git a/pages/docs/migration/_meta.json b/pages/docs/migration/_meta.json index e40ab3980d..7b48d4696f 100644 --- a/pages/docs/migration/_meta.json +++ b/pages/docs/migration/_meta.json @@ -1,5 +1,4 @@ { - "overview": "Overview", "adobe-analytics": "Adobe Analytics", "amplitude": "Amplitude", "google-analytics": "Google Analytics", diff --git a/pages/docs/orgs-and-projects/overview.md b/pages/docs/orgs-and-projects.md similarity index 100% rename from pages/docs/orgs-and-projects/overview.md rename to pages/docs/orgs-and-projects.md diff --git a/pages/docs/orgs-and-projects/_meta.json b/pages/docs/orgs-and-projects/_meta.json index 486a77c36c..b6feb81c47 100644 --- a/pages/docs/orgs-and-projects/_meta.json +++ b/pages/docs/orgs-and-projects/_meta.json @@ -1,5 +1,4 @@ { - "overview": "Overview", "organizations": "Organizations", "managing-projects": "Managing Projects", "roles-and-permissions": "Roles & Permissions" diff --git a/pages/docs/orgs-and-projects/roles-and-permissions.md b/pages/docs/orgs-and-projects/roles-and-permissions.md index 2622a84897..62f72b8567 100644 --- a/pages/docs/orgs-and-projects/roles-and-permissions.md +++ b/pages/docs/orgs-and-projects/roles-and-permissions.md @@ -93,13 +93,13 @@ Paid Organizations have four roles: Owner, Admin, Billing Admin and Member. Free | Modify 2FA and SSO | ✅ | ✅ | ❌ | ❌ | | Request Organization Deletion | ✅ | ❌ | ❌ | ❌ | -#### Owner +**Owner** >As a best practice, it is recommended to have at least 2 Organization Owners at all times, in case an owner loses access to their account or is no longer working with the company. Organization Owners have administrative permissions for the organization and all the projects in the organization. Multiple users can be Owners. However, each organization must have at least one Owner. -#### Admin +**Admin** Organization Admins have permissions to manage projects, members and roles in the organization. Organization Admins have the same permissions as Organization Owners **except** for the following: @@ -110,7 +110,7 @@ Organization Admins have permissions to manage projects, members and roles in th In addition, an Organization Admin would not be able to assign any user to anything higher than Admin (i.e. Organization Owner). -#### Billing Admin +**Billing Admin** Organization Billing Admins can only manage billing plans for your company. The Billing Admin does not have to belong to a team or project. A user can be a Billing Admin and also a member of a Project or a Team simultaneously. @@ -121,7 +121,7 @@ Billing admins can view organization settings solely to: - View Receipts - Submit a Downgrade Request -#### Member +**Member** Organization Members have no permissions to control or manage organization settings. In order for a user to have access to project(s) and/or team(s), they must first be added to the organization as a Member. @@ -176,23 +176,23 @@ The table below is an overview of the permissions per role for reports and other | Download CSV in Lexicon | ✅ | ✅ | ✅ | ✅ | | Upload a Lookup Table | ✅ | ✅ | ✅ | ✅ | -#### Owner +**Owner** When a user creates a project, they own and have complete control over it. They have all permissions at the project level and can provision project ownership to other project users. Organization Owners, by default, have administrative permissions to assume an owner role in a project. -#### Admin +**Admin** Project Admins have the same set of permissions as project owners. However, they cannot delete or reset the project or manage its security. In addition, a Project Admin would not be able to assign any user to anything higher than Admin (i.e. Project Owner). Organization Admins, by default, have administrative permissions to assume an admin role in a project. -#### Analyst +**Analyst** Project Analysts can create and save Mixpanel reports and Boards. They can also share their saved reports and Boards, along with reports and Boards in which they have editor permissions. They however do not have permissions to manage project user roles. -#### Consumer +**Consumer** Project Consumers can view and save their own reports and Boards. However, they cannot share their saved reports and Boards with other project users as these will be marked as private. diff --git a/pages/docs/privacy/overview.md b/pages/docs/privacy.md similarity index 99% rename from pages/docs/privacy/overview.md rename to pages/docs/privacy.md index 608b6be6d2..dd8c669812 100644 --- a/pages/docs/privacy/overview.md +++ b/pages/docs/privacy.md @@ -1,4 +1,6 @@ -# Overview +# Privacy + +## Overview Mixpanel believes in respecting and protecting people’s fundamental online privacy and data rights. This is why we've built Mixpanel's analysis tools in compliance with industry best practices and global data regulations like the GDPR and the CCPA. Visit our [Privacy Hub](https://mixpanel.com/legal/privacy-hub/) to see how we comply with various privacy guidelines. diff --git a/pages/docs/privacy/_meta.json b/pages/docs/privacy/_meta.json index 3f9e0db957..a3f4942330 100644 --- a/pages/docs/privacy/_meta.json +++ b/pages/docs/privacy/_meta.json @@ -1,5 +1,4 @@ { - "overview": "Overview", "protecting-user-data": "Protecting User Data", "legal-hub": { "title": "Legal Hub ↗", diff --git a/pages/docs/reports.mdx b/pages/docs/reports.mdx index 29c52ca5a5..9bed4bdc56 100644 --- a/pages/docs/reports.mdx +++ b/pages/docs/reports.mdx @@ -102,7 +102,7 @@ You can download reports in four formats: - PDF - Formatted API -To download Insights, Funnels, and Retention reports, click the "..." icon on the upper right corner of each report. Note the [limitations on downloads](/docs/reports#report-exports). +To download Insights, Funnels, and Retention reports, click the "..." icon on the upper right corner of each report and select "Export". Note the [limitations on downloads](/docs/reports#report-exports). ## Limits and Ordering diff --git a/pages/docs/tracking-methods/id-management/original-id-merge.md b/pages/docs/tracking-methods/id-management/original-id-merge.md index d8ce0d5c23..d473451910 100644 --- a/pages/docs/tracking-methods/id-management/original-id-merge.md +++ b/pages/docs/tracking-methods/id-management/original-id-merge.md @@ -1,6 +1,6 @@ # Original ID Merge -> Call out to check ID management version in settings and link to Simplified doc +> [Check your project's ID Merge version](/docs/tracking-methods/id-management#check-your-id-management-version) before proceeding. If your project is using Simplified ID Merge, refer to the documentation on [Simplified ID Merge here](/docs/tracking-methods/id-management/simplified-id-merge). ## Overview - System use 3 events to manipulate distinct_id diff --git a/pages/docs/tracking-methods/id-management/simplified-id-merge.md b/pages/docs/tracking-methods/id-management/simplified-id-merge.md index 883a013c1d..638eae144b 100644 --- a/pages/docs/tracking-methods/id-management/simplified-id-merge.md +++ b/pages/docs/tracking-methods/id-management/simplified-id-merge.md @@ -1,6 +1,7 @@ # Simplified ID Merge -> Call out to check ID management version in settings and link to Original doc +> > [Check your project's ID Merge version](/docs/tracking-methods/id-management#check-your-id-management-version) before proceeding. If your project is using Original ID Merge, refer to the documentation on [Simplified ID Merge here](/docs/tracking-methods/id-management/original-id-merge). + ## Overview - System use $device_id and $user_id to manipulate distinct_id From 6dead3e680fde2f103866fdda2385c86a90b5c36 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Mon, 1 Jul 2024 10:00:46 -0700 Subject: [PATCH 08/12] Myronkaifung content reorg misc (#1197) * Update and rename breakdowns-and-filters.md to funnels-breakdowns-and-filters.md * Update _meta.json * Rename funnels-conversion-criteria.md to funnels-conversion-criteria.mdx * Rename flows-conversion-criteria.md to flows-conversion-criteria.mdx --- ...ows-conversion-criteria.md => flows-conversion-criteria.mdx} | 0 pages/docs/reports/funnels/_meta.json | 2 +- ...akdowns-and-filters.md => funnels-breakdowns-and-filters.md} | 2 +- ...s-conversion-criteria.md => funnels-conversion-criteria.mdx} | 0 4 files changed, 2 insertions(+), 2 deletions(-) rename pages/docs/reports/flows/{flows-conversion-criteria.md => flows-conversion-criteria.mdx} (100%) rename pages/docs/reports/funnels/{breakdowns-and-filters.md => funnels-breakdowns-and-filters.md} (99%) rename pages/docs/reports/funnels/{funnels-conversion-criteria.md => funnels-conversion-criteria.mdx} (100%) diff --git a/pages/docs/reports/flows/flows-conversion-criteria.md b/pages/docs/reports/flows/flows-conversion-criteria.mdx similarity index 100% rename from pages/docs/reports/flows/flows-conversion-criteria.md rename to pages/docs/reports/flows/flows-conversion-criteria.mdx diff --git a/pages/docs/reports/funnels/_meta.json b/pages/docs/reports/funnels/_meta.json index 263adffc2f..bfcc1c5a84 100644 --- a/pages/docs/reports/funnels/_meta.json +++ b/pages/docs/reports/funnels/_meta.json @@ -2,6 +2,6 @@ "funnel-behavior": "Funnel Behavior", "measurements": "Measurements", "funnels-conversion-critera": "Funnels Conversion Criteria", - "breakdowns-and-filters": "Breakdowns and Filters", + "funnels-breakdowns-and-filters": "Funnels Breakdowns and Filters", "visualizations": "Visualizations" } diff --git a/pages/docs/reports/funnels/breakdowns-and-filters.md b/pages/docs/reports/funnels/funnels-breakdowns-and-filters.md similarity index 99% rename from pages/docs/reports/funnels/breakdowns-and-filters.md rename to pages/docs/reports/funnels/funnels-breakdowns-and-filters.md index fc241bb9c4..dfa70553d3 100644 --- a/pages/docs/reports/funnels/breakdowns-and-filters.md +++ b/pages/docs/reports/funnels/funnels-breakdowns-and-filters.md @@ -1,4 +1,4 @@ -# Breakdowns and Filters +# Funnels Breakdowns and Filters ## Overview Funnels measure sequences of events as a behavior, which adds complexity when filters and breakdowns are applied. This article will go over the Funnels property attribution mechanism, as well as the impact of filters and breakdowns on your funnel results. diff --git a/pages/docs/reports/funnels/funnels-conversion-criteria.md b/pages/docs/reports/funnels/funnels-conversion-criteria.mdx similarity index 100% rename from pages/docs/reports/funnels/funnels-conversion-criteria.md rename to pages/docs/reports/funnels/funnels-conversion-criteria.mdx From 3bcd330089b4871b2576a019d38e0d996200818f Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Mon, 1 Jul 2024 12:19:06 -0700 Subject: [PATCH 09/12] Myronkaifung content reorg misc (#1202) * Update and rename breakdowns-and-filters.md to funnels-breakdowns-and-filters.md * Update _meta.json * Rename funnels-conversion-criteria.md to funnels-conversion-criteria.mdx * Rename flows-conversion-criteria.md to flows-conversion-criteria.mdx * Update _meta.json * Update _meta.json --- pages/docs/reports/flows/_meta.json | 2 +- pages/docs/reports/funnels/_meta.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/docs/reports/flows/_meta.json b/pages/docs/reports/flows/_meta.json index d4518b4e28..62109904a4 100644 --- a/pages/docs/reports/flows/_meta.json +++ b/pages/docs/reports/flows/_meta.json @@ -1,6 +1,6 @@ { "anchor-events": "Anchor Events", "visualizations": "Visualizations", - "flows-conversion-crietria": "Flows Conversion Criteria", + "flows-conversion-criteria": "Flows Conversion Criteria", "flows-breakdown": "Flows Breakdown" } diff --git a/pages/docs/reports/funnels/_meta.json b/pages/docs/reports/funnels/_meta.json index bfcc1c5a84..04faec3206 100644 --- a/pages/docs/reports/funnels/_meta.json +++ b/pages/docs/reports/funnels/_meta.json @@ -1,7 +1,7 @@ { "funnel-behavior": "Funnel Behavior", "measurements": "Measurements", - "funnels-conversion-critera": "Funnels Conversion Criteria", + "funnels-conversion-criteria": "Funnels Conversion Criteria", "funnels-breakdowns-and-filters": "Funnels Breakdowns and Filters", "visualizations": "Visualizations" } From 9965fc138152c0ef883b5236375f081ad8997ae7 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Wed, 3 Jul 2024 19:00:59 -0700 Subject: [PATCH 10/12] Myronkaifung content reorg darkmode (#1206) * Update overrides.scss * Update theme.config.tsx * Update theme.config.tsx * Update theme.config.tsx * Update overrides.scss * Update overrides.scss * Update what-is-mixpanel.mdx * Update what-to-track.mdx * Update install-mixpanel.mdx * Update identify-users.mdx * Update identify-users.mdx * Update what-is-mixpanel.mdx * Update what-is-mixpanel.mdx * Update what-is-mixpanel.mdx * Update theme.config.tsx * Update overrides.scss * Update theme.config.tsx * Update overrides.scss * Update FeedbackCollector.module.scss * Update overrides.scss * Update overrides.scss * Update overrides.scss * Update theme.config.tsx * Update identify-users.mdx * Update track-events.mdx * Update theme.config.tsx * Update track-events.mdx --- .../FeedbackCollector.module.scss | 63 +- pages/docs/quickstart/identify-users.mdx | 366 ++--- pages/docs/quickstart/install-mixpanel.mdx | 181 ++- pages/docs/quickstart/track-events.mdx | 7 +- pages/docs/what-is-mixpanel.mdx | 92 +- pages/docs/what-to-track.mdx | 84 +- pages/overrides.scss | 1262 +++++++++++++---- theme.config.tsx | 44 +- 8 files changed, 1486 insertions(+), 613 deletions(-) diff --git a/components/FeedbackCollector/FeedbackCollector.module.scss b/components/FeedbackCollector/FeedbackCollector.module.scss index 25adfaf875..c118bea0bc 100644 --- a/components/FeedbackCollector/FeedbackCollector.module.scss +++ b/components/FeedbackCollector/FeedbackCollector.module.scss @@ -2,59 +2,60 @@ @use "sass:color"; .root { - border-top-width: 1px; - padding-top: 28px; + border-top-width: 1px; + padding-top: 28px; } .title { - font-weight: 500; - font-size: 16px; + font-weight: 500; + font-size: 16px; } .feedback { - margin-bottom: 36px; - margin-top: 36px; + margin-bottom: 36px; + margin-top: 36px; } .buttonContainer { - display: inline-flex; - flex-wrap: wrap; + display: inline-flex; + flex-wrap: wrap; } .button { - background-color: colors.$base80; - border-radius: 16px; - box-shadow: 0 6px 12px color.adjust(colors.$black, $alpha: -0.95); - display: flex; - font-weight: 500; - margin-right: 16px; - margin-top: 16px; - padding: 16px 24px; + // background-color: colors.$base80; + border-radius: 16px; + box-shadow: 0 6px 12px color.adjust(colors.$black, $alpha: -0.95); + display: flex; + font-weight: 500; + margin-right: 16px; + margin-top: 16px; + padding: 16px 24px; + transition: 0.5s; + + &:hover { + background-color: colors.$purple20; + color: colors.$purple100; + box-shadow: 0 6px 12px color.adjust(colors.$purple140, $alpha: -0.95); transition: 0.5s; - &:hover { - background-color: colors.$purple20; - box-shadow: 0 6px 12px color.adjust(colors.$purple140, $alpha: -0.95); - transition: 0.5s; - - .thumbsDown, .thumbsUp { - color: colors.$purple200; - transition: 0.5s; - } - + .thumbsDown, + .thumbsUp { + color: colors.$purple140; + transition: 0.5s; } + } } .thumbsUp { - color: green; + color: green; } .thumbsDown { - color: colors.$lava140; + color: colors.$lava140; } .inlineIcon { - display: inline-block; - margin-left: 8px; - width: 22px; + display: inline-block; + margin-left: 8px; + width: 22px; } diff --git a/pages/docs/quickstart/identify-users.mdx b/pages/docs/quickstart/identify-users.mdx index 9fcb2c443b..5b655d1e9c 100644 --- a/pages/docs/quickstart/identify-users.mdx +++ b/pages/docs/quickstart/identify-users.mdx @@ -1,211 +1,256 @@ -# Identify Users +# Track Events -import { Tab, Tabs } from 'nextra-theme-docs' +import { Tab, Tabs } from "nextra-theme-docs"; -import ExtendedButton from '/components/ExtendedButton/ExtendedButton' -import ExtendedTabs from '/components/ExtendedTabs/ExtendedTabs'; +import ExtendedButton from "/components/ExtendedButton/ExtendedButton"; +import ExtendedTabs from "/components/ExtendedTabs/ExtendedTabs"; -import { dataItems } from '/utils/constants'; +import { dataItems } from "/utils/constants"; ## Overview -This step introduces the `identify` method, which allows you to assign an ID to your users. +This step introduces the `track` method, which allows you to see how your users are using your product. -It also introduces the `people.set` method, which allows you to define the attributes of each user. +Use the track method to track events on behalf of your users. Add this code snippet to basic events like "Sign Up" and any additional events that may track the core features of your product. ## Code -Replace `USER_ID` with a unique identifier, preferably the user ID from your database. - -Including the user's email is also suggested, along with any additional **User Properties** such as name, avatar, created date, etc. +Replace `Sign Up` with a unique identifier for the event. Passing additional information is possible using the properties object. ```js Javascript -mixpanel.identify('USER_ID') - -mixpanel.people.set({ '$name': 'Jane Doe', - '$email': 'jane.doe@example.com', - 'plan' : 'Premium' - // Add anything else about the user here - }); +mixpanel.track('Sign Up', { + 'Signup Type': 'Referral' +}) ``` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events). + +**More resources:** +_ Video: [Debug Common Issues When Installing Mixpanel on Web](https://www.loom.com/embed/fbba03274dc441b49b578e8a734b1d99). +_ Docs: [Read the Full Javascript SDK Docs](/docs/tracking-methods/sdks/javascript/) \* Github: [Browse the Open Source SDKs](https://github.com/mixpanel) + -```python -mp.people_set('USER_ID', {'$name' : 'Jane Doe', - '$email' : 'jane.doe@example.com', - 'plan' : 'Premium' - # Add anything else about the user here +```python Python +# Note: you must supply the USER_ID +mp.track('USER_ID', 'Sign Up', { + 'Signup Type': 'Referral' }) ``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events). + +**More resources:** +_ Docs: [Read the Python SDK Doc](/docs/tracking-methods/sdks/python/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) -```javascript -mixpanel.people.set('USER_ID', { - $name: 'Jane Doe', - $email: 'jane.doe@example.com', - plan: 'premium' - // Add anything else about the user here +```js Node.js +// Note: you must supply the USER_ID +mixpanel.track("Sign Up", { + distinct_id: "USER_ID", + "Signup Type": "Referral", }); ``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events). + +**More resources:** +_ Docs: [Read the Node.js SDK Doc](/docs/tracking-methods/sdks/nodejs/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) + -```go -exampleUser := mp.NewPeopleProperties("USER_ID", map[string]any{ - "$name": "Jane Doe", - "$email": "jane.doe@example.com", - "plan": "Premium" - // Add anything else about the user here +```go Go +exampleEvent = mp.NewEvent("Sign Up", "USER_ID", map[string]any{ + "Signup Type": "Referral", }) -err := mp.PeopleSet(ctx, []*mixpanel.PeopleProperties{ - exampleUser, - }, +err := mp.Track(ctx, +[]\*mp.PeopleProperties{ +exampleUser, +}, ) -``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. +```` +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events). + +**More resources:** + * Docs: [Read the Go SDK Doc](/docs/tracking-methods/sdks/go/) + * Github: [Browse the Open Source SDKs](https://github.com/mixpanel) -```ruby -mp.people.set('USER_ID', { - '$name' => 'Jane Doe', - '$email' => 'jane.doe@example.com', - 'plan' => 'Premium' - # Add anything else about the user here -}); -``` +```ruby Ruby +# Note: you must supply the USER_ID +mp.track('USER_ID', 'Sign Up', { + 'Signup Type' => 'Referral' +}) +```` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events). + +**More resources:** +_ Docs: [Read the Ruby SDK Doc](/docs/tracking-methods/sdks/ruby/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. -```java +```java Java +import com.mixpanel.mixpanelapi.ClientDelivery; + +// You can send properties along with events JSONObject props = new JSONObject(); -props.put("$name", "Jane Doe"); -props.put("$email", "jane.doe@example.com"); -props.put("plan", "Premium"); -JSONObject update = messageBuilder.set("USER_ID", props); +props.put("Signup Type", "Referral"); + +// Create an event +JSONObject sentEvent = messageBuilder.event(userId, "Sign Up", props); + +ClientDelivery delivery = new ClientDelivery(); +delivery.addMessage(sentEvent); // Send the update to mixpanel -mixpanel.sendMessage(update); -``` -Server-side SDKs do not have an `identify` function as the ID management is handled by your server. Read our full guide on [Server Side ID Management]. -You may want to disable ip geolocation when using a server-side SDK. You can learn more about [geolocation in server-side implementations]. +MixpanelAPI mixpanel = new MixpanelAPI(); +mixpanel.deliver(delivery); + +```` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events page](https://mixpanel.com/report/events). + +**More resources:** + * Docs: [Read the Java SDK Doc](/docs/tracking-methods/sdks/java/) + * Github: [Browse the Open Source SDKs](https://github.com/mixpanel) -```javascript Javascript -mixpanel.identify("USER_ID"); +```javascript +mixpanel.track("Sign Up", { + "Signup Type": "Referral" +}) +```` -// Identify must be called before properties are set -mixpanel.getPeople().set("$name", "Jane Doe"); -mixpanel.getPeople().set("$email", "jane.doe@example.com"); -mixpanel.getPeople().set("plan", "Premium"); -``` +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page. + +**More resources:** +_ Docs: [Read the React Native SDK Doc](/docs/tracking-methods/sdks/react-native/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) -You may want to disable ip geolocation when using a server-side SDK. You can learn more in [Server-Side Best Practices](/docs/tracking-best-practices/server-side-best-practices) ```java -mixpanel.identify("USER_ID"); - -// Identify must be called before properties are set -mixpanel.getPeople().set("$name", "Jane Doe"); -mixpanel.getPeople().set("$email", "jane.doe@example.com"); -mixpanel.getPeople().set("plan", "Premium"); +mixpanel.track('Sign Up', { + 'Signup Type': 'Referral' +}); ``` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page. + +**More resources:** +_ Docs: [Read the Flutter SDK Docs](/docs/tracking-methods/sdks/flutter/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) + -```objc Objective-C -[mixpanel identify:@"USER_ID"]; - -[mixpanel.people set:@{@"$name": @"Jane Doe"}]; -[mixpanel.people set:@{@"$email": @"jane.deo@example.com"}]; -[mixpanel.people set:@{@"plan": @"Premium"}]; +```objc +[mixpanel track:@"Signed Up" properties: + @{ @"Signup Type": @"Referral" } +]; ``` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page. + +**More resources:** +_ Docs: [Read the iOS (Objective-C) SDK Doc](/docs/tracking-methods/sdks/ios/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) + -```swift Swift -Mixpanel.mainInstance().identify(distinctId: "USER_ID") - -Mixpanel.mainInstance().people.set(properties: [ "$name":"Jane Doe", - "$email":"jane.doe@example.com", - "$plan":"Premium"]) +```swift +Mixpanel.mainInstance().track(event:"Sign Up", properties: [ + "Signup Type": "Referral", +]) ``` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page. + +**More resources:** +_ Docs: [Read the iOS (Swift) SDK Doc](/docs/tracking-methods/sdks/swift/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) + -```java Java -// The second param is a flag for allowing profile updates -mp.identify("USER_ID", true); - -// Identify must be called before properties are set -mp.getPeople().set("$name", "Jane Doe"); -mp.getPeople().set("$email", "jane.doe@example.com"); -mp.getPeople().set("plan", "Premium"); +```java +JSONObject props = new JSONObject(); +props.put("Signup Type", "Referral"); +mp.track("Signed Up", props); ``` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page. + +**More resources:** +_ Docs: [Read the Android SDK Doc](/docs/tracking-methods/sdks/android/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) + ```csharp -Mixpanel.Identify("USER_ID"); - -// Identify must be called before properties are set -Mixpanel.People.Set("$name", "Jane Doe"); -Mixpanel.People.Set("$email", "jane.doe@example.com"); -Mixpanel.People.Set("plan", "Premium"); +var props = new Value(); +props["Signup Type"] = "Referral"; +Mixpanel.Track('Sign up', props); ``` + +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page. + +**More resources:** +_ Docs: [Read the Unity SDK Doc](/docs/tracking-methods/sdks/unity/) +_ Github: [Browse the Open Source SDKs](https://github.com/mixpanel) + -If you don't see an SDK or an integration in your language, you can send events to our API directly. +If you don't see an SDK or an integration in your language, you can send events to our API directly. Here's a sample script. Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). ```python test.py +# Fill this out +import json +import time import requests -url = "https://api.mixpanel.com/engage#profile-set" - -payload = [ - { - "$token": "YOUR_TOKEN", - "$distinct_id": "USER_ID", - "$set": { - "$name": "Jane Doe", - "$email": "jane.doe@example.com", - "plan": "Premium" - } - } +events = [ + {"event": "my_test_event", "properties": {"time": int(time.time()), "distinct_id": "test_user_1", "$insert_id": "04ce0cf4-a633-4371-b665-9b45317b4976", "city": "San Francisco"}}, + {"event": "another_event", "properties": {"time": int(time.time()), "distinct_id": "test_user_2", "$insert_id": "3b033b9a-6bc9-4b70-90c3-a53e11f6896e", "city": "Seattle"}} ] -headers = { - "accept": "text/plain", - "content-type": "application/json" -} - -response = requests.post(url, json=payload, headers=headers) +resp = requests.post( + "https://api.mixpanel.com/import", + params={"strict": "1"}, + auth=("YOUR_TOKEN", ""), + headers={"Content-Type": "application/json"}, + data=json.dumps(events) +) -print(response.text) +print(resp.json()) ``` +🎉 Congratulations, you've tracked your first event! You can see it in Mixpanel via the [Events](https://mixpanel.com/report/events) page. + +See our [API reference](https://developer.mixpanel.com/reference/events) for more details. + **Best Practices for Scale** You can use this API at scale, for example to backfill historical data into Mixpanel or as part of a high-throughput streaming pipeline. We provide walkthroughs for [Amazon S3](/docs/data-pipelines/integrations/amazon-s3) and [Google Cloud Storage](/docs/data-pipelines/integrations/google-cloud-storage) to provide a more production-grade example of how to use this API at scale. @@ -223,67 +268,72 @@ Here are some other best practices: Our Import API is built to ingest billions of events per day across our customers. That said, we do rate limit at very high scale to ensure quality of service and real-time ingestion. Please refer to our [Import API docs](https://developer.mixpanel.com/reference/import-events) for details. All of our sample code transparently retries and backoff from rate limit exceptions. If you require a higher-limit for a 1-time backfill, please reach out to us at apis@mixpanel.com. + -🎉 Congratulations, you've tracked your first user! You can see them in Mixpanel via the [Users page](https://mixpanel.com/report/users). - -







+

+

+

+

{/* Next Section */}


+
+{/*
*/} +
-

Next: Track Events

-

Once you've implemented `identify`, it's time to track what your users are doing in your product.

-

- +

+ You're Ready to Start Using Mixpanel +

+

+ It's time to create your first [report](/docs/reports/overview) or use one + of our [many templates](/docs/boards/templates). +

+

+
- -



+

+

## FAQ export function FAQBox({ title, children }) { return ( -
+
- {title} + {title}
{children}
- ) + ); } - -If tracking client-side, just call `.identify()` when a user logs in and `.reset()` - when they log out. Mixpanel will automatically stitch the user journey across - logged out and logged in. - - If tracking server-side, check out our [server-side best practices guide](/docs/best-practices/server-side-best-practices). - For more information, read our comprehensive guide on [Identifying Users](/docs/tracking-methods/id-management/identifying-users). + + Yes, if you pass `track_pageview: true` in the `mixpanel.init()` call, + Mixpanel will automatically track a "Page View" event every time a new page is + loaded. Learn more + [here](/docs/tracking-methods/sdks/javascript#tracking-page-views). - -Mixpanel's Data Ingestion APIs and Client-Side SDKs automatically collect certain properties on every event -or user profile update. Examples include: location, operating system, device, etc. Mixpanel calls this auto-generated data "Default Properties". - -[Learn More About Default Properties](/docs/data-structure/property-reference#default-properties) - + + If tracking from the web, make sure you've disabled ad blockers and your Do Not Track (DNT) + browser settings are set to false when testing your JavaScript implementation. If + the DNT setting is set to true, then Mixpanel won't collect information from that Mixpanel + instance. We also recommend [setting up a proxy server](/docs/tracking-methods/sdks/javascript#tracking-via-proxy) + so that you don't lose events due to ad-blockers. - - If a user opts out of tracking, you can call the `.optOutTracking()` method on any of our - client-side SDKs; this prevents any subsequent data being tracked from that user's device. - Learn more [here](/docs/privacy/protecting-user-data). +If tracking from a mobile device, events may take 1-2 minutes to appear because Mixpanel's +mobile SDKs buffer events for 1 minute, or when the app transitions to the background, to +conserve battery life and bandwidth. You can call `.flush()` in the mobile SDKs to manually flush events to Mixpanel. - For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission - through the AppTrackingTransparency(ATT) framework. For more details, refer to our - [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details). +
diff --git a/pages/docs/quickstart/install-mixpanel.mdx b/pages/docs/quickstart/install-mixpanel.mdx index b45ec9f0bc..ec44a4b73e 100644 --- a/pages/docs/quickstart/install-mixpanel.mdx +++ b/pages/docs/quickstart/install-mixpanel.mdx @@ -1,24 +1,21 @@ # Install Mixpanel -import { Tab, Tabs } from 'nextra-theme-docs' -import { Card, Cards } from 'nextra-theme-docs' -import { Callout } from 'nextra-theme-docs' +import { Tab, Tabs } from "nextra-theme-docs"; +import { Card, Cards } from "nextra-theme-docs"; +import { Callout } from "nextra-theme-docs"; -import ExtendedButton from '/components/ExtendedButton/ExtendedButton' -import ExtendedTabs from '/components/ExtendedTabs/ExtendedTabs' +import ExtendedButton from "/components/ExtendedButton/ExtendedButton"; +import ExtendedTabs from "/components/ExtendedTabs/ExtendedTabs"; -import { dataItems } from '/utils/constants'; +import { dataItems } from "/utils/constants"; ## Overview Installing Mixpanel is easy. This guide will show you how to do it with our SDKs. - - -Already collect product data? Connect your - **[Data Warehouse](/docs/tracking-methods/data-warehouse)** or via - **[3rd Party Integrations](/docs/tracking-methods/integrations/)**. - +Already collect product data? Connect your +**[Data Warehouse](/docs/tracking-methods/data-warehouse)** or via +**[3rd Party Integrations](/docs/tracking-methods/integrations/)**. ## Code @@ -56,10 +53,14 @@ Replace `YOUR_TOKEN` with your project token. You can find your token [here](htt ```js Javascript //Import Mixpanel SDK -import mixpanel from 'mixpanel-browser'; +import mixpanel from "mixpanel-browser"; // Near entry of your product, init Mixpanel -mixpanel.init('YOUR_TOKEN', {debug: true, track_pageview: true, persistence: 'localStorage'}); +mixpanel.init("YOUR_TOKEN", { + debug: true, + track_pageview: true, + persistence: "localStorage", +}); ``` @@ -75,23 +76,28 @@ Replace `YOUR_TOKEN` with your project token. You can find your token [here](htt from mixpanel import Mixpanel mp = Mixpanel("YOUR_TOKEN") -``` + +```` ##### Install the SDK ```shell Node.js npm install mixpanel -``` +```` + ##### Configure the SDK + Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + ```js Node.js // Grab the Mixpanel factory -var Mixpanel = require('mixpanel'); +var Mixpanel = require("mixpanel"); // Create an instance of the mixpanel client -var mixpanel = Mixpanel.init('YOUR_TOKEN'); +var mixpanel = Mixpanel.init("YOUR_TOKEN"); ``` + @@ -110,24 +116,29 @@ import ( ) func main() { - ctx := context.Background() - mp := mixpanel.NewApiClient("YOUR_TOKEN") +ctx := context.Background() +mp := mixpanel.NewApiClient("YOUR_TOKEN") } -``` + +```` ##### Install the SDK ```shell Ruby gem install mixpanel-ruby -``` +```` + ##### Configure the SDK + Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + ```ruby Ruby require 'mixpanel-ruby' mp = Mixpanel::Tracker.new(YOUR_TOKEN) ``` + @@ -147,10 +158,11 @@ Replace `YOUR_TOKEN` with your project token. You can find your token [here](htt import com.mixpanel.mixpanelapi.MessageBuilder; import com.mixpanel.mixpanelapi.MixpanelAPI; -// Set up an instance of MixpanelAPI +// Set up an instance of MixpanelAPI MixpanelAPI mixpanel = new MixpanelAPI(); MessageBuilder messageBuilder = new MessageBuilder('YOUR_TOKEN'); + ``` @@ -159,14 +171,18 @@ MessageBuilder messageBuilder = new MessageBuilder('YOUR_TOKEN'); Under your app's root directory, run: ``` + npm install mixpanel-react-native + ``` Under your application's iOS folder, run: ``` + pod install -``` + +```` Note: For XCode 12.5+, there is a known compile issue, please refer to this [workaround](https://github.com/mixpanel/mixpanel-react-native/issues/43#issuecomment-829599732). ##### Configure the SDK @@ -179,7 +195,8 @@ import { Mixpanel } from "mixpanel-react-native"; const trackAutomaticEvents = false; const mixpanel = new Mixpanel("YOUR_TOKEN", trackAutomaticEvents); mixpanel.init(); -``` +```` + @@ -189,8 +206,11 @@ Add `mixpanel_flutter: ^2.0.0` to your package's pubspec.yaml file and run: ``` flutter pub get ``` + ##### Configure the SDK + Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + ```dart import 'package:mixpanel_flutter/mixpanel_flutter.dart'; class _YourClassState extends State { @@ -208,6 +228,7 @@ class _YourClassState extends State { } } ``` + @@ -215,19 +236,21 @@ class _YourClassState extends State { -Note: Swift Package Manager requires Xcode 12+ -1. In Xcode, select File > Swift Packages > Add Package Dependency. -2. Follow the prompts using the URL for this repository and must select a version greater than or equal to v4.0.0 + Note: Swift Package Manager requires Xcode 12+ 1. In Xcode, select File > + Swift Packages > Add Package Dependency. 2. Follow the prompts using the URL + for this repository and must select a version greater than or equal to v4.0.0 -1. Create a Podfile in your Xcode project directory by running `pod init` in your terminal, edit the Podfile generated, and add the following line: `pod 'Mixpanel'`. -2. Run `pod install` in your Xcode project directory. CocoaPods should download and install the Mixpanel library, and create a new Xcode workspace. Open up this workspace in Xcode or typing `open *.xcworkspace` in your terminal. + 1. Create a Podfile in your Xcode project directory by running `pod init` in + your terminal, edit the Podfile generated, and add the following line: `pod + 'Mixpanel'`. 2. Run `pod install` in your Xcode project directory. CocoaPods + should download and install the Mixpanel library, and create a new Xcode + workspace. Open up this workspace in Xcode or typing `open *.xcworkspace` in + your terminal. - -Add `github "mixpanel/mixpanel-iphone"` to your Cartfile. - +Add `github "mixpanel/mixpanel-iphone"` to your Cartfile. ##### Configure the SDK @@ -235,14 +258,15 @@ Replace `YOUR_TOKEN` with your project token. You can find your token [here](htt ```objc #import "Mixpanel/Mixpanel.h" -- (BOOL)application:(UIApplication _)application +- (BOOL)application:(UIApplication _)application didFinishLaunchingWithOptions:(NSDictionary _)launchOptions { ... - Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR_TOKEN" - trackAutomaticEvents: NO]; + Mixpanel \*mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR_TOKEN" + trackAutomaticEvents: NO]; ... -} -``` + } + +```` @@ -281,7 +305,8 @@ func application(_ application: UIApplication, Mixpanel.initialize(token: "YOUR_TOKEN", trackAutomaticEvents: false) ... } -``` +```` + @@ -305,8 +330,11 @@ Next, add the following permissions in your AndroidManifest.xml: ``` + ##### Configure the SDK + Replace `YOUR_TOKEN` with your project token. You can find your token [here](https://mixpanel.com/settings/project). + ```java import com.mixpanel.android.mpmetrics.MixpanelAPI; @@ -324,6 +352,7 @@ public class MainActivity extends ActionBarActivity { } } ``` + @@ -331,15 +360,16 @@ public class MainActivity extends ActionBarActivity { Add `https://github.com/mixpanel/mixpanel-unity.git#master` to the dependencies section of `com.mixpanel.unity`. Alternatively, you can download and install the .unitypackage file from our [releases page](https://github.com/mixpanel/mixpanel-unity/releases). + ##### Configure the SDK -To initialize the library, first open the unity project settings menu for Mixpanel. (Edit -> Project Settings -> Mixpanel) -Then, enter your project token into the Token and Debug Token input fields within the inspector. -You can find your token [here](https://mixpanel.com/settings/project). +To initialize the library, first open the unity project settings menu for Mixpanel. (Edit -> Project Settings -> Mixpanel) +Then, enter your project token into the Token and Debug Token input fields within the inspector. +You can find your token [here](https://mixpanel.com/settings/project). ![unity_screenshots](https://user-images.githubusercontent.com/36679208/152408022-62440f50-04c7-4ff3-b331-02d3d3122c9e.jpg) -Note: If you prefer to initialize Mixpanel manually, you can select the `Manual Initialization` in the settings and +Note: If you prefer to initialize Mixpanel manually, you can select the `Manual Initialization` in the settings and call `Mixpanel.Init()` to initialize. To use mixpanel, add the following sample code to a part of your application: @@ -347,7 +377,9 @@ To use mixpanel, add the following sample code to a part of your application: ```csharp using mixpanel; ``` + You're + ##### Install the SDK @@ -355,13 +387,16 @@ You're No install required -Using the HTTP API does not require an installation. **You're ready to move to the next step.** +Using the HTTP API does not require an installation. **You're ready to move to the +next step.** +

+

+

- -





+
{/* Next Section */} @@ -369,42 +404,48 @@ Using the HTTP API does not require an installation. **You're ready to move to t

-

Next: Identify Your Users

-

With Mixpanel installed, you’re now ready to identify the users who use your product.

-

- +

+ Next: Identify Your Users +

+

+ With Mixpanel installed, you’re now ready to identify the users who use your + product. +

+

+
-



+

+

## FAQ export function FAQBox({ title, children }) { return ( -
+
- {title} + {title}
{children}
- ) + ); } Yes, if you pass `track_pageview: true` in the `mixpanel.init()` call, - Mixpanel will automatically track a "Page View" event every time a new - page is loaded. - Learn more [here](/docs/tracking-methods/sdks/javascript#tracking-page-views). + Mixpanel will automatically track a "Page View" event every time a new page is + loaded. Learn more + [here](/docs/tracking-methods/sdks/javascript#tracking-page-views). When tracking on web, we recommend using localStorage, as this is more reliable: ```javascript -mixpanel.set_config({ persistence: "localStorage" }); +mixpanel.set_config({ persistence: "localStorage" }); ``` Please note that cross-subdomain tracking is not possible when using local storage. If your implementation requires cross-subdomain tracking, remove the persistence flag and use the default "cookie" persistence option. @@ -412,10 +453,11 @@ Please note that cross-subdomain tracking is not possible when using local stora - No, our Mixpanel JavaScript SDK does not set or use any third-party cookies. If you wish - to disable cookies entirely, you can set the disable_persistence option to true when initializing - your Mixpanel JS instance. Note that disabling persistence will disable the use of super properties - and anonymous -> identified user tracking. + No, our Mixpanel JavaScript SDK does not set or use any third-party cookies. + If you wish to disable cookies entirely, you can set the disable_persistence + option to true when initializing your Mixpanel JS instance. Note that + disabling persistence will disable the use of super properties and anonymous + -> identified user tracking. @@ -423,9 +465,10 @@ Please note that cross-subdomain tracking is not possible when using local stora client-side SDKs; this prevents any subsequent data being tracked from that user's device. Learn more [here](/docs/privacy/protecting-user-data). - For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission - through the AppTrackingTransparency(ATT) framework. For more details, refer to our - [Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details). - +For iOS specifically: Mixpanel does not use IDFA, so it does not require user permission +through the AppTrackingTransparency(ATT) framework. For more details, refer to our +[Apple App Developer Privacy Guidance](https://mixpanel.com/legal/app-store-privacy-details). + +
diff --git a/pages/docs/quickstart/track-events.mdx b/pages/docs/quickstart/track-events.mdx index 9d10e35917..fd38bc8f98 100644 --- a/pages/docs/quickstart/track-events.mdx +++ b/pages/docs/quickstart/track-events.mdx @@ -264,6 +264,8 @@ All of our sample code transparently retries and backoff from rate limit excepti







+
+ {/* Next Section */}
@@ -297,7 +299,7 @@ export function FAQBox({ title, children }) { className="last-of-type:mb-0 rounded-xl bg-[#f5f2f2] p-0 mt-6" > - {title} + {title}
{children}
@@ -321,4 +323,5 @@ export function FAQBox({ title, children }) { If tracking from a mobile device, events may take 1-2 minutes to appear because Mixpanel's mobile SDKs buffer events for 1 minute, or when the app transitions to the background, to conserve battery life and bandwidth. You can call `.flush()` in the mobile SDKs to manually flush events to Mixpanel. - \ No newline at end of file + +
diff --git a/pages/docs/what-is-mixpanel.mdx b/pages/docs/what-is-mixpanel.mdx index e05108a56f..de859d562d 100644 --- a/pages/docs/what-is-mixpanel.mdx +++ b/pages/docs/what-is-mixpanel.mdx @@ -1,20 +1,38 @@ -# What is Mixpanel? +import ExtendedButton from "/components/ExtendedButton/ExtendedButton"; -import ExtendedButton from '/components/ExtendedButton/ExtendedButton' +# What is Mixpanel? -Mixpanel will help you better understand your customers and answer questions about your product. -It enables you to track how users engage with your product and analyze this data with interactive reports +Mixpanel will help you better understand your customers and answer questions about your product. +It enables you to track how users engage with your product and analyze this data with interactive reports that let you query and visualize the results with just a few clicks. Mixpanel is built on three key concepts: [**Events**](#events), [**Users**](#users), and [**Properties**](#properties).

-
-

+
+

+ +

## Concepts @@ -26,21 +44,26 @@ Before you get started, you should know three Mixpanel concepts: - **Properties** are the attributes of your users and events ### Events -An event is a data point that represents an interaction between a user and your product. Events can be a wide range of interactions. + +An event is a data point that represents an interaction between a user and your product. Events can be a wide range of interactions. Imagine you run a cafe where customers can purchase a coffee via an app. Each purchase is an event that can be tracked in Mixpanel. ![image](/event-1.svg) + ### Users + On the other side of an event is a user — the specific individual who completed an interaction with your product. Each user has a unique identifier that you can use to track their activity. This identifier can be an email address, a username, or a unique ID. Mixpanel uses a unique ID to identify users. ![image](/events-and-users.svg) + ### Properties + You can track additional information about **users** and **events**. These details are called **properties**. -An **Event Property** describes an event. For a coffee purchase, the event would be *Purchased Item* and the event properties could be *type* (in this case a Coffee) and *price* (in this case $2.50). +An **Event Property** describes an event. For a coffee purchase, the event would be _Purchased Item_ and the event properties could be _type_ (in this case a Coffee) and _price_ (in this case $2.50). ![image](/event.svg) @@ -51,25 +74,40 @@ A **User Property** describes a User. This could be their name, email, age, etc. Properties allow you to create groups of users (aka [cohorts](/docs/users/cohorts)) and also enable you to filter for certain events or users. These powerful features make it easy to identify trends and new customer insights. -





+

+

+

+
+ ## Next Steps Now that you understand the basics, **we recommend planning the first events you would like to track**. This will help you understand what you need to get started. Choosing these events should take no more than 5 minutes.

- +





-

Already Know What You Want to Track?

-

If you already know the events you want to track, you can skip planning and start by installing Mixpanel.

-

- +

+ Already Know What You Want to Track? +

+

+ If you already know the events you want to track, you can skip planning and + start by installing Mixpanel. +

+

+


@@ -77,10 +115,19 @@ Now that you understand the basics, **we recommend planning the first events you

-

Explore a demo dataset

-

Register for a free account to explore a full demo of Mixpanel. If you make a Board and like it, you can move it into your own project and add your own data.

-

- +

+ Explore a demo dataset +

+

+ Register for a free account to explore a full demo of Mixpanel. If you make + a Board and like it, you can move it into your own project and add your own + data. +

+

+


@@ -93,3 +140,4 @@ Now that you understand the basics, **we recommend planning the first events you

+
diff --git a/pages/docs/what-to-track.mdx b/pages/docs/what-to-track.mdx index 5081f9f512..7042846fe6 100644 --- a/pages/docs/what-to-track.mdx +++ b/pages/docs/what-to-track.mdx @@ -1,76 +1,96 @@ -import ExtendedButton from '/components/ExtendedButton/ExtendedButton' +import ExtendedButton from "/components/ExtendedButton/ExtendedButton"; # What to Track In this page, we provide guidance on what to track and how to track it. ## Start With Two Events + We recommend starting with just 2 events, which can provide a lot of value with little effort: -* **Sign Up** - Tracking Sign Up is a quick way to understand your product's growth; by counting the number -of Sign Ups, you can answer "How many new users am I acquiring every day, week, and month?". +- **Sign Up** - Tracking Sign Up is a quick way to understand your product's growth; by counting the number + of Sign Ups, you can answer "How many new users am I acquiring every day, week, and month?". -* **Value Moment** - Tracking a value moment can help you assess how well your product is doing. You can -answer questions like "How many users experience value in my product each day/week/month?" or -"How many users come back (retain) and experience the moment again?". +- **Value Moment** - Tracking a value moment can help you assess how well your product is doing. You can + answer questions like "How many users experience value in my product each day/week/month?" or + "How many users come back (retain) and experience the moment again?". ### Choose a Value Moment Value moments are often the use of important features or taking a critical action. Here are some examples: -* **Social**: Post Created, Friend Added -* **E-Commerce**: Purchase Completed, Review Submitted -* **Media**: Video Watched, Article Read -* **SaaS**: Document Created, Call Started + +- **Social**: Post Created, Friend Added +- **E-Commerce**: Purchase Completed, Review Submitted +- **Media**: Video Watched, Article Read +- **SaaS**: Document Created, Call Started We recommend keeping your event names short and descriptive. We like to use the Object-Action convention, as you can see in the examples above. ### Include Properties + Properties add context to the event. We recommend these properties for your two events: **Sign Up** - * **Source** (e.g Referral, Organic, Paid) - * **Country** (e.g. United States, Vietnam, Germany) - * **OS** (e.g. Windows, iOS, Android) + +- **Source** (e.g Referral, Organic, Paid) +- **Country** (e.g. United States, Vietnam, Germany) +- **OS** (e.g. Windows, iOS, Android) **Value Moment** - * Up to you! This will depend greatly on your value moment: - * A "Video Watched" event may benefit from a "Duration" property - * A "Message Liked" event may benefit from a "Message Type" property - * Ask yourself: What is the most important information related to your value moment? +- Up to you! This will depend greatly on your value moment: + - A "Video Watched" event may benefit from a "Duration" property + - A "Message Liked" event may benefit from a "Message Type" property +- Ask yourself: What is the most important information related to your value moment? ## We Recommend Server-Side Tracking -Adblockers and browsers are making it harder and harder to track users on the client-side. -If you want to make sure the data you're collecting is accurate, you'll want to do most of + +Adblockers and browsers are making it harder and harder to track users on the client-side. +If you want to make sure the data you're collecting is accurate, you'll want to do most of your tracking server-side. -**Frontend event tracking (especially on the web) loses between 15% and 30% of events**. -If you're only tracking on the client-side, you're missing out on a lot of data, even if you're +**Frontend event tracking (especially on the web) loses between 15% and 30% of events**. +If you're only tracking on the client-side, you're missing out on a lot of data, even if you're using a reverse proxy. Want to learn more? [Read our full guide](/docs/tracking-methods/choosing-the-right-method/) on choosing the right method for tracking. -





- {/* Next Section */} +

+ +


-

Next Steps

-

Once you've chosen a few events to track first, you're ready to set up Mixpanel.

-

- +

Next Steps

+

+ Once you've chosen a few events to track first, you're ready to set up + Mixpanel. +

+

+
-


-

Tracking Plan

-

Outline your events and properties definition in a centralized document as a source of truth on your implementation.

-

- +

+ Tracking Plan +

+

+ Outline your events and properties definition in a centralized document as a + source of truth on your implementation. +

+

+ +
diff --git a/pages/overrides.scss b/pages/overrides.scss index 2cea173fb6..d1ef9b5118 100644 --- a/pages/overrides.scss +++ b/pages/overrides.scss @@ -8,360 +8,1058 @@ $border-radius-md: 24px; $border-radius-lg: 100px; @font-face { - font-display: swap; - font-family: typography.$garnett; - font-style: normal; - font-weight: 500; - src: url("#{typography.$cdn-base}#{typography.$garnett-medium-base}.woff2") - format("woff2"); + font-display: swap; + font-family: typography.$garnett; + font-style: normal; + font-weight: 500; + src: url("#{typography.$cdn-base}#{typography.$garnett-medium-base}.woff2") + format("woff2"); } @font-face { - font-display: swap; - font-family: typography.$garnett; - font-style: normal; - font-weight: 400; - src: url("#{typography.$cdn-base}#{typography.$garnett-regular-base}.woff2") - format("woff2"); + font-display: swap; + font-family: typography.$garnett; + font-style: normal; + font-weight: 400; + src: url("#{typography.$cdn-base}#{typography.$garnett-regular-base}.woff2") + format("woff2"); } @font-face { - font-display: swap; - font-family: typography.$arizona-text-variable; - font-style: normal; - src: url("#{typography.$cdn-base}#{typography.$arizona-text-base}.woff2") - format("woff2"); + font-display: swap; + font-family: typography.$arizona-text-variable; + font-style: normal; + src: url("#{typography.$cdn-base}#{typography.$arizona-text-base}.woff2") + format("woff2"); } @font-face { - font-display: swap; - font-family: typography.$arizona-text-light; - font-style: normal; - src: url("#{typography.$cdn-base}#{typography.$arizona-text-light-base}.woff2") - format("woff2"); + font-display: swap; + font-family: typography.$arizona-text-light; + font-style: normal; + src: url("#{typography.$cdn-base}#{typography.$arizona-text-light-base}.woff2") + format("woff2"); } @font-face { - font-display: swap; - font-family: typography.$apercu; - font-weight: 500; - src: url("#{typography.$cdn-base}#{typography.$apercu-base}.woff2") - format("woff2"); + font-display: swap; + font-family: typography.$apercu; + font-weight: 500; + src: url("#{typography.$cdn-base}#{typography.$apercu-base}.woff2") + format("woff2"); } @font-face { - font-family: typography.$apercu-pro; - font-style: normal; - font-weight: 400; - src: url("#{typography.$cdn-base}/apercu/web/5.008/apercu-regular-pro.woff2") - format("woff2"); + font-family: typography.$apercu-pro; + font-style: normal; + font-weight: 400; + src: url("#{typography.$cdn-base}/apercu/web/5.008/apercu-regular-pro.woff2") + format("woff2"); } @font-face { - font-family: typography.$apercu-pro; - font-style: normal; - font-weight: 500; - src: url("#{typography.$cdn-base}/apercu/web/5.008/apercu-medium-pro.woff2") - format("woff2"); + font-family: typography.$apercu-pro; + font-style: normal; + font-weight: 500; + src: url("#{typography.$cdn-base}/apercu/web/5.008/apercu-medium-pro.woff2") + format("woff2"); } @font-face { - font-family: typography.$apercu-pro; - font-style: normal; - font-weight: 700; - src: url("#{typography.$cdn-base}/apercu/web/5.008/apercu-bold-pro.woff2") - format("woff2"); + font-family: typography.$apercu-pro; + font-style: normal; + font-weight: 700; + src: url("#{typography.$cdn-base}/apercu/web/5.008/apercu-bold-pro.woff2") + format("woff2"); } - -// One-off here because I think the font family definitions this was based on are messed up! +// One-off here because I think the font family definitions this was based on are messed up! @font-face { - font-family: "Apercu Monospaced"; - font-style: normal; - font-weight: 400; - src: url("https://cdn.mxpnl.com/static/marketing/fonts/apercu/web/5.008/apercu-mono-regular-pro.woff2") - format("woff2"); + font-family: "Apercu Monospaced"; + font-style: normal; + font-weight: 400; + src: url("https://cdn.mxpnl.com/static/marketing/fonts/apercu/web/5.008/apercu-mono-regular-pro.woff2") + format("woff2"); } +//Bold top nav buttons on hover +.nextra-nav-container { + .nx-text-sm { + // color: colors.$purple200; + &:hover { + font-weight: bold; + transition-duration: 0.5s; + } + &:active { + font-weight: bold; + } + } +} +// Light Theme Starts Here +.light { + line-height: 1.8; + font-size: 0.88rem; + letter-spacing: 0.3px; -.theme-mixpanel { - line-height: 1.8; - font-size: 0.88rem; - letter-spacing: 0.3px; + // We'll handle our own antialiasing. + .nx-subpixel-antialiased { + -webkit-font-smoothing: unset; + -moz-osx-font-smoothing: unset; + } - // We'll handle our own antialiasing. - .nx-subpixel-antialiased { - -webkit-font-smoothing: unset; - -moz-osx-font-smoothing: unset; + // We'll handle our own tracking. + .nx-tracking-tight { + letter-spacing: unset; + } + + .nx-font-semibold, + .nx-font-bold, + p strong { + font-weight: 500; // Override to a weight that we actually DO support, otherwise we risk faux bold + } + + .nx-font-semibold, + .nx-font-bold, + li strong { + font-weight: 500; // Override to a weight that we actually DO support, otherwise we risk faux bold + } + + // Get rid of all heading border-bottoms + h1, + h2, + h3, + h4, + h5 { + &.nx-border-b { + border-width: 0; } - + } - // We'll handle our own tracking. - .nx-tracking-tight { - letter-spacing: unset; + h1, + h2, + h3, + h4, + h5 { + color: colors.$purple200; + } + + body { + background-color: colors.$base100; + -moz-osx-font-smoothing: grayscale; + -webkit-font-smoothing: antialiased; + overscroll-behavior-y: none; + font-family: typography.$garnett-stack; + } + + // Modify breadcrumbs + .nextra-breadcrumb { + text-transform: uppercase; + letter-spacing: 2px; + font-size: 14px; + font-weight: 500; + color: colors.$purple200; + .nx-font-medium { + color: colors.$purple100; } + .nx-text-ellipsis:hover { + color: colors.$purple100; + cursor: pointer; + } + } + + .nextra-nav-container { + background-color: colors.$purple140; + + // // Modify image assets in top nav + // path { + // fill: colors.$base100; + // } - .nx-font-semibold, .nx-font-bold, - p strong { - font-weight: 500; // Override to a weight that we actually DO support, otherwise we risk faux bold + // .nextra-nav-container-blur { + // background-color: colors.$purple40; + // } + + // Set color for top nav flex region + .nx-mx-auto > nx-flex { + background-color: colors.$purple40; } - .nx-font-semibold, .nx-font-bold, - li strong { - font-weight: 500; // Override to a weight that we actually DO support, otherwise we risk faux bold + // //Modify top nav tabs + // .nx-text-sm { + // color: colors.$purple200; + // &:hover { + // font-weight: bold; + // } + // &:active { + // font-weight: bold; + // } + // } + + // Modify search module + .Search_searchBar__rnWt2 { + ::placeholder { + text-align: center; + } } - - // Get rid of all heading border-bottoms - h1, h2, h3, h4, h5 { - &.nx-border-b { - border-width: 0; - } + } + + // All code/mono type + code, + kbd, + samp, + pre { + font-family: "Apercu Monospaced", monospace; + font-size: 15px; + line-height: 150%; + font-variant-ligatures: none; + font-feature-settings: normal; + letter-spacing: initial; + // Modify code block syntax color + --shiki-color-text: #414141; + --shiki-color-background: transparent; + --shiki-token-constant: #1976d2; + --shiki-token-string: #22863a; + --shiki-token-comment: #aaa; + --shiki-token-keyword: #d32f2f; + --shiki-token-parameter: #ff9800; + --shiki-token-function: #6f42c1; + --shiki-token-string-expression: #22863a; + --shiki-token-punctuation: #212121; + --shiki-token-link: #22863a; + } + + //modify code tab switches + // [role~="tab"] { + // color: colors.$base100; + // } + + //modify code tab hover + [role~="tab"]:hover { + background-color: colors.$purple20; + color: colors.$purple140; + } + + //modify selected tab + .nx-border-primary-500[role~="tab"] { + background-color: colors.$purple20; + color: colors.$purple140; + } + + //modify code block window + // .nextra-code-block pre { + // // background-color: colors.$grey100; + // // scrollbar-color: colors.$black; + // // box-shadow: 0px -7px 6px -8px rgba(32, 31, 36, 0.1); + // } + + .nextra-content { + h1, + h2, + h3, + h4, + h5 { + letter-spacing: -0.3px; } + } - h1, h2, h3, h4, h5 { - color:colors.$purple200; + // Modify nextra-cards + a.nextra-card { + span { + display: flex; + justify-content: center; + background-color: colors.$purple20; + &:hover { + background-color: colors.$purple50; + transition-duration: 0.5s; + } } + } - body { - background-color: colors.$base100; - -moz-osx-font-smoothing: grayscale; - -webkit-font-smoothing: antialiased; - overscroll-behavior-y: none; - font-family: typography.$garnett-stack; + // left-hand sidebar + .nextra-sidebar-container { + // nextra currently doesn't name anything in the sidebar properly and only has tailwind functional + // names, and so this is hacked together so that we get the view that we want + + // bold the parent links, first two are desktop version, second two are mobile version + // extra specificity is required because we want to distinguish between the top level and nested files + .nextra-scrollbar + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > a, + .nextra-scrollbar + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > button, + .nextra-scrollbar + > ul + > li.open + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > a, + .nextra-scrollbar + > ul + > li.open + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > button { + font-weight: 500; } - // All code/mono type - code, kbd, samp, pre { - font-family: "Apercu Monospaced", monospace; - font-size: 15px; - line-height: 150%; - font-variant-ligatures: none; - font-feature-settings: normal; - letter-spacing: initial; + // Bottom scroll mask + .nx-sticky.nx-bottom-0 { + background-color: colors.$base100; + box-shadow: 0px -7px 6px -8px rgba(0, 0, 0, 0.1); } - .nextra-content { - h1, h2, h3, h4, h5 { - letter-spacing: -0.3px; - } + .nx-transform-gpu > .nx-transition-opacity { + // styles the separator / category titles + .first\:nx-mt-0 { + align-items: center; + color: colors.$grey80; + display: flex; + grid-gap: 8px; + letter-spacing: 0.16rem; + padding-bottom: 0; + padding-top: 24px; + } + + // modify pressed state + a:active { + background-color: color.adjust(colors.$purple40, $alpha: -0.6); + } + + // modify the selected nav item + .nx-text-primary-800 { + background-color: colors.$purple20; + color: colors.$purple140; + } + + // modify the non-selected nav items + .nx-text-gray-500 { + color: colors.$purple200; + } + + // remove the vertical rule within dropdowns + .before\:nx-w-px:before { + width: 0; + } + + // modify hover states + .hover\:nx-bg-gray-100:hover { + background-color: colors.$purple20; + color: colors.$purple140; + } + + // add background color to focus states + li > a:focus-visible, + li > button:focus-visible { + background-color: colors.$white; + } + + // add more spacing to focused states + li { + margin-left: 4px; + margin-right: 4px; + } + + // add more spacing to focused states + .nx-pt-1 { + padding-bottom: 0.25rem; + } + + // decrease the indent in the nav + ul { + margin-left: 0; + } } + } - // left-hand sidebar - .nextra-sidebar-container { - // nextra currently doesn't name anything in the sidebar properly and only has tailwind functional - // names, and so this is hacked together so that we get the view that we want + // Right-hand sidebar + .nextra-toc { + // Remove all hardcoded white backgrounds and shadow filters + .nx-shadow-\[0_-12px_16px_white\] { + box-shadow: unset; + } + .nx-bg-white { + background-color: colors.$base100; + } - // bold the parent links, first two are desktop version, second two are mobile version - // extra specificity is required because we want to distinguish between the top level and nested files - .nextra-scrollbar > .nx-transform-gpu > .nx-transition-opacity > ul > li > a, - .nextra-scrollbar > .nx-transform-gpu > .nx-transition-opacity > ul > li > button, - .nextra-scrollbar > ul > li.open > .nx-transform-gpu > .nx-transition-opacity > ul > li > a, - .nextra-scrollbar > ul > li.open > .nx-transform-gpu > .nx-transition-opacity > ul > li > button { - font-weight: 500; - } + // Add some spacing between the sidebar sections + ul li { + margin-top: $base-spacing * 2; + margin-bottom: $base-spacing * 2; + } - // Bottom scroll mask - > .nx-sticky.nx-bottom-0 { - background-color: colors.$base100; - box-shadow: 0px -7px 6px -8px rgba(0, 0, 0, 0.1); - } + // modify selected bookmark + .nx-text-primary-600 { + color: colors.$purple100; + } - .nx-transform-gpu > .nx-transition-opacity { - // styles the separator / category titles - .first\:nx-mt-0 { - align-items: center; - color: colors.$grey80; - display: flex; - grid-gap: 8px; - letter-spacing: 0.16rem; - padding-bottom: 0; - padding-top: 24px; - } - - // modify pressed state - a:active { - background-color: color.adjust(colors.$purple40, $alpha: -0.6); - } - - // modify the selected nav item - .nx-text-primary-800 { - background-color: colors.$purple20; - color: colors.$purple140; - } - - // modify the non-selected nav items - .nx-text-gray-500 { - color: colors.$purple200; - } - - // remove the vertical rule within dropdowns - .before\:nx-w-px:before { - width: 0; - } - - // modify hover states - .hover\:nx-bg-gray-100:hover { - background-color: colors.$purple20; - color: colors.$purple140; - } - - // add background color to focus states - li > a:focus-visible, li > button:focus-visible { - background-color: colors.$white; - } - - // add more spacing to focused states - li { - margin-left: 4px; - margin-right: 4px; - } - - // add more spacing to focused states - .nx-pt-1 { - padding-bottom: 0.25rem; - } - - // decrease the indent in the nav - ul { - margin-left: 0; - } - } + // modify non-selected bookmarks + // .nx-text-gray-500 { + // // background-color: colors.$purple20; + // color: colors.$base100; + // } + + // modify hover states + .nx-text-gray-500:hover { + // background-color: colors.$purple20; + color: colors.$purple100; } + } - // Right-hand sidebar - .nextra-toc { - // Remove all hardcoded white backgrounds and shadow filters - .nx-shadow-\[0_-12px_16px_white\] { - box-shadow: unset; - } - .nx-bg-white { - background-color: colors.$base100; - } + .nextra-breadcrumb { + text-transform: uppercase; + letter-spacing: 2px; + font-size: 14px; + font-weight: 500; + } - // Add some spacing between the sidebar sections - ul li { - margin-top: $base-spacing * 2; - margin-bottom: $base-spacing * 2; - } - - } - - .nextra-breadcrumb { - text-transform: uppercase; - letter-spacing: 2px; - font-size: 14px; - font-weight: 500; - } - - // Custom Search theming from Algolia Docsearch - .DocSearch { - --docsearch-primary-color: #{colors.$purple200}; - --docsearch-highlight-color: #{colors.$purple100}; - --docsearch-spacing: #{$base-spacing * 3}; - --docsearch-modal-width: 47rem; - --docsearch-container-background: rgba(27,11,59,.85); - --docsearch-modal-background: white; - --docsearch-footer-height: 60px; - --docsearch-hit-color: #{colors.$purple200}; - --docsearch-muted-color: #{colors.$purple200}; - - // Global Nextra theming makes the focus ring look a little nasty - input:focus-visible { - box-shadow: none; - } + // Custom Search theming from Algolia Docsearch + .DocSearch { + --docsearch-primary-color: #{colors.$purple200}; + --docsearch-highlight-color: #{colors.$purple100}; + --docsearch-spacing: #{$base-spacing * 3}; + --docsearch-modal-width: 47rem; + --docsearch-container-background: rgba(27, 11, 59, 0.85); + --docsearch-modal-background: white; + --docsearch-footer-height: 60px; + --docsearch-hit-color: #{colors.$purple200}; + --docsearch-muted-color: #{colors.$purple200}; - &-SearchBar { - padding: 80px 88px 32px; - } + // Global Nextra theming makes the focus ring look a little nasty + input:focus-visible { + box-shadow: none; + } - &-Modal { - border-radius: $border-radius-md; - } + &-SearchBar { + padding: 80px 88px 32px; + } - &-Dropdown { - padding: 0 90px; - margin-bottom: 20px; - } - - .DocSearch-Hit-action, .DocSearch-Hit-icon, .DocSearch-Hit-Tree { - color: #{colors.$purple40}; - } + &-Modal { + border-radius: $border-radius-md; + } - &-Hit-Tree { - opacity: 1; - } + &-Dropdown { + padding: 0 90px; + margin-bottom: 20px; + } - &-Hit a { - transition: background-color 0.1s linear; - border-radius: 0; - box-shadow: none; - } + .DocSearch-Hit-action, + .DocSearch-Hit-icon, + .DocSearch-Hit-Tree { + color: #{colors.$purple40}; + } - &-Hits mark { - color: colors.$purple100; - font-weight: bold; - } + &-Hit-Tree { + opacity: 1; + } - &-Hit { - border-radius: $border-radius; - padding-bottom: initial; - margin-bottom: $base-spacing; - border: 2px solid #{colors.$purple100}; - overflow: hidden; - } + &-Hit a { + transition: background-color 0.1s linear; + border-radius: 0; + box-shadow: none; + } - &-Form { - border-radius: $border-radius-md; - box-shadow: inset 0 0 0 2px colors.$grey30; - transition: box-shadow 0.15s linear; + &-Hits mark { + color: colors.$purple100; + font-weight: bold; + } - .DocSearch-MagnifierLabel { - color: colors.$grey30; - transition: color 0.15s linear; - } + &-Hit { + border-radius: $border-radius; + padding-bottom: initial; + margin-bottom: $base-spacing; + border: 2px solid #{colors.$purple100}; + overflow: hidden; + } - &:focus-within { - box-shadow: var(--docsearch-searchbox-shadow); + &-Form { + border-radius: $border-radius-md; + box-shadow: inset 0 0 0 2px colors.$grey30; + transition: box-shadow 0.15s linear; - .DocSearch-MagnifierLabel { - color: var(--docsearch-highlight-color); - } - } - } + .DocSearch-MagnifierLabel { + color: colors.$grey30; + transition: color 0.15s linear; + } - &-Footer { - border-radius: 0 0 $border-radius-md $border-radius-md; - } + &:focus-within { + box-shadow: var(--docsearch-searchbox-shadow); - &-Commands-Key { - box-shadow: none; - background: transparent; - color: colors.$grey50; + .DocSearch-MagnifierLabel { + color: var(--docsearch-highlight-color); } + } + } - &-Label { - color: colors.$grey50; - } + &-Footer { + border-radius: 0 0 $border-radius-md $border-radius-md; + } - &-Screen-Icon { - display: flex; - justify-content: center; - color: unset; - } + &-Commands-Key { + box-shadow: none; + background: transparent; + color: colors.$grey50; + } - &-NoResults-Prefill-List { - display: none; - } + &-Label { + color: colors.$grey50; + } - &-StartScreen { - display: none; - } + &-Screen-Icon { + display: flex; + justify-content: center; + color: unset; + } - &-NoResults { - color: colors.$grey50; - } + &-NoResults-Prefill-List { + display: none; + } + + &-StartScreen { + display: none; } + &-NoResults { + color: colors.$grey50; + } + } } +// Dark theme starts here +.dark { + line-height: 1.8; + font-size: 0.88rem; + letter-spacing: 0.3px; + + // We'll handle our own antialiasing. + .nx-subpixel-antialiased { + -webkit-font-smoothing: unset; + -moz-osx-font-smoothing: unset; + } + + // We'll handle our own tracking. + .nx-tracking-tight { + letter-spacing: unset; + } + + .nx-font-semibold, + .nx-font-bold, + p strong { + font-weight: 500; // Override to a weight that we actually DO support, otherwise we risk faux bold + } + + .nx-font-semibold, + .nx-font-bold, + li strong { + font-weight: 500; // Override to a weight that we actually DO support, otherwise we risk faux bold + } + + //set color of hyperlinks + .nx-underline[href] { + color: colors.$purple40; + } + + summary::-webkit-details-marker { + color: colors.$base100; + } + + // Get rid of all heading border-bottoms + h1, + h2, + h3, + h4, + h5 { + &.nx-border-b { + border-width: 0; + } + } + + // Set color to markdown headers + h1, + h2, + h3, + h4, + h5 { + color: colors.$base100; + } + + Modify high level stuff across body body { + -moz-osx-font-smoothing: grayscale; + -webkit-font-smoothing: antialiased; + overscroll-behavior-y: none; + font-family: typography.$garnett-stack; + // background-color: colors.$black; + } + + // Modify top nav container + .nextra-nav-container { + background-color: colors.$purple200; + + // Modify image assets in top nav + path { + fill: colors.$base100; + } + + .nextra-nav-container-blur { + background-color: colors.$purple40; + } + + // Set color for top nav flex region + .nx-mx-auto > nx-flex { + background-color: colors.$purple100; + } + + //Modify top nav tabs + .nx-text-sm { + color: colors.$base100; + } + + // Modify search module + .Search_searchBar__rnWt2 { + ::placeholder { + text-align: center; + } + } + } + + // Modify main body of article + .nx-w-full > main { + color: colors.$base100; + } + + .nx-mt-6 { + border-bottom: colors.$black; + } + + // modify buttons in integration pages + a.nextra-card { + span { + display: flex; + justify-content: center; + background-color: colors.$purple200; + &:hover { + background-color: colors.$purple140; + transition-duration: 0.5s; + } + } + } + + // Modify code output + code, + kbd, + samp, + pre { + font-family: "Apercu Monospaced", monospace; + font-size: 15px; + line-height: 150%; + font-variant-ligatures: none; + font-feature-settings: normal; + letter-spacing: initial; + --shiki-color-text: #d1d1d1; + --shiki-token-constant: #79b8ff; + --shiki-token-string: #ffab70; + --shiki-token-comment: #6b737c; + --shiki-token-keyword: #f97583; + --shiki-token-parameter: #ff9800; + --shiki-token-function: #b392f0; + --shiki-token-string-expression: #4bb74a; + --shiki-token-punctuation: #bbb; + --shiki-token-link: #ffab70; + } + + //modify code tab switches + [role~="tab"] { + color: colors.$base100; + } + + //modify code tab hover + [role~="tab"]:hover { + background-color: colors.$purple20; + color: colors.$purple140; + } + + //modify selected tab + .nx-border-primary-500[role~="tab"] { + background-color: colors.$purple20; + color: colors.$purple140; + } + + //modify code block window + .nextra-code-block pre { + background-color: colors.$grey100; + scrollbar-color: colors.$black; + box-shadow: 0px -7px 6px -8px rgba(32, 31, 36, 0.1); + } + + // Modify markdown headers + .nextra-content { + h1, + h2, + h3, + h4, + h5 { + letter-spacing: -0.3px; + color: colors.$base100; + } + } + + // Modify left-hand Nav + .nextra-sidebar-container { + // background-color: colors.$black; + + // .nx-flex { + // background-color: colors.$black; + // } + + // nextra currently doesn't name anything in the sidebar properly and only has tailwind functional + // names, and so this is hacked together so that we get the view that we want + + // bold the parent links, first two are desktop version, second two are mobile version + // extra specificity is required because we want to distinguish between the top level and nested files + .nextra-scrollbar + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > a, + .nextra-scrollbar + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > button, + .nextra-scrollbar + > ul + > li.open + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > a, + .nextra-scrollbar + > ul + > li.open + > .nx-transform-gpu + > .nx-transition-opacity + > ul + > li + > button { + font-weight: 500; + } + + // Bottom scroll mask + > .nx-sticky.nx-bottom-0 { + // background-color: colors.$black; + box-shadow: 0px -7px 6px -8px rgba(32, 31, 36, 0.1); + border-top: colors.$black; + } + + .nx-transform-gpu > .nx-transition-opacity { + // styles the separator / category titles text + .first\:nx-mt-0 { + align-items: center; + color: colors.$base100; + display: flex; + grid-gap: 8px; + letter-spacing: 0.16rem; + padding-bottom: 0; + padding-top: 24px; + } + + // modify pressed state + a:active { + background-color: color.adjust(colors.$purple40, $alpha: -0.6); + } + + // modify the selected nav item + .nx-text-primary-800 { + background-color: colors.$purple20; + color: colors.$purple140; + } + + // modify the non-selected nav items + .nx-text-gray-500 { + color: colors.$base80; + } + + // remove the vertical rule within dropdowns + .before\:nx-w-px:before { + width: 0; + } + + // modify hover states + .hover\:nx-bg-gray-100:hover { + background-color: colors.$purple20; + color: colors.$purple140; + } + + // add background color to focus states + li > a:focus-visible, + li > button:focus-visible { + background-color: colors.$white; + } + + // add more spacing to focused states + li { + margin-left: 4px; + margin-right: 4px; + } + + // add more spacing to focused states + .nx-pt-1 { + padding-bottom: 0.25rem; + } + + // decrease the indent in the nav + ul { + margin-left: 0; + } + } + } + + // Modify Right-hand ToC + .nextra-toc { + // Remove all hardcoded white backgrounds and shadow filters + .nx-shadow-\[0_-12px_16px_white\] { + box-shadow: unset; + } + // .nx-bg-white { + // background-color: colors.$black; + // } + + .nextra-scrollbar { + // set background color for bookmark region + // background-color: colors.$black; + + // set font color for bookmark header + p { + color: colors.$base100; + cursor: default; + } + + // modify selected bookmark + .nx-text-primary-600 { + color: colors.$purple50; + } + + // modify non-selected bookmarks + .nx-text-gray-500 { + // background-color: colors.$purple20; + color: colors.$base100; + } + + // modify hover states + .nx-text-gray-500:hover { + // background-color: colors.$purple20; + color: colors.$purple50; + } + } + + // Add some spacing between the sidebar sections + ul li { + margin-top: $base-spacing * 2; + margin-bottom: $base-spacing * 2; + } + } + + // Modify breadcrumbs + .nextra-breadcrumb { + text-transform: uppercase; + letter-spacing: 2px; + font-size: 14px; + font-weight: 500; + color: colors.$base100; + .nx-font-medium { + color: colors.$purple50; + } + .nx-text-ellipsis:hover { + color: colors.$purple50; + cursor: pointer; + } + } + + // Custom Search theming from Algolia Docsearch + .DocSearch { + // --docsearch-primary-color: #{colors.$purple200}; + // --docsearch-highlight-color: #{colors.$purple100}; + // --docsearch-spacing: #{$base-spacing * 3}; + // --docsearch-modal-width: 47rem; + // --docsearch-container-background: rgba(27, 11, 59, 0.85); + // --docsearch-modal-background: white; + // --docsearch-footer-height: 60px; + // --docsearch-hit-color: #{colors.$purple200}; + // --docsearch-muted-color: #{colors.$purple200}; + + // Global Nextra theming makes the focus ring look a little nasty + input:focus-visible { + box-shadow: none; + } + + //Center placeholder text + input[class~="searchBar"]::placeholder { + text-align: center; + } + + &-SearchBar { + padding: 80px 88px 32px; + } + + &-Modal { + border-radius: $border-radius-md; + } + + &-Dropdown { + padding: 0 90px; + margin-bottom: 20px; + } + + .DocSearch-Hit-action, + .DocSearch-Hit-icon, + .DocSearch-Hit-Tree { + color: #{colors.$purple40}; + } + + &-Hit-Tree { + opacity: 1; + } + + &-Hit a { + transition: background-color 0.1s linear; + border-radius: 0; + box-shadow: none; + } + + &-Hits mark { + color: colors.$purple100; + font-weight: bold; + } + + &-Hit { + border-radius: $border-radius; + padding-bottom: initial; + margin-bottom: $base-spacing; + border: 2px solid #{colors.$purple100}; + overflow: hidden; + } + + &-Form { + border-radius: $border-radius-md; + box-shadow: inset 0 0 0 2px colors.$grey30; + transition: box-shadow 0.15s linear; + + .DocSearch-MagnifierLabel { + color: colors.$grey30; + transition: color 0.15s linear; + } + + &:focus-within { + box-shadow: var(--docsearch-searchbox-shadow); + + .DocSearch-MagnifierLabel { + color: var(--docsearch-highlight-color); + } + } + } + + &-Footer { + border-radius: 0 0 $border-radius-md $border-radius-md; + } + + &-Commands-Key { + box-shadow: none; + background: transparent; + color: colors.$grey50; + } + + &-Label { + color: colors.$grey50; + } + + &-Screen-Icon { + display: flex; + justify-content: center; + color: unset; + } + + &-NoResults-Prefill-List { + display: none; + } + + &-StartScreen { + display: none; + } + + &-NoResults { + color: colors.$grey50; + } + } + + // Fix JSX in Quickstart + .next-steps-sections { + .bg-base100 { + background-color: #111111; + } + details { + background-color: #111111; + + summary { + background-color: #111111; + } + } + } + + // Modify Footer + footer { + background-color: #111111; + opacity: 100%; + hr { + opacity: 0%; + } + } + + // Modify copyright text at bottom + .nx-justify-center { + color: colors.$base100; + } + + // Modify hide sidebar button + button[title="Hide sidebar"] { + path { + fill: colors.$base100; + } + } + + // Modify contact support area + // .nx-mt-8 { + // border-top: colors.$black; + // } + + // Modify Navigation buttons at the bottom + .nx-mb-8 > a { + color: colors.$base100; + } + + .nx-mb-8 > a:hover { + color: colors.$purple50; + } + + //remove borders around bottom navigation + // div .nx-mb-8 { + // border-color: colors.$black; + // } + + button [class~="Feedback"] { + background-color: #111111; + } +} diff --git a/theme.config.tsx b/theme.config.tsx index 06f42aac65..4c51511a0d 100644 --- a/theme.config.tsx +++ b/theme.config.tsx @@ -2,7 +2,14 @@ import { FC, ReactNode } from "react"; import { DocsThemeConfig } from "nextra-theme-docs"; import Search from "./components/Search/Search"; import MixpanelLogoWordmark from "./components/svg/MixpanelLogoWordmark"; -import { AdminIcon, AnalysisIcon, DataInIcon, DataOutIcon, IntroIcon, SupportIcon } from "./components/svg/NavIcon"; +import { + AdminIcon, + AnalysisIcon, + DataInIcon, + DataOutIcon, + IntroIcon, + SupportIcon, +} from "./components/svg/NavIcon"; import MainContent from "./components/MainContent/MainContent"; function renderComponent(ComponentOrNode: FC | ReactNode, props?: T) { @@ -12,12 +19,12 @@ function renderComponent(ComponentOrNode: FC | ReactNode, props?: T) { } const config: DocsThemeConfig = { - darkMode: false, + darkMode: true, nextThemes: { - defaultTheme: `theme-mixpanel`, - forcedTheme: `theme-mixpanel`, + defaultTheme: `system`, }, docsRepositoryBase: "https://github.com/mixpanel/docs/tree/main", + // toc: {} head: ( <> + icon = ; break; case `DATA IN`: - icon = + icon = ; break; case `ANALYSIS`: - icon = + icon = ; break; case `ADMIN`: - icon = + icon = ; break; case `DATA OUT`: - icon = + icon = ; break; case `SUPPORT`: - icon = + icon = ; break; case `ENTERPRISE`: - icon = + icon = ; break; - } - return ( - <>{icon} {title} - ) - } else { + } + return ( + <> + {icon} {title} + + ); + } else { return <>{title}; } }, From 29c4fbdbc984b23e5b464bc5083af274672436e8 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Wed, 14 Aug 2024 16:02:00 -0700 Subject: [PATCH 11/12] Update and rename events-and-properties.md to events-and-properties.mdx --- ...roperties.md => events-and-properties.mdx} | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) rename pages/docs/data-structure/{events-and-properties.md => events-and-properties.mdx} (70%) diff --git a/pages/docs/data-structure/events-and-properties.md b/pages/docs/data-structure/events-and-properties.mdx similarity index 70% rename from pages/docs/data-structure/events-and-properties.md rename to pages/docs/data-structure/events-and-properties.mdx index 51653fbcef..df88509cdb 100644 --- a/pages/docs/data-structure/events-and-properties.md +++ b/pages/docs/data-structure/events-and-properties.mdx @@ -1,14 +1,17 @@ +import { Callout } from 'nextra/components' + # Events And Properties ## Overview -Events are the core of [Mixpanel's Data Model](/docs/tutorials/plan/tracking-strategy#the-mixpanel-data-model). All events should have an **Event Name**, a **Timestamp** of when that event has occured, and a **[Distinct ID](/docs/tracking-methods/id-management/identifying-users#what-is-distinct-id)** (Mixpanel's identifier for a user) to tie all events belonging to the same user. Events can optionally have a set of properties, which describes the event in more detail. +Events are the core of [Mixpanel's Data Model](/docs/tutorials/plan/tracking-strategy#the-mixpanel-data-model). All events should have an **Event Name**, a **Timestamp** of when that event has occurred, and a **[Distinct ID](/docs/tracking-methods/id-management/identity-management#distinct-id)** (Mixpanel's identifier for a user) to tie all events belonging to the same user. Events can optionally have a set of properties, which describes the event in more detail. * If you're familiar with databases, events are like tables and properties are like columns. * If you're familiar with Google Analytics, events are like hits and properties are like dimensions. -> **Note:** There are a few use cases, such as tracking [Ad Spend](/docs/data-structure/advanced/ad-spend), in which the event should not be tied to specific users; as such, these events should be sent without a Distinct ID, but this is the exception. - + + **Note:** There are a few use cases, such as tracking [Ad Spend](/docs/tracking-methods/integrations/ad-spend), in which the event should not be tied to specific users; as such, these events should be sent without a Distinct ID, but this is the exception. + For more information about events refer to the documentation on [The Mixpanel Data Model](/docs/tutorials/plan/tracking-strategy#the-mixpanel-data-model). ## Examples @@ -16,7 +19,7 @@ For more information about events refer to the documentation on [The Mixpanel Da * A `Page Viewed` event might have a property called `Page URL`, which is set to the URL of the page that was viewed. * A `Signed Up` event might have a property called `Signup Type`, which indicates whether the signup was `organic` vs `referral`. * A `Song Played` event might have a property called `Song Name`, which is set to the name of the song that was played. -* A `Order Completed` event might have a property called `Items`, which is a list of objects, each of which contains details about an item, like its name, category, and price. +* An `Order Completed` event might have a property called `Items`, which is a list of objects, each of which contains details about an item, like its name, category, and price. ## Use Cases @@ -31,11 +34,11 @@ You can filter, breakdown, and aggregate your events by their properties to answ ### Keep Events as Actions -We recommend striking the right balance when defining your events. Events should neither be too broad nor too specific, and should be defined at the level of how you plan to analyse the user's action or behaviour. Also keeping in mind to use event properties to provide context or details about an event, instead of creating different events to capture similar actions. +We recommend striking the right balance when defining your events. Events should neither be too broad nor too specific, and should be defined at the level of how you plan to analyse the user's action or behavior. Also keep in mind to use event properties to provide context or details about an event, instead of creating different events to capture similar actions. **For example:** -* If your goal is to analyse at high-level how users traverse through different pages: instead of tracking multiple events `Home Page Viewed` and `Pricing Page Viewed`, track a `Page Viewed` event with a `Page Name` property set to **"\/home"** or **"\/pricing"**. See [Tracking Page Views](/docs/tracking-methods/sdks/javascript#tracking-page-views) in our Javascript SDK documentation on how to instrument this. +* If your goal is to analyze at high-level how users traverse through different pages: instead of tracking multiple events `Home Page Viewed` and `Pricing Page Viewed`, track a `Page Viewed` event with a `Page Name` property set to **"\/home"** or **"\/pricing"**. See [Tracking Page Views](/docs/tracking-methods/sdks/javascript#tracking-page-views) in our Javascript SDK documentation on how to instrument this. * If your goal is to track users adding items to a shopping cart: instead of tracking multiple events `Add Shirt to Cart`, `Add Hoodie to Cart`, and `Add Socks to Cart`, track a `Add to Cart` event with a `Item` property set to **"Shirt"**, or **"Hoodie"**, or **"Socks"**. @@ -59,16 +62,19 @@ For example, don't create an event name like `Purchase (11-01-2019)`. Instead, c > **Tip:** Learn more best practices around defining your events and properties under our tutorials for [Creating a Tracking Plan](/docs/tutorials/plan/tracking-strategy#tracking-plan-methodology). + ## FAQ ### What types of data can I send as properties? -Mixpanel accepts arbitrary JSON as properties, including strings, numbers, booleans, lists, and objects. See our [API docs](https://developer.mixpanel.com/reference/import-events) for more details. +Mixpanel accepts arbitrary JSON as properties, including strings, numbers, booleans, lists, and objects. See our [Property Reference doc](https://docs.mixpanel.com/docs/data-structure/property-reference#supported-data-types) or our [API docs](https://developer.mixpanel.com/reference/import-events) for more details. ### What are the limits of events and properties? We don't have a limit on the total number of events you can send to Mixpanel, but it will factor into your [pricing](https://mixpanel.com/pricing). -We have a soft limit of 2000 distinct event names in a 30 day window. If you send more event names, we'll still ingest them, but those event names will not be indexed and will not appear in our autocomplete menus. +We have a soft limit of 5000 distinct event names. If you send more event names, we'll still ingest them, but those event names will not be indexed and will not appear in our autocomplete menus. Each event can have up to 2000 properties. Event property names can be at most 255 characters in length (longer names are truncated). Event property values are limited based on data type, refer to these limits under [Supported Data Types](/docs/data-structure/property-reference#supported-data-types). -**Note**: while events can have up to 2000 properties and batches of events can have up to 2000 events per ingestion batch, some libraries might default to sending the data through the GET protocol which would have a much lower size limit since the information is appended to the URL. If you are hitting the limits on the size of the request, first verify if the method being used is GET and can be switched to POST. + + **Note**: while events can have up to 2000 properties and batches of events can have up to 2000 events per ingestion batch, some libraries might default to sending the data through the GET protocol which would have a much lower size limit since the information is appended to the URL. If you are hitting the limits on the size of the request, first verify if the method being used is GET and can be switched to POST. + From 0b9405520015fd58777f2ea40b4090e783880988 Mon Sep 17 00:00:00 2001 From: myronkaifung <97630035+myronkaifung@users.noreply.github.com> Date: Mon, 25 Nov 2024 10:00:06 -0800 Subject: [PATCH 12/12] Update lookup-tables.md --- pages/docs/data-structure/lookup-tables.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/docs/data-structure/lookup-tables.md b/pages/docs/data-structure/lookup-tables.md index 9ae161eab7..4d5aaafc0c 100644 --- a/pages/docs/data-structure/lookup-tables.md +++ b/pages/docs/data-structure/lookup-tables.md @@ -37,7 +37,7 @@ Then, whenever you use an event with the `song_id` property, you'll have access The benefit is that you don't need to change your tracking code at all. You can upload this Lookup Table after the fact and it automatically joins onto all prior events or user profiles with the mapped property. -We also provide an [API](https://developer.mixpanel.com/reference/replace-lookup-table) and [Warehouse Connectors](/docs/tracking-methods/data-warehouse#lookup-tables) to keep Lookup Tables synced on a recurring basis. +We also provide an [API](https://developer.mixpanel.com/reference/replace-lookup-table) and [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors#lookup-tables) to keep Lookup Tables synced on a recurring basis. ## Use Cases @@ -84,7 +84,7 @@ You can also upload Lookup Tables straight from your reports. Lookup tables uplo This feature can be useful if you need to have the lookup table mapping only for a specific report or if you wish to override an existing globally mapped lookup table for a property within a report. -Lookup Tables can be replaced with a fresh copy, either via our UI, [API](https://developer.mixpanel.com/reference/replace-lookup-table), or [Warehouse Connectors](/docs/tracking-methods/data-warehouse#lookup-tables). +Lookup Tables can be replaced with a fresh copy, either via our UI, [API](https://developer.mixpanel.com/reference/replace-lookup-table), or [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors#lookup-tables). ## How do I use a Lookup Table? @@ -107,7 +107,7 @@ Lookup Tables have a limit of **100MB** per CSV file or roughly 1M rows. You can * Don't use Lookup Tables when the ID is a User ID. Instead use [User Profiles](/docs/data-structure/user-profiles). Mixpanel is more optimized for User Profiles, so they don't have any scale limits and support more opinionated workflows in our product (like clicking into a report and seeing the list of User Profiles). * Don't use Lookup Tables as a way to mutate events. For example, it might be tempting to have an Orders lookup table, with 1 row per Order that a customer makes. Then, you can update the Orders table whenever an order is mutated (eg: when you issue a refund). This approach will quickly run into the 100MB scale limit and will make it difficult to do the analysis you need. Instead, we recommend modeling state changes as events, which doesn't have scale limits and preserves the history of state changes. Track an `Order Completed` event and an `Order Refunded` or `Order Modified` event. You can then use our funnels report to answer questions like: "what % of orders were refunded?" -A good use case for Lookup Tables are for mapping metadata that changes over time, since lookup tables can be replaced via the Mixpanel UI or programatically via [API](https://developer.mixpanel.com/reference/replace-lookup-table) or [Warehouse Connectors](/docs/tracking-methods/data-warehouse#lookup-tables), and changes are retroactive. A currency exchange rate table mapped to `Order Currency` property which can be used to convert `Order Amount`; or a region territory grouping table mapped to `Country` are good examples. +A good use case for Lookup Tables are for mapping metadata that changes over time, since lookup tables can be replaced via the Mixpanel UI or programatically via [API](https://developer.mixpanel.com/reference/replace-lookup-table) or [Warehouse Connectors](/docs/tracking-methods/warehouse-connectors#lookup-tables), and changes are retroactive. A currency exchange rate table mapped to `Order Currency` property which can be used to convert `Order Amount`; or a region territory grouping table mapped to `Country` are good examples. ### Who has access?