mixpanel-browser 2.74.0 → 2.76.0

package/dist/mixpanel.globals.js

@@ -3,9 +3,17 @@
 
     var Config = {
         DEBUG: false,
-        LIB_VERSION: '2.74.0'
+        LIB_VERSION: '2.76.0'
     };
 
+    // Window global names for async modules
+    var TARGETING_GLOBAL_NAME = '__mp_targeting';
+    var RECORDER_GLOBAL_NAME = '__mp_recorder';
+
+    // Constants that are injected at build-time for the names of async modules.
+    var RECORDER_FILENAME = 'mixpanel-recorder-bIS4LMGd.js';
+    var TARGETING_FILENAME = 'mixpanel-targeting-BcAPS-Mz.js';
+
     // since es6 imports are static and we run unit tests from the console, window won't be defined when importing this file
     var win;
     if (typeof(window) === 'undefined') {
@@ -594,15 +602,8 @@
         return toString.call(obj) === '[object Array]';
     };
 
-    // from a comment on http://dbj.org/dbj/?p=286
-    // fails on only one very rare and deliberate custom object:
-    // var bomb = { toString : undefined, valueOf: function(o) { return "function BOMBA!"; }};
     _.isFunction = function(f) {
-        try {
-            return /^\s*\bfunction\b/.test(f);
-        } catch (x) {
-            return false;
-        }
+        return typeof f === 'function';
     };
 
     _.isArguments = function(obj) {
@@ -2129,6 +2130,17 @@
 
     var NOOP_FUNC = function () {};
 
+    var urlMatchesRegexList = function (url, regexList) {
+        var matches = false;
+        for (var i = 0; i < regexList.length; i++) {
+            if (url.match(regexList[i])) {
+                matches = true;
+                break;
+            }
+        }
+        return matches;
+    };
+
     var JSONStringify = null, JSONParse = null;
     if (typeof JSON !== 'undefined') {
         JSONStringify = JSON.stringify;
@@ -2151,15 +2163,6 @@
     _['toArray']                = _.toArray;
     _['NPO']                    = NpoPromise;
 
-    /**
-     * @param {import('./session-recording').SerializedRecording} serializedRecording
-     * @returns {boolean}
-     */
-    var isRecordingExpired = function(serializedRecording) {
-        var now = Date.now();
-        return !serializedRecording || now > serializedRecording['maxExpires'] || now > serializedRecording['idleExpires'];
-    };
-
     // stateless utils
     // mostly from https://github.com/mixpanel/mixpanel-js/blob/989ada50f518edab47b9c4fd9535f9fbd5ec5fc0/src/autotrack-utils.js
 
@@ -3424,27 +3427,15 @@
     };
 
     Autocapture.prototype.currentUrlBlocked = function() {
-        var i;
         var currentUrl = _.info.currentUrl();
 
         var allowUrlRegexes = this.getConfig(CONFIG_ALLOW_URL_REGEXES) || [];
         if (allowUrlRegexes.length) {
             // we're using an allowlist, only track if current URL matches
-            var allowed = false;
-            for (i = 0; i < allowUrlRegexes.length; i++) {
-                var allowRegex = allowUrlRegexes[i];
-                try {
-                    if (currentUrl.match(allowRegex)) {
-                        allowed = true;
-                        break;
-                    }
-                } catch (err) {
-                    logger$4.critical('Error while checking block URL regex: ' + allowRegex, err);
-                    return true;
-                }
-            }
-            if (!allowed) {
-                // wasn't allowed by any regex
+            try {
+                return !urlMatchesRegexList(currentUrl, allowUrlRegexes);
+            } catch (err) {
+                logger$4.critical('Error while checking block URL regexes: ', err);
                 return true;
             }
         }
@@ -3454,17 +3445,12 @@
             return false;
         }
 
-        for (i = 0; i < blockUrlRegexes.length; i++) {
-            try {
-                if (currentUrl.match(blockUrlRegexes[i])) {
-                    return true;
-                }
-            } catch (err) {
-                logger$4.critical('Error while checking block URL regex: ' + blockUrlRegexes[i], err);
-                return true;
-            }
+        try {
+            return urlMatchesRegexList(currentUrl, blockUrlRegexes);
+        } catch (err) {
+            logger$4.critical('Error while checking block URL regexes: ', err);
+            return true;
         }
-        return false;
     };
 
     Autocapture.prototype.pageviewTrackingConfig = function() {
@@ -3908,14 +3894,62 @@
     // TODO integrate error_reporter from mixpanel instance
     safewrapClass(Autocapture);
 
-    var logger$3 = console_with_prefix('flags');
+    /**
+     * Get the promise-based targeting loader
+     * @param {Function} loadExtraBundle - Function to load external bundle (callback-based)
+     * @param {string} targetingSrc - URL to targeting bundle
+     * @returns {Promise} Promise that resolves with targeting library
+     */
+    var getTargetingPromise = function(loadExtraBundle, targetingSrc) {
+        // Return existing promise if already initialized or loading
+        if (win[TARGETING_GLOBAL_NAME] && typeof win[TARGETING_GLOBAL_NAME].then === 'function') {
+            return win[TARGETING_GLOBAL_NAME];
+        }
+
+        // Create loading promise and set it as the global immediately
+        // This makes minified build behavior consistent with dev/CJS builds
+        win[TARGETING_GLOBAL_NAME] = new Promise(function (resolve) {
+            loadExtraBundle(targetingSrc, resolve);
+        }).then(function () {
+            var p = win[TARGETING_GLOBAL_NAME];
+            if (p && typeof p.then === 'function') {
+                return p;
+            }
+            throw new Error('targeting failed to load');
+        }).catch(function (err) {
+            delete win[TARGETING_GLOBAL_NAME];
+            throw err;
+        });
+
+        return win[TARGETING_GLOBAL_NAME];
+    };
 
+    var logger$3 = console_with_prefix('flags');
     var FLAGS_CONFIG_KEY = 'flags';
 
     var CONFIG_CONTEXT = 'context';
     var CONFIG_DEFAULTS = {};
     CONFIG_DEFAULTS[CONFIG_CONTEXT] = {};
 
+    /**
+     * Generate a unique key for a pending first-time event
+     * @param {string} flagKey - The flag key
+     * @param {string} firstTimeEventHash - The first_time_event_hash from the pending event definition
+     * @returns {string} Composite key in format "flagKey:firstTimeEventHash"
+     */
+    var getPendingEventKey = function(flagKey, firstTimeEventHash) {
+        return flagKey + ':' + firstTimeEventHash;
+    };
+
+    /**
+     * Extract the flag key from a pending event key
+     * @param {string} eventKey - The composite event key in format "flagKey:firstTimeEventHash"
+     * @returns {string} The flag key portion
+     */
+    var getFlagKeyFromPendingEventKey = function(eventKey) {
+        return eventKey.split(':')[0];
+    };
+
     /**
      * FeatureFlagManager: support for Mixpanel's feature flagging product
      * @constructor
@@ -3927,6 +3961,8 @@
         this.setMpConfig = initOptions.setConfigFunc;
         this.getMpProperty = initOptions.getPropertyFunc;
         this.track = initOptions.trackingFunc;
+        this.loadExtraBundle = initOptions.loadExtraBundle || function() {};
+        this.targetingSrc = initOptions.targetingSrc || '';
     };
 
     FeatureFlagManager.prototype.init = function() {
@@ -3939,6 +3975,8 @@
         this.fetchFlags();
 
         this.trackedFeatures = new Set();
+        this.pendingFirstTimeEvents = {};
+        this.activatedFirstTimeEvents = {};
     };
 
     FeatureFlagManager.prototype.getFullConfig = function() {
@@ -4019,17 +4057,78 @@
                     throw new Error('No flags in API response');
                 }
                 var flags = new Map();
+                var pendingFirstTimeEvents = {};
+
+                // Process flags from response
                 _.each(responseFlags, function(data, key) {
-                    flags.set(key, {
-                        'key': data['variant_key'],
-                        'value': data['variant_value'],
-                        'experiment_id': data['experiment_id'],
-                        'is_experiment_active': data['is_experiment_active'],
-                        'is_qa_tester': data['is_qa_tester']
+                    // Check if this flag has any activated first-time events this session
+                    var hasActivatedEvent = false;
+                    var prefix = key + ':';
+                    _.each(this.activatedFirstTimeEvents, function(activated, eventKey) {
+                        if (eventKey.startsWith(prefix)) {
+                            hasActivatedEvent = true;
+                        }
                     });
-                });
+
+                    if (hasActivatedEvent) {
+                        // Preserve the activated variant, don't overwrite with server's current variant
+                        var currentFlag = this.flags && this.flags.get(key);
+                        if (currentFlag) {
+                            flags.set(key, currentFlag);
+                        }
+                    } else {
+                        // Use server's current variant
+                        flags.set(key, {
+                            'key': data['variant_key'],
+                            'value': data['variant_value'],
+                            'experiment_id': data['experiment_id'],
+                            'is_experiment_active': data['is_experiment_active'],
+                            'is_qa_tester': data['is_qa_tester']
+                        });
+                    }
+                }, this);
+
+                // Process top-level pending_first_time_events array
+                var topLevelDefinitions = responseBody['pending_first_time_events'];
+                if (topLevelDefinitions && topLevelDefinitions.length > 0) {
+                    _.each(topLevelDefinitions, function(def) {
+                        var flagKey = def['flag_key'];
+                        var eventKey = getPendingEventKey(flagKey, def['first_time_event_hash']);
+
+                        // Skip if this specific event has already been activated this session
+                        if (this.activatedFirstTimeEvents[eventKey]) {
+                            return;
+                        }
+
+                        // Store pending event definition using composite key
+                        pendingFirstTimeEvents[eventKey] = {
+                            'flag_key': flagKey,
+                            'flag_id': def['flag_id'],
+                            'project_id': def['project_id'],
+                            'first_time_event_hash': def['first_time_event_hash'],
+                            'event_name': def['event_name'],
+                            'property_filters': def['property_filters'],
+                            'pending_variant': def['pending_variant']
+                        };
+                    }, this);
+                }
+
+                // Preserve any activated orphaned flags (flags that were activated but are no longer in response)
+                if (this.activatedFirstTimeEvents) {
+                    _.each(this.activatedFirstTimeEvents, function(activated, eventKey) {
+                        var flagKey = getFlagKeyFromPendingEventKey(eventKey);
+                        if (activated && !flags.has(flagKey) && this.flags && this.flags.has(flagKey)) {
+                            // Keep the activated flag even though it's not in the new response
+                            flags.set(flagKey, this.flags.get(flagKey));
+                        }
+                    }, this);
+                }
+
                 this.flags = flags;
+                this.pendingFirstTimeEvents = pendingFirstTimeEvents;
                 this._traceparent = traceparent;
+
+                this._loadTargetingIfNeeded();
             }.bind(this)).catch(function(error) {
                 this.markFetchComplete();
                 logger$3.error(error);
@@ -4053,6 +4152,177 @@
         this._fetchInProgressStartTime = null;
     };
 
+    /**
+     * Proactively load targeting bundle if any pending events have property filters
+     */
+    FeatureFlagManager.prototype._loadTargetingIfNeeded = function() {
+        var hasPropertyFilters = false;
+        _.each(this.pendingFirstTimeEvents, function(evt) {
+            if (evt['property_filters'] && !_.isEmptyObject(evt['property_filters'])) {
+                hasPropertyFilters = true;
+            }
+        });
+
+        if (hasPropertyFilters) {
+            this.getTargeting().then(function() {
+                logger$3.log('targeting loaded for property filter evaluation');
+            });
+        }
+    };
+
+    /**
+     * Get the targeting library (initializes if not already loaded)
+     * This method is primarily for testing - production code should rely on automatic loading
+     * @returns {Promise} Promise that resolves with targeting library
+     */
+    FeatureFlagManager.prototype.getTargeting = function() {
+        return getTargetingPromise(
+            this.loadExtraBundle.bind(this),
+            this.targetingSrc
+        ).catch(function(error) {
+            logger$3.error('Failed to load targeting: ' + error);
+        }.bind(this));
+    };
+
+    /**
+     * Check if a tracked event matches any pending first-time events and activate the corresponding flag variant
+     * @param {string} eventName - The name of the event being tracked
+     * @param {Object} properties - Event properties to evaluate against property filters
+     *
+     * When a match is found (event name matches and property filters pass), this method:
+     * - Switches the flag to the pending variant
+     * - Marks the event as activated for this session
+     * - Records the activation via the API (fire-and-forget)
+     */
+    FeatureFlagManager.prototype.checkFirstTimeEvents = function(eventName, properties) {
+        if (!this.pendingFirstTimeEvents || _.isEmptyObject(this.pendingFirstTimeEvents)) {
+            return;
+        }
+
+        // Check if targeting promise exists (either bundled or async loaded)
+        if (win[TARGETING_GLOBAL_NAME] && _.isFunction(win[TARGETING_GLOBAL_NAME].then)) {
+            win[TARGETING_GLOBAL_NAME].then(function(library) {
+                this._processFirstTimeEventCheck(eventName, properties, library);
+            }.bind(this)).catch(function() {
+                // If targeting failed to load, process with null
+                // Events without property filters will still match
+                this._processFirstTimeEventCheck(eventName, properties, null);
+            }.bind(this));
+        } else {
+            // No targeting available, process with null
+            // Events without property filters will still match
+            this._processFirstTimeEventCheck(eventName, properties, null);
+        }
+    };
+
+    /**
+     * Internal method to process first-time event checks with loaded targeting library
+     * @param {string} eventName - The name of the event being tracked
+     * @param {Object} properties - Event properties to evaluate against property filters
+     * @param {Object} targeting - The loaded targeting library
+     */
+    FeatureFlagManager.prototype._processFirstTimeEventCheck = function(eventName, properties, targeting) {
+        _.each(this.pendingFirstTimeEvents, function(pendingEvent, eventKey) {
+            if (this.activatedFirstTimeEvents[eventKey]) {
+                return;
+            }
+
+            var flagKey = pendingEvent['flag_key'];
+
+            // Use targeting module to check if event matches
+            var matchResult;
+
+            // If no targeting library and event has property filters, skip it
+            if (!targeting && pendingEvent['property_filters'] && !_.isEmptyObject(pendingEvent['property_filters'])) {
+                logger$3.warn('Skipping event check for "' + flagKey + '" - property filters require targeting library');
+                return;
+            }
+
+            // For simple events (no property filters), just check event name
+            if (!targeting) {
+                matchResult = {
+                    matches: eventName === pendingEvent['event_name'],
+                    error: null
+                };
+            } else {
+                var criteria = {
+                    'event_name': pendingEvent['event_name'],
+                    'property_filters': pendingEvent['property_filters']
+                };
+                matchResult = targeting['eventMatchesCriteria'](
+                    eventName,
+                    properties,
+                    criteria
+                );
+            }
+
+            if (matchResult.error) {
+                logger$3.error('Error checking first-time event for flag "' + flagKey + '": ' + matchResult.error);
+                return;
+            }
+
+            if (!matchResult.matches) {
+                return;
+            }
+
+            logger$3.log('First-time event matched for flag "' + flagKey + '": ' + eventName);
+
+            var newVariant = {
+                'key': pendingEvent['pending_variant']['variant_key'],
+                'value': pendingEvent['pending_variant']['variant_value'],
+                'experiment_id': pendingEvent['pending_variant']['experiment_id'],
+                'is_experiment_active': pendingEvent['pending_variant']['is_experiment_active']
+            };
+
+            this.flags.set(flagKey, newVariant);
+            this.activatedFirstTimeEvents[eventKey] = true;
+
+            this.recordFirstTimeEvent(
+                pendingEvent['flag_id'],
+                pendingEvent['project_id'],
+                pendingEvent['first_time_event_hash']
+            );
+        }, this);
+    };
+
+    FeatureFlagManager.prototype.getFirstTimeEventApiRoute = function(flagId) {
+        // Construct URL: {api_host}/flags/{flagId}/first-time-events
+        return this.getFullApiRoute() + '/' + flagId + '/first-time-events';
+    };
+
+    FeatureFlagManager.prototype.recordFirstTimeEvent = function(flagId, projectId, firstTimeEventHash) {
+        var distinctId = this.getMpProperty('distinct_id');
+        var traceparent = generateTraceparent();
+
+        // Build URL with query string parameters
+        var searchParams = new URLSearchParams();
+        searchParams.set('mp_lib', 'web');
+        searchParams.set('$lib_version', Config.LIB_VERSION);
+        var url = this.getFirstTimeEventApiRoute(flagId) + '?' + searchParams.toString();
+
+        var payload = {
+            'distinct_id': distinctId,
+            'project_id': projectId,
+            'first_time_event_hash': firstTimeEventHash
+        };
+
+        logger$3.log('Recording first-time event for flag: ' + flagId);
+
+        // Fire-and-forget POST request
+        this.fetch.call(win, url, {
+            'method': 'POST',
+            'headers': {
+                'Content-Type': 'application/json',
+                'Authorization': 'Basic ' + btoa(this.getMpConfig('token') + ':'),
+                'traceparent': traceparent
+            },
+            'body': JSON.stringify(payload)
+        }).catch(function(error) {
+            // Silent failure - cohort sync will catch up
+            logger$3.error('Failed to record first-time event for flag ' + flagId + ': ' + error);
+        });
+    };
+
     FeatureFlagManager.prototype.getVariant = function(featureName, fallback) {
         if (!this.fetchPromise) {
             return new Promise(function(resolve) {
@@ -4171,76 +4441,423 @@
     // Deprecated method
     FeatureFlagManager.prototype['get_feature_data'] = FeatureFlagManager.prototype.getFeatureData;
 
-    /* eslint camelcase: "off" */
+    // Exports intended only for testing
+    FeatureFlagManager.prototype['getTargeting'] = FeatureFlagManager.prototype.getTargeting;
+
+    var MIXPANEL_DB_NAME = 'mixpanelBrowserDb';
 
+    var RECORDING_EVENTS_STORE_NAME = 'mixpanelRecordingEvents';
+    var RECORDING_REGISTRY_STORE_NAME = 'mixpanelRecordingRegistry';
+
+    // note: increment the version number when adding new object stores
+    var DB_VERSION = 1;
+    var OBJECT_STORES = [RECORDING_EVENTS_STORE_NAME, RECORDING_REGISTRY_STORE_NAME];
 
     /**
-     * DomTracker Object
-     * @constructor
+     * @type {import('./wrapper').StorageWrapper}
      */
-    var DomTracker = function() {};
+    var IDBStorageWrapper = function (storeName) {
+        /**
+         * @type {Promise<IDBDatabase>|null}
+         */
+        this.dbPromise = null;
+        this.storeName = storeName;
+    };
 
+    IDBStorageWrapper.prototype._openDb = function () {
+        return new PromisePolyfill(function (resolve, reject) {
+            var openRequest = win.indexedDB.open(MIXPANEL_DB_NAME, DB_VERSION);
+            openRequest['onerror'] = function () {
+                reject(openRequest.error);
+            };
 
-    // interface
-    DomTracker.prototype.create_properties = function() {};
-    DomTracker.prototype.event_handler = function() {};
-    DomTracker.prototype.after_track_handler = function() {};
+            openRequest['onsuccess'] = function () {
+                resolve(openRequest.result);
+            };
 
-    DomTracker.prototype.init = function(mixpanel_instance) {
-        this.mp = mixpanel_instance;
-        return this;
-    };
+            openRequest['onupgradeneeded'] = function (ev) {
+                var db = ev.target.result;
 
-    /**
-     * @param {Object|string} query
-     * @param {string} event_name
-     * @param {Object=} properties
-     * @param {function=} user_callback
-     */
-    DomTracker.prototype.track = function(query, event_name, properties, user_callback) {
-        var that = this;
-        var elements = _.dom_query(query);
+                OBJECT_STORES.forEach(function (storeName) {
+                    db.createObjectStore(storeName);
+                });
+            };
+        });
+    };
 
-        if (elements.length === 0) {
-            console.error('The DOM query (' + query + ') returned 0 elements');
-            return;
+    IDBStorageWrapper.prototype.init = function () {
+        if (!win.indexedDB) {
+            return PromisePolyfill.reject('indexedDB is not supported in this browser');
         }
 
-        _.each(elements, function(element) {
-            _.register_event(element, this.override_event, function(e) {
-                var options = {};
-                var props = that.create_properties(properties, this);
-                var timeout = that.mp.get_config('track_links_timeout');
-
-                that.event_handler(e, this, options);
-
-                // in case the mixpanel servers don't get back to us in time
-                window.setTimeout(that.track_callback(user_callback, props, options, true), timeout);
+        if (!this.dbPromise) {
+            this.dbPromise = this._openDb();
+        }
 
-                // fire the tracking event
-                that.mp.track(event_name, props, that.track_callback(user_callback, props, options));
+        return this.dbPromise
+            .then(function (dbOrError) {
+                if (dbOrError instanceof win['IDBDatabase']) {
+                    return PromisePolyfill.resolve();
+                } else {
+                    return PromisePolyfill.reject(dbOrError);
+                }
             });
-        }, this);
+    };
 
-        return true;
+    IDBStorageWrapper.prototype.isInitialized = function () {
+        return !!this.dbPromise;
     };
 
     /**
-     * @param {function} user_callback
-     * @param {Object} props
-     * @param {boolean=} timeout_occured
+     * @param {IDBTransactionMode} mode
+     * @param {function(IDBObjectStore): void} storeCb
      */
-    DomTracker.prototype.track_callback = function(user_callback, props, options, timeout_occured) {
-        timeout_occured = timeout_occured || false;
-        var that = this;
-
-        return function() {
-            // options is referenced from both callbacks, so we can have
-            // a 'lock' of sorts to ensure only one fires
-            if (options.callback_fired) { return; }
-            options.callback_fired = true;
-
-            if (user_callback && user_callback(timeout_occured, props) === false) {
+    IDBStorageWrapper.prototype.makeTransaction = function (mode, storeCb) {
+        var storeName = this.storeName;
+        var doTransaction = function (db) {
+            return new PromisePolyfill(function (resolve, reject) {
+                var transaction = db.transaction(storeName, mode);
+                transaction.oncomplete = function () {
+                    resolve(transaction);
+                };
+                transaction.onabort = transaction.onerror = function () {
+                    reject(transaction.error);
+                };
+
+                storeCb(transaction.objectStore(storeName));
+            });
+        };
+
+        return this.dbPromise
+            .then(doTransaction)
+            .catch(function (err) {
+                if (err && err['name'] === 'InvalidStateError') {
+                    // try reopening the DB if the connection is closed
+                    this.dbPromise = this._openDb();
+                    return this.dbPromise.then(doTransaction);
+                } else {
+                    return PromisePolyfill.reject(err);
+                }
+            }.bind(this));
+    };
+
+    IDBStorageWrapper.prototype.setItem = function (key, value) {
+        return this.makeTransaction('readwrite', function (objectStore) {
+            objectStore.put(value, key);
+        });
+    };
+
+    IDBStorageWrapper.prototype.getItem = function (key) {
+        var req;
+        return this.makeTransaction('readonly', function (objectStore) {
+            req = objectStore.get(key);
+        }).then(function () {
+            return req.result;
+        });
+    };
+
+    IDBStorageWrapper.prototype.removeItem = function (key) {
+        return this.makeTransaction('readwrite', function (objectStore) {
+            objectStore.delete(key);
+        });
+    };
+
+    IDBStorageWrapper.prototype.getAll = function () {
+        var req;
+        return this.makeTransaction('readonly', function (objectStore) {
+            req = objectStore.getAll();
+        }).then(function () {
+            return req.result;
+        });
+    };
+
+    /**
+     * @param {import('./session-recording').SerializedRecording} serializedRecording
+     * @returns {boolean}
+     */
+    var isRecordingExpired = function(serializedRecording) {
+        var now = Date.now();
+        return !serializedRecording || now > serializedRecording['maxExpires'] || now > serializedRecording['idleExpires'];
+    };
+
+    /* eslint camelcase: "off" */
+
+
+    /**
+     * RecorderManager: manages session recording initialization, lifecycle and state
+     * @constructor
+     */
+    var RecorderManager = function(initOptions) {
+        // TODO - Passing in mixpanel instance as it is still needed for recorder creation
+        // but ideally we should be able to remove this dependency.
+        this.mixpanelInstance = initOptions.mixpanelInstance;
+
+        this.getMpConfig = initOptions.getConfigFunc;
+        this.getTabId = initOptions.getTabIdFunc;
+        this.reportError = initOptions.reportErrorFunc;
+        this.getDistinctId = initOptions.getDistinctIdFunc;
+        this.loadExtraBundle = initOptions.loadExtraBundle;
+        this.recorderSrc = initOptions.recorderSrc;
+        this.targetingSrc = initOptions.targetingSrc;
+        this.libBasePath = initOptions.libBasePath;
+
+        this._recorder = null;
+    };
+
+    RecorderManager.prototype.shouldLoadRecorder = function() {
+        if (this.getMpConfig('disable_persistence')) {
+            console.log('Load recorder check skipped due to disable_persistence config');
+            return PromisePolyfill.resolve(false);
+        }
+
+        var recording_registry_idb = new IDBStorageWrapper(RECORDING_REGISTRY_STORE_NAME);
+        var tab_id = this.getTabId();
+        return recording_registry_idb.init()
+            .then(function () {
+                return recording_registry_idb.getAll();
+            })
+            .then(function (recordings) {
+                for (var i = 0; i < recordings.length; i++) {
+                    // if there are expired recordings in the registry, we should load the recorder to flush them
+                    // if there's a recording for this tab id, we should load the recorder to continue the recording
+                    if (isRecordingExpired(recordings[i]) || recordings[i]['tabId'] === tab_id) {
+                        return true;
+                    }
+                }
+                return false;
+            })
+            .catch(_.bind(function (err) {
+                this.reportError('Error checking recording registry', err);
+                return false;
+            }, this));
+    };
+
+    RecorderManager.prototype.checkAndStartSessionRecording = function(force_start, rate) {
+        if (!win['MutationObserver']) {
+            console.critical('Browser does not support MutationObserver; skipping session recording');
+            return PromisePolyfill.resolve();
+        }
+
+        var loadRecorder = _.bind(function(startNewIfInactive) {
+            return new PromisePolyfill(_.bind(function(resolve) {
+                var handleLoadedRecorder = safewrap(_.bind(function() {
+                    this._recorder = this._recorder || new win[RECORDER_GLOBAL_NAME](this.mixpanelInstance);
+                    this._recorder['resumeRecording'](startNewIfInactive);
+                    resolve();
+                }, this));
+
+                if (_.isUndefined(win[RECORDER_GLOBAL_NAME])) {
+                    var recorderSrc = this.recorderSrc || (this.libBasePath + RECORDER_FILENAME);
+                    this.loadExtraBundle(recorderSrc, handleLoadedRecorder);
+                } else {
+                    handleLoadedRecorder();
+                }
+            }, this));
+        }, this);
+
+        /**
+         * If the user is sampled or start_session_recording is called, we always load the recorder since it's guaranteed a recording should start.
+         * Otherwise, if the recording registry has any records then it's likely there's a recording in progress or orphaned data that needs to be flushed.
+         */
+        var effective_rate = _.isUndefined(rate) ? this.getMpConfig('record_sessions_percent') : rate;
+        var is_sampled = effective_rate > 0 && Math.random() * 100 <= effective_rate;
+        if (force_start || is_sampled) {
+            return loadRecorder(true);
+        } else {
+            return this.shouldLoadRecorder()
+                .then(_.bind(function (shouldLoad) {
+                    if (shouldLoad) {
+                        return loadRecorder(false);
+                    }
+                    return PromisePolyfill.resolve();
+                }, this));
+        }
+    };
+
+    RecorderManager.prototype.isRecording = function() {
+        // Safety check: ensure isRecording method exists (older CDN builds may not have it)
+        if (!this._recorder || !_.isFunction(this._recorder['isRecording'])) {
+            return false;
+        }
+        try {
+            return this._recorder['isRecording']();
+        } catch (e) {
+            this.reportError('Error checking if recording is active', e);
+            return false;
+        }
+    };
+
+    RecorderManager.prototype.startRecordingOnEvent = function(event_name, properties) {
+        var isRecording = this.isRecording();
+        var recordingTriggerEvents = this.getMpConfig('recording_event_triggers');
+
+        if (!isRecording && recordingTriggerEvents) {
+            var trigger = recordingTriggerEvents[event_name];
+            if (trigger && typeof trigger['percentage'] === 'number') {
+                var newRate = trigger['percentage'];
+                var propertyFilters = trigger['property_filters'];
+                if (propertyFilters && !_.isEmptyObject(propertyFilters)) {
+                    var targetingSrc = this.targetingSrc || (this.libBasePath + TARGETING_FILENAME);
+                    getTargetingPromise(this.loadExtraBundle, targetingSrc)
+                        .then(function(targeting) {
+                            try {
+                                var result = targeting['eventMatchesCriteria'](
+                                    event_name,
+                                    properties,
+                                    {
+                                        'event_name': event_name,
+                                        'property_filters': propertyFilters
+                                    }
+                                );
+                                if (result['matches']) {
+                                    this.checkAndStartSessionRecording(false, newRate);
+                                }
+                            } catch (err) {
+                                console.critical('Could not parse recording event trigger properties logic:', err);
+                            }
+                        }.bind(this)).catch(function(err) {
+                            console.critical('Failed to load targeting library:', err);
+                        });
+                } else {
+                    this.checkAndStartSessionRecording(false, newRate);
+                }
+            }
+        }
+    };
+
+    RecorderManager.prototype.stopSessionRecording = function() {
+        if (this._recorder) {
+            return this._recorder['stopRecording']();
+        }
+        return PromisePolyfill.resolve();
+    };
+
+    RecorderManager.prototype.pauseSessionRecording = function() {
+        if (this._recorder) {
+            return this._recorder['pauseRecording']();
+        }
+        return PromisePolyfill.resolve();
+    };
+
+    RecorderManager.prototype.resumeSessionRecording = function() {
+        if (this._recorder) {
+            return this._recorder['resumeRecording']();
+        }
+        return PromisePolyfill.resolve();
+    };
+
+    RecorderManager.prototype.isRecordingHeatmapData = function() {
+        return this.getSessionReplayId() && this.getMpConfig('record_heatmap_data');
+    };
+
+    RecorderManager.prototype.getSessionRecordingProperties = function() {
+        var props = {};
+        var replay_id = this.getSessionReplayId();
+        if (replay_id) {
+            props['$mp_replay_id'] = replay_id;
+        }
+        return props;
+    };
+
+    RecorderManager.prototype.getSessionReplayUrl = function() {
+        var replay_url = null;
+        var replay_id = this.getSessionReplayId();
+        if (replay_id) {
+            var query_params = _.HTTPBuildQuery({
+                'replay_id': replay_id,
+                'distinct_id': this.getDistinctId(),
+                'token': this.getMpConfig('token')
+            });
+            replay_url = 'https://mixpanel.com/projects/replay-redirect?' + query_params;
+        }
+        return replay_url;
+    };
+
+    RecorderManager.prototype.getSessionReplayId = function() {
+        var replay_id = null;
+        if (this._recorder) {
+            replay_id = this._recorder['replayId'];
+        }
+        return replay_id || null;
+    };
+
+    // "private" public method to reach into the recorder in test cases
+    RecorderManager.prototype.getRecorder = function() {
+        return this._recorder;
+    };
+
+    safewrapClass(RecorderManager);
+
+    /* eslint camelcase: "off" */
+
+
+    /**
+     * DomTracker Object
+     * @constructor
+     */
+    var DomTracker = function() {};
+
+
+    // interface
+    DomTracker.prototype.create_properties = function() {};
+    DomTracker.prototype.event_handler = function() {};
+    DomTracker.prototype.after_track_handler = function() {};
+
+    DomTracker.prototype.init = function(mixpanel_instance) {
+        this.mp = mixpanel_instance;
+        return this;
+    };
+
+    /**
+     * @param {Object|string} query
+     * @param {string} event_name
+     * @param {Object=} properties
+     * @param {function=} user_callback
+     */
+    DomTracker.prototype.track = function(query, event_name, properties, user_callback) {
+        var that = this;
+        var elements = _.dom_query(query);
+
+        if (elements.length === 0) {
+            console.error('The DOM query (' + query + ') returned 0 elements');
+            return;
+        }
+
+        _.each(elements, function(element) {
+            _.register_event(element, this.override_event, function(e) {
+                var options = {};
+                var props = that.create_properties(properties, this);
+                var timeout = that.mp.get_config('track_links_timeout');
+
+                that.event_handler(e, this, options);
+
+                // in case the mixpanel servers don't get back to us in time
+                window.setTimeout(that.track_callback(user_callback, props, options, true), timeout);
+
+                // fire the tracking event
+                that.mp.track(event_name, props, that.track_callback(user_callback, props, options));
+            });
+        }, this);
+
+        return true;
+    };
+
+    /**
+     * @param {function} user_callback
+     * @param {Object} props
+     * @param {boolean=} timeout_occured
+     */
+    DomTracker.prototype.track_callback = function(user_callback, props, options, timeout_occured) {
+        timeout_occured = timeout_occured || false;
+        var that = this;
+
+        return function() {
+            // options is referenced from both callbacks, so we can have
+            // a 'lock' of sorts to ensure only one fires
+            if (options.callback_fired) { return; }
+            options.callback_fired = true;
+
+            if (user_callback && user_callback(timeout_occured, props) === false) {
                 // user can prevent the default functionality by
                 // returning false from their callback
                 return;
@@ -6692,133 +7309,6 @@
         return timestamp;
     };
 
-    var MIXPANEL_DB_NAME = 'mixpanelBrowserDb';
-
-    var RECORDING_EVENTS_STORE_NAME = 'mixpanelRecordingEvents';
-    var RECORDING_REGISTRY_STORE_NAME = 'mixpanelRecordingRegistry';
-
-    // note: increment the version number when adding new object stores
-    var DB_VERSION = 1;
-    var OBJECT_STORES = [RECORDING_EVENTS_STORE_NAME, RECORDING_REGISTRY_STORE_NAME];
-
-    /**
-     * @type {import('./wrapper').StorageWrapper}
-     */
-    var IDBStorageWrapper = function (storeName) {
-        /**
-         * @type {Promise<IDBDatabase>|null}
-         */
-        this.dbPromise = null;
-        this.storeName = storeName;
-    };
-
-    IDBStorageWrapper.prototype._openDb = function () {
-        return new PromisePolyfill(function (resolve, reject) {
-            var openRequest = win.indexedDB.open(MIXPANEL_DB_NAME, DB_VERSION);
-            openRequest['onerror'] = function () {
-                reject(openRequest.error);
-            };
-
-            openRequest['onsuccess'] = function () {
-                resolve(openRequest.result);
-            };
-
-            openRequest['onupgradeneeded'] = function (ev) {
-                var db = ev.target.result;
-
-                OBJECT_STORES.forEach(function (storeName) {
-                    db.createObjectStore(storeName);
-                });
-            };
-        });
-    };
-
-    IDBStorageWrapper.prototype.init = function () {
-        if (!win.indexedDB) {
-            return PromisePolyfill.reject('indexedDB is not supported in this browser');
-        }
-
-        if (!this.dbPromise) {
-            this.dbPromise = this._openDb();
-        }
-
-        return this.dbPromise
-            .then(function (dbOrError) {
-                if (dbOrError instanceof win['IDBDatabase']) {
-                    return PromisePolyfill.resolve();
-                } else {
-                    return PromisePolyfill.reject(dbOrError);
-                }
-            });
-    };
-
-    IDBStorageWrapper.prototype.isInitialized = function () {
-        return !!this.dbPromise;
-    };
-
-    /**
-     * @param {IDBTransactionMode} mode
-     * @param {function(IDBObjectStore): void} storeCb
-     */
-    IDBStorageWrapper.prototype.makeTransaction = function (mode, storeCb) {
-        var storeName = this.storeName;
-        var doTransaction = function (db) {
-            return new PromisePolyfill(function (resolve, reject) {
-                var transaction = db.transaction(storeName, mode);
-                transaction.oncomplete = function () {
-                    resolve(transaction);
-                };
-                transaction.onabort = transaction.onerror = function () {
-                    reject(transaction.error);
-                };
-
-                storeCb(transaction.objectStore(storeName));
-            });
-        };
-
-        return this.dbPromise
-            .then(doTransaction)
-            .catch(function (err) {
-                if (err && err['name'] === 'InvalidStateError') {
-                    // try reopening the DB if the connection is closed
-                    this.dbPromise = this._openDb();
-                    return this.dbPromise.then(doTransaction);
-                } else {
-                    return PromisePolyfill.reject(err);
-                }
-            }.bind(this));
-    };
-
-    IDBStorageWrapper.prototype.setItem = function (key, value) {
-        return this.makeTransaction('readwrite', function (objectStore) {
-            objectStore.put(value, key);
-        });
-    };
-
-    IDBStorageWrapper.prototype.getItem = function (key) {
-        var req;
-        return this.makeTransaction('readonly', function (objectStore) {
-            req = objectStore.get(key);
-        }).then(function () {
-            return req.result;
-        });
-    };
-
-    IDBStorageWrapper.prototype.removeItem = function (key) {
-        return this.makeTransaction('readwrite', function (objectStore) {
-            objectStore.delete(key);
-        });
-    };
-
-    IDBStorageWrapper.prototype.getAll = function () {
-        var req;
-        return this.makeTransaction('readonly', function (objectStore) {
-            req = objectStore.getAll();
-        }).then(function () {
-            return req.result;
-        });
-    };
-
     /* eslint camelcase: "off" */
 
     /*
@@ -6953,12 +7443,17 @@
         'record_collect_fonts':              false,
         'record_console':                    true,
         'record_heatmap_data':               false,
+        'recording_event_triggers':          {},
         'record_idle_timeout_ms':            30 * 60 * 1000, // 30 minutes
         'record_mask_inputs':                true,
         'record_max_ms':                     MAX_RECORDING_MS,
         'record_min_ms':                     0,
+        'record_network':                    false,
+        'record_network_options':            {},
         'record_sessions_percent':           0,
-        'recorder_src':                      'https://cdn.mxpnl.com/libs/mixpanel-recorder.min.js',
+        'recorder_src':                      null,
+        'targeting_src':                     null,
+        'lib_base_path':                     'https://cdn.mxpnl.com/libs/',
         'remote_settings_mode':              SETTING_DISABLED // 'strict', 'fallback', 'disabled'
     };
 
@@ -7112,6 +7607,19 @@
             'callback_fn': ((name === PRIMARY_INSTANCE_NAME) ? name : PRIMARY_INSTANCE_NAME + '.' + name) + '._jsc'
         }));
 
+        this.recorderManager = new RecorderManager({
+            mixpanelInstance: this,
+            getConfigFunc: _.bind(this.get_config, this),
+            setConfigFunc: _.bind(this.set_config, this),
+            getTabIdFunc: _.bind(this.get_tab_id, this),
+            reportErrorFunc: _.bind(this.report_error, this),
+            getDistinctIdFunc: _.bind(this.get_distinct_id, this),
+            recorderSrc: this.get_config('recorder_src'),
+            targetingSrc: this.get_config('targeting_src'),
+            libBasePath: this.get_config('lib_base_path'),
+            loadExtraBundle: load_extra_bundle
+        });
+
         this['_jsc'] = NOOP_FUNC;
 
         this.__dom_loaded_queue = [];
@@ -7188,7 +7696,9 @@
             getConfigFunc: _.bind(this.get_config, this),
             setConfigFunc: _.bind(this.set_config, this),
             getPropertyFunc: _.bind(this.get_property, this),
-            trackingFunc: _.bind(this.track, this)
+            trackingFunc: _.bind(this.track, this),
+            loadExtraBundle: load_extra_bundle,
+            targetingSrc: this.get_config('targeting_src') || (this.get_config('lib_base_path') + TARGETING_FILENAME)
         });
         this.flags.init();
         this['flags'] = this.flags;
@@ -7201,11 +7711,11 @@
         // Based on remote_settings_mode, fetch remote settings and then start session recording if applicable
         var mode = this.get_config('remote_settings_mode');
         if (mode === SETTING_STRICT || mode === SETTING_FALLBACK) {
-            this._fetch_remote_settings(mode).then(_.bind(function() {
-                this._check_and_start_session_recording();
+            this.__session_recording_init_promise = this._fetch_remote_settings(mode).then(_.bind(function() {
+                return this._check_and_start_session_recording();
             }, this));
         } else {
-            this._check_and_start_session_recording();
+            this.__session_recording_init_promise = this._check_and_start_session_recording();
         }
     };
 
@@ -7249,132 +7759,50 @@
         return this.tab_id || null;
     };
 
-    MixpanelLib.prototype._should_load_recorder = function () {
-        if (this.get_config('disable_persistence')) {
-            console.log('Load recorder check skipped due to disable_persistence config');
-            return Promise.resolve(false);
-        }
-
-        var recording_registry_idb = new IDBStorageWrapper(RECORDING_REGISTRY_STORE_NAME);
-        var tab_id = this.get_tab_id();
-        return recording_registry_idb.init()
-            .then(function () {
-                return recording_registry_idb.getAll();
-            })
-            .then(function (recordings) {
-                for (var i = 0; i < recordings.length; i++) {
-                    // if there are expired recordings in the registry, we should load the recorder to flush them
-                    // if there's a recording for this tab id, we should load the recorder to continue the recording
-                    if (isRecordingExpired(recordings[i]) || recordings[i]['tabId'] === tab_id) {
-                        return true;
-                    }
-                }
-                return false;
-            })
-            .catch(_.bind(function (err) {
-                this.report_error('Error checking recording registry', err);
-            }, this));
-    };
-
     MixpanelLib.prototype._check_and_start_session_recording = addOptOutCheckMixpanelLib(function(force_start) {
-        if (!win['MutationObserver']) {
-            console.critical('Browser does not support MutationObserver; skipping session recording');
-            return;
-        }
-
-        var loadRecorder = _.bind(function(startNewIfInactive) {
-            var handleLoadedRecorder = _.bind(function() {
-                this._recorder = this._recorder || new win['__mp_recorder'](this);
-                this._recorder['resumeRecording'](startNewIfInactive);
-            }, this);
-
-            if (_.isUndefined(win['__mp_recorder'])) {
-                load_extra_bundle(this.get_config('recorder_src'), handleLoadedRecorder);
-            } else {
-                handleLoadedRecorder();
-            }
-        }, this);
-
-        /**
-         * If the user is sampled or start_session_recording is called, we always load the recorder since it's guaranteed a recording should start.
-         * Otherwise, if the recording registry has any records then it's likely there's a recording in progress or orphaned data that needs to be flushed.
-         */
-        var is_sampled = this.get_config('record_sessions_percent') > 0 && Math.random() * 100 <= this.get_config('record_sessions_percent');
-        if (force_start || is_sampled) {
-            loadRecorder(true);
-        } else {
-            this._should_load_recorder()
-                .then(function (shouldLoad) {
-                    if (shouldLoad) {
-                        loadRecorder(false);
-                    }
-                });
-        }
+        return this.recorderManager.checkAndStartSessionRecording(force_start);
     });
 
+    MixpanelLib.prototype._start_recording_on_event = function(event_name, properties) {
+        return this.recorderManager.startRecordingOnEvent(event_name, properties);
+    };
+
     MixpanelLib.prototype.start_session_recording = function () {
-        this._check_and_start_session_recording(true);
+        return this._check_and_start_session_recording(true);
     };
 
     MixpanelLib.prototype.stop_session_recording = function () {
-        if (this._recorder) {
-            return this._recorder['stopRecording']();
-        }
-        return Promise.resolve();
+        return this.recorderManager.stopSessionRecording();
     };
 
     MixpanelLib.prototype.pause_session_recording = function () {
-        if (this._recorder) {
-            return this._recorder['pauseRecording']();
-        }
-        return Promise.resolve();
+        return this.recorderManager.pauseSessionRecording();
     };
 
     MixpanelLib.prototype.resume_session_recording = function () {
-        if (this._recorder) {
-            return this._recorder['resumeRecording']();
-        }
-        return Promise.resolve();
+        return this.recorderManager.resumeSessionRecording();
     };
 
     MixpanelLib.prototype.is_recording_heatmap_data = function () {
-        return this._get_session_replay_id() && this.get_config('record_heatmap_data');
+        return this.recorderManager.isRecordingHeatmapData();
     };
 
     MixpanelLib.prototype.get_session_recording_properties = function () {
-        var props = {};
-        var replay_id = this._get_session_replay_id();
-        if (replay_id) {
-            props['$mp_replay_id'] = replay_id;
-        }
-        return props;
+        return this.recorderManager.getSessionRecordingProperties();
     };
 
     MixpanelLib.prototype.get_session_replay_url = function () {
-        var replay_url = null;
-        var replay_id = this._get_session_replay_id();
-        if (replay_id) {
-            var query_params = _.HTTPBuildQuery({
-                'replay_id': replay_id,
-                'distinct_id': this.get_distinct_id(),
-                'token': this.get_config('token')
-            });
-            replay_url = 'https://mixpanel.com/projects/replay-redirect?' + query_params;
-        }
-        return replay_url;
-    };
-
-    MixpanelLib.prototype._get_session_replay_id = function () {
-        var replay_id = null;
-        if (this._recorder) {
-            replay_id = this._recorder['replayId'];
-        }
-        return replay_id || null;
+        return this.recorderManager.getSessionReplayUrl();
     };
 
     // "private" public method to reach into the recorder in test cases
     MixpanelLib.prototype.__get_recorder = function () {
-        return this._recorder;
+        return this.recorderManager.getRecorder();
+    };
+
+    // "private" public method to get session recording init promise in test cases
+    MixpanelLib.prototype.__get_recording_init_promise = function () {
+        return this.__session_recording_init_promise;
     };
 
     // Private methods
@@ -7632,6 +8060,7 @@
     };
 
     MixpanelLib.prototype._fetch_remote_settings = function(mode) {
+        var self = this;
         var disableRecordingIfStrict = function() {
             if (mode === 'strict') {
                 self.set_config({'record_sessions_percent': 0});
@@ -7652,7 +8081,6 @@
         };
         var query_string = _.HTTPBuildQuery(request_params);
         var full_url = settings_endpoint + '?' + query_string;
-        var self = this;
 
         var abortController = new AbortController();
         var timeout_id = setTimeout(function() {
@@ -7844,6 +8272,34 @@
         this._execute_array([item]);
     };
 
+    /**
+     * Enables events on the Mixpanel object. If passed no arguments,
+     * this function enable tracking of all events. If passed an
+     * array of event names, those events will be enabled, but other
+     * existing disabled events will continue to be not tracked.
+     *
+     * @param {Array} [events] An array of event names to enable
+     */
+    MixpanelLib.prototype.enable = function(events) {
+        var keys, new_disabled_events, i, j;
+
+        if (typeof(events) === 'undefined') {
+            this._flags.disable_all_events = false;
+        } else {
+            keys = {};
+            new_disabled_events = [];
+            for (i = 0; i < events.length; i++) {
+                keys[events[i]] = true;
+            }
+            for (j = 0; j < this.__disabled_events.length; j++) {
+                if (!keys[this.__disabled_events[j]]) {
+                    new_disabled_events.push(this.__disabled_events[j]);
+                }
+            }
+            this.__disabled_events = new_disabled_events;
+        }
+    };
+
     /**
      * Disable events on the Mixpanel object. If passed no arguments,
      * this function disables tracking of any event. If passed an
@@ -8017,6 +8473,8 @@
             this.report_error('Invalid value for property_blacklist config: ' + property_blacklist);
         }
 
+        this._start_recording_on_event(event_name, properties);
+
         var data = {
             'event': event_name,
             'properties': properties
@@ -8030,6 +8488,11 @@
             send_request_options: options
         }, callback);
 
+        // Check for first-time event matches
+        if (this.flags && this.flags.checkFirstTimeEvents) {
+            this.flags.checkFirstTimeEvents(event_name, properties);
+        }
+
         return ret;
     });
 
@@ -9220,6 +9683,7 @@
     // MixpanelLib Exports
     MixpanelLib.prototype['init']                               = MixpanelLib.prototype.init;
     MixpanelLib.prototype['reset']                              = MixpanelLib.prototype.reset;
+    MixpanelLib.prototype['enable']                             = MixpanelLib.prototype.enable;
     MixpanelLib.prototype['disable']                            = MixpanelLib.prototype.disable;
     MixpanelLib.prototype['time_event']                         = MixpanelLib.prototype.time_event;
     MixpanelLib.prototype['track']                              = MixpanelLib.prototype.track;
@@ -9263,6 +9727,7 @@
 
     // Exports intended only for testing
     MixpanelLib.prototype['__get_recorder']                     = MixpanelLib.prototype.__get_recorder;
+    MixpanelLib.prototype['__get_recording_init_promise']       = MixpanelLib.prototype.__get_recording_init_promise;
 
     // MixpanelPersistence Exports
     MixpanelPersistence.prototype['properties']            = MixpanelPersistence.prototype.properties;