diff --git a/pages/docs/data-structure/group-analytics.mdx b/pages/docs/data-structure/group-analytics.mdx index 55f29858f5..1755aff9c8 100644 --- a/pages/docs/data-structure/group-analytics.mdx +++ b/pages/docs/data-structure/group-analytics.mdx @@ -1,6 +1,6 @@ import { Callout } from 'nextra/components' -# Group Analytics: Group users together as an aggregated unit of measurement +# Group Analytics Customers on an Enterprise or Growth plan can access Group Analytics as an add-on package. See our [pricing page](https://mixpanel.com/pricing/) for more details. @@ -11,43 +11,47 @@ import { Callout } from 'nextra/components' Mixpanel Group Analytics allows behavioral data analysis at a customized group level (such as account, device—or any other way you want to assess your business). -Historically, Mixpanel grouped events by a single identifier called the distinct_id. This ultimately grouped events by the individual user. Group Analytics allows you to establish an event property other than the distinct_id, such as company ID, account ID, project ID, or billing ID, as an identifier by which to analyze your data. - -
-

- -

-
+Historically, Mixpanel grouped events by a single identifier called the distinct_id. This ultimately grouped events by the individual user. Group Analytics allows you to establish an event property other than the distinct_id, such as company ID, account ID, project ID, or billing ID, as an identifier by which to analyze your data. Mixpanel now supports two models, Hierarchical and Standard, for grouping data. Which one you use depends on whether the relationship between your groups and your users is something you need Mixpanel to enforce. -### Data Modeling +## Hierarchical Groups -Mixpanel Group Analysis allows you to select alternative unique identifiers in reports. +A purpose-built model for **B2B SaaS** where users belong to companies. Mixpanel enforces a two-level hierarchy — **Company** (top level) and **User** (bottom level) — using the reserved properties `$company_id` and `$user_id`. Identity is the composite key (`$company_id`, `$user_id`), which means the same `$user_id` in two different companies is treated as two distinct users. + +Use Hierarchical Groups when: +- You are a B2B product where every user belongs to exactly one company (or account, workspace, organization, etc.) +- The company/user relationship is known from the onset of your tracking + +→ [Hierarchical Groups](/docs/data-structure/group-analytics/hierarchical-groups) + +## Standard Groups -By default, Mixpanel counts unique users by distinct_id. Group Analytics allows you to uniquely count events by an alternative identifier, such as company ID, invite ID, or another value shared by a group of individuals with different distinct_ids. Below you will see an example of an event coming into a project that has `company_id` and `team_id` set up as separate group keys. You will see how, starting with a single event being ingested (on the left), by switching the identifier you're analyzing on, the event can be read with said identifier as the user key to do the analysis on: +Define one or more **group keys** — event properties like `company_id`, `team_id`, or `project_id` — and analyze uniques, funnels, and retention by those keys instead of (or in addition to) `distinct_id`. Each group key is independent: Mixpanel does not assume any relationship between them or between groups and users. - +Use Standard Group Analytics when: +- You need flexible, independent grouping dimensions (restaurants, drivers, devices, etc.) +- Your groups don't have a strict parent-child relationship with users -This allows behavioral analysis from a business or group level, as opposed to an individual level. You can answer questions such as: +→ [Standard Group Analytics](/docs/data-structure/group-analytics/standard-group-analytics) + +## Choosing between the two + +| | Hierarchical Groups | Standard Group Analytics | +|---|---|---| +| **Relationship model** | Two-level hierarchy: Company → User | Flat — group keys are independent | +| **Identity** | Composite: `$company:\|$user:` | `distinct_id` unchanged | +| **User uniqueness** | `$user_id` scoped to `$company_id` | Global `distinct_id` | +| **Reserved properties** | `$company_id` and `$user_id` | None — you define your own group keys | +| **ID Management** | Simplified ID Merge only | Original or Simplified ID merge | +| **Project setup** | Must be enabled at project creation | Can be added to existing projects (but data only attributed to groups after set up, not retroactive) | +| **Best for** | B2B SaaS with company → user structure | Marketplace, multi-entity, or non-B2B models | + +> **Important:** You cannot migrate a Standard project to Hierarchical (or vice versa) after the project has been created. Choose the model that matches your data before you start sending events. + +### Data Modeling + +Mixpanel Group Analysis allows you to select alternative unique identifiers in reports. + +By default, Mixpanel counts unique users by distinct_id. Group Analytics allows you to uniquely count events by an alternative identifier, such as company ID, invite ID, or another value shared by a group of individuals with different distinct_ids. This allows behavioral analysis from a business or group level, as opposed to an individual level. You can answer questions such as: - Which companies are engaging the most with a product? - In instances where there are more than one user per account, such as a video streaming service, how are events triggered at an account level? @@ -92,46 +96,3 @@ For example, you can create an Insights report that shows Signups by unique User Similarly, you can build a report that displays Conversion Rates per User and per Company. ![](/saved-metrics-and-behaviors12.png) - - -### B2B Company Analytics - -Company Analytics is a feature within Group Analytics tailored to B2B SaaS Companies. Here we focus on the idea that users ‘belong’ to a company, and that company behavior is dependent on user behavioral activity. For instance, if you have 2 accounts, each worth $50M but with 5 and 20 users respectively, the account with 20 users is considered more healthy and likely to renew compared to the other account. - -Company Analytics enables you to understand such account health and activation metrics, which are derived from the underlying user activity. - -To use these features, you must [designate the group key as a company key when setting up the group](/docs/data-structure/group-analytics#setup-b2b-company-key). - -#### Company Profiles - -The Company Profiles page gives you a holistic view into your company health, which includes key metrics and company profile properties (i.e, company attributes). - -Company Health Metrics on the page include KPIs on usage (DAU, WAU, MAU, new users), users’ engagement level (activity per user, life cycle of user), and their retention (Day 1, Week 1, and Month 1). - -You can view the definition of each metric by clicking on the metric card, which will open the underlying Mixpanel report. - -To access this page, click on Users/ Companies → Company Profile. - -Note: This is only available if you have [set up a B2B Company Key](/docs/data-structure/group-analytics#setup-b2b-company-key), an option available in the Group Analytics package. - -![image](/B2B_Company_Profiles.webp) - -#### Activation Metrics - -SaaS companies often have use cases that require them to segment companies based on the number of users and the quality of users. - -For example, a question you may have is 'What is the number of trial accounts that have more than two active users?'. The hypothesis is that these accounts will convert faster. - -We have a computed property in both breakdown and filter, called the **“Number of users who did…”**, available in the Group Analytics add-on, which enables you to answer these types of questions as it allows you to break down account activity by the number of active users. - -![image](/B2B_Activation_1.webp) - -When using **“Number of users who did…”** as a breakdown, we show you how many downloads came from different types of account health. -For example, 605 downloads came from accounts with zero active users. ~1.5 downloads in the last 30 days came from accounts with two active users. Where an “active user” is defined by both the activity (e.g., event as such document created) and frequency of the activity (e.g., performing the event ≥1 time). - -In a line chart, we look for activity per interval. - -For example, in the below daily chart, we’re looking for activity qualification per day (i.e., an active user is one who has created at least one document on that day). -The chart below shows that on Aug 19th, 35 accounts downloaded a document. Of the 35 accounts, 32 had one active user, 2 had two active users, and 1 had twenty-eight active users. Since most downloads originated from accounts with only one active user, we can conclude there is no correlation between account document downloaded activity and account health. - -![image](/B2B_Activation_2.webp) diff --git a/pages/docs/data-structure/group-analytics/_meta.ts b/pages/docs/data-structure/group-analytics/_meta.ts index eb7b9d5953..1a63660ecb 100644 --- a/pages/docs/data-structure/group-analytics/_meta.ts +++ b/pages/docs/data-structure/group-analytics/_meta.ts @@ -1,4 +1,4 @@ export default { - "group-analytics-implementation": "Implementation", - "group-analytics-faq": "FAQ" + "legacy": "Legacy Group Analytics", + "hierarchical": "Hierarchical Groups" } \ No newline at end of file diff --git a/pages/docs/data-structure/group-analytics/hierarchical-groups.md b/pages/docs/data-structure/group-analytics/hierarchical-groups.md new file mode 100644 index 0000000000..1274257945 --- /dev/null +++ b/pages/docs/data-structure/group-analytics/hierarchical-groups.md @@ -0,0 +1,196 @@ +# Hierarchical Groups + +> **Looking for Standard Group Analytics?** If you need flexible, independent group keys without an enforced hierarchy, see [Standard Group Analytics](/docs/data-structure/group-analytics/standard-group-analytics) instead. + +Hierarchical Groups is a purpose-built data model for B2B products where **users belong to companies**. Mixpanel enforces a two-level hierarchy — Company (top level) and User (bottom level) — using the reserved properties `$company_id` and `$user_id`. This structure gives you native account-level analytics: count unique companies, measure per-account activation, and understand which accounts are healthy based on the behavior of their users. + +## Overview + +Hierarchical Groups uses a two-level structure: + +- **Company level** (top): Identified by `$company_id`. Represents an account, organization, workspace, or any top-level entity. +- **User level** (bottom): Identified by `$user_id`. Represents an individual user within a company. + +The relationship is **many-to-one**: each user belongs to exactly one company, but a company can have many users. + +### Composite Identity + +In a Hierarchical Groups project, Mixpanel constructs the `$distinct_id` from the composite key: + +``` +$distinct_id = $company:|$user: +``` + +This has a critical implication: **`$user_id` is not globally unique.** A user with `$user_id: alice` in `$company_id: acme` is a completely different user from `$user_id: alice` in `$company_id: globex`. They will have separate profiles and their events will be counted independently. + +Additionally, `$company_id` and `$user_id` must be set at the same time. Setting either property determines the canonical `$distinct_id` for a user based on the composite properties available. If `$company_id` or `$user_id` are missing Mixpaenl will generate a canonical user_id that does not include the missing property. For example, a user with `$user_id: alice` without a `$company_id` cannot be later attributed to the same user that is `$user_id: alice` in `$company_id: acme`. + +### How Analysis Works + +When you analyze by **Company**, Mixpanel implicitly filters to events where `$company_id` is set and counts uniques by `$company_id`. When you analyze by **User**, it counts uniques by the composite `$distinct_id`. Additional group keys you define (beyond `$company_id` and `$user_id`) also implicitly filter by `$company_id`. The additional group keys are defined by the composite of `$company_id` and `` (team, org, etc.). The hierarchy will only ever extend one level company -> user or company -> other_group. + +## Prerequisites + +Before enabling Hierarchical Groups, make sure you meet these requirements: + +**You must have a stable `$company_id` and `$user_id` value.** You cannot use identity management to merge different composites of a `$company_id` and `$user_id` together. If you don't yet know what value to use for these properties, we do not recommend enabling Hierarchical Groups. It is possible to merge anonymous events (only `$device_id`, no `$company_id` and `$user_id` properties set) to a `$company_id` and `$user_id` composite with Simplified ID merge (see [Identity Management](#id_managment) below). + +**You must use Simplified ID Merge.** Hierarchical Groups is not supported on projects using Original ID Merge. + +**This is a project-creation-time decision.** You cannot convert an existing standard project to Hierarchical Groups, and you cannot remove Hierarchical Groups from a project once enabled. Choose your model before sending any data. Existing projects would need to have their data migrated to a *new* Hierarchical project to work on this system. + +## Identity Management +NEED TO FILL THIS IN + + +## Implementation +Hierarchical groups can only be implemented via Data Warehouse Connectors or directly via the HTTP APIs. The groups methods in Mixpanel's SDKs only support classic groups presently. + +### Events + +#### Import API +When sending events via the Import API, include `$company_id` and `$user_id` as event properties. The `distinct_id` property should also be present but Mixpanel will override it with the composite identity. + +```bash +curl --request POST \ + --url 'https://api.mixpanel.com/import?strict=1&project_id=YOUR_PROJECT_ID' \ + --header 'Content-Type: application/json' \ + --header 'accept: application/json' \ + --header 'authorization: Basic YOUR_API_SECRET_BASE64' \ + --data '[ + { + "event": "Feature Used", + "properties": { + "time": 1690000000, + "$insert_id": "unique_event_id", + "$company_id": "acme_corp", + "$user_id": "alice", + "distinct_id": "placeholder", + "feature_name": "dashboard" + } + } + ]' +``` + +After ingestion, this event will have: +- `$company_id`: `acme_corp` +- `$user_id`: `alice` +- `$distinct_id`: `$company:acme_corp|$user:alice` + +#### Warehouse Connector: Events + +When creating a Warehouse Connector for events: + +1. Create a new WHC as you normally would, but stop at the **Map Columns** step. +2. Map the column containing your top-level identifier to **Company ID**. +3. Map the column containing your user-level identifier to **User ID**. This mapping is **required** for Hierarchical Groups projects (it is optional in standard projects). +4. Additional group properties must be set on the event but do not require any special mapping in the set up process. +5. Complete the sync. + +After the sync runs, verify that your events carry all three properties: `$company_id`, `$user_id`, and the auto-generated `$distinct_id` in the format `$company:|$user:`. + +### Profiles + +Profiles store metadata about entity (company, user, and any other groups youve set up). They appear in the **Users** tab of the UI. At the top of the page you will see the groups that you've set up. + +INSERT_PICTURE_HERE + +#### Warehouse Connector: Profiles + +1. Create a new Warehouse Connector and select **Group Table** as the source type. +2. At the **Map Columns** step: + - Set **Group Key** to the group you want this sync to send profile data for (`$company_id`, `$user_id`, etc.) + - Set **Group ID** to the column containing your group identifier values. + - Set **Company ID** to the column containing the identifier values for `$company_id` — this ensures the profile is correctly associated within the hierarchy. +3. Map any additional columns to profile properties. +4. Create the sync. + +After import, profiles will have a Distinct ID in the format `$company:` if doing a `$company_id` sync, `$company:|$user:` for a user sync, or `$company:|:` for other groups you've set up. + +### Groups API + +To create or update company profiles via the HTTP API, use the `/groups` endpoint. There are three key values that must be set in order to properly set profiles for hierarchical groups (outside of `$set`) - `$group_key`, `$group_id`, and `$company_id`. + +- `$group_key` - this should be set to the name of the group key you want to set the profile properties to (`$company_id`, `$user_id`, etc.) +- `$group_id` - this should be set to the actual value of the group key you want to set those properties on (`acme_corp`, `user_123`, etc.) +- `$company_id` - this should be the value of the parent `$company_id` associated with this child entity (`acme_corp`) + +Company Profile Example: +```bash +curl --request POST \ + --url 'https://api.mixpanel.com/groups?strict=1' \ + --header 'Content-Type: application/json' \ + --data '[ + { + "$token": "YOUR_PROJECT_TOKEN", + "$group_key": "$company_id", + "$group_id": "acme_corp", + "$company_id": "acme_corp", + "$set": { + "$name": "Acme Corporation", + "plan": "enterprise", + "industry": "Technology", + "arr": 120000 + } + } + ]' +``` + +User Profile Example: +```bash +curl --request POST \ + --url 'https://api.mixpanel.com/groups?strict=1' \ + --header 'Content-Type: application/json' \ + --data '[ + { + "$token": "YOUR_PROJECT_TOKEN", + "$group_key": "$user_id", + "$group_id": "alice", + "$company_id": "acme_corp", + "$set": { + "$name": "Alice Smith", + "role": "admin", + "signup_date": "2024-01-15" + } + } + ]' +``` + +Additional Group Key Example: +```bash +curl --request POST \ + --url 'https://api.mixpanel.com/groups?strict=1' \ + --header 'Content-Type: application/json' \ + --data '[ + { + "$token": "YOUR_PROJECT_TOKEN", + "$group_key": "team_id", + "$group_id": "engineering", + "$company_id": "acme_corp", + "$set": { + "$name": "Engineering Team", + "headcount": 25 + } + } + ]' +``` +> **Important:** The values of `$group_key`, `$group_id`, and `$company_id` value should be the bare ID (e.g., `acme_corp`), not the prefixed form (`$company:acme_corp`). + +## FAQ + +**Can I start with a standard project and switch to Hierarchical Groups later?** +No. Hierarchical Groups must be enabled at project creation. If you later decide you need it, you would create a new project with Hierarchical Groups enabled and re-import your data with correct `$company_id` values on every historical event. + +**What happens if I send events without `$company_id`?** +The event will still be ingested, but the `$distinct_id` will not include the company prefix. The event will not appear in Company-level analysis. If you later send events for the same `$user_id` with a `$company_id`, Mixpanel will treat them as different users, resulting in split profiles. + +**Is the same `$user_id` in two different companies treated as two different users?** +Yes. User identity is the composite key (`$company_id`, `$user_id`). An event with `$company_id: acme` and `$user_id: alice` is a completely different user from `$company_id: globex` and `$user_id: alice`. They will have separate profiles and separate event histories. + +**Why do my user profiles not appear after a Warehouse Connector sync?** +The most common causes are: +1. You used a "User Table" source type instead of "Group Table." User profiles in Hierarchical Groups must use the Group Table type. +3. The `$user_id` and `$company_id` values in the profile sync don't match the values on your events, so they're creating profiles that don't correspond to any event data. + +**Does Hierarchical Groups work with Original ID Merge** +No. Hierarchical Groups requires Simplified ID Merge. If your project uses Original ID Merge, it is not compatible. diff --git a/pages/docs/data-structure/group-analytics/hierarchical/_meta.ts b/pages/docs/data-structure/group-analytics/hierarchical/_meta.ts new file mode 100644 index 0000000000..eb02dc6db0 --- /dev/null +++ b/pages/docs/data-structure/group-analytics/hierarchical/_meta.ts @@ -0,0 +1,4 @@ +export default { + "group-analytics-implementation": "Implementation", + "group-analytics-faq": "FAQ" +} diff --git a/pages/docs/data-structure/group-analytics/hierarchical/group-analytics-faq.mdx b/pages/docs/data-structure/group-analytics/hierarchical/group-analytics-faq.mdx new file mode 100644 index 0000000000..09d2cac870 --- /dev/null +++ b/pages/docs/data-structure/group-analytics/hierarchical/group-analytics-faq.mdx @@ -0,0 +1,107 @@ +# Hierarchical Groups FAQ + +## Limits + +[Content placeholder: Specific limits for hierarchical groups] + +- Maximum hierarchy depth: [TBD] +- Maximum number of child groups per parent: [TBD] +- Group profile limits: [TBD] +- Event attribution limits: [TBD] + +## Hierarchy Structure + +### How many levels can I have in my hierarchy? + +[Content placeholder: Answer about maximum hierarchy depth and recommended structures] + +### Can a group have multiple parents? + +[Content placeholder: Answer about whether groups can belong to multiple parents in the hierarchy] + +### Can I change the hierarchy structure after it's set up? + +[Content placeholder: Answer about modifying hierarchy relationships after initial setup] + +## Event Attribution + +### How are events attributed in hierarchical groups? + +[Content placeholder: Explanation of how events flow through the hierarchy and are attributed at each level] + +### What happens if I only send a child group key without the parent? + +[Content placeholder: Behavior when partial hierarchy information is sent with an event] + +### Can I query events at any level of the hierarchy? + +[Content placeholder: Explanation of which hierarchy levels are queryable and how] + +## Reporting and Analysis + +### How do metrics roll up through the hierarchy? + +[Content placeholder: Explanation of aggregation behavior from child to parent groups] + +### Can I filter by parent group and see child group breakdown? + +[Content placeholder: Cross-level filtering and breakdown capabilities] + +### Are user properties supported when analyzing by hierarchical groups? + +[Content placeholder: Relationship between user properties and hierarchical group analysis] + +## Group Profiles + +### How do group profiles work in a hierarchy? + +[Content placeholder: Explanation of group profiles at different hierarchy levels] + +### Can child groups inherit properties from parent groups? + +[Content placeholder: Property inheritance behavior in hierarchical groups] + +### How do I export hierarchical group profiles via API? + +[Content placeholder: API instructions for exporting group profiles with hierarchy information] + +```bash +# Placeholder: API example for exporting hierarchical group data +curl --request POST \ + --url https://mixpanel.com/api/2.0/engage \ + --header 'Authorization: Basic ' \ + --data 'data_group_id=' +``` + +## Migration and Compatibility + +### How is Hierarchical Groups different from Legacy Group Analytics? + +Hierarchical Groups extends the legacy Group Analytics by adding parent-child relationships between groups. This allows: +- Roll-up analysis across organizational levels +- Cross-level filtering and breakdowns +- Automatic event attribution through hierarchy levels + +Legacy Group Analytics treats all group keys as independent entities without relationships. + +### Can I use both Legacy and Hierarchical Groups in the same project? + +[Content placeholder: Compatibility between legacy and hierarchical groups] + +### What happens to my existing group data when I migrate to Hierarchical Groups? + +[Content placeholder: Migration path and data preservation] + +## Best Practices + +### When should I use Hierarchical Groups vs Legacy Group Analytics? + +[Content placeholder: Guidance on choosing between hierarchical and legacy approaches] + +### What's the recommended hierarchy structure for B2B SaaS companies? + +[Content placeholder: Common patterns and recommendations for hierarchy setup] + +### How should I handle groups that move between parents? + +[Content placeholder: Best practices for managing group relationship changes] diff --git a/pages/docs/data-structure/group-analytics/hierarchical/group-analytics-implementation.mdx b/pages/docs/data-structure/group-analytics/hierarchical/group-analytics-implementation.mdx new file mode 100644 index 0000000000..7e9eb51b01 --- /dev/null +++ b/pages/docs/data-structure/group-analytics/hierarchical/group-analytics-implementation.mdx @@ -0,0 +1,132 @@ +import { Callout, Tabs } from 'nextra/components' + +# Hierarchical Groups Implementation Guide + + + Hierarchical Groups is available for Enterprise customers. Contact your account team for more details. + + +## Overview + +Hierarchical Groups extends Mixpanel's Group Analytics by allowing you to define parent-child relationships between groups. This enables analysis across organizational hierarchies such as companies → divisions → teams, or accounts → projects → workspaces. + +## Setup + +### Configuring Hierarchical Groups in Project Settings + +To set up hierarchical groups, you'll need to define both the group keys and their relationships. + +1. Navigate to your Project Settings (requires project owner or admin permissions) +2. Navigate to the **Hierarchical Groups** section +3. Click **+Add Hierarchical Group Structure** +4. Define your hierarchy levels (e.g., Company → Team → Project) + +[Content placeholder: Detailed setup steps with screenshots] + +### Defining Parent-Child Relationships + +[Content placeholder: Instructions on how to configure which group keys are parents/children of each other] + + + Group hierarchies must be defined before data is sent. The hierarchy structure determines how events and profiles roll up through the organization. + + +## Tracking Events with Hierarchical Groups + +Events in hierarchical groups automatically inherit relationships based on the group structure you've defined. + +[Content placeholder: Explanation of how event attribution works with hierarchical groups] + +### Example: Multi-Level Organization + +```javascript +// Example: User belongs to a Team, which belongs to a Company +mixpanel.track("feature_used", { + team_id: "team_123", + company_id: "company_456" +}); +``` + +[Content placeholder: Detailed examples showing how events roll up through hierarchy levels] + + + + ```javascript Javascript + // Placeholder: JavaScript implementation examples for hierarchical groups + mixpanel.setGroup("company_id", "company_1"); + mixpanel.setGroup("team_id", "team_a"); + mixpanel.track("event_name"); + ``` + + + ```kotlin Kotlin + // Placeholder: Kotlin implementation examples for hierarchical groups + mixpanel.setGroup("company_id", "company_1"); + mixpanel.setGroup("team_id", "team_a"); + mixpanel.track("event_name"); + ``` + + + ```swift Swift + // Placeholder: Swift implementation examples for hierarchical groups + Mixpanel.mainInstance().setGroup(groupKey: "company_id", groupID: "company_1") + Mixpanel.mainInstance().setGroup(groupKey: "team_id", groupID: "team_a") + Mixpanel.mainInstance().track(event: "event_name") + ``` + + + ```python Python + # Placeholder: Python implementation examples for hierarchical groups + mp.track('user_id', 'event_name', { + 'company_id': 'company_1', + 'team_id': 'team_a' + }) + ``` + + + +## Managing Hierarchical Group Profiles + +Hierarchical group profiles allow you to set properties at each level of your organization structure. + +[Content placeholder: How to create and update group profiles at different hierarchy levels] + +### Setting Parent-Child Relationships + +[Content placeholder: API/SDK examples for establishing parent-child relationships between group profiles] + +```python +# Placeholder: Example of setting up hierarchical relationship +mp.group_set('team_id', 'team_a', { + 'Team Name': 'Engineering Team A', + 'parent_company_id': 'company_1' +}) +``` + +## Roll-Up Analysis + +One of the key features of hierarchical groups is the ability to analyze behavior at any level and see how it rolls up. + +[Content placeholder: Explanation of how metrics aggregate through hierarchy levels] + +### Cross-Level Filtering + +[Content placeholder: How to filter and break down data across different hierarchy levels] + +## SDK References for Hierarchical Groups + +[Content placeholder: Links to SDK-specific implementation guides] + +- [HTTP API](https://developer.mixpanel.com/reference/group-set-property) +- [Javascript SDK](/docs/tracking-methods/sdks/javascript#group-analytics) +- [iOS-Swift SDK](/docs/tracking-methods/sdks/swift#group-analytics) +- [Android SDK](/docs/tracking-methods/sdks/android#group-analytics) +- [Python SDK](/docs/tracking-methods/sdks/python#group-analytics) + +## Migration from Legacy Group Analytics + +[Content placeholder: Guide for customers migrating from legacy group analytics to hierarchical groups] + +### Compatibility Considerations + +[Content placeholder: What to know when transitioning existing group analytics implementations] diff --git a/pages/docs/data-structure/group-analytics/legacy/_meta.ts b/pages/docs/data-structure/group-analytics/legacy/_meta.ts new file mode 100644 index 0000000000..eb02dc6db0 --- /dev/null +++ b/pages/docs/data-structure/group-analytics/legacy/_meta.ts @@ -0,0 +1,4 @@ +export default { + "group-analytics-implementation": "Implementation", + "group-analytics-faq": "FAQ" +} diff --git a/pages/docs/data-structure/group-analytics/group-analytics-faq.mdx b/pages/docs/data-structure/group-analytics/legacy/group-analytics-faq.mdx similarity index 100% rename from pages/docs/data-structure/group-analytics/group-analytics-faq.mdx rename to pages/docs/data-structure/group-analytics/legacy/group-analytics-faq.mdx diff --git a/pages/docs/data-structure/group-analytics/group-analytics-implementation.mdx b/pages/docs/data-structure/group-analytics/legacy/group-analytics-implementation.mdx similarity index 100% rename from pages/docs/data-structure/group-analytics/group-analytics-implementation.mdx rename to pages/docs/data-structure/group-analytics/legacy/group-analytics-implementation.mdx diff --git a/pages/docs/data-structure/group-analytics/standard-group-analytics.md b/pages/docs/data-structure/group-analytics/standard-group-analytics.md new file mode 100644 index 0000000000..ab58a172c2 --- /dev/null +++ b/pages/docs/data-structure/group-analytics/standard-group-analytics.md @@ -0,0 +1,185 @@ +# Standard Group Analytics + +> **Looking for Hierarchical Groups?** If your product has a B2B company → user relationship, see [Hierarchical Groups](/docs/data-structure/group-analytics/hierarchical-groups) instead. + +Standard Group Analytics lets you establish event properties other than `distinct_id` as identifiers by which to analyze your data. By defining **group keys** — such as `company_id`, `account_id`, `project_id`, or `billing_id` — you can count uniques, build funnels, and measure retention at the group level rather than (or alongside) the individual user level. + +## Overview + +By default, Mixpanel counts unique users by `distinct_id`. Group Analytics lets you count uniques by an alternative identifier — one shared by a set of individuals with different `distinct_id` values. For example, if five users share the same `company_id`, a "unique companies" count for an event those five users all performed would return 1, not 5. + +Each group key you define is **independent**. Mixpanel does not assume any relationship between group keys or between groups and users. You can define up to 5 group keys per project, and events can carry values for multiple group keys simultaneously. + +### Group Profiles + +Just as User Profiles store metadata about individual users, **Group Profiles** store metadata about groups. A group profile is identified by a `group_key` and `group_id` pair — for example, the group key `company` with the group ID `acme_corp`. Group profile properties (like company name, plan tier, or industry) can be used as filters and breakdowns in reports. + +### Company Analytics (B2B Key) + +Company Analytics is a feature within Standard Group Analytics tailored for B2B SaaS. It introduces the concept of a **B2B Company Key** — a designated group key that represents "company" in your data model. With a B2B Company Key, you get access to the **"Number of users who did…"** computed property, which lets you segment companies by the count and quality of their active users. For example: "How many trial accounts have more than two users who completed onboarding?" + +> **Note:** Company Analytics and Hierarchical Groups solve similar B2B problems but work very differently. Company Analytics sits on top of Standard Group Analytics and does not enforce a company → user identity relationship. Hierarchical Groups does. See the [comparison table](/docs/data-structure/group-analytics#choosing-between-the-two) for help deciding. + +## Data Model + +### Events + +For an event to be attributed to a group, the event must include the **group key as an event property** with the group ID as its value. Without the group key property on the event, Mixpanel cannot attribute that event to a group. + +```json +{ + "event": "Purchase", + "properties": { + "distinct_id": "user_123", + "time": 1690000000, + "company_id": "acme_corp", + "team_id": "engineering", + "amount": 99.99 + } +} +``` + +In this example, if `company_id` and `team_id` are both registered as group keys, this event will be attributed to the `acme_corp` company group and the `engineering` team group. + +### Group Profiles + +Group profiles are key-value stores of metadata about a specific group. They are identified by the combination of `group_key` and `group_id`. + +```json +{ + "$group_key": "company_id", + "$group_id": "acme_corp", + "$set": { + "$name": "Acme Corporation", + "plan": "enterprise", + "industry": "Technology", + "employee_count": 500 + } +} +``` + +### Identity + +Standard Group Analytics does **not** change how `distinct_id` or user identity works. Users are still identified by `distinct_id` as normal. Group keys provide an additional, independent axis for counting uniques — they do not replace or modify user identity. + +## Implementation + +### Step 1: Define Group Keys in Project Settings + +Before sending group data, register your group keys in **Project Settings → Group Keys**. You can register up to 5 group keys per project. Each group key corresponds to an event property name (e.g., `company_id`). + +### Step 2: Send Events with Group Key Properties + +Ensure that every event you want attributed to a group includes the group key as an event property. You can do this in two ways: + +**Option A: Set the group on the user (SDK)** + +Calling `set_group()` registers the group key as a super property on the user, so it is automatically attached to all subsequent events. + +**JavaScript:** +```javascript +// Register the current user to the "acme_corp" company group. +// All future events from this user will include company_id = "acme_corp". +mixpanel.set_group("company_id", "acme_corp"); +``` + +**Python:** +```python +# No SDK-level super property for server-side. +# Include the group key directly in event properties (see Option B). +``` + +**Option B: Include the group key directly on events** + +For server-side tracking or when you want selective attribution, include the group key property on individual events. + +```json +{ + "event": "Invoice Paid", + "properties": { + "distinct_id": "user_456", + "time": 1690000000, + "company_id": "acme_corp", + "amount": 2500 + } +} +``` + +### Step 3: Create Group Profiles + +Group profiles are optional but recommended — they let you filter and break down reports by group-level metadata (e.g., company plan, industry). + +**JavaScript:** +```javascript +// Set properties on the "acme_corp" company group profile +mixpanel.get_group("company_id", "acme_corp").set({ + "$name": "Acme Corporation", + "plan": "enterprise", + "industry": "Technology" +}); +``` + +**Python:** +```python +from mixpanel import Mixpanel + +mp = Mixpanel("YOUR_PROJECT_TOKEN") + +mp.group_set("company_id", "acme_corp", { + "$name": "Acme Corporation", + "plan": "enterprise", + "industry": "Technology" +}) +``` + +**HTTP API:** +```bash +curl https://api.mixpanel.com/groups \ + --header 'Content-Type: application/json' \ + --data '[ + { + "$token": "YOUR_PROJECT_TOKEN", + "$group_key": "company_id", + "$group_id": "acme_corp", + "$set": { + "$name": "Acme Corporation", + "plan": "enterprise" + } + } + ]' +``` + +### Step 4: Set Up a B2B Company Key (optional) + +If one of your group keys represents "company" and you want access to the **"Number of users who did…"** computed property, designate that group key as your B2B Company Key in **Project Settings → Group Keys**. + +### Warehouse Connector Implementation + +When importing data through a Warehouse Connector: + +**Events:** Map your group key columns in the "Map Columns" step. Ensure the column names match the group keys registered in Project Settings. + +**Group Profiles:** Select "Group Table" as the source type. Set the "Group Key" to the group key you want to populate (e.g., `company_id`), and set the "Group ID" to the column that contains the unique identifier for each group. + +## Analysis + +Once group keys are configured and events are flowing with group key properties: + +- In **Insights**, **Funnels**, **Retention**, and **Flows**, use the metric selector to switch from counting by "Unique Users" to counting by your group (e.g., "Unique Companies"). +- You can mix metrics in a single Insights report — for example, one metric counting unique users and another counting unique companies. +- **Group profile properties** are available as filters and breakdowns when analyzing by the corresponding group. +- **User profile properties** are available when analyzing by users, but **not** when analyzing by groups. + +## FAQ + +**Does Mixpanel backfill historical events to groups?** +No. Mixpanel attributes events to groups only from the date the group key was registered in Project Settings. Historical events that contain the group key as a property but were sent before the group key was configured will not be retroactively attributed. + +**Can I use group profile properties when analyzing by users?** +Yes. Group properties are available as filters and breakdowns when analyzing by users. The reverse is not true — user properties are not available when analyzing by groups. + +**How do I export group profiles?** +Use the Engage API endpoint with the `data_group_id` parameter. + +**What's the difference between Group Analytics and Lookup Tables?** +Both augment events with metadata, but Group Analytics also **indexes** your events by the group key. This means you can do funnels, retention, and unique counts by the group key. Lookup Tables only support filtering and breakdowns — they do not support unique counting or sequential analysis by the join key.