Official Mixpanel JavaScript Client Library
This release updates capabilities related to web/marketing/attribution analytics.
The track_pageview
init option now accepts three string values to support SPA pageview tracking:
"url-with-path"
: fire pageview events only when main url path changes (https://example.com/foo
-> https://example.com/bar
but not https://example.com/foo?bar=1
-> https://example.com/foo?bar=2
)"url-with-path-and-query-string"
: fire pageview events only when main url path or query string changes (https://example.com/foo?bar=1
-> https://example.com/foo?bar=2
but not https://example.com/foo?bar=1#baz
-> https://example.com/foo?bar=1#qux
)"full-url"
: fire pageview events when anything on the URL changesExample:
mixpanel.init(`my token`, {track_pageview: `url-with-path-and-query-string`});
Profile properties storing referrer info ($initial_referrer
and $initial_referring_domain
) are now saved with set_once
instead of set
, to prevent overwriting.
Persistence of UTM parameters can now be turned off with the init option {stop_utm_persistence: true}
. This is opt-in today but will be the default setting in a future release. The stop_utm_persistence
option will also override the store_google
option, which is responsible persisting UTM parameters today. If store_google
and stop_utm_persistence
are both true
, any persisted UTM parameters will be cleared from storage.
Visits from AhrefsSiteAudit crawler are now ignored.
This update patches a discrepancy between the minified and unminified versions of the packaged SDK. Campaign parameters will now be stored as super properties persistently in all versions.
API endpoint routes can now be configured individually, so you can rename /track, /engage, and /groups HTTP endpoints arbitrarily. Configure with the api_routes
option:
mixpanel.init(`my token`, {
api_host: `https://my-proxy.example.com`,
api_routes: {
track: `foo/`,
engage: `bar/`,
groups: `baz/`,
},
));
In the above example, event-tracking requests will go to https://my-proxy.example.com/foo/
, user profile updates to https://my-proxy.example.com/bar/
, etc.
Other fixes:
mixpanel.track()
will no longer be mutatedadd_group()
when adding a new group to an existing listNew default event properties are now captured with each event, holding campaign data present on the URL at the time of tracking. These include UTM parameters (in the format utm_source
, utm_campaign
, etc.) and Click Identifiers (e.g., gclid
, fbclid
, etc.). This functionality can be disabled with the initialization setting {track_marketing: false}
.
~UTM parameter properties are no longer persisted across pageloads as superproperties. They will be present only on events tracked on the same pageload where they were present initially.~ (2023-09-13) Correction: UTM parameter properties still persist across pageloads as superproperties. Persistence will be removed in a future release.
For better first-touch attribution, UTM parameters present on the URL on pageload will be "set once" as profile properties (meaning that a new value will not overwrite any existing value on the profile property). These property names take the format initial_utm_source
, initial_utm_campaign
, etc. This functionality can be disabled with the initialization setting {skip_first_touch_marketing: true}
.
Support for automatic page-view tracking has been restored. With the init option {track_pageview: true}
, an event named $mp_web_page_view
will be tracked on pageload, containing properties identifying the current page (current_page_title
, current_url_path
, etc.) as well as any UTM parameters and Click Identifiers. Pageview events with these properties can also be triggered manually:
// track a pageview event
mixpanel.track_pageview();
// track pageview with additional properties
mixpanel.track_pageview({'Test variant': 'control'});
Automatic page-view tracking may be turned on by default in a future release.
Miscellaneous updates:
performance.now()
when available as part of its time-based entropy algorithmmixpanel.com
(looser than previous host checks)The mixpanel.identify()
implementation has been updated for compatibility with Mixpanel's new identity management system (v3). From this version, we will prefix randomly-generated device-specific distinct_ids with "$device:". The prefix is applied the next time a new random ID is generated; any IDs generated by previous SDK versions and persisted in the browser will continue to be used as-is until reset is called to generate a new ID. This does not change the value sent for the $device_id
property, which will continue to be the randomly-generated ID without a prefix. Mixpanel's $identify endpoint has been updated to accept UUIDs with this prefix to coordinate with this change.
This release also contains more aggressive client-side deduplication in the event-batching system, to reduce superfluous network sends in edge cases where parts of the queue/batch system fail. Related to this update, events now include a property mp_sent_by_lib_version
which can distinguish the version of the library that actually sent an event over the network vs the version that originally queued the event.
All code relating to in-app notifications has been removed, as the "Messages & Experiments" product is now entirely inactive after a 1.5 year deprecation cycle. The only noticeable changes should be:
/decide
API endpoint.There is now also support for surfacing SDK errors/warnings via the error_reporter
configuration option. Exceptions and error messages which the SDK catches and handles will be passed to your handler function if supplied, e.g.:
mixpanel.init('my token', {
error_reporter: function(msg, err) {
Rollbar.warn(msg, err); // send to your 3rd-party error monitor
console.error(...arguments); // blow up your dev console locally
},
});
The err
argument is an Error
object preserving the stack. Note that errors that make it to the user-configured reporter are generally already handled by the SDK and should be used just for informational/debugging/monitoring purposes (e.g., "Error; retry in 10000 ms" is the batch/retry system responding to a network failure). Some errors are informative for uncovering implementation issues, e.g. "No event name provided to mixpanel.track".
Several fixes are included in this release:
var
declarations were missing for the asynchronous HTML "snippet" loader (https://github.com/mixpanel/mixpanel-js/issues/215)localStorage
becomes unusable after an event has already been queued).The new api_payload_format
configuration option controls whether request payloads are base64-encoded before sending (base64
option) or sent as plain JSON (json
option).
When the tracking server (api_host
) is Mixpanel's own API servers (*.mixpanel.com), this value now defaults to json
. This setting reduces payload size, simplifies inspection of request content with browser dev tools, and supports emoji content π₯ seamlessly:
mixpanel.track('Signed up π', {name: 'πΎπ»πΎπ»πΎ'});
For backwards compatibility with proxy server implementations, if api_host
is NOT a mixpanel.com server, then the default format remains base64. To force plain JSON encoding with a custom proxy host, initialize with option {api_payload_format: 'json'}
.
The batch_requests
configuration introduced in v2.36.0 is now on by default for all projects. To turn it off, initialize the SDK with the explicit option {batch_requests: false}
. Individual track()
calls can still bypass the queueing system with the flag {send_immediately: true}
.
In addition, this release contains several updates/fixes for send/retry behavior:
unload
event is no longer used to determine when to flush queues via sendBeacon on page close; this is now detected via the more modern alternatives visibilitychange
and pagehide
.Code supporting the now-defunct Autotrack feature has now been removed. Support was already previously dropped in Mixpanel's APIs.