Mixpanel

The Mixpanel add-on brings everything Mixpanel to Analytics Core: the browser SDK and its event handler, server delivery through the Import API, the consent-aware identity the server route needs, and optional User Profiles synchronization. Core carries none of it. These features share Analytics → Settings → Mixpanel, a page the add-on registers.

Configure Mixpanel

1. Enter the Project Token and choose the project's Data Residency Region: United States, European Union, or India.
2. Leave Send events from the browser on to use browser delivery. Its event toggles default to enabled.
3. For server delivery, activate the Mixpanel add-on, enable Send selected events with the Mixpanel Import API, then enable the server events you need. The server switch and individual server events default to off.
4. Save, send a test event from Tools, and verify the event in Mixpanel.

The project token is part of browser configuration. It is not a private service-account credential. The chosen region determines the fixed ingestion host for both routes; select the region containing your project.

Disable Mixpanel Analytics pauses the integration. A channel with every event disabled contributes no active event route.

What this add-on adds

• A private Mixpanel browser SDK instance with autocapture, marketing attribution and session recording off, plus the mixpanelBrowser event handler when browser sending is on.
• The mixpanelImportAPI server route, with the transport that supplies mixpanel_consent, mixpanel_distinct_id and mixpanel_device_id on the events that route wants. Only this transport can set them; markup and the public capture call cannot, and a withdrawal between capture and delivery leaves the posted copy anonymous.
• Server-side validation of those three properties: consent only on an explicit true, and an identifier only when it is exactly what the SDK produced. Both identifiers are removed when the visitor denies statistics consent.
• The reserved custom-event name enabled, which would collide with its channel switches.
• window.xpacMixpanelBridge for Mixpanel's own consent gate. Its test tool takes no input and shows no links.

Consent and identity

Mixpanel follows the shared statistics category when Analytics consent is enabled: the add-on listens for Analytics' consent changes and opts its SDK in or out to match. Its own Require consent before tracking control adds a Mixpanel-only gate, which your code opens or closes through the bridge the add-on ships:

window.xpacMixpanelBridge.setConsent(true);

That call changes Mixpanel alone. To change the shared category for every destination, call window.xpADL.setConsent({ statistics: false }) instead; a marketing-only change never grants Mixpanel. Events captured before approval are skipped instead of retained for later delivery.

Browser and Import events share the device/distinct identifier, event name, timestamp, and insert ID. Server delivery requires browser-approved identity; enabling the Import route does not bypass consent. The SDK can initialize even with browser event sending off so that the server route has a matching consent-aware identity.

The optional Identify signed-in users after consent setting enables the supported account-ID path on browser and Import routes. The browser SDK identifies the permitted account and includes $user_id; the server derives that ID from the current authenticated WordPress account. Withdrawal opts out and clears browser persistence. Imported device IDs remain provider-owned and cannot be replaced by arbitrary capture properties.

Withdrawing consent also discards the SDK's in-memory device association. A later grant creates a new anonymous device identity before applying any currently permitted account identification. The bridge's opt-in cannot restore persistence while the shared statistics category or the browser's Do Not Track setting still prevents tracking.

An anonymous-to-account transition preserves the device association. A later logout or switch to a different account resets the previous identity. With browser event sending off, this local identity setup does not send the SDK's automatic $identify event.

Synchronize WordPress user profiles

Identifying an account links its events. Mixpanel's User Profiles API separately stores properties shown in its Users view. To enable that feature:

1. Activate the Mixpanel add-on alongside the current Analytics Core and configure the project token and region.
2. In Analytics → Settings → Privacy, enable Identify signed-in users after consent.
3. In Mixpanel, enable Synchronize signed-in users to Mixpanel User Profiles.
4. Select any optional account properties you want to share. Every property toggle starts off.
5. Visit a tracked page while signed in, with statistics and Mixpanel consent permitted. Check that user's WordPress ID in Mixpanel's Users view.

With synchronization enabled and optional fields off, only the account ID is sent. XPAC takes account properties from the authenticated WordPress user, not capture properties supplied by a browser. Names are limited to 255 UTF-8 bytes; roles are a sorted list. The registration date describes the WordPress account, not the date Mixpanel first created its profile.

The first permitted page_view triggers the update. Import API event sending can remain off: a profile-only route does not import a page-view event. Both the shared statistics decision and Mixpanel's consent decision must permit synchronization; anonymous users and excluded roles do not synchronize. An earlier view captured before consent is not replayed, so another page view is needed after permission.

An unchanged profile updates at most once per day. Changed properties, a changed project, or a failed request can retry on a later permitted page view after a one-minute cooldown. XPAC stores only a profile hash and attempt timestamps in user metadata to enforce those bounds. There is no background account import, and saving a profile in WordPress does not immediately send it to Mixpanel.

Profile requests use the project's regional /engage endpoint with IP geolocation disabled and without changing Mixpanel's profile update time. Disabling an optional field or uninstalling XPAC removes no previously stored Mixpanel data. Review or erase existing remote profiles in Mixpanel; automatic remote erasure, group profiles and session replay are not implemented.

Geolocation and duplicate routes

Use visitor IP for browser-event geolocation defaults to off. Import events use ip=0. If geolocation is enabled and the browser route carries an event, XPAC suppresses that event's server copy so a later import cannot replace the browser-enriched event. When geolocation is off, both selected routes can carry the shared deduplication keys.

Verification and limits

The Import API uses strict validation. XPAC distinguishes an accepted event, a provider rejection and a transport failure. Tools → Send test event uses a generated identity and ip=0; it sends a real test event to the configured project. The tool takes no input, and wp xpac analytics test-event mixpanelimportapi takes no options. It does not send a user-profile update. Verify profile synchronization separately using a permitted signed-in page view and the Users view.

Trusted PHP integrations can enrich Import properties with the payload filter. The final event is checked before sending: strings must be valid UTF-8, numeric values must be finite, each property object or list must contain fewer than 255 entries, nesting is limited to three levels, and an event must be smaller than 1 MiB. Invalid enrichment appears as a payload failure in delivery diagnostics. The filter cannot replace event names, identity, timestamps, insert IDs, or routing credentials.

Imports run at shutdown with bounded timeouts and no durable retry. If your server cannot release the visitor before shutdown, default dispatch is nonblocking and cannot confirm acceptance. Tools keeps the most recent delivery failure; Mixpanel's event view confirms arrival.

Profiles follow the same bounded shutdown delivery policy. Strict validation must confirm one accepted profile with no record errors, even when HTTP returns 200. An accepted request still does not prove the profile appears in the intended project, and a nonblocking request is reported as queued. Unconfirmed queued profile updates also receive the daily bound. See Mixpanel's Profile Set API and User Profiles guide.

See the Analytics developer guide and generated Mixpanel hooks for payload customization.