mixpanel-browser 2.54.1 → 2.55.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+**2.55.1** (27 Aug 2024)
+- Adds a minimum recording length option for session recording
+- Fixes and improvements for session recording batcher to support offline queueing and retry
+- Fix for query param parsing/escaping
+- Support for more UTM tags / click IDs (thanks @aliyalcinkaya)
+
+**2.55.0** (2 Aug 2024)
+- Added new build to support native JavaScript modules
+
 **2.54.1** (30 Jul 2024)
 - Fixes and improvements for user-idleness detection in session recording
 

package/README.md

@@ -8,16 +8,16 @@ intended to be used by websites wishing to send data to Mixpanel projects. A ful
 is available [here](https://developer.mixpanel.com/docs/javascript-full-api-reference).
 
 ## Alternative installation via NPM
-This library is available as a [package on NPM](https://www.npmjs.com/package/mixpanel-browser) (named `mixpanel-browser` to distinguish it from Mixpanel's server-side Node.js library, available on NPM as `mixpanel`). To install into a project using NPM with a front-end packager such as [Browserify](http://browserify.org/) or [Webpack](https://webpack.github.io/):
+This library is available as a [package on NPM](https://www.npmjs.com/package/mixpanel-browser) (named `mixpanel-browser` to distinguish it from Mixpanel's server-side Node.js library, available on NPM as `mixpanel`). To install into a project using NPM with a front-end packager such as [Vite](https://vitejs.dev/) or [Webpack](https://webpack.github.io/):
 
 ```sh
 npm install --save mixpanel-browser
 ```
 
-You can then require the lib like a standard Node.js module:
+You can then import the lib:
 
 ```javascript
-var mixpanel = require('mixpanel-browser');
+import mixpanel from 'mixpanel-browser';
 
 mixpanel.init("YOUR_TOKEN");
 mixpanel.track("An event");
@@ -35,38 +35,29 @@ To load the core SDK and optionally load session recording bundle asynchronously
 import mixpanel from 'mixpanel-browser/src/loaders/loader-module-with-async-recorder';
 ```
 
-## Alternative installation via Bower
-`mixpanel-js` is also available via front-end package manager [Bower](http://bower.io/). After installing Bower, fetch into your project's `bower_components` dir with:
-```sh
-bower install mixpanel
-```
-
-### Using Bower to load the snippet
-You can then load the lib via the embed code (snippet) with a script reference:
-```html
-<script src="bower_components/mixpanel/mixpanel-jslib-snippet.min.js"></script>
-```
-which loads the _latest_ library version from the Mixpanel CDN ([http://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js](http://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js)).
+## Use as a browser JavaScript module
 
-### Using Bower to load the entire library
-If you wish to load the specific version downloaded in your Bower package, there are two options.
+If you are leveraging [browser JavaScript modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), you can use [`importmap`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to pull in this library.
 
-1) Override the CDN library location with the global `MIXPANEL_CUSTOM_LIB_URL` var:
 ```html
-<script>
-  window.MIXPANEL_CUSTOM_LIB_URL = 'bower_components/mixpanel/mixpanel.js';
+<script type="importmap">
+{
+  "imports": {
+    "mixpanel-browser": "https://cdn.mxpnl.com/libs/mixpanel-js/dist/mixpanel.module.js"
+  }
+}
 </script>
-<script src="bower_components/mixpanel/mixpanel-jslib-snippet.min.js"></script>
+<script type="module" src="main.js"></script>
 ```
-or
 
-2) Recompile the snippet with a custom `MIXPANEL_LIB_URL` using [Closure Compiler](https://developers.google.com/closure/compiler/):
-```sh
-java -jar compiler.jar --js src/loaders/mixpanel-jslib-snippet.js --js_output_file mixpanel-jslib-snippet.min.js --compilation_level ADVANCED_OPTIMIZATIONS --define='MIXPANEL_LIB_URL="bower_components/mixpanel/mixpanel.js"'
-```
+Then you are free to import `mixpanel-browser` in your javascript modules.
 
-### Upgrading from mixpanel-bower v2.2.0 or v2.0.0
-If you originally installed Mixpanel via Bower at its previous home ([https://github.com/drubin/mixpanel-bower](https://github.com/drubin/mixpanel-bower)), the two old versions have remained functionally unchanged. To upgrade to v2.3.6 or later (the first Bower version in the official repo) from a previous Bower install, note the changed filenames: previous references to `mixpanel.js` should become `mixpanel-jslib-snippet.min.js` (the minified embed code), and previous references to `mixpanel.dev.js` should become `mixpanel.js` (the library source) or `mixpanel.min.js` (the minified library for production use).
+```js
+// main.js
+import mixpanel from 'mixpanel-browser';
+
+mixpanel.init('YOUR_TOKEN', {debug: true, track_pageview: true, persistence: 'localStorage'});
+```
 
 ## Building bundles for release
 - Install development dependencies: `npm install`
@@ -87,4 +78,4 @@ Mixpanel production releases are tested against a large matrix of browsers and o
 - Publish to readme.io via the [rdme](https://www.npmjs.com/package/rdme) util: `RDME_API_KEY=<API_KEY> RDME_DOC_VERSION=<version> npm run dox-publish`
 
 ## Thanks
-For patches and support: @bohanyang, @dehau, @drubin, @D1plo1d, @feychenie, @mogstad, @pfhayes, @sandorfr, @stefansedich, @gfx, @pkaminski, @austince, @danielbaker, @mkdai, @wolever, @dpraul, @chriszamierowski, @JoaoGomesTW
+For patches and support: @bohanyang, @dehau, @drubin, @D1plo1d, @feychenie, @mogstad, @pfhayes, @sandorfr, @stefansedich, @gfx, @pkaminski, @austince, @danielbaker, @mkdai, @wolever, @dpraul, @chriszamierowski, @JoaoGomesTW, @@aliyalcinkaya

package/build.sh

@@ -27,6 +27,7 @@ if [ ! -z "$FULL" ]; then
     echo 'Building module bundles'
     npx rollup -i src/loaders/loader-module.js -f amd -o build/mixpanel.amd.js -c rollup.config.js
     npx rollup -i src/loaders/loader-module.js -f cjs -o build/mixpanel.cjs.js -c rollup.config.js
+    npx rollup -i src/loaders/loader-module.js -f es -o build/mixpanel.module.js -c rollup.config.js
     npx rollup -i src/loaders/loader-module-core.js -f cjs -o build/mixpanel-core.cjs.js -c rollup.config.js
     npx rollup -i src/loaders/loader-module-with-async-recorder.js -f cjs -o build/mixpanel-with-async-recorder.cjs.js -c rollup.config.js
     npx rollup -i src/loaders/loader-module.js -f umd -o build/mixpanel.umd.js -n mixpanel -c rollup.config.js

package/dist/mixpanel-core.cjs.js

@@ -2,7 +2,7 @@
 
 var Config = {
     DEBUG: false,
-    LIB_VERSION: '2.54.1'
+    LIB_VERSION: '2.55.1'
 };
 
 /* eslint camelcase: "off", eqeqeq: "off" */
@@ -14,7 +14,7 @@ if (typeof(window) === 'undefined') {
         hostname: ''
     };
     win = {
-        navigator: { userAgent: '' },
+        navigator: { userAgent: '', onLine: true },
         document: {
             location: loc,
             referrer: ''
@@ -968,7 +968,7 @@ _.HTTPBuildQuery = function(formdata, arg_separator) {
 _.getQueryParam = function(url, param) {
     // Expects a raw URL
 
-    param = param.replace(/[[]/, '\\[').replace(/[\]]/, '\\]');
+    param = param.replace(/[[]/g, '\\[').replace(/[\]]/g, '\\]');
     var regexS = '[\\?&]' + param + '=([^&#]*)',
         regex = new RegExp(regexS),
         results = regex.exec(url);
@@ -1425,8 +1425,8 @@ _.dom_query = (function() {
     };
 })();
 
-var CAMPAIGN_KEYWORDS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
-var CLICK_IDS = ['dclid', 'fbclid', 'gclid', 'ko_click_id', 'li_fat_id', 'msclkid', 'ttclid', 'twclid', 'wbraid'];
+var CAMPAIGN_KEYWORDS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term', 'utm_id', 'utm_source_platform','utm_campaign_id', 'utm_creative_format', 'utm_marketing_tactic'];
+var CLICK_IDS = ['dclid', 'fbclid', 'gclid', 'ko_click_id', 'li_fat_id', 'msclkid', 'sccid', 'ttclid', 'twclid', 'wbraid'];
 
 _.info = {
     campaignParams: function(default_value) {
@@ -1708,6 +1708,15 @@ var extract_domain = function(hostname) {
     return matches ? matches[0] : '';
 };
 
+/**
+ * Check whether we have network connection. default to true for browsers that don't support navigator.onLine (IE)
+ * @returns {boolean}
+ */
+var isOnline = function() {
+    var onLine = win.navigator['onLine'];
+    return _.isUndefined(onLine) || onLine;
+};
+
 var JSONStringify = null, JSONParse = null;
 if (typeof JSON !== 'undefined') {
     JSONStringify = JSON.stringify;
@@ -2523,7 +2532,12 @@ RequestBatcher.prototype.flush = function(options) {
                     this.flush();
                 } else if (
                     _.isObject(res) &&
-                    (res.httpStatusCode >= 500 || res.httpStatusCode === 429 || res.error === 'timeout')
+                    (
+                        res.httpStatusCode >= 500
+                        || res.httpStatusCode === 429
+                        || (res.httpStatusCode <= 0 && !isOnline())
+                        || res.error === 'timeout'
+                    )
                 ) {
                     // network or API error, or 429 Too Many Requests, retry
                     var retryMS = this.flushInterval * 2;
@@ -4247,6 +4261,7 @@ var DEFAULT_CONFIG = {
     'record_mask_text_class':            new RegExp('^(mp-mask|fs-mask|amp-mask|rr-mask|ph-mask)$'),
     'record_mask_text_selector':         '*',
     'record_max_ms':                     MAX_RECORDING_MS,
+    'record_min_ms':                     0,
     'record_sessions_percent':           0,
     'recorder_src':                      'https://cdn.mxpnl.com/libs/mixpanel-recorder.min.js'
 };

package/dist/mixpanel-recorder.js

@@ -4510,7 +4510,7 @@
 
     var Config = {
         DEBUG: false,
-        LIB_VERSION: '2.54.1'
+        LIB_VERSION: '2.55.1'
     };
 
     /* eslint camelcase: "off", eqeqeq: "off" */
@@ -4522,7 +4522,7 @@
             hostname: ''
         };
         win = {
-            navigator: { userAgent: '' },
+            navigator: { userAgent: '', onLine: true },
             document: {
                 location: loc,
                 referrer: ''
@@ -4536,6 +4536,8 @@
 
     // Maximum allowed session recording length
     var MAX_RECORDING_MS = 24 * 60 * 60 * 1000; // 24 hours
+    // Maximum allowed value for minimum session recording length
+    var MAX_VALUE_FOR_MIN_RECORDING_MS = 8 * 1000; // 8 seconds
 
     /*
      * Saved references to long variable names, so that closure compiler can
@@ -5447,7 +5449,7 @@
     _.getQueryParam = function(url, param) {
         // Expects a raw URL
 
-        param = param.replace(/[[]/, '\\[').replace(/[\]]/, '\\]');
+        param = param.replace(/[[]/g, '\\[').replace(/[\]]/g, '\\]');
         var regexS = '[\\?&]' + param + '=([^&#]*)',
             regex = new RegExp(regexS),
             results = regex.exec(url);
@@ -5904,8 +5906,8 @@
         };
     })();
 
-    var CAMPAIGN_KEYWORDS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
-    var CLICK_IDS = ['dclid', 'fbclid', 'gclid', 'ko_click_id', 'li_fat_id', 'msclkid', 'ttclid', 'twclid', 'wbraid'];
+    var CAMPAIGN_KEYWORDS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term', 'utm_id', 'utm_source_platform','utm_campaign_id', 'utm_creative_format', 'utm_marketing_tactic'];
+    var CLICK_IDS = ['dclid', 'fbclid', 'gclid', 'ko_click_id', 'li_fat_id', 'msclkid', 'sccid', 'ttclid', 'twclid', 'wbraid'];
 
     _.info = {
         campaignParams: function(default_value) {
@@ -6187,6 +6189,15 @@
         return matches ? matches[0] : '';
     };
 
+    /**
+     * Check whether we have network connection. default to true for browsers that don't support navigator.onLine (IE)
+     * @returns {boolean}
+     */
+    var isOnline = function() {
+        var onLine = win.navigator['onLine'];
+        return _.isUndefined(onLine) || onLine;
+    };
+
     var JSONStringify = null, JSONParse = null;
     if (typeof JSON !== 'undefined') {
         JSONStringify = JSON.stringify;
@@ -7018,7 +7029,12 @@
                         this.flush();
                     } else if (
                         _.isObject(res) &&
-                        (res.httpStatusCode >= 500 || res.httpStatusCode === 429 || res.error === 'timeout')
+                        (
+                            res.httpStatusCode >= 500
+                            || res.httpStatusCode === 429
+                            || (res.httpStatusCode <= 0 && !isOnline())
+                            || res.error === 'timeout'
+                        )
                     ) {
                         // network or API error, or 429 Too Many Requests, retry
                         var retryMS = this.flushInterval * 2;
@@ -7169,6 +7185,7 @@
         this.maxTimeoutId = null;
 
         this.recordMaxMs = MAX_RECORDING_MS;
+        this.recordMinMs = 0;
         this._initBatcher();
     };
 
@@ -7200,16 +7217,24 @@
             logger.critical('record_max_ms cannot be greater than ' + MAX_RECORDING_MS + 'ms. Capping value.');
         }
 
+        this.recordMinMs = this.get_config('record_min_ms');
+        if (this.recordMinMs > MAX_VALUE_FOR_MIN_RECORDING_MS) {
+            this.recordMinMs = MAX_VALUE_FOR_MIN_RECORDING_MS;
+            logger.critical('record_min_ms cannot be greater than ' + MAX_VALUE_FOR_MIN_RECORDING_MS + 'ms. Capping value.');
+        }
+
         this.recEvents = [];
         this.seqNo = 0;
-        this.replayStartTime = null;
+        this.replayStartTime = new Date().getTime();
 
         this.replayId = _.UUID();
 
-        if (shouldStopBatcher) {
-            // this is the case when we're starting recording after a reset
+        if (shouldStopBatcher || this.recordMinMs > 0) {
+            // the primary case for shouldStopBatcher is when we're starting recording after a reset
             // and don't want to send anything over the network until there's
             // actual user activity
+            // this also applies if the minimum recording length has not been hit yet
+            // so that we don't send data until we know the recording will be long enough
             this.batcher.stop();
         } else {
             this.batcher.start();
@@ -7223,11 +7248,16 @@
             }, this), this.get_config('record_idle_timeout_ms'));
         }, this);
 
+        var blockSelector = this.get_config('record_block_selector');
+        if (blockSelector === '' || blockSelector === null) {
+            blockSelector = undefined;
+        }
+
         this._stopRecording = record({
             'emit': _.bind(function (ev) {
                 this.batcher.enqueue(ev);
                 if (isUserEvent(ev)) {
-                    if (this.batcher.stopped) {
+                    if (this.batcher.stopped && new Date().getTime() - this.replayStartTime >= this.recordMinMs) {
                         // start flushing again after user activity
                         this.batcher.start();
                     }
@@ -7235,7 +7265,7 @@
                 }
             }, this),
             'blockClass': this.get_config('record_block_class'),
-            'blockSelector': this.get_config('record_block_selector'),
+            'blockSelector': blockSelector,
             'collectFonts': this.get_config('record_collect_fonts'),
             'inlineImages': this.get_config('record_inline_images'),
             'maskAllInputs': true,
@@ -7289,14 +7319,14 @@
         }
     };
 
-    MixpanelRecorder.prototype._sendRequest = function(reqParams, reqBody, callback) {
+    MixpanelRecorder.prototype._sendRequest = function(currentReplayId, reqParams, reqBody, callback) {
         var onSuccess = _.bind(function (response, responseBody) {
             // Increment sequence counter only if the request was successful to guarantee ordering.
             // RequestBatcher will always flush the next batch after the previous one succeeds.
-            if (response.status === 200) {
+            // extra check to see if the replay ID has changed so that we don't increment the seqNo on the wrong replay
+            if (response.status === 200 && this.replayId === currentReplayId) {
                 this.seqNo++;
             }
-
             callback({
                 status: 0,
                 httpStatusCode: response.status,
@@ -7319,7 +7349,7 @@
                 callback({error: error});
             });
         }).catch(function (error) {
-            callback({error: error});
+            callback({error: error, httpStatusCode: 0});
         });
     };
 
@@ -7327,9 +7357,15 @@
         const numEvents = data.length;
 
         if (numEvents > 0) {
+            var replayId = this.replayId;
             // each rrweb event has a timestamp - leverage those to get time properties
             var batchStartTime = data[0].timestamp;
-            if (this.seqNo === 0) {
+            if (this.seqNo === 0 || !this.replayStartTime) {
+                // extra safety net so that we don't send a null replay start time
+                if (this.seqNo !== 0) {
+                    this.reportError('Replay start time not set but seqNo is not 0. Using current batch start time as a fallback.');
+                }
+
                 this.replayStartTime = batchStartTime;
             }
             var replayLengthMs = data[numEvents - 1].timestamp - this.replayStartTime;
@@ -7338,7 +7374,7 @@
                 'distinct_id': String(this._mixpanel.get_distinct_id()),
                 'seq': this.seqNo,
                 'batch_start_time': batchStartTime / 1000,
-                'replay_id': this.replayId,
+                'replay_id': replayId,
                 'replay_length_ms': replayLengthMs,
                 'replay_start_time': this.replayStartTime / 1000
             };
@@ -7361,11 +7397,11 @@
                     .blob()
                     .then(_.bind(function(compressedBlob) {
                         reqParams['format'] = 'gzip';
-                        this._sendRequest(reqParams, compressedBlob, callback);
+                        this._sendRequest(replayId, reqParams, compressedBlob, callback);
                     }, this));
             } else {
                 reqParams['format'] = 'body';
-                this._sendRequest(reqParams, eventsJson, callback);
+                this._sendRequest(replayId, reqParams, eventsJson, callback);
             }
         }
     });