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

Non-persistent superproperties, hooks for transforming data, delayed tracking

This release adds several new capabilities for finer control over (super)properties, event data, and batch sending.

A new persistent option to mixpanel.register() and mixpanel.register_once() allows control over whether to persist the given superproperties beyond the current pageload or not:

// include this prop only with events on the current page, i.e.
// don't put it in the superproperties cookie/localStorage entry
mixpanel.register({'Name': 'Pat'}, {persistent: false});

// default is still true; superproperties will be stored across pageloads
mixpanel.register_once({'Referrer to signup page': 'example.com'});

A new hooks capability supports transforming event data and profile updates just before they are sent over the network:

mixpanel.init('my token', {
  hooks: {
    before_send_events: eventData => {
      eventData.event = eventData.event.toUpperCase(); // normalize event name
      delete eventData.properties['bad prop']; // remove a (super)prop
      return eventData; // always return the new event data, even if you modified it in place like here
    },
  },
});

A new batch_autostart config option and start_batch_senders() method allow finer control over when to start sending batches over the network in request-batching mode. If the SDK is initialized with {batch_autostart: false}, tracked events will queue up without going over the network until mixpanel.start_batch_senders() is called explicitly. This is mainly useful for advanced use cases where you need to enrich events retroactively with data not yet available when mixpanel.track() was called (using a before-send hook).

Request-batching mode has been fixed for configurations that set sendBeacon as the default API transport instead of XHR. Note that since sendBeacon includes no facility for determining whether the request succeeded, there is no retry mechanism for failed requests in this configuration; as long as the browser says it enqueued the beacon call, the batch will be considered successfully sent.

Default-on request-batching has been expanded to 60% of projects.

Proxy-related fixes and batching rollout update

• Bodies of POST requests are now escaped to ensure that valid Base64 always gets sent to the APIs. This allows custom proxy servers to expect valid Base64 in every case (the mixpanel.com API servers already accepted and handled the technically invalid Base64 chars).
• batch_requests will not default to true if a non-mixpanel.com api_host is specified, to avoid silently regressing existing setups with proxies that don't support batches. Batching can always be forced on by explicitly setting batch_requests: true.
• Default-on request-batching has been expanded to 30% of projects.

UTM/referrer fixes

This update ensures that, even if a page does not track any events, the standard set of superproperties for UTM parameters and initial referrer are still persisted for use with later events. This behavior used to occur automatically due to tracking the mp_page_view event upon initialization, which was turned off by default in v2.37.0.

With this change, the deprecated track_pageview configuration option has no effect anymore and has been removed entirely.

Pageview and batch/retry updates

Automatic tracking of the mp_page_view event is now off by default. This event has been deprecated for years and is dropped by the Mixpanel API servers.

The batch_requests config option now defaults to true for a subset of projects, turning on batch/queue/retry support. To force this mode on or off explicitly, use the {batch_requests: true} option in mixpanel.init(). The default-on configuration will be gradually rolled out to all projects.