mixpanel-browser 2.71.1 → 2.73.0

package/.github/workflows/tests.yml

@@ -22,3 +22,4 @@ jobs:
           node-version: ${{ matrix.node-version }}
       - run: npm ci
       - run: npm test
+      - run: npm run build-dist

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+**2.73.0** (23 Dec 2025)
+- Adds several new hooks: `before_identify`, `before_register`, `before_register_once`, `before_track`, `before_unregister`
+- Adds instance-initialization notification to allow Data Inspector browser extension to hook into SDK actions
+- Fixes and extends type definitions
+
+**2.72.0** (14 Nov 2025)
+- Adds Autocapture rage-click configuration option `interactive_elements_only`, to ignore clicks on non-interactive page elements such as text. Configure with: `mixpanel.init('<TOKEN>', {autocapture: {rage_click: {interactive_elements_only: true}}})`
+- Adds TypeScript types for Feature Flags subsystem (`mixpanel.flags`)
+- Adds JS console data to Session Recordings, enabled by default but configurable via the `record_console` initialization option.
+- Fixes an issue in session recording where closing and opening a page would upload a replay shorter than the configured minimum duration (`record_min_ms`)
+- Fixes an issue in session recording where payloads get truncated on old Safari versions due to a bug in their CompressionStream implementation
+
 **2.71.1** (30 Oct 2025)
 - fixes issue with $mp_page_leave events getting tracked when `record_heatmap_data` is on and there was no session recording taking place.
 

package/dist/mixpanel-core.cjs.d.ts

@@ -2,7 +2,7 @@ export type Persistence = "cookie" | "localStorage";
 
 export type ApiPayloadFormat = "base64" | "json";
 
-export type PushItem = Array<string | Dict>;
+export type PushItem = Array<string | Dict | ((this: Mixpanel) => void)>;
 
 export type Query = string | Element | Element[];
 
@@ -43,20 +43,22 @@ export interface OutTrackingOptions extends ClearOptOutInOutOptions {
 export type RageClickConfig =
   | boolean
   | {
-    /** Distance threshold in pixels for clicks to be considered within the same area (default: 30) */
-    threshold_px?: number;
-    /** Time window in milliseconds for clicks to be considered rapid (default: 1000) */
-    timeout_ms?: number;
-    /** Number of clicks required to trigger a rage click event (default: 3) */
-    click_count?: number;
-  };
+      /** Distance threshold in pixels for clicks to be considered within the same area (default: 30) */
+      threshold_px?: number;
+      /** Time window in milliseconds for clicks to be considered rapid (default: 1000) */
+      timeout_ms?: number;
+      /** Number of clicks required to trigger a rage click event (default: 3) */
+      click_count?: number;
+      /** Whether to only track rage clicks on interactive elements like buttons, links, inputs (default: false) */
+      interactive_elements_only?: boolean;
+    };
 
 export type DeadClickConfig =
   | boolean
   | {
-    /** Time in milliseconds to wait after a click before qualifying it as dead (default: 500) */
-    timeout_ms?: number;
-  };
+      /** Time in milliseconds to wait after a click before qualifying it as dead (default: 500) */
+      timeout_ms?: number;
+    };
 
 export interface RegisterOptions {
   persistent: boolean;
@@ -149,6 +151,15 @@ export interface AutocaptureConfig {
   block_element_callback?: (element: Element, event: Event) => boolean;
 }
 
+export interface FlagsConfig {
+  context: Dict;
+}
+
+export interface BeforeSendHookPayload {
+  event: string;
+  properties: Record<string, any>;
+}
+
 export interface Config {
   api_host: string;
   api_routes: {
@@ -161,10 +172,14 @@ export interface Config {
   app_host: string;
   api_payload_format: ApiPayloadFormat;
   autotrack: boolean;
+  batch_autostart: boolean;
+  batch_requests: boolean;
   cdn: string;
   cookie_domain: string;
   cross_site_cookie: boolean;
   cross_subdomain_cookie: boolean;
+  error_reporter: (msg: string, err?: Error) => void;
+  flags: boolean | FlagsConfig;
   persistence: Persistence;
   persistence_name: string;
   cookie_name: string;
@@ -200,10 +215,10 @@ export interface Config {
   inapp_protocol: string;
   inapp_link_new_window: boolean;
   ignore_dnt: boolean;
-  batch_requests: boolean;
   batch_size: number;
   batch_flush_interval_ms: number;
   batch_request_timeout_ms: number;
+  recorder_src: string;
   record_block_class: string | RegExp;
   record_block_selector: string;
   record_collect_fonts: boolean;
@@ -216,6 +231,29 @@ export interface Config {
   record_sessions_percent: number;
   record_canvas: boolean;
   record_heatmap_data: boolean;
+  hooks: {
+    before_identify?: (new_distinct_id: string) => string | null;
+    before_register?: (
+      props: Dict,
+      days_or_options?: number | Partial<RegisterOptions>
+    ) => Dict | Array<Dict | number | Partial<RegisterOptions>> | null;
+    before_register_once?: (
+      props: Dict,
+      default_value?: any,
+      days_or_options?: number | Partial<RegisterOptions>
+    ) => Dict | Array<any | Dict | number | Partial<RegisterOptions>> | null;
+    before_send_events?: (
+      event: BeforeSendHookPayload
+    ) => BeforeSendHookPayload | null;
+    before_track?: (
+      event_name: string,
+      properties: Dict
+    ) => string | Array<string | Dict> | null;
+    before_unregister?: (
+      property: string,
+      options?: Partial<RegisterOptions>
+    ) => string | Partial<RegisterOptions> | null;
+  };
 }
 
 export type VerboseResponse =
@@ -277,19 +315,50 @@ export interface Group {
   unset(prop: string, callback?: Callback): void;
 }
 
+export interface FlagsVariant {
+  key: string;
+  value: any;
+  experiment_id?: string;
+  is_experiment_active?: boolean;
+  is_qa_tester?: boolean;
+}
+
+export interface FlagsUpdateContextOptions {
+  replace?: boolean;
+}
+
+export interface FlagsManager {
+  are_flags_ready(): boolean;
+  get_variant(
+    featureName: string,
+    fallback: FlagsVariant
+  ): Promise<FlagsVariant>;
+  get_variant_sync(featureName: string, fallback: FlagsVariant): FlagsVariant;
+  get_variant_value(featureName: string, fallbackValue: any): Promise<any>;
+  get_variant_value_sync(featureName: string, fallbackValue: any): any;
+  is_enabled(featureName: string, fallbackValue?: boolean): Promise<boolean>;
+  is_enabled_sync(featureName: string, fallbackValue?: boolean): boolean;
+  update_context(
+    context: Dict,
+    options?: FlagsUpdateContextOptions
+  ): Promise<void>;
+}
+
 export interface Mixpanel {
   add_group(group_key: string, group_id: string, callback?: Callback): void;
   alias(alias: string, original?: string): void;
   clear_opt_in_out_tracking(options?: Partial<ClearOptOutInOutOptions>): void;
   disable(events?: string[]): void;
+  flags: FlagsManager;
   get_config(prop_name?: string): any;
   get_distinct_id(): any;
   get_group(group_key: string, group_id: string): Group;
   get_property(property_name: string): any;
+  get_session_replay_url(): string;
   has_opted_in_tracking(options?: Partial<HasOptedInOutOptions>): boolean;
   has_opted_out_tracking(options?: Partial<HasOptedInOutOptions>): boolean;
   identify(unique_id?: string): any;
-  init(token: string, config: Partial<Config>, name: string): Mixpanel;
+  init(token: string, config: Partial<Config>, name?: string): Mixpanel;
   opt_in_tracking(options?: Partial<InTrackingOptions>): void;
   opt_out_tracking(options?: Partial<OutTrackingOptions>): void;
   push(item: PushItem): void;
@@ -314,6 +383,7 @@ export interface Mixpanel {
     group_ids: string | string[] | number | number[],
     callback?: Callback
   ): void;
+  start_batch_senders(): void;
   time_event(event_name: string): void;
   track(
     event_name: string,
@@ -343,6 +413,7 @@ export interface Mixpanel {
   ): void;
   unregister(property: string, options?: Partial<RegisterOptions>): void;
   people: People;
+  start_batch_senders(): void;
   start_session_recording(): void;
   stop_session_recording(): void;
   get_session_recording_properties(): { $mp_replay_id?: string } | {};

package/dist/mixpanel-core.cjs.js

@@ -2,7 +2,7 @@
 
 var Config = {
     DEBUG: false,
-    LIB_VERSION: '2.71.1'
+    LIB_VERSION: '2.73.0'
 };
 
 // since es6 imports are static and we run unit tests from the console, window won't be defined when importing this file
@@ -22,7 +22,9 @@ if (typeof(window) === 'undefined') {
         screen: { width: 0, height: 0 },
         location: loc,
         addEventListener: function() {},
-        removeEventListener: function() {}
+        removeEventListener: function() {},
+        dispatchEvent: function() {},
+        CustomEvent: function () {}
     };
 } else {
     win = window;
@@ -2892,20 +2894,65 @@ function isDefinitelyNonInteractive(element) {
     return false;
 }
 
+/**
+ * Get the composed path of a click event for elements embedded in shadow DOM.
+ * @param {Event} event - event to get the composed path from
+ * @returns {Array} the composed path of the click event
+*/
+function getClickEventComposedPath(event) {
+    if ('composedPath' in event) {
+        return event['composedPath']();
+    }
+
+    return [];
+}
+
+/**
+ * Get the element from a click event, accounting for elements embedded in shadow DOM.
+ * @param {Event} event - event to get the target from
+ * @returns {Element | null} the element that was the target of the click event
+ */
+function getClickEventTargetElement(event) {
+    var path = getClickEventComposedPath(event);
+
+    if (path && path.length > 0) {
+        return path[0];
+    }
+
+    return event['target'] || event['srcElement'];
+}
+
 /** @const */ var DEFAULT_RAGE_CLICK_THRESHOLD_PX = 30;
 /** @const */ var DEFAULT_RAGE_CLICK_TIMEOUT_MS = 1000;
 /** @const */ var DEFAULT_RAGE_CLICK_CLICK_COUNT = 4;
+/** @const */ var DEFAULT_RAGE_CLICK_INTERACTIVE_ELEMENTS_ONLY = false;
 
 function RageClickTracker() {
     this.clicks = [];
 }
 
-RageClickTracker.prototype.isRageClick = function(x, y, options) {
+/**
+ * Determines if a click event is part of a rage click sequence.
+ * @param {Event} event - the original click event.
+ * @param {import('../index.d.ts').RageClickConfig} options - configuration options for rage click detection.
+ * @returns {boolean} - true if the click is considered a rage click, false otherwise.
+ */
+RageClickTracker.prototype.isRageClick = function(event, options) {
     options = options || {};
     var thresholdPx = options['threshold_px'] || DEFAULT_RAGE_CLICK_THRESHOLD_PX;
     var timeoutMs = options['timeout_ms'] || DEFAULT_RAGE_CLICK_TIMEOUT_MS;
     var clickCount = options['click_count'] || DEFAULT_RAGE_CLICK_CLICK_COUNT;
+    var interactiveElementsOnly = options['interactive_elements_only'] || DEFAULT_RAGE_CLICK_INTERACTIVE_ELEMENTS_ONLY;
+
+    if (interactiveElementsOnly) {
+        var target = getClickEventTargetElement(event);
+        if (!target || isDefinitelyNonInteractive(target)) {
+            return false;
+        }
+    }
+
     var timestamp = Date.now();
+    var x = event['pageX'], y = event['pageY'];
 
     var lastClick = this.clicks[this.clicks.length - 1];
     if (
@@ -2936,28 +2983,16 @@ ShadowDOMObserver.prototype.getEventTarget = function(event) {
     if (!this.observedShadowRoots) {
         return;
     }
-    var path = this.getComposedPath(event);
-    if (path && path.length) {
-        return path[0];
-    }
 
-    return event['target'] || event['srcElement'];
+    return getClickEventTargetElement(event);
 };
 
-
-ShadowDOMObserver.prototype.getComposedPath = function(event) {
-    if ('composedPath' in event) {
-        return event['composedPath']();
-    }
-
-    return [];
-};
 ShadowDOMObserver.prototype.observeFromEvent = function(event) {
     if (!this.observedShadowRoots) {
         return;
     }
 
-    var path = this.getComposedPath(event);
+    var path = getClickEventComposedPath(event);
 
     // Check each element in path for shadow roots
     for (var i = 0; i < path.length; i++) {
@@ -3709,7 +3744,7 @@ Autocapture.prototype.initRageClickTracking = function() {
             return;
         }
 
-        if (this._rageClickTracker.isRageClick(ev['pageX'], ev['pageY'], currentRageClickConfig)) {
+        if (this._rageClickTracker.isRageClick(ev, currentRageClickConfig)) {
             this.trackDomEvent(ev, MP_EV_RAGE_CLICK);
         }
     }.bind(this);
@@ -6802,8 +6837,6 @@ var mixpanel_master; // main mixpanel instance / object
 var INIT_MODULE  = 0;
 var INIT_SNIPPET = 1;
 
-var IDENTITY_FUNC = function(x) {return x;};
-
 /** @const */ var PRIMARY_INSTANCE_NAME = 'mixpanel';
 /** @const */ var PAYLOAD_TYPE_BASE64   = 'base64';
 /** @const */ var PAYLOAD_TYPE_JSON     = 'json';
@@ -6897,6 +6930,7 @@ var DEFAULT_CONFIG = {
     'record_block_selector':             'img, video, audio',
     'record_canvas':                     false,
     'record_collect_fonts':              false,
+    'record_console':                    true,
     'record_heatmap_data':               false,
     'record_idle_timeout_ms':            30 * 60 * 1000, // 30 minutes
     'record_mask_text_class':            new RegExp('^(mp-mask|fs-mask|amp-mask|rr-mask|ph-mask)$'),
@@ -6968,6 +7002,17 @@ var create_mplib = function(token, config, name) {
     // global debug to be true
     Config.DEBUG = Config.DEBUG || instance.get_config('debug');
 
+    var source = init_type === INIT_MODULE ? 'module' : 'snippet';
+    win.dispatchEvent(new win.CustomEvent('$mp_sdk_to_extension_event', {
+        'detail': {
+            'instance': instance,
+            'source': source,
+            'token': token,
+            'name': name,
+            'info': _.info
+        }
+    }));
+
     // if target is not defined, we called init after the lib already
     // loaded, so there won't be an array of things to execute
     if (!_.isUndefined(target) && _.isArray(target)) {
@@ -7038,6 +7083,8 @@ MixpanelLib.prototype._init = function(token, config, name) {
         }
     }
 
+    this.hooks = {};
+
     this.set_config(_.extend({}, DEFAULT_CONFIG, variable_features, config, {
         'name': name,
         'token': token,
@@ -7638,7 +7685,12 @@ MixpanelLib.prototype.init_batchers = function() {
                         );
                     }, this),
                     beforeSendHook: _.bind(function(item) {
-                        return this._run_hook('before_send_' + attrs.type, item);
+                        var ret = this._run_hook('before_send_' + attrs.type, item);
+                        if (ret) {
+                            return ret[0];
+                        } else {
+                            return null;
+                        }
                     }, this),
                     stopAllBatchingFunc: _.bind(this.stop_batch_senders, this),
                     usePersistence: true,
@@ -7731,6 +7783,9 @@ MixpanelLib.prototype._track_or_batch = function(options, callback) {
     var send_request_immediately = _.bind(function() {
         if (!send_request_options.skip_hooks) {
             truncated_data = this._run_hook('before_send_' + options.type, truncated_data);
+            if (truncated_data) {
+                truncated_data = truncated_data[0];
+            }
         }
         if (truncated_data) {
             console.log('MIXPANEL REQUEST:');
@@ -7785,6 +7840,17 @@ MixpanelLib.prototype._track_or_batch = function(options, callback) {
  * with the tracking payload sent to the API server is returned; otherwise false.
  */
 MixpanelLib.prototype.track = addOptOutCheckMixpanelLib(function(event_name, properties, options, callback) {
+    var ret;
+    if (!(options && options.skip_hooks)) {
+        ret = this._run_hook('before_track', event_name, properties);
+        if (ret === null) {
+            return;
+        } else {
+            event_name = ret[0];
+            properties = ret[1];
+        }
+    }
+
     if (!callback && typeof options === 'function') {
         callback = options;
         options = null;
@@ -7854,7 +7920,7 @@ MixpanelLib.prototype.track = addOptOutCheckMixpanelLib(function(event_name, pro
         'event': event_name,
         'properties': properties
     };
-    var ret = this._track_or_batch({
+    ret = this._track_or_batch({
         type: 'events',
         data: data,
         endpoint: this.get_api_host('events') + '/' + this.get_config('api_routes')['track'],
@@ -8200,6 +8266,14 @@ var options_for_register = function(days_or_options) {
  * @param {boolean} [days_or_options.persistent=true] - whether to put in persistent storage (cookie/localStorage)
  */
 MixpanelLib.prototype.register = function(props, days_or_options) {
+    var ret = this._run_hook('before_register', props, days_or_options);
+    if (ret === null) {
+        return;
+    } else {
+        props = ret[0];
+        days_or_options = ret[1];
+    }
+
     var options = options_for_register(days_or_options);
     if (options['persistent']) {
         this['persistence'].register(props, options['days']);
@@ -8236,6 +8310,15 @@ MixpanelLib.prototype.register = function(props, days_or_options) {
  * @param {boolean} [days_or_options.persistent=true] - whether to put in persistent storage (cookie/localStorage)
  */
 MixpanelLib.prototype.register_once = function(props, default_value, days_or_options) {
+    var ret = this._run_hook('before_register_once', props, default_value, days_or_options);
+    if (ret === null) {
+        return;
+    } else {
+        props = ret[0];
+        default_value = ret[1];
+        days_or_options = ret[2];
+    }
+
     var options = options_for_register(days_or_options);
     if (options['persistent']) {
         this['persistence'].register_once(props, default_value, options['days']);
@@ -8259,6 +8342,14 @@ MixpanelLib.prototype.register_once = function(props, default_value, days_or_opt
  * @param {boolean} [options.persistent=true] - whether to look in persistent storage (cookie/localStorage)
  */
 MixpanelLib.prototype.unregister = function(property, options) {
+    var ret = this._run_hook('before_unregister', property, options);
+    if (ret === null) {
+        return;
+    } else {
+        property = ret[0];
+        options = ret[1];
+    }
+
     options = options_for_register(options);
     if (options['persistent']) {
         this['persistence'].unregister(property);
@@ -8307,6 +8398,13 @@ MixpanelLib.prototype.identify = function(
     //  _set_once_callback:function  A callback to be run if and when the People set_once queue is flushed
     //  _union_callback:function  A callback to be run if and when the People union queue is flushed
     //  _unset_callback:function  A callback to be run if and when the People unset queue is flushed
+    var ret = this._run_hook('before_identify', new_distinct_id);
+
+    if (ret === null) {
+        return -1;
+    } else {
+        new_distinct_id = ret[0];
+    }
 
     var previous_distinct_id = this.get_distinct_id();
     if (new_distinct_id && previous_distinct_id !== new_distinct_id) {
@@ -8631,6 +8729,25 @@ MixpanelLib.prototype.set_config = function(config) {
         if (('autocapture' in config || 'record_heatmap_data' in config) && this.autocapture) {
             this.autocapture.init();
         }
+
+        if (_.isObject(config['hooks'])) {
+            this.hooks = {};
+            _.each(config['hooks'], function(hook_value, hook_name) {
+                if (_.isFunction(hook_value)) {
+                    this.hooks[hook_name] = [hook_value];
+                } else if (_.isArray(hook_value)) {
+                    this.hooks[hook_name] = [];
+                    for (var i = 0; i < hook_value.length; i++) {
+                        if (!_.isFunction(hook_value[i])) {
+                            console.critical('Invalid hook added. Hook is not a function');
+                        }
+                        this.hooks[hook_name].push(hook_value[i]);
+                    }
+                } else {
+                    console.critical('Invalid hooks added. Ensure that the hook values passed into config.hooks are functions or arrays of functions.');
+                }
+            }, this);
+        }
     }
 };
 
@@ -8648,12 +8765,26 @@ MixpanelLib.prototype.get_config = function(prop_name) {
  * @returns {any|null} return value of user-provided hook, or null if nothing was returned
  */
 MixpanelLib.prototype._run_hook = function(hook_name) {
-    var ret = (this['config']['hooks'][hook_name] || IDENTITY_FUNC).apply(this, slice.call(arguments, 1));
-    if (typeof ret === 'undefined') {
-        this.report_error(hook_name + ' hook did not return a value');
-        ret = null;
-    }
-    return ret;
+    var hook_data = slice.call(arguments, 1);
+    _.each(this.hooks[hook_name], function(hook) {
+        if (hook_data === null) {
+            return null;
+        }
+
+        var ret = hook.apply(this, hook_data);
+
+        if (typeof ret === 'undefined') {
+            this.report_error(hook_name + ' hook did not return a valid value');
+            hook_data = null;
+        } else {
+            if (!_.isArray(ret)) {
+                ret = [ret];
+            }
+            hook_data.splice.apply(hook_data, [0, ret.length].concat(ret));
+        }
+    }, this);
+
+    return hook_data;
 };
 
 /**
@@ -8964,6 +9095,25 @@ MixpanelLib.prototype.report_error = function(msg, err) {
     }
 };
 
+MixpanelLib.prototype.add_hook = function(hook_name, hook_fn) {
+    if (!this.hooks[hook_name]) {
+        this.hooks[hook_name] = [];
+    }
+    this.hooks[hook_name].push(hook_fn);
+};
+
+MixpanelLib.prototype.remove_hook = function(hook_name, hook_fn) {
+    var fn_index;
+    if (this.hooks[hook_name]) {
+        fn_index = this.hooks[hook_name].indexOf(hook_fn);
+        if (fn_index !== -1) {
+            this.hooks[hook_name].splice(fn_index, 1);
+        } else {
+            console.log('remove_hook failed. Matching hook was not found');
+        }
+    }
+};
+
 // EXPORTS (for closure compiler)
 
 // MixpanelLib Exports
@@ -8996,6 +9146,8 @@ MixpanelLib.prototype['get_group']                          = MixpanelLib.protot
 MixpanelLib.prototype['set_group']                          = MixpanelLib.prototype.set_group;
 MixpanelLib.prototype['add_group']                          = MixpanelLib.prototype.add_group;
 MixpanelLib.prototype['remove_group']                       = MixpanelLib.prototype.remove_group;
+MixpanelLib.prototype['add_hook']                           = MixpanelLib.prototype.add_hook;
+MixpanelLib.prototype['remove_hook']                        = MixpanelLib.prototype.remove_hook;
 MixpanelLib.prototype['track_with_groups']                  = MixpanelLib.prototype.track_with_groups;
 MixpanelLib.prototype['start_batch_senders']                = MixpanelLib.prototype.start_batch_senders;
 MixpanelLib.prototype['stop_batch_senders']                 = MixpanelLib.prototype.stop_batch_senders;