Mixpanel is a product analytics destination. RudderStack sends events to Mixpanel’s APIs from its servers, or — for web sources — through Mixpanel’s own SDK in device mode.
In a Mixpanel destination spec:
type: mpdefinition_version: 1version: rudder/v1
kind: destination
metadata:
name: mixpanel-prod
spec:
id: mixpanel-prod
display_name: Mixpanel Production
type: mp
definition_version: 1
enabled: true
config:
token: "{{ .MIXPANEL_TOKEN }}"
data_residency: us
identity_merge_api: simplified
use_user_defined_page_event_name: true
user_defined_page_event_template: "Viewed {{ category }} {{ name }} page"
use_user_defined_screen_event_name: false
set_once_properties:
- signup_date
prop_increments:
- purchase_count
group_key_settings:
- company_id
strict_mode: false
drop_traits_in_track_event: false
union_properties:
- interests
append_properties:
- viewed_plans
use_new_mapping: true
user_deletion_api: engage
connection_mode:
web: cloud
cloud: cloud
consent_management:
web:
- provider: oneTrust
consents:
- analyticsThe above example connects everything in cloud mode, so it omits the web SDK settings, which apply only to web sources in device mode — see Web device mode.
config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.
Mixpanel settings split by connection mode. The groups below say which mode each key affects. Rudder CLI accepts every key whatever the mode — a key for the other mode is stored and ignored.
token
RequiredSecret
Type:
string
Description: Your Mixpanel project token, from Project Settings > Access Keys in Mixpanel.
Notes:
{{ path || fallback }} template is accepted in place of a literal.{{ .VAR }} reference rather than a literal — see Secrets.
data_residency
Required
Type:
string
Description: Region of the Mixpanel servers RudderStack sends data to.
Notes:
us, eu, or in.us. Rudder CLI requires it explicitly.identity_merge_api
Required
Type:
string
Description: Mixpanel ID merge API used to tie user activity together across devices.
Notes:
simplified or original. If you choose simplified, turn on Simplified ID Merge for your project in Mixpanel first.original. Rudder CLI requires it explicitly.These keys apply in both modes.
use_user_defined_page_event_name
Type:
boolean
Default value:
false
Description:
Name page events from user_defined_page_event_template instead of the default name.
user_defined_page_event_template
Type:
string
Default value:
Viewed {{ category }} {{ name }} page
Description:
Template for page event names. Each {{ field }} is replaced with that field from the event — category from properties.category, and name from the event name.
Notes:
use_user_defined_page_event_name is true. Omitting it uses the default template; an explicit empty string fails validation.{{ category }}-style fields have no leading dot, so Rudder CLI’s variable substitution leaves them alone.page event named Home with properties.category: Integration becomes Viewed Integration Home page.
use_user_defined_screen_event_name
Type:
boolean
Default value:
false
Description:
Name screen events from user_defined_screen_event_template instead of the default name.
user_defined_screen_event_template
Type:
string
Default value:
Viewed {{ category }} {{ name }} screen
Description:
Template for screen event names, on the same terms as user_defined_page_event_template.
Notes:
use_user_defined_screen_event_name is true. Omitting it uses the default template; an explicit empty string fails validation.These keys apply in both modes. Each takes an array of property or trait names, each at most 100 characters or a {{ path || fallback }} template.
set_once_properties
Type:
array of strings
Description:
identify traits Mixpanel sets on a user profile once and never overwrites.
prop_increments
Type:
array of strings
Description: Numeric properties to increment on the user’s Mixpanel People profile.
group_key_settings
Type:
array of strings
Description:
Group keys that identify groups in Mixpanel. RudderStack sends group calls only when at least one key is listed.
These keys apply to events sent in cloud mode. The dashboard shows them only when the destination has a cloud-mode connection.
strict_mode
Type:
boolean
Default value:
false
Description: Have Mixpanel validate each request and return an error for every event that fails, rather than accepting what it can. See Mixpanel’s Import Events API.
drop_traits_in_track_event
Type:
boolean
Default value:
false
Description:
Drop the persisted user traits (context.traits) from track events. When false, they’re sent alongside the event properties.
union_properties
Type:
array of strings
Description:
identify traits whose values are added to a list property on the profile only if not already present.
append_properties
Type:
array of strings
Description:
identify traits whose values are appended to a list property on the profile.
use_new_mapping
Type:
boolean
Default value:
false
Description:
Send name traits in snake case — $first_name and $last_name — instead of the older $firstName and $lastName. The old mapping is being deprecated, so turn this on.
user_deletion_api
Type:
string
Default value:
engage
Description: Mixpanel API RudderStack uses to delete a user.
Notes:
engage — deletes the user profile but keeps its events.task — deletes the profile and its events. Needs gdpr_api_token.gdpr_api_token
RequiredSecret
Type:
string
Description: Mixpanel GDPR API token, used to delete a user’s profile and events.
Notes:
user_deletion_api is task. Leave it unset otherwise.{{ path || fallback }} template is accepted in place of a literal.service_account_user_name
SecretInternal
Type:
string
Description: Username of a Mixpanel service account.
Notes:
service_account_secret, and project_id are a Mixpanel service account credential, used together. token is required either way, so set these only if your destination already uses them.
service_account_secret
SecretInternal
Type:
string
Description:
Secret of the Mixpanel service account named in service_account_user_name.
Notes:
project_id
Internal
Type:
string
Description: Mixpanel project ID, sent with service account authentication.
Notes:
These keys configure Mixpanel’s SDK in the browser, so they apply only to web sources connected in device mode.
people
Type:
boolean
Default value:
false
Description:
Send identify calls to Mixpanel People. This is what the dashboard calls Use Mixpanel People.
set_all_traits_by_default
Type:
boolean
Default value:
false
Description:
Set every identify trait as a super property, and — when people is true — as a People property too.
super_properties
Type:
array of strings
Description: Event properties to set as Mixpanel super properties.
people_properties
Type:
array of strings
Description:
identify traits to set as Mixpanel People properties.
event_increments
Type:
array of strings
Description: Event names whose occurrences are counted on the user’s People profile.
consolidated_page_calls
Type:
boolean
Default value:
true
Description:
Send every page call as a Loaded a Page event. Mixpanel recommends leaving this on.
track_categorized_pages
Type:
boolean
Default value:
false
Description:
Also send an event for each page call that has a category — page("Docs", "Index") becomes Viewed Docs Index Page.
track_named_pages
Type:
boolean
Default value:
false
Description:
Also send an event for each page call that has a name — page("Signup") becomes Viewed Signup Page.
source_name
Type:
string
Description:
Value sent as rudderstack_source_name with every event, page, and screen call.
Notes:
{{ path || fallback }} template.session_replay_percentage
Type:
object
Description:
Percentage of SDK initializations that qualify for session replay, sent to Mixpanel as record_sessions_percent. When unset, no sessions are recorded.
Notes:
web, the only source type it applies to.0 to 100, written as a string — "20", not 20. A template is accepted.session_replay_percentage:
web: "20"ignore_dnt
Type:
boolean
Default value:
false
Description: Have Mixpanel’s SDK ignore the browser’s Do Not Track setting.
cross_subdomain_cookie
Type:
boolean
Default value:
false
Description: Persist the Mixpanel cookie across subdomains of your site.
persistence_type
Type:
string
Default value:
cookie
Description: Where Mixpanel’s SDK persists its state.
Notes:
none, cookie, or localStorage. With localStorage, an existing Mixpanel cookie of the same name is moved into local storage.persistence_name
Type:
string
Description: Suffix added to the Mixpanel cookie name.
Notes:
{{ path || fallback }} template.secure_cookie
Type:
boolean
Default value:
false
Description: Mark the Mixpanel cookie as secure, so it’s sent only over HTTPS.
Client-side event filtering is applied by the RudderStack SDK, so it affects only web sources connected indevicemode. Events sent incloudmode aren’t filtered by it.
event_filtering
Type:
object
Description:
Restricts which track events the SDK passes to Mixpanel, by event name.
Notes:
whitelist — array of event names to allow; every other track event is dropped.blacklist — array of event names to drop; every other track event is allowed.{{ path || fallback }} template.Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.
connection_mode
Type:
object
Description: Maps each source type you connect to the mode its events reach Mixpanel in, using the modes in Source types.
Notes:
device for android.connection_mode:
web: device
cloud: cloudconsent_management
Type:
object
Description:
Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.
Mixpanel accepts events from these source types in the mentioned connection modes:
| Source type | Connection mode |
|---|---|
android |
cloud |
android_kotlin |
cloud |
ios |
cloud |
ios_swift |
cloud |
web |
cloud, device |
unity |
cloud |
cloud |
cloud |
react_native |
cloud |
flutter |
cloud |
cordova |
cloud |
Only web offers device mode, which loads Mixpanel’s SDK in the browser. In cloud mode Mixpanel accepts alias, group, identify, page, screen, and track; in device mode, web sources send alias, group, identify, page, and track. See Mixpanel device mode.
The dashboard additionally offers Mixpanel to AMP, Shopify, and Reverse ETL sources. Rudder CLI doesn’t manage those connections, soamp,shopify, andwarehouseare invalid here.
An event stream connection to this destination is checked against two rules at validate time.
The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. An unsupported type reports:
destination 'mixpanel-prod' (type 'mp') does not support source 'my-source':
source type 'amp' is not among supported source types: android, android_kotlin, ...The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:
destination 'mixpanel-prod' config has no 'connection_mode' entry for source type 'web'Mixpanel needs no additional config keys to connect a source of any type, in any mode.
Rudder CLI treats four keys as secrets: token, gdpr_api_token, service_account_user_name, and service_account_secret. Write each one you use as a {{ .VAR }} reference and supply the value at apply time:
config:
token: "{{ .MIXPANEL_TOKEN }}"
gdpr_api_token: "{{ .MIXPANEL_GDPR_TOKEN }}"export RUDDER_MIXPANEL_TOKEN="..."
rudder-cli apply
# or
rudder-cli apply --var-file secrets.vars.yamlNote that:
rudder-cli import writes may or may not include secret keys. Before you apply, make sure every secret key your configuration needs is present and populated through variable substitution.See How to Use Variable Substitution in Rudder CLI.