Attribution/web analytics updates

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 changes

Example:

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.

Minification fix for UTM campaign properties

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.

Configurable API endpoints, miscellaneous updates and fixes

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:

• Event properties object passed to mixpanel.track() will no longer be mutated
• Super properties are now reloaded from persistence when making every tracking call (i.e., kept fresh when another tab/window in the same browser has updated them)
• Extra failsafe behavior for trying to clear queued requests when localStorage doesn't work on startup, e.g., when localStorage is full so writes fail
• Block Chrome-Lighthouse user agent
• Fix for error in add_group() when adding a new group to an existing list

Marketing analytics improvements

New 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:

• UUID generation now uses performance.now() when available as part of its time-based entropy algorithm
• The network payload format now defaults to JSON for any API host containing the string mixpanel.com (looser than previous host checks)

Identity management updates

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.

In-app notifications removal, configurable error-reporting

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:

• The SDK no longer makes network calls to the /decide API endpoint.
• The gzipped size of the minified full SDK is now 17435 bytes.

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:

• Several var declarations were missing for the asynchronous HTML "snippet" loader (#215)
• Some edge cases of the batch/retry system have been fixed that could cause many extraneous network requests (primarily in cases where localStorage becomes unusable after an event has already been queued).

Support for non-base64 request payloads

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'}.

Batch/retry system updates

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:

• Requests blocked on the client side (e.g., via an adblocker) are no longer retried.
• 429 (rate-limited) responses from the API are retried with backoff (in batch mode)
• The deprecated 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.

Autrotrack removal

Code supporting the now-defunct Autotrack feature has now been removed. Support was already previously dropped in Mixpanel's APIs.

Updates to crawler list and implementation logging

• more crawlers/bots are blocked (e.g., Pinterest, FB, more Google crawlers)
• debug-mode logging has been added when the browser's Do Not Track or individual opt-out settings are preventing tracking calls
• a more explicit error message is logged when the script tag embed code ("snippet") is included more than once on a page