Misc fixes and updates

• Adds a minimum recording length option for session recording. For example, {record_min_ms: 4000} won't send any recordings that are less than 4 seconds long. The maximum value allowed is 8000.
• Added a fix for session recordings being sent with an empty start time.
• Fixes and improvements for request batcher to support offline queueing and retry.
• Fix for query param parsing/escaping (#443).
• Support for more UTM tags / click IDs (#442).

Module bundling and session recording updates

The SDK is now provided in several new builds with different options around included modules and asynchronous loading:

1. Core mixpanel build with bundled mixpanel-recorder session-recording module (default):

import mixpanel from 'mixpanel-browser';

2. Core mixpanel build that optionally loads mixpanel-recorder asynchronously via script tag (previous default):

import mixpanel from 'mixpanel-browser/src/loaders/loader-module-with-async-recorder';

3. Core mixpanel build only (no session recording available):

import mixpanel from 'mixpanel-browser/src/loaders/loader-module-core';

This release also includes updates and improvements to the session recording module:

• Improved reliability via integration with the main SDK's network batching/retry system
• Inactivity timeouts are now determined by user interaction events
• New configuration options enable inlining of images and fonts into recording payloads:

mixpanel.init(`my token`, {
  record_sessions_percent: 5,
  record_collect_fonts: true,
  record_inline_images: true,
});

NOTE: with image-inlining turned on, image-intensive pages may increase payload size significantly and possibly surpass the API server's request size limit.

Session recording updates

• Network payload format for session recording batches has changed, including client-side compression on browsers which support it
• Google Tag Manager wrapper now includes session-recording start/stop methods

Revert to persisting UTM params by default

This release reverts the UTM param persistence change introduced in v2.51.0, to minimize disruption for older implementations. UTM parameters will be persisted by default in super property storage when the SDK finds them on pageload. To opt in to the recommended modern behavior, use initialization option {stop_utm_persistence: true}.

Updates to UTM param persistence, localStorage/cookie migration, session recording

• UTM parameters are no longer persisted as superproperties by default. Mixpanel analyses now have attribution support that does not require client-side persistence of these properties. To opt in to the previous behavior, use initialization option {stop_utm_persistence: false}.
• localStorage->cookie migration support: when switching an implementation from localStorage persistence to cookie persistence (to support cross-subdomain tracking), the SDK will now automatically copy any existing superproperties from localStorage into the new superprop cookie. This migration behavior already existed in the opposite direction (going from cookie to localStorage).
• The initialization options record_block_class, record_block_selector, and record_mask_text_class offer finer-grained control over elements to block in session recording, and provide stricter defaults.
• New method mixpanel.get_session_recording_properties() exposes Replay ID property for tagging events controlled by other client-side SDKs such as Segment or mParticle.

Session recording support

v2.50.0

2.50.0

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)