[WIP] Restructure Group Analytics + add Hierarchical groups content

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
 
 <Callout type="info">
   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.
-
-<div
-  style={{
-    position: "relative",
-    paddingBottom: "64.90384615384616%",
-    height: 0,
-  }}
->
-  <p>
-    <iframe
-      src="https://www.youtube-nocookie.com/embed/jrIiwhdHCdg"
-      frameBorder="0"
-      webkitallowfullscreen="true"
-      mozallowfullscreen="true"
-      allowFullScreen
-      style={{
-        position: "absolute",
-        top: 0,
-        left: 0,
-        width: "100%",
-        height: "100%",
-        borderRadius: "16px",
-      }}
-    ></iframe>
-  </p>
-</div>
+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.
 
-<img src="/group_analytics_data_model.png" />
+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:<company_id>\|$user:<user_id>` | `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)

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"
 }