> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Mixpanel

[Web](#)[ Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/mixpanel)[ Package](https://www.npmjs.com/package/@walkeros/web-destination-mixpanel)

[Mixpanel](https://mixpanel.com/) is a product analytics platform with people profiles, group analytics, and cohort-based reporting. This destination forwards walkerOS events to Mixpanel via the official [`mixpanel-browser`](https://www.npmjs.com/package/mixpanel-browser) SDK, translating events into `mixpanel.track(...)` calls and resolving identity, people properties, group assignments, and consent opt-in/opt-out.

Where this fits

Mixpanel is a **web destination** in the walkerOS flow:

## Installation[​](#installation "Direct link to Installation")

```bash
npm install @walkeros/web-destination-mixpanel
```

* Integrated
* Bundled

```typescript
import { startFlow } from '@walkeros/collector';
import { destinationMixpanel } from '@walkeros/web-destination-mixpanel';

await startFlow({
  destinations: {
    mixpanel: {
      code: destinationMixpanel,
      config: {
        settings: {
          apiKey: 'YOUR_PROJECT_TOKEN',
          api_host: 'https://api-eu.mixpanel.com',
        },
      },
    },
  },
});
```

Add to your `flow.json` destinations:

```json
"destinations": {
  "mixpanel": {
    "package": "@walkeros/web-destination-mixpanel",
    "config": {
      "settings": {
        "apiKey": "YOUR_PROJECT_TOKEN",
        "api_host": "https://api-eu.mixpanel.com"
      }
    }
  }
}
```

[See bundled mode setup](/preview/pr-749/docs/getting-started/modes/bundled.md) | [CLI reference](/preview/pr-749/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see [destination configuration](/docs/destinations#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property                      | Type                         | Description                                                                                                                                                                                                                | More |
| ----------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `apiKey*`                     | `string`                     | Your Mixpanel project token. Find it in your Mixpanel project settings under "Project Settings" and "Access Keys". Passed to mixpanel.init() as the first argument (like a1b2c3d4e5f6789012345678abcdef12).                |      |
| `api_host`                    | `string`                     | Mixpanel ingestion host. Default: https\://api-js.mixpanel.com. Use https\://api-eu.mixpanel.com for EU residency.                                                                                                         |      |
| `persistence`                 | `'cookie' \| 'localStorage'` | Client-side persistence backend. Default: cookie.                                                                                                                                                                          |      |
| `cross_subdomain_cookie`      | `boolean`                    | Share cookie across subdomains. Default: true.                                                                                                                                                                             |      |
| `cookie_expiration`           | `integer`                    | Cookie expiration in days. Default: 365.                                                                                                                                                                                   |      |
| `secure_cookie`               | `boolean`                    | Only send cookie over HTTPS. Default: false.                                                                                                                                                                               |      |
| `ip`                          | `boolean`                    | Enable server-side IP geolocation. Default: true.                                                                                                                                                                          |      |
| `batch_requests`              | `boolean`                    | Use the /batch endpoint instead of individual requests. Default: true.                                                                                                                                                     |      |
| `batch_size`                  | `integer`                    | Max events per batch. Default: 50.                                                                                                                                                                                         |      |
| `batch_flush_interval_ms`     | `integer`                    | Batch flush interval in ms. Default: 5000.                                                                                                                                                                                 |      |
| `debug`                       | `boolean`                    | Enable verbose SDK logging. Default: false.                                                                                                                                                                                |      |
| `opt_out_tracking_by_default` | `boolean`                    | Start in opted-out state until opt\_in\_tracking() is called. Default: false.                                                                                                                                              |      |
| `track_pageview`              | `boolean \| string`          | Enable Mixpanel auto-pageview tracking. walkerOS default: false (walkerOS sources handle page views).                                                                                                                      |      |
| `autocapture`                 | `any`                        | Enable Mixpanel web autocapture. walkerOS default: false (walkerOS sources handle event capture).                                                                                                                          |      |
| `record_sessions_percent`     | `number`                     | Session replay sampling rate (0-100). Default: 0 (disabled). Session replay is bundled in the npm build.                                                                                                                   |      |
| `record_mask_all_inputs`      | `boolean`                    | Mask all input values in session replay. Default: true.                                                                                                                                                                    |      |
| `identify`                    | `any`                        | walkerOS mapping value resolving to an identity object. Keys: distinctId.                                                                                                                                                  |      |
| `group`                       | `any`                        | walkerOS mapping value resolving to { key, id } → mixpanel.set\_group(key, id). Resolved and sent with set\_group on every push (set\_group also updates the user profile). A rule-level group replaces it for that event. |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](/docs/mapping).

| Property       | Type  | Description                                                                                                                                                                               | More |
| -------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `identify`     | `any` | Per-event identity mapping. Resolves to { distinctId } → mixpanel.identify(distinctId).                                                                                                   |      |
| `people`       | `any` | Per-event people operations. Resolves to an object with any of: set, set\_once, increment, append, union, remove, unset, delete\_user. Each key fires a separate mixpanel.people.\* call. |      |
| `group`        | `any` | Per-event group assignment. Resolves to { key, id } → mixpanel.set\_group(key, id).                                                                                                       |      |
| `groupProfile` | `any` | Per-event group profile operations. Resolves to { key, id, set?, set\_once?, unset?, union?, remove?, delete? } → mixpanel.get\_group(key, id).set/... calls.                             |      |
| `reset`        | `any` | Logout trigger. Resolves to a truthy value → mixpanel.reset(). Typically used with silent: true on a user logout rule.                                                                    |      |

## Examples

### Delete user

An account delete fires Mixpanel people.delete\_user to remove the user profile from the project.

Event

```json
{
  "name": "account delete",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "913ff8b78dc17374",
  "trigger": "test",
  "entity": "account",
  "action": "delete",
  "timestamp": 1700000107,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "silent": true,
  "settings": {
    "people": {
      "map": {
        "delete_user": {
          "value": true
        }
      }
    }
  }
}
```

Out

```javascript
mixpanel.people.delete_user()
```

### Group profile

A company update sets Mixpanel group profile properties via get\_group.set and get\_group.set\_once.

Event

```json
{
  "name": "company update",
  "data": {
    "company_id": "acme-inc",
    "company_name": "Acme, Inc.",
    "plan": "enterprise",
    "employee_count": 250,
    "founded_year": 2010
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "d8b659ea21b7bb18",
  "trigger": "test",
  "entity": "company",
  "action": "update",
  "timestamp": 1700000110,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "silent": true,
  "settings": {
    "groupProfile": {
      "map": {
        "key": {
          "value": "company_id"
        },
        "id": "data.company_id",
        "set": {
          "map": {
            "name": "data.company_name",
            "plan": "data.plan",
            "employee_count": "data.employee_count"
          }
        },
        "set_once": {
          "map": {
            "founded": "data.founded_year"
          }
        }
      }
    }
  }
}
```

Out

```javascript
mixpanel.get_group.set("company_id", "acme-inc", {
  "name": "Acme, Inc.",
  "plan": "enterprise",
  "employee_count": 250
});

mixpanel.get_group.set_once("company_id", "acme-inc", {
  "founded": 2010
})
```

### Consent granted

With consent: { analytics: true } in the destination config, a walker consent command that grants analytics calls mixpanel.opt\_in\_tracking.

Event

```json
{
  "analytics": true
}
```

Out

```javascript
mixpanel.opt_in_tracking()
```

### Consent revoked

With consent: { analytics: true } in the destination config, a walker consent command that denies analytics calls mixpanel.opt\_out\_tracking to stop event capture.

Event

```json
{
  "analytics": false
}
```

Out

```javascript
mixpanel.opt_in_tracking();

mixpanel.opt_out_tracking()
```

### Default track

A walker event becomes a Mixpanel track call with the event name and empty properties.

Event

```json
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "20aa3605c4d26191",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000100,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```javascript
mixpanel.track("product view", {})
```

### Destination identify

With settings.identify mapping distinctId to 'user.id', the destination calls mixpanel.identify before the default track.

Event

```json
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "62f27e7b7ddee1e6",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000104,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```javascript
mixpanel.identify("us3r");

mixpanel.track("page view", {})
```

### Include data

With include: \['data'] in the destination config, the event data section is flattened into prefixed Mixpanel track properties.

Event

```json
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "a1c78c728d51074c",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000102,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```javascript
mixpanel.track("product view", {
  "data_id": "ers",
  "data_name": "Everyday Ruck Snack",
  "data_color": "black",
  "data_size": "l",
  "data_price": 420
})
```

### All people operations

A profile update exercises the full Mixpanel people vocabulary including set, increment, append, union, and remove.

Event

```json
{
  "name": "profile update",
  "data": {
    "name": "Jane Doe",
    "email": "jane@acme.com",
    "page": "/docs/getting-started",
    "removed_tag": "trial",
    "source": "referral"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "d975ab91e6f69a83",
  "trigger": "test",
  "entity": "profile",
  "action": "update",
  "timestamp": 1700000106,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "silent": true,
  "settings": {
    "people": {
      "map": {
        "set": {
          "map": {
            "name": "data.name",
            "email": "data.email"
          }
        },
        "set_once": {
          "map": {
            "signup_source": "data.source"
          }
        },
        "increment": {
          "map": {
            "page_views": {
              "value": 1
            }
          }
        },
        "append": {
          "map": {
            "visited_pages": "data.page"
          }
        },
        "union": {
          "map": {
            "unique_tags": {
              "value": [
                "active"
              ]
            }
          }
        },
        "remove": {
          "map": {
            "tags": "data.removed_tag"
          }
        },
        "unset": {
          "value": [
            "old_plan"
          ]
        }
      }
    }
  }
}
```

Out

```javascript
mixpanel.people.set({
  "name": "Jane Doe",
  "email": "jane@acme.com"
});

mixpanel.people.set_once({
  "signup_source": "referral"
});

mixpanel.people.increment({
  "page_views": 1
});

mixpanel.people.append({
  "visited_pages": "/docs/getting-started"
});

mixpanel.people.union({
  "unique_tags": [
    "active"
  ]
});

mixpanel.people.remove({
  "tags": "trial"
});

mixpanel.people.unset([
  "old_plan"
])
```

### Rule include overrides

With include: \['data'] in the destination config, the rule's include: \['globals'] replaces it, so this event forwards only globals.

Event

```json
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "0299477d8848bb3f",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000103,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "include": [
    "globals"
  ]
}
```

Out

```javascript
mixpanel.track("order complete", {
  "globals_pagegroup": "shop"
})
```

### Group association

A user login associates the user to a company group via mixpanel.set\_group and fires the default track.

Event

```json
{
  "name": "user login",
  "data": {
    "user_id": "user-456",
    "company_id": "acme-inc"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "c494180ab44bc4a2",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000109,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "settings": {
    "group": {
      "map": {
        "key": {
          "value": "company_id"
        },
        "id": "data.company_id"
      }
    }
  }
}
```

Out

```javascript
mixpanel.set_group("company_id", "acme-inc");

mixpanel.track("user login", {})
```

### User login identify

A user login identifies the user and fires Mixpanel people set, set\_once, and increment operations.

Event

```json
{
  "name": "user login",
  "data": {
    "user_id": "new-user-123",
    "plan": "premium",
    "company": "Acme",
    "email": "user@acme.com"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "033f72b867ecd839",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000105000,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "silent": true,
  "settings": {
    "identify": {
      "map": {
        "distinctId": "data.user_id"
      }
    },
    "people": {
      "map": {
        "set": {
          "map": {
            "plan": "data.plan",
            "company": "data.company",
            "email": "data.email"
          }
        },
        "set_once": {
          "map": {
            "first_login": "timestamp"
          }
        },
        "increment": {
          "map": {
            "login_count": {
              "value": 1
            }
          }
        }
      }
    }
  }
}
```

Out

```javascript
mixpanel.identify("new-user-123");

mixpanel.people.set({
  "plan": "premium",
  "company": "Acme",
  "email": "user@acme.com"
});

mixpanel.people.set_once({
  "first_login": 1700000105000
});

mixpanel.people.increment({
  "login_count": 1
})
```

### User logout reset

A user logout calls mixpanel.reset to clear persistence and generate a new anonymous distinct id.

Event

```json
{
  "name": "user logout",
  "data": {
    "string": "foo",
    "number": 1,
    "boolean": true,
    "array": [
      0,
      "text",
      false
    ]
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "50a2af96b36c64bf",
  "trigger": "test",
  "entity": "user",
  "action": "logout",
  "timestamp": 1700000108,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```json
{
  "silent": true,
  "settings": {
    "reset": true
  }
}
```

Out

```javascript
mixpanel.reset()
```

## Intentionally not supported[​](#intentionally-not-supported "Direct link to Intentionally not supported")

These Mixpanel methods have no setting in this destination:

* **`alias()`**: in a project with Mixpanel ID Merge, `mixpanel.identify` (called through the `identify` setting) connects events from before and after login. Without ID Merge, Mixpanel uses `alias()` for this.
* **`register()` / super properties**: set `include` in the destination config (next to `settings`, for example `include: ['globals']`) to attach event sections to every event instead.
* **`people.track_charge`**: deprecated in `mixpanel-browser` and has no effect. Send revenue events as regular `track()` calls with a `revenue` property.
* **`time_event` / page view auto-tracking**: walkerOS sources handle event capture and timing.

All other built-in `mixpanel-browser` config options pass through `settings` directly (e.g. `api_host`, `persistence`, `cross_subdomain_cookie`, `secure_cookie`, `ip`, `property_blacklist`, `loaded` callback, etc.).

## Related[​](#related "Direct link to Related")

* [Mixpanel documentation](https://docs.mixpanel.com/)
* [`mixpanel-browser` SDK reference](https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript)