mixpanel-browser 2.48.1 → 2.49.0

package/dist/mixpanel.umd.js

@@ -6,7 +6,7 @@
 
     var Config = {
         DEBUG: false,
-        LIB_VERSION: '2.48.1'
+        LIB_VERSION: '2.49.0'
     };
 
     // since es6 imports are static and we run unit tests from the console, window won't be defined when importing this file
@@ -905,6 +905,7 @@
     // sending false tracking data
     var BLOCKED_UA_STRS = [
         'ahrefsbot',
+        'ahrefssiteaudit',
         'baiduspider',
         'bingbot',
         'bingpreview',
@@ -1625,7 +1626,14 @@
             return '';
         },
 
-        properties: function() {
+        currentUrl: function() {
+            return window$1.location.href;
+        },
+
+        properties: function(extra_props) {
+            if (typeof extra_props !== 'object') {
+                extra_props = {};
+            }
             return _.extend(_.strip_empty_properties({
                 '$os': _.info.os(),
                 '$browser': _.info.browser(userAgent, navigator.vendor, windowOpera),
@@ -1633,7 +1641,7 @@
                 '$referring_domain': _.info.referringDomain(document$1.referrer),
                 '$device': _.info.device(userAgent)
             }), {
-                '$current_url': window$1.location.href,
+                '$current_url': _.info.currentUrl(),
                 '$browser_version': _.info.browserVersion(userAgent, navigator.vendor, windowOpera),
                 '$screen_height': screen.height,
                 '$screen_width': screen.width,
@@ -1641,7 +1649,7 @@
                 '$lib_version': Config.LIB_VERSION,
                 '$insert_id': cheap_guid(),
                 'time': _.timestamp() / 1000 // epoch time in seconds
-            });
+            }, _.strip_empty_properties(extra_props));
         },
 
         people_properties: function() {
@@ -3207,7 +3215,6 @@
         data[SET_ACTION] = _.extend(
             {},
             _.info.people_properties(),
-            this._mixpanel['persistence'].get_referrer_info(),
             data[SET_ACTION]
         );
         return this._send_request(data, callback);
@@ -4167,10 +4174,12 @@
         'cookie_domain':                     '',
         'cookie_name':                       '',
         'loaded':                            NOOP_FUNC,
+        'mp_loader':                         null,
         'track_marketing':                   true,
         'track_pageview':                    false,
         'skip_first_touch_marketing':        false,
         'store_google':                      true,
+        'stop_utm_persistence':              false,
         'save_referrer':                     true,
         'test':                              false,
         'verbose':                           false,
@@ -4404,8 +4413,9 @@
             }, '');
         }
 
-        if (this.get_config('track_pageview')) {
-            this.track_pageview();
+        var track_pageview_option = this.get_config('track_pageview');
+        if (track_pageview_option) {
+            this._init_url_change_tracking(track_pageview_option);
         }
     };
 
@@ -4414,12 +4424,25 @@
     MixpanelLib.prototype._loaded = function() {
         this.get_config('loaded')(this);
         this._set_default_superprops();
+        this['people'].set_once(this['persistence'].get_referrer_info());
+
+        // The original 'store_google' functionality will be deprecated and the config will be
+        // used to clear previously managed UTM parameters from persistence.
+        // stop_utm_persistence is `false` by default now but will be default `true` in the future.
+        if (this.get_config('store_google') && this.get_config('stop_utm_persistence')) {
+            var utm_params = _.info.campaignParams(null);
+            _.each(utm_params, function(_utm_value, utm_key) {
+                // We need to unregister persisted UTM parameters so old values
+                // are not mixed with the new UTM parameters
+                this.unregister(utm_key);
+            }.bind(this));
+        }
     };
 
     // update persistence with info on referrer, UTM params, etc
     MixpanelLib.prototype._set_default_superprops = function() {
         this['persistence'].update_search_keyword(document$1.referrer);
-        if (this.get_config('store_google')) {
+        if (this.get_config('store_google') && !this.get_config('stop_utm_persistence')) {
             this.register(_.info.campaignParams());
         }
         if (this.get_config('save_referrer')) {
@@ -4457,6 +4480,55 @@
         return dt.track.apply(dt, args);
     };
 
+    MixpanelLib.prototype._init_url_change_tracking = function(track_pageview_option) {
+        var previous_tracked_url = '';
+        var tracked = this.track_pageview();
+        if (tracked) {
+            previous_tracked_url = _.info.currentUrl();
+        }
+
+        if (_.include(['full-url', 'url-with-path-and-query-string', 'url-with-path'], track_pageview_option)) {
+            window$1.addEventListener('popstate', function() {
+                window$1.dispatchEvent(new Event('mp_locationchange'));
+            });
+            window$1.addEventListener('hashchange', function() {
+                window$1.dispatchEvent(new Event('mp_locationchange'));
+            });
+            var nativePushState = window$1.history.pushState;
+            if (typeof nativePushState === 'function') {
+                window$1.history.pushState = function(state, unused, url) {
+                    nativePushState.call(window$1.history, state, unused, url);
+                    window$1.dispatchEvent(new Event('mp_locationchange'));
+                };
+            }
+            var nativeReplaceState = window$1.history.replaceState;
+            if (typeof nativeReplaceState === 'function') {
+                window$1.history.replaceState = function(state, unused, url) {
+                    nativeReplaceState.call(window$1.history, state, unused, url);
+                    window$1.dispatchEvent(new Event('mp_locationchange'));
+                };
+            }
+            window$1.addEventListener('mp_locationchange', function() {
+                var current_url = _.info.currentUrl();
+                var should_track = false;
+                if (track_pageview_option === 'full-url') {
+                    should_track = current_url !== previous_tracked_url;
+                } else if (track_pageview_option === 'url-with-path-and-query-string') {
+                    should_track = current_url.split('#')[0] !== previous_tracked_url.split('#')[0];
+                } else if (track_pageview_option === 'url-with-path') {
+                    should_track = current_url.split('#')[0].split('?')[0] !== previous_tracked_url.split('#')[0].split('?')[0];
+                }
+
+                if (should_track) {
+                    var tracked = this.track_pageview();
+                    if (tracked) {
+                        previous_tracked_url = current_url;
+                    }
+                }
+            }.bind(this));
+        }
+    };
+
     /**
      * _prepare_callback() should be called by callers of _send_request for use
      * as the callback argument.
@@ -4925,7 +4997,7 @@
         // update properties with pageview info and super-properties
         properties = _.extend(
             {},
-            _.info.properties(),
+            _.info.properties({'mp_loader': this.get_config('mp_loader')}),
             marketing_properties,
             this['persistence'].properties(),
             this.unpersisted_superprops,
@@ -5089,10 +5161,9 @@
 
     /**
      * Track a default Mixpanel page view event, which includes extra default event properties to
-     * improve page view data. The `config.track_pageview` option for <a href="#mixpanelinit">mixpanel.init()</a>
-     * may be turned on for tracking page loads automatically.
+     * improve page view data.
      *
-     * ### Usage
+     * ### Usage:
      *
      *     // track a default $mp_web_page_view event
      *     mixpanel.track_pageview();
@@ -5109,6 +5180,23 @@
      *     // views on different products or internal applications that are considered completely separate
      *     mixpanel.track_pageview({'page': 'customer-search'}, {'event_name': '[internal] Admin Page View'});
      *
+     * ### Notes:
+     *
+     * The `config.track_pageview` option for <a href="#mixpanelinit">mixpanel.init()</a>
+     * may be turned on for tracking page loads automatically.
+     *
+     *     // track only page loads
+     *     mixpanel.init(PROJECT_TOKEN, {track_pageview: true});
+     *
+     *     // track when the URL changes in any manner
+     *     mixpanel.init(PROJECT_TOKEN, {track_pageview: 'full-url'});
+     *
+     *     // track when the URL changes, ignoring any changes in the hash part
+     *     mixpanel.init(PROJECT_TOKEN, {track_pageview: 'url-with-path-and-query-string'});
+     *
+     *     // track when the path changes, ignoring any query parameter or hash changes
+     *     mixpanel.init(PROJECT_TOKEN, {track_pageview: 'url-with-path'});
+     *
      * @param {Object} [properties] An optional set of additional properties to send with the page view event
      * @param {Object} [options] Page view tracking options
      * @param {String} [options.event_name] - Alternate name for the tracking event
@@ -5859,7 +5947,7 @@
     /**
      * Opt the user in to data tracking and cookies/localstorage for this Mixpanel instance
      *
-     * ### Usage
+     * ### Usage:
      *
      *     // opt user in
      *     mixpanel.opt_in_tracking();
@@ -5899,7 +5987,7 @@
     /**
      * Opt the user out of data tracking and cookies/localstorage for this Mixpanel instance
      *
-     * ### Usage
+     * ### Usage:
      *
      *     // opt user out
      *     mixpanel.opt_out_tracking();
@@ -5940,7 +6028,7 @@
     /**
      * Check whether the user has opted in to data tracking and cookies/localstorage for this Mixpanel instance
      *
-     * ### Usage
+     * ### Usage:
      *
      *     var has_opted_in = mixpanel.has_opted_in_tracking();
      *     // use has_opted_in value
@@ -5957,7 +6045,7 @@
     /**
      * Check whether the user has opted out of data tracking and cookies/localstorage for this Mixpanel instance
      *
-     * ### Usage
+     * ### Usage:
      *
      *     var has_opted_out = mixpanel.has_opted_out_tracking();
      *     // use has_opted_out value
@@ -5974,7 +6062,7 @@
     /**
      * Clear the user's opt in/out status of data tracking and cookies/localstorage for this Mixpanel instance
      *
-     * ### Usage
+     * ### Usage:
      *
      *     // clear user's opt-in/out status
      *     mixpanel.clear_opt_in_out_tracking();

package/doc/readme.io/javascript-full-api-reference.md

@@ -78,6 +78,20 @@ ___
 Clear the user's opt in/out status of data tracking and cookies/localstorage for this Mixpanel instance
 
 
+### Usage:
+
+```javascript
+// clear user's opt-in/out status
+mixpanel.clear_opt_in_out_tracking();
+
+// clear user's opt-in/out status with specific cookie configuration - should match
+// configuration used when opt_in_tracking/opt_out_tracking methods were called.
+mixpanel.clear_opt_in_out_tracking({
+    cookie_expiration: 30,
+    secure_cookie: true
+});
+```
+
 
 
 | Argument | Type | Description |
@@ -189,6 +203,13 @@ ___
 Check whether the user has opted in to data tracking and cookies/localstorage for this Mixpanel instance
 
 
+### Usage:
+
+```javascript
+var has_opted_in = mixpanel.has_opted_in_tracking();
+// use has_opted_in value
+```
+
 
 
 | Argument | Type | Description |
@@ -207,6 +228,13 @@ ___
 Check whether the user has opted out of data tracking and cookies/localstorage for this Mixpanel instance
 
 
+### Usage:
+
+```javascript
+var has_opted_out = mixpanel.has_opted_out_tracking();
+// use has_opted_out value
+```
+
 
 
 | Argument | Type | Description |
@@ -271,6 +299,23 @@ ___
 Opt the user in to data tracking and cookies/localstorage for this Mixpanel instance
 
 
+### Usage:
+
+```javascript
+// opt user in
+mixpanel.opt_in_tracking();
+
+// opt user in with specific event name, properties, cookie configuration
+mixpanel.opt_in_tracking({
+    track_event_name: 'User opted in',
+    track_event_properties: {
+        'Email': 'jdoe@example.com'
+    },
+    cookie_expiration: 30,
+    secure_cookie: true
+});
+```
+
 
 
 | Argument | Type | Description |
@@ -294,6 +339,19 @@ ___
 Opt the user out of data tracking and cookies/localstorage for this Mixpanel instance
 
 
+### Usage:
+
+```javascript
+// opt user out
+mixpanel.opt_out_tracking();
+
+// opt user out with different cookie configuration from Mixpanel instance
+mixpanel.opt_out_tracking({
+    cookie_expiration: 30,
+    secure_cookie: true
+});
+```
+
 
 
 | Argument | Type | Description |
@@ -438,6 +496,16 @@ The default config is:
 
 ```javascript
 {
+  // host for requests (customizable for e.g. a local proxy)
+  api_host: 'https://api-js.mixpanel.com',
+
+  // endpoints for different types of requests
+  api_routes: {
+    track: 'track/',
+    engage: 'engage/',
+    groups: 'groups/',
+  }
+
   // HTTP method for tracking requests
   api_method: 'POST'
 
@@ -696,9 +764,47 @@ If you pass a function in as the properties argument, the  function will receive
 
 ___
 ## mixpanel.track_pageview
-Track a default Mixpanel page view event, which includes extra default event properties to  improve page view data. The <code>config.track_pageview</code> option for <a href="#mixpanelinit">mixpanel.init()</a>  may be turned on for tracking page loads automatically.
+Track a default Mixpanel page view event, which includes extra default event properties to  improve page view data.
+
+
+### Usage:
+
+```javascript
+// track a default $mp_web_page_view event
+mixpanel.track_pageview();
+
+// track a page view event with additional event properties
+mixpanel.track_pageview({'ab_test_variant': 'card-layout-b'});
 
+// example approach to track page views on different page types as event properties
+mixpanel.track_pageview({'page': 'pricing'});
+mixpanel.track_pageview({'page': 'homepage'});
 
+// UNCOMMON: Tracking a page view event with a custom event_name option. NOT expected to be used for
+// individual pages on the same site or product. Use cases for custom event_name may be page
+// views on different products or internal applications that are considered completely separate
+mixpanel.track_pageview({'page': 'customer-search'}, {'event_name': '[internal] Admin Page View'});
+
+```
+
+
+### Notes:
+The <code>config.track_pageview</code> option for <a href="#mixpanelinit">mixpanel.init()</a>  may be turned on for tracking page loads automatically.
+
+
+```javascript
+// track only page loads
+mixpanel.init(PROJECT_TOKEN, {track_pageview: true});
+
+// track when the URL changes in any manner
+mixpanel.init(PROJECT_TOKEN, {track_pageview: 'full-url'});
+
+// track when the URL changes, ignoring any changes in the hash part
+mixpanel.init(PROJECT_TOKEN, {track_pageview: 'url-with-path-and-query-string'});
+
+// track when the path changes, ignoring any query parameter or hash changes
+mixpanel.init(PROJECT_TOKEN, {track_pageview: 'url-with-path'});
+```
 
 
 | Argument | Type | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixpanel-browser",
-  "version": "2.48.1",
+  "version": "2.49.0",
   "description": "The official Mixpanel JavaScript browser client library",
   "main": "dist/mixpanel.cjs.js",
   "directories": {

package/src/config.js

@@ -1,6 +1,6 @@
 var Config = {
     DEBUG: false,
-    LIB_VERSION: '2.48.1'
+    LIB_VERSION: '2.49.0'
 };
 
 export default Config;

package/src/loaders/loader-globals.js

@@ -0,0 +1,4 @@
+/* eslint camelcase: "off" */
+import { init_from_snippet } from '../mixpanel-core';
+
+init_from_snippet();

package/src/{loader-module.js → loaders/loader-module.js}

@@ -1,5 +1,5 @@
 /* eslint camelcase: "off" */
-import { init_as_module } from './mixpanel-core';
+import { init_as_module } from '../mixpanel-core';
 
 var mixpanel = init_as_module();
 

package/src/loaders/mixpanel-js-wrapper.js

@@ -0,0 +1,143 @@
+import './mixpanel-jslib-snippet';
+
+/*
+ * @see src/loaders/mixpanel-js-wrapper.md
+ */
+(function (win, wrapper) {
+
+    // If window.mixpanel doesn't exist, return
+    if (!win['mixpanel'] || typeof win['mixpanel']['init'] !== 'function') return;
+
+    // Enumerate available commands
+    var commandEnum = [
+        'add_group',
+        'alias',
+        'clear_opt_in_out_tracking',
+        'disable',
+        /* Ignore getters
+        'get_config',
+        'get_distinct_id',
+        'get_group',
+        'get_property',
+        'has_opted_in_tracking',
+        'has_opted_out_tracking',
+        */
+        /* Ignore init
+        'init'
+        */
+        'identify',
+        'opt_in_tracking',
+        'opt_out_tracking',
+        /* Ignore push
+        'push',
+        */
+        'register',
+        'register_once',
+        'remove_group',
+        'reset',
+        'set_config',
+        'set_group',
+        'time_event',
+        'track',
+        'track_forms',
+        'track_links',
+        'track_pageview',
+        'track_with_groups',
+        'unregister',
+        'people.append',
+        'people.clear_charges',
+        'people.delete_user',
+        'people.increment',
+        'people.remove',
+        'people.set',
+        'people.set_once',
+        'people.track_charge',
+        'people.union',
+        'people.unset',
+        'group.remove',
+        'group.set',
+        'group.set_once',
+        'group.union',
+        'group.unset'
+    ];
+
+    /* The people API can't be used with the .push() interface, so it requires its
+     * own helper method. To interact with it, simply use the _mixpanel interface
+     * as before.
+     *
+     * window._mixpanel('<libraryName.>people.set', 'gender', 'm');
+     *
+     */
+    var people = function (mp, cmd, args) {
+        // Extract the command
+        var peopleCmd = cmd.split('.').pop();
+
+        // Call the respective mixpanel method
+        mp['people'][peopleCmd].apply(mp['people'], args);
+    };
+
+    /* To utilize the group API, the command must include the group key and ID as
+     * an array in the second argument.
+     *
+     * window._mixpanel('<libraryName.>.group.set', ['group_key', 'group_id'], {
+     *   someGroupProperty: 'someGroupValue'
+     * });
+     *
+     */
+    var group = function (mp, cmd, args) {
+        // Extract the command
+        var groupCmd = cmd.split('.').pop();
+
+        // Extract the group info
+        var groupInfo = args.shift();
+
+        // Validate the group array
+        if (!Array.isArray(groupInfo) || groupInfo.length !== 2) return;
+
+        // Get group reference
+        var group = mp['get_group'].apply(mp, groupInfo);
+
+        // Call the respective group method
+        group[groupCmd].apply(group, args);
+
+    };
+
+    // Build the command wrapper logic
+    win[wrapper] = win[wrapper] || function () {
+
+        // Build array out of arguments
+        var args = [].slice.call(arguments, 0);
+
+        // Pick the first argument as the command
+        var cmd = args.shift();
+
+        /* Commands can be passed to different namespaces with syntax:
+         * window._mixpanel('libraryName.command', arguments)
+         */
+        var libraryName = null;
+        var cmdParts = cmd.match(/^([^.]+)\.(.+)$/);
+        if (cmdParts && cmdParts.length === 3 && !/people|group/.test(cmdParts[1])) {
+            libraryName = cmdParts[1];
+            cmd = cmdParts[2];
+        }
+
+        // If libraryName is set, use that as the mixpanel interface
+        var mp = libraryName ? window['mixpanel'][libraryName] : window['mixpanel'];
+
+        // Return if namespace not found
+        if (!mp) return;
+
+        // If cmd is not one of the available ones, return
+        if (commandEnum.indexOf(cmd) === -1) return;
+
+        // Handle people command
+        if (/^people\./.test(cmd)) return people(mp, cmd, args);
+
+        // Handle group command
+        if (/^group\./.test(cmd)) return group(mp, cmd, args);
+
+        // Push the command to mixpanel
+        return mp.push.apply(mp, [[cmd].concat(args)]);
+
+    };
+})(window, '_mixpanel');