Mixpanel
Server-side event delivery to Mixpanel for product analytics, people profiles, and group analytics via the official mixpanel Node.js SDK.
Mixpanel is a server destination in the walkerOS flow:
Sends events server-side to Mixpanel via `/track` (real-time, up to 5 days old) or `/import` (historical, any age). Supports people profile operations, group analytics, and identity resolution.
Installation
npm install @walkeros/collector @walkeros/server-destination-mixpanel- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationMixpanel from '@walkeros/server-destination-mixpanel';
await startFlow({
destinations: {
mixpanel: {
code: destinationMixpanel,
config: {
settings: {
apiKey: process.env.MIXPANEL_API_KEY,
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "server"
},
"destinations": {
"mixpanel": {
"package": "@walkeros/server-destination-mixpanel",
"config": {
"settings": {
"apiKey": "$secret.MIXPANEL_API_KEY"
}
}
}
}
}
}
}Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
apiKey | string | Your Mixpanel project token. Find it in Project Settings > Access Keys. Passed as the first argument to Mixpanel.init(). | |
secret | string | API secret for the /import endpoint (historical data). Required when useImport is true. | |
host | string | Mixpanel API host. Default: 'api.mixpanel.com' (US). Use 'api-eu.mixpanel.com' (EU) or 'api-in.mixpanel.com' (India). | |
protocol | string | Protocol for API requests. Default: 'https'. | |
keepAlive | boolean | Reuse HTTP connections. Default: true. | |
geolocate | boolean | Parse IP for geolocation. Default: false. Server IP caveat: all users map to server location unless $ip is overridden. | |
debug | boolean | Enable SDK debug logging. Default: false. | |
verbose | boolean | Enable verbose request logging. Default: false. | |
test | boolean | Enable dry-run mode. Default: false. | |
useImport | boolean | Use /import endpoint instead of /track. Accepts events of any age (no 5-day limit). Requires secret for authentication. | |
identify | any | walkerOS mapping value resolving to { distinctId, alias? }. distinctId is passed as distinct_id on every SDK call. | |
include | any | Has no effect: this destination does not read settings.include. To flatten event sections such as ['data', 'globals'] into prefixed track() properties, set include in the destination config. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
identify | any | Per-event identity mapping. Resolves to { distinctId, alias? }. distinctId is passed as distinct_id to all SDK calls. | |
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 mp.people.* call with distinct_id as first arg. | |
group | any | Per-event group association. Resolves to { key, id }. The group key/id is added as a track() property. | |
groupProfile | any | Per-event group profile operations. Resolves to { key, id, set?, set_once?, union?, remove?, unset?, delete? }. Fires mp.groups.* calls. | |
useImport | any | Per-event import flag. When truthy, uses mp.import() instead of mp.track() for this rule. |
Examples
Alias before track
A user login merges a prior anonymous id into the new user id via mp.alias before sending the track event.
{
"name": "user login",
"data": {
"user_id": "new-user-456",
"anon_id": "anon-789"
},
"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": "83569ca31dc5de73",
"trigger": "test",
"entity": "user",
"action": "login",
"timestamp": 1700000108000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"settings": {
"identify": {
"map": {
"distinctId": "data.user_id",
"alias": "data.anon_id"
}
}
}
}mp.alias("new-user-456", "anon-789");
mp.track("user login", {
"distinct_id": "new-user-456"
})Common people operations
A profile update exercises the common Mixpanel people vocabulary: set, set_once, increment, append, union, remove, and unset. delete_user is not covered by this example.
{
"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": "9f0c1f4842ba6224",
"trigger": "test",
"entity": "profile",
"action": "update",
"timestamp": 1700000105000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"silent": true,
"settings": {
"identify": {
"map": {
"distinctId": "user.id"
}
},
"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"
]
}
}
}
}
}mp.people.set("us3r", {
"name": "Jane Doe",
"email": "jane@acme.com"
});
mp.people.set_once("us3r", {
"signup_source": "referral"
});
mp.people.increment("us3r", {
"page_views": 1
});
mp.people.append("us3r", {
"visited_pages": "/docs/getting-started"
});
mp.people.union("us3r", {
"unique_tags": [
"active"
]
});
mp.people.remove("us3r", {
"tags": "trial"
});
mp.people.unset("us3r", [
"old_plan"
])Group profile
A company update sets Mixpanel group profile properties via groups.set and groups.set_once.
{
"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": "27b19fe9b40324cf",
"trigger": "test",
"entity": "company",
"action": "update",
"timestamp": 1700000106000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"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"
}
}
}
}
}
}mp.groups.set("company_id", "acme-inc", {
"name": "Acme, Inc.",
"plan": "enterprise",
"employee_count": 250
});
mp.groups.set_once("company_id", "acme-inc", {
"founded": 2010
})Default track
With settings.identify mapping distinctId to 'user.id', a walkerOS event is forwarded to Mixpanel as a track call with that distinct_id. Without identify the track call carries no distinct_id.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "db22fb16c70f663d",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000100000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}mp.track("product view", {
"distinct_id": "us3r"
})Historical import
With settings.useImport: true and settings.identify mapping distinctId to 'user.id', the event goes through mp.import with its timestamp, for backfilling historical Mixpanel data. The /import endpoint also needs settings.secret: without it every event fails.
{
"name": "order complete",
"data": {
"value": 99.99
},
"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": "235d0d7bd7a213f2",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000107000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}mp.import("order complete", 1700000107000, {
"distinct_id": "us3r"
})Per-event identify
A mapping-level identify overrides settings.identify and resolves the distinct_id from event data.
{
"name": "user login",
"data": {
"user_id": "resolved-id",
"plan": "premium"
},
"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": "e73b24b9c5521944",
"trigger": "test",
"entity": "user",
"action": "login",
"timestamp": 1700000102000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"settings": {
"identify": {
"map": {
"distinctId": "data.user_id"
}
}
}
}mp.track("user login", {
"distinct_id": "resolved-id"
})Track with group
With settings.identify mapping distinctId to 'user.id', a group key and id are attached as a Mixpanel track property so the event is associated with a company or account.
{
"name": "page view",
"data": {
"company_id": "acme"
},
"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": "f0cc5f6fec3d8eeb",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000103000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"settings": {
"group": {
"map": {
"key": {
"value": "company_id"
},
"id": "data.company_id"
}
}
}
}mp.track("page view", {
"distinct_id": "us3r",
"company_id": "acme"
})Track with include
With settings.identify mapping distinctId to 'user.id' and include: ['data'] in the destination config, the event data section is flattened into prefixed Mixpanel track properties.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "db22fb16c70f663d",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000101000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}mp.track("product view", {
"distinct_id": "us3r",
"data_id": "ers",
"data_name": "Everyday Ruck Snack",
"data_color": "black",
"data_size": "l",
"data_price": 420,
"data_currency": "EUR"
})User login people
A user login fires Mixpanel people.set, set_once, and increment operations without sending a track event.
{
"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": "99a1b89513e4d3ac",
"trigger": "test",
"entity": "user",
"action": "login",
"timestamp": 1700000104000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"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
}
}
}
}
}
}
}mp.people.set("new-user-123", {
"plan": "premium",
"company": "Acme",
"email": "user@acme.com"
});
mp.people.set_once("new-user-123", {
"first_login": 1700000104000
});
mp.people.increment("new-user-123", {
"login_count": 1
})Identity
Without settings.identify the track calls carry no distinct_id, so the quickstart's events are tied to no user. Map distinctId in settings.identify, for example to user.id as the examples above do, or per rule. People operations run only when a distinctId resolves.
Consent and delivery
The quickstart sets no config.consent, so Mixpanel receives every event. Add config.consent to send only with consent (consent management).
Each event is sent at once. This destination has no pushBatch, so config.batch has no effect and the collector logs one ERROR line saying so (batch scheduling). A request that fails or that Mixpanel rejects fails the event with the code transport.