> For the complete documentation index, see [llms.txt](https://docs.guideflow.com/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guideflow.com/help/integrations/analytics-integrations/mixpanel-integration.md).

# Mixpanel integration

Mixpanel is a powerful analytics tool that helps you track user interactions with your web or mobile applications. This tool collects data that can be used to build custom reports and measure user engagement and retention. Mixpanel is particularly helpful for web applications, especially SaaS, but it also supports mobile apps.

Thanks to Guideflow's integration with Mixpanel, you can send the Guideflow analytics data to your Mixpanel account. <br>

**Including the available events:**

* First Interaction: The first time a user interacts with the guideflow.
* Create New Lead: The event is triggered when a new lead is created.
* Step Viewed: The event triggered after the step was visited.
* External Link Clicked: The event triggered when a user clicks on a link leading to an external website or resource.
* Completed: The event marking the completion of guideflow.
* Session Ended: The event is triggered when a user closes the guideflow tab.

### **How to connect Mixpanel:**

{% @guideflow/guideflow-embed requestedUrl="<https://app.guideflow.com/player/lpxqd6a4rn>" %}

**The different steps:**

* In your Guideflow dashboard, go to 'Integrations' in your workspace.
* Look for Mixpanel under 'Analytics' and click 'Connect'.
* Choose where your server is located.
* Go to your Mixpanel, find 'Project Settings', and copy your project token.
* Paste the token into Guideflow's Mixpanel integration section as the 'write key'.
* Choose which user actions in Guideflow you want to track in Mixpanel.
* Decide if you want this for all guideflows or just specific ones.

### **Test your integration**:&#x20;

After setting up, try interacting with a Guideflow. Then, check Mixpanel's 'Events' to see if the Guideflow actions are recorded. This helps make sure everything's working right.

By setting up this integration, you make it easier to see how users interact with your Guideflows, helping you make better decisions to improve their experience.

## Guideflow → Mixpanel Integration Specifications

Below you can find detailed technical specifications describing how the Guideflow Mixpanel integration behaves in its current implementation. It is written for **integration consumers** — workspace admins configuring the integration, and analysts who read the resulting data in Mixpanel. It contains no code.

***

### 1. What the integration does

When enabled for a workspace, Guideflow forwards viewer activity from your guideflows into your Mixpanel project. It does two distinct things:

1. **Event tracking** — sends a Mixpanel event for each meaningful viewer interaction (viewing a flow, viewing a step, submitting a form, completing a flow, clicking an external link).
2. **People profile management** — creates and updates a Mixpanel People profile for **known leads** (viewers who submit a form with recognizable contact fields), including a rolling history of which flows they have viewed.

Event tracking happens for **all** supported interactions. Profile management is **lead-gated** — it only happens when a viewer identifies themselves (see §5).

***

### 2. Configuration

The integration has two settings:

| Setting                 | Meaning                                                                                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Project token / key** | Your Mixpanel **ingestion** project token. Data is only sent when this is set. If it is empty, the integration silently does nothing.                     |
| **EU residency**        | When enabled, all data is sent to Mixpanel's EU host (`api-eu.mixpanel.com`) for data-residency compliance. When disabled, the default (US) host is used. |

Each event type can additionally be toggled on or off per workspace, so you can choose which interactions are forwarded.

> No Mixpanel **Query/Engage read APIs** are used. The integration only *sends* data (ingestion), so it is not subject to query rate limits and never reads back existing profiles.

***

### 3. Identity model (important)

Every event and every profile is keyed by a stable, anonymous viewer hash called **`guideflow_user_hash`**, which is sent as Mixpanel's `distinct_id`.

Consequences for consumers:

* Guideflow writes into its **own profile space**, identified by this hash.
* The integration **never searches for, merges, or overwrites** profiles that were created by other tools or by a different identifier. There is no risk of Guideflow clobbering an existing Mixpanel profile keyed by, say, a user ID or email from another system.
* `guideflow_user_hash` is also stored as an explicit profile property so you can correlate it with your own data.

***

### 4. Events

The following events are sent. The **Mixpanel event name** column shows exactly what you will see in Mixpanel.

| Interaction           | Mixpanel event name     | Notes                                                                                                                                  |
| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| First interaction     | `first-interaction`     | First time a viewer engages with a flow. If the payload already contains lead fields, it also triggers lead/profile handling (see §5). |
| Step viewed           | `slide-viewed`          | One per step/slide viewed.                                                                                                             |
| Lead created          | `lead-created`          | Fired when a viewer submits a form. Drives profile creation/update.                                                                    |
| Flow completed        | `completed`             | Marked with `guideflow_is_completed = true` and `guideflow_percent_of_completion = 100`.                                               |
| External link clicked | `external-link-clicked` | Marked with `guideflow_cta_clicked = true`.                                                                                            |

> The internal `end-session` event is **not** forwarded to Mixpanel.

#### Event properties

Each event carries a flattened set of properties drawn from:

* all `guideflow_`-prefixed context fields (e.g. flow id, title, source, city/country, session id),
* the flow's metadata, and
* the viewer's submitted form variables.

Empty/null values are dropped, and `distinct_id` is set to `guideflow_user_hash`. Unlike profiles, **events are not filtered** — they keep the full event/step-scoped context (step id, time spent, url, etc.).

***

### 5. People profiles (lead-gated)

A Mixpanel People profile is **only** created or updated when a viewer becomes a **known lead** — i.e. submits a form containing at least one recognized contact field. This happens on the `lead-created` event, and also on `first-interaction` when that payload already includes contact fields.

Rules:

* **No anonymous profiles.** Passive interactions (viewing flows/steps, completing, link clicks) without contact fields only produce *events* — they never create or modify a profile.
* If a form is submitted but contains **no recognized contact field**, the event is still tracked but **no profile is written**.

#### Recognized contact fields → profile properties

| Submitted form field | Mixpanel profile property |
| -------------------- | ------------------------- |
| `email`              | `$email`                  |
| `first_name`         | `$first_name`             |
| `last_name`          | `$last_name`              |
| `phone`              | `$phone`                  |
| `company`            | `guideflow_company`       |
| `website`            | `guideflow_website`       |

`$name` is composed automatically from first + last name when available. `$email`, `$first_name`, `$last_name`, `$phone`, `$name` are Mixpanel's standard reserved profile attributes, so they populate the native profile UI.

#### Additional context stored on the profile

Beyond the contact fields, the profile also receives the remaining `guideflow_`-prefixed context from the lead event (e.g. flow title, session id), plus the explicit `guideflow_user_hash`.

The following **event/step-scoped** properties are deliberately **excluded** from profiles (they remain on events, but would be noisy/misleading on a long-lived profile):

```
guideflow_cta_clicked        guideflow_percent_of_completion
guideflow_folder_id          guideflow_step_id
guideflow_folder_name        guideflow_step_index
guideflow_id                 guideflow_step_name
guideflow_is_completed       guideflow_steps_total_number
guideflow_name               guideflow_time_spend
                             guideflow_url
```

***

### 6. Viewing history on the profile

On each lead capture, the profile's viewing history is updated so you can see, at a glance, what a known lead has watched. These properties are maintained:

| Property                           | Update behavior   | Description                                                                            |
| ---------------------------------- | ----------------- | -------------------------------------------------------------------------------------- |
| `guideflow_flows_viewed`           | Appended (unique) | List of flow IDs the lead has viewed. Grows over time; no duplicates.                  |
| `guideflow_flows_viewed_names`     | Appended (unique) | List of flow names viewed (only added when a name is resolvable).                      |
| `guideflow_last_flow_id`           | Overwritten       | ID of the most recently viewed flow.                                                   |
| `guideflow_last_flow_name`         | Overwritten       | Name of the most recently viewed flow (only when resolvable).                          |
| `guideflow_last_seen`              | Overwritten       | Timestamp of the most recent lead capture.                                             |
| `guideflow_first_seen`             | Set once          | Timestamp the profile was first created by this integration. Never changes afterwards. |
| `guideflow_created_by_integration` | Set once          | Marker (`true`) indicating the profile originated from the Guideflow integration.      |

Notes:

* **Timestamps** are ISO‑8601 UTC strings, generated server-side at the moment Guideflow processes the lead event (they are not taken from the client payload).
* `guideflow_first_seen` uses "set once" semantics, so it always reflects the genuine first time the lead was seen and is never overwritten by later captures.

***

### 7. Write semantics summary

The integration uses three Mixpanel profile operations, which determines how values evolve over time:

* **Set (overwrite):** identity fields, contact-derived `guideflow_*` fields, and the "last viewed" pointers — refreshed on every lead capture.
* **Set once (write only if absent):** `guideflow_first_seen`, `guideflow_created_by_integration` — captured once and preserved.
* **Union (append unique):** `guideflow_flows_viewed`, `guideflow_flows_viewed_names` — accumulate without duplicates.

Event tracking and profile writes are performed together for a lead event.

***

### 8. Behavior & reliability notes

* **Not configured:** if no project token is set, no events and no profile writes are sent.
* **Failures are isolated and logged:** a failure sending one event does not silently corrupt others; errors are logged with context.
* **Idempotency of history:** because viewed-flow lists use union semantics, re-processing the same flow does not create duplicates.
* **Data residency:** controlled solely by the EU residency setting.

***

### 9. Quick FAQ

**Why don't I see a profile for every viewer?** By design — profiles are only created for known leads (form submitters with a recognized contact field). Anonymous viewers generate events only.

**Why is the profile keyed by a hash instead of email?** To keep Guideflow's data in its own namespace and avoid overwriting profiles owned by other systems. The email is still stored as `$email`, and the hash is available as `guideflow_user_hash` for correlation.

**Why are step-level properties (step id, time spent, url, etc.) missing from profiles?** They are intentionally excluded from profiles because they describe a single moment, not the person. They are still present on the corresponding events.

**Can I query/segment leads by which flows they watched?** Yes — use `guideflow_flows_viewed` / `guideflow_flows_viewed_names` (full history) or `guideflow_last_flow_id` / `guideflow_last_flow_name` (most recent), along with `guideflow_first_seen` / `guideflow_last_seen` for recency.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.guideflow.com/help/integrations/analytics-integrations/mixpanel-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.