mixpanel-browser 2.48.1 → 2.50.0

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.50.0",
   "description": "The official Mixpanel JavaScript browser client library",
   "main": "dist/mixpanel.cjs.js",
   "directories": {
@@ -32,6 +32,7 @@
   },
   "homepage": "https://github.com/mixpanel/mixpanel-js",
   "devDependencies": {
+    "@rollup/plugin-node-resolve": "15.2.3",
     "babel": "6.5.2",
     "babel-core": "6.7.2",
     "babel-preset-es2015": "6.6.0",
@@ -51,10 +52,14 @@
     "morgan": "1.9.1",
     "rdme": "7.5.0",
     "request": "2.88.0",
-    "rollup": "0.25.8",
+    "rollup": "2.79.1",
+    "rollup-plugin-esbuild": "4.10.3",
     "rollup-plugin-npm": "1.4.0",
     "sinon": "8.1.1",
     "sinon-chai": "3.5.0",
     "webpack": "1.12.2"
+  },
+  "dependencies": {
+    "rrweb": "2.0.0-alpha.4"
   }
 }

package/src/config.js

@@ -1,6 +1,6 @@
 var Config = {
     DEBUG: false,
-    LIB_VERSION: '2.48.1'
+    LIB_VERSION: '2.50.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');

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

@@ -0,0 +1,114 @@
+# Mixpanel JavaScript SDK wrapper for Google Tag Manager
+The purpose of this wrapper is to provide a JavaScript interface for interacting with the `window.mixpanel` interface.
+
+The wrapper has been designed with [Google Tag Manager](https://tagmanager.google.com) in mind. GTM's [custom templates](https://developers.google.com/tag-manager/templates) offer a way to deploy custom JavaScript without having to resort to Custom HTML tags and with the ability to craft a user interface for the scripts within Google Tag Manager.
+
+However, one of the defining features of custom templates is their [sandboxed JavaScript API](https://developers.google.com/tag-manager/templates/sandboxed-javascript) inventory, which severely restricts what type of browser JavaScript can be executed in the template code.
+
+Mixpanel's [JavaScript SDK](https://developer.mixpanel.com/docs/javascript-full-api-reference) makes use of JavaScript features which are not permitted by the sandbox of GTM's custom templates (e.g. object instances initiated with the `new` keyword, `this` and `prototype`, etc.).
+
+Thus, in order to interact with Mixpanel's JavaScript SDK via Google Tag Manager's custom templates (or any other context where the aforementioned JavaScript features cannot be used), this wrapper is required. [The template loads this wrapper](https://github.com/mixpanel/mixpanel-gtm-template/blob/2f577d826acc7d96d138367db339035b8f9df359/src/template.tpl#L1383) in the sandboxed template code.
+
+# Deployment
+The wrapper is served by the Mixpanel CDN at https://cdn.mxpnl.com/libs/mixpanel-js-wrapper.js
+
+# How it works
+When the wrapper JavaScript is loaded in the browser, the global method `window._mixpanel()` is created for interacting with the wrapper.
+
+This namespace includes all the methods supported by the [JavaScript SDK](https://developer.mixpanel.com/docs/javascript-full-api-reference) with some exceptions (see below). Each method can be invoked by passing the command name as the first argument of the call to `window._mixpanel()`.
+
+If this command name is prefixed with `<string>.`, then `<string>` will be used as the [library name](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelinit). After the command, all additional arguments are processed as arguments to the command method itself.
+
+For example, to dispatch an event named `Add To Cart` using a custom library name, you could use this command:
+
+```
+window._mixpanel(
+    'myTracker.track', // Run the track command and utilize the library name "myTracker"
+    'Add To Cart', // Event name is the first argument to the track command
+    {product_id: 'shirt123'} // (optional) Event parameters are the second argument to the track command
+);
+```
+
+## `group`
+[Link to specification](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelgroup)
+
+Use this command to interact with group properties.
+
+Syntax:
+
+`window._mixpanel('<library_name.>group.<group_command>', ['<group_key>', '<group_id>'], <parameters>)`
+
+Example:
+```
+// Union a property for a group
+window._mixpanel(
+    'group.union',
+    ['my_group_key', 'my_group_id'],
+    'location',
+    ['San Francisco', 'London']
+);
+```
+
+| Parameter name | Description |
+|----------------|-------------|
+| `library_name` | (Optional) target a specific library/instance name with this command |
+| `group_command` | (Required) one of `set`, `set_once`, `remove`, `union`, `unset` |
+| `parameters` | All the parameters you want to submit to the `group` command. |
+
+## `people`
+[Link to specification](https://developer.mixpanel.com/docs/javascript-full-api-reference#mixpanelpeople)
+
+Interact with the people analytics property.
+
+Syntax:
+
+`window._mixpanel('<library_name.>people.<people_command>', <parameters>)`
+
+Example:
+```
+// Set the "gender" property "n/a"
+window._mixpanel(
+    'people.set',
+    'gender',
+    'n/a'
+);
+```
+
+| Parameter name | Description |
+|----------------|-------------|
+| `library_name` | (Optional) target a specific library/instance name with this command |
+| `people_command` | (Required) one of `append`, `clear_charge`, `delete_user`, `increment`, `remove`, `set`, `set_once`, `track_charge`, `union`, `unset` |
+| `parameters` | All the parameters you want to submit to the `people` command. |
+
+## Other commands
+
+All other commands can be sent to the `_mixpanel` interface like this:
+
+`window._mixpanel('<library_name.><command_name>', <parameters>)`
+
+Example:
+
+```
+window._mixpanel(
+    'my_mixpanel.register',
+    {'Account Type': 'Free'}
+);
+```
+
+## Exceptions
+
+Because the wrapper only pipes commands to the actual `window.mixpanel` interface, the wrapper cannot be used for get-methods. So the following commands **are not** supported by the wrapper:
+
+`get_config`
+`get_distinct_id`
+`get_group`
+`get_property`
+`has_opted_in_tracking`
+`has_opted_out_tracking`
+
+The following commands are also disabled due to not being relevant with the wrapper:
+
+`push`
+`init`
+
+Initialization is done with the `window.mixpanel` interface directly, and `push` is already used by the wrapper to forward calls to the main interface.