Merge pull request #62 from amplitude/revert-61-revert-60-set_group

Set Group

Author: djih

CHANGELOG.md

@@ -1,5 +1,6 @@
 ## Unreleased
 
+* Add support for setting groups for users and events. See the [Readme](https://github.com/amplitude/Amplitude-Javascript#setting-groups) for more information.
 * Add `logRevenueV2` and new `Revenue` class to support logging revenue events with properties, and revenue type. See [Readme](https://github.com/amplitude/Amplitude-Javascript#tracking-revenue) for more info.
 * Add helper method to regenerate a new random deviceId. This can be used to anonymize a user after they log out. Note this is not recommended unless you know what are you doing. See [Readme](https://github.com/amplitude/Amplitude-Javascript#logging-out-and-anonymous-users) for more information.
 

README.md

@@ -18,7 +18,7 @@ This Readme will guide you through using Amplitude's Javascript SDK to track use
           return this}}var o=function(){this._q=[];return this};var a=["add","append","clearAll","prepend","set","setOnce","unset"];
           for(var u=0;u<a.length;u++){i(o,a[u])}n.Identify=o;var c=function(){this._q=[];return this;
           };var p=["setProductId","setQuantity","setPrice","setRevenueType","setEventProperties"];
-          for(var l=0;l<p.length;l++){i(c,p[l])}n.Revenue=c;var d=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties","logRevenueV2","regenerateDeviceId"];
+          for(var l=0;l<p.length;l++){i(c,p[l])}n.Revenue=c;var d=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties","setGroup","logRevenueV2","regenerateDeviceId"];
           function v(e){function t(t){e[t]=function(){e._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
           }}for(var n=0;n<d.length;n++){t(d[n])}}v(n);e.amplitude=n})(window,document);
 
@@ -266,6 +266,29 @@ amplitude.init('YOUR_API_KEY_HERE', null, {
 # Advanced #
 This SDK automatically grabs useful data about the browser, including browser type and operating system version.
 
+### Setting Groups ###
+
+Amplitude supports assigning users to groups, and performing queries such as Count by Distinct on those groups. An example would be if you want to group your users based on what organization they are in by using an orgId. You can designate Joe to be in orgId 10, while Sue is in orgId 15. When performing an event segmentation query, you can then select Count by Distinct orgIds to query the number of different orgIds that have performed a specific event. As long as at least one member of that group has performed the specific event, that group will be included in the count. See our help article on [Count By Distinct]() for more information.
+
+When setting groups you need to define a `groupType` and `groupName`(s). In the above example, 'orgId' is a `groupType`, and the value 10 or 15 is the `groupName`. Another example of a `groupType` could be 'sport' with `groupNames` like 'tennis', 'baseball', etc.
+
+You can use `setGroup(groupType, groupName)` to designate which groups a user belongs to. Note: this will also set the `groupType`: `groupName` as a user property. **This will overwrite any existing groupName value set for that user's groupType, as well as the corresponding user property value.** `groupType` is a string, and `groupName` can be either a string or an array of strings to indicate a user being in multiple groups (for example Joe is in orgId 10 and 16, so the `groupName` would be [10, 16]).
+
+```javascript
+amplitude.setGroup('orgId', '15');
+amplitude.setGroup('sport', ['soccer', 'tennis']);
+```
+
+You can also use `logEventWithGroups` to set event-level groups, meaning the group designation only applies for the specific event being logged and does not persist on the user (unless you explicitly set it with `setGroup`).
+
+```javascript
+var eventProperties = {
+  'key': 'value'
+}
+
+amplitude.logEventWithGroups('initialize_game', eventProperties, {'sport': 'soccer'});
+```
+
 ### Setting Version Name ###
 By default, no version name is set. You can specify a version name to distinguish between different versions of your site by calling `setVersionName`:
 

amplitude-segment-snippet.min.js

@@ -1,8 +1,8 @@
 (function(e,t){var r=e.amplitude||{_q:[]};function n(e,t){e.prototype[t]=function(){
-this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));return this}}var i=function(){
-this._q=[];return this};var s=["add","append","clearAll","prepend","set","setOnce","unset"];
-for(var o=0;o<s.length;o++){n(i,s[o])}r.Identify=i;var a=function(){this._q=[];return this;
-};var c=["setProductId","setQuantity","setPrice","setRevenueType","setEventProperties"];
-for(var u=0;u<c.length;u++){n(a,c[u])}r.Revenue=a;var l=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties","logRevenueV2","regenerateDeviceId"];
-function p(e){function t(t){e[t]=function(){e._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
-}}for(var r=0;r<l.length;r++){t(l[r])}}p(r);e.amplitude=r})(window,document);
+this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));return this}}var s=function(){
+this._q=[];return this};var i=["add","append","clearAll","prepend","set","setOnce","unset"];
+for(var o=0;o<i.length;o++){n(s,i[o])}r.Identify=s;var a=function(){this._q=[];return this;
+};var u=["setProductId","setQuantity","setPrice","setRevenueType","setEventProperties"];
+for(var c=0;c<u.length;c++){n(a,u[c])}r.Revenue=a;var p=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties","setGroup","logRevenueV2","regenerateDeviceId"];
+function l(e){function t(t){e[t]=function(){e._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
+}}for(var r=0;r<p.length;r++){t(p[r])}}l(r);e.amplitude=r})(window,document);

amplitude-snippet.min.js

@@ -5,6 +5,6 @@ s.parentNode.insertBefore(r,s);function i(e,t){e.prototype[t]=function(){this._q
 return this}}var o=function(){this._q=[];return this};var a=["add","append","clearAll","prepend","set","setOnce","unset"];
 for(var u=0;u<a.length;u++){i(o,a[u])}n.Identify=o;var c=function(){this._q=[];return this;
 };var p=["setProductId","setQuantity","setPrice","setRevenueType","setEventProperties"];
-for(var l=0;l<p.length;l++){i(c,p[l])}n.Revenue=c;var d=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties","logRevenueV2","regenerateDeviceId"];
+for(var l=0;l<p.length;l++){i(c,p[l])}n.Revenue=c;var d=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify","clearUserProperties","setGroup","logRevenueV2","regenerateDeviceId"];
 function v(e){function t(t){e[t]=function(){e._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
 }}for(var n=0;n<d.length;n++){t(d[n])}}v(n);e.amplitude=n})(window,document);

amplitude.js

@@ -199,13 +199,17 @@ Amplitude.prototype.init = function init(apiKey, opt_userId, opt_config, opt_cal
       // validate event properties for unsent events
       for (var i = 0; i < this._unsentEvents.length; i++) {
         var eventProperties = this._unsentEvents[i].event_properties;
+        var groups = this._unsentEvents[i].groups;
         this._unsentEvents[i].event_properties = utils.validateProperties(eventProperties);
+        this._unsentEvents[i].groups = utils.validateGroups(groups);
       }
 
       // validate user properties for unsent identifys
       for (var j = 0; j < this._unsentIdentifys.length; j++) {
         var userProperties = this._unsentIdentifys[j].user_properties;
+        var identifyGroups = this._unsentIdentifys[j].groups;
         this._unsentIdentifys[j].user_properties = utils.validateProperties(userProperties);
+        this._unsentIdentifys[j].groups = utils.validateGroups(identifyGroups);
       }
 
       this._sendEventsIfReady(); // try sending unsent events
@@ -658,6 +662,31 @@ Amplitude.prototype.setUserId = function setUserId(userId) {
   }
 };
 
+/**
+ * Add user to a group or groups. You need to specify a groupType and groupName(s).
+ * For example you can group people by their organization.
+ * In that case groupType is "orgId" and groupName would be the actual ID(s).
+ * groupName can be a string or an array of strings to indicate a user in multiple gruups.
+ * You can also call setGroup multiple times with different groupTypes to track multiple types of groups (up to 5 per app).
+ * Note: this will also set groupType: groupName as a user property.
+ * See the [SDK Readme]{@link https://github.com/amplitude/Amplitude-Javascript#setting-groups} for more information.
+ * @public
+ * @param {string} groupType - the group type (ex: orgId)
+ * @param {string|list} groupName - the name of the group (ex: 15), or a list of names of the groups
+ * @example amplitude.setGroup('orgId', 15); // this adds the current user to orgId 15.
+ */
+Amplitude.prototype.setGroup = function(groupType, groupName) {
+  if (!this._apiKeySet('setGroup()') || !utils.validateInput(groupType, 'groupType', 'string') ||
+        utils.isEmptyString(groupType)) {
+    return;
+  }
+
+  var groups = {};
+  groups[groupType] = groupName;
+  var identify = new Identify().set(groupType, groupName);
+  this._logEvent(Constants.IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
+};
+
 /**
  * Sets whether to opt current user out of tracking.
  * @public
@@ -790,7 +819,9 @@ Amplitude.prototype.identify = function(identify_obj, opt_callback) {
   if (identify_obj instanceof Identify) {
     // only send if there are operations
     if (Object.keys(identify_obj.userPropertiesOperations).length > 0) {
-      return this._logEvent(Constants.IDENTIFY_EVENT, null, null, identify_obj.userPropertiesOperations, opt_callback);
+      return this._logEvent(
+        Constants.IDENTIFY_EVENT, null, null, identify_obj.userPropertiesOperations, null, opt_callback
+        );
     }
   } else {
     utils.log('Invalid identify input type. Expected Identify object but saw ' + type(identify_obj));
@@ -804,7 +835,7 @@ Amplitude.prototype.identify = function(identify_obj, opt_callback) {
 /**
  * Set a versionName for your application.
  * @public
- * @param {string} versionName
+ * @param {string} versionName - The version to set for your application.
  * @example amplitude.setVersionName('1.12.3');
  */
 Amplitude.prototype.setVersionName = function setVersionName(versionName) {
@@ -818,7 +849,7 @@ Amplitude.prototype.setVersionName = function setVersionName(versionName) {
  * Private logEvent method. Keeps apiProperties from being publicly exposed.
  * @private
  */
-Amplitude.prototype._logEvent = function _logEvent(eventType, eventProperties, apiProperties, userProperties, callback) {
+Amplitude.prototype._logEvent = function _logEvent(eventType, eventProperties, apiProperties, userProperties, groups, callback) {
   _loadCookieData(this); // reload cookie before each log event to sync event meta-data between windows and tabs
   if (!eventType || this.options.optOut) {
     if (type(callback) === 'function') {
@@ -845,6 +876,7 @@ Amplitude.prototype._logEvent = function _logEvent(eventType, eventProperties, a
     userProperties = userProperties || {};
     apiProperties = apiProperties || {};
     eventProperties = eventProperties || {};
+    groups = groups || {};
     var event = {
       device_id: this.options.deviceId,
       user_id: this.options.userId,
@@ -866,7 +898,8 @@ Amplitude.prototype._logEvent = function _logEvent(eventType, eventProperties, a
         name: 'amplitude-js',
         version: version
       },
-      sequence_number: sequenceNumber // for ordering events and identifys
+      sequence_number: sequenceNumber, // for ordering events and identifys
+      groups: utils.truncate(utils.validateGroups(groups))
       // country: null
     };
 
@@ -927,7 +960,33 @@ Amplitude.prototype.logEvent = function logEvent(eventType, eventProperties, opt
     }
     return -1;
   }
-  return this._logEvent(eventType, eventProperties, null, null, opt_callback);
+  return this._logEvent(eventType, eventProperties, null, null, null, opt_callback);
+};
+
+/**
+ * Log an event with eventType, eventProperties, and groups. Use this to set event-level groups.
+ * Note: the group(s) set only apply for the specific event type being logged and does not persist on the user
+ * (unless you explicitly set it with setGroup).
+ * See the [SDK Readme]{@link https://github.com/amplitude/Amplitude-Javascript#setting-groups} for more information
+ * about groups and Count by Distinct on the Amplitude platform.
+ * @public
+ * @param {string} eventType - name of event
+ * @param {object} eventProperties - (optional) an object with string keys and values for the event properties.
+ * @param {object} groups - (optional) an object with string groupType: groupName values for the event being logged.
+ * groupName can be a string or an array of strings.
+ * @param {Amplitude~eventCallback} opt_callback - (optional) a callback function to run after the event is logged.
+ * Note: the server response code and response body from the event upload are passed to the callback function.
+ * @example amplitude.logEventWithGroups('Clicked Button', null, {'orgId': 24});
+ */
+Amplitude.prototype.logEventWithGroups = function(eventType, eventProperties, groups, opt_callback) {
+  if (!this._apiKeySet('logEventWithGroup()') ||
+        !utils.validateInput(eventType, 'eventType', 'string')) {
+    if (type(opt_callback) === 'function') {
+      opt_callback(0, 'No request sent');
+    }
+    return -1;
+  }
+  return this._logEvent(eventType, eventProperties, null, null, groups, opt_callback);
 };
 
 /**
@@ -989,7 +1048,7 @@ Amplitude.prototype.logRevenue = function logRevenue(price, quantity, product) {
     special: 'revenue_amount',
     quantity: quantity || 1,
     price: price
-  });
+  }, null, null, null);
 };
 
 /**
@@ -2298,8 +2357,8 @@ var validateProperties = function validateProperties(properties) {
     var key = property;
     var keyType = type(key);
     if (keyType !== 'string') {
-      log('WARNING: Non-string property key, received type ' + keyType + ', coercing to string "' + key + '"');
       key = String(key);
+      log('WARNING: Non-string property key, received type ' + keyType + ', coercing to string "' + key + '"');
     }
 
     // validate value
@@ -2343,11 +2402,76 @@ var validatePropertyValue = function validatePropertyValue(key, value) {
   return value;
 };
 
+var validateGroups = function validateGroups(groups) {
+  var groupsType = type(groups);
+  if (groupsType !== 'object') {
+    log('Error: invalid groups format. Expecting Javascript object, received ' + groupsType + ', ignoring');
+    return {};
+  }
+
+  var copy = {}; // create a copy with all of the valid properties
+  for (var group in groups) {
+    if (!groups.hasOwnProperty(group)) {
+      continue;
+    }
+
+    // validate key
+    var key = group;
+    var keyType = type(key);
+    if (keyType !== 'string') {
+      key = String(key);
+      log('WARNING: Non-string groupType, received type ' + keyType + ', coercing to string "' + key + '"');
+    }
+
+    // validate value
+    var value = validateGroupName(key, groups[group]);
+    if (value === null) {
+      continue;
+    }
+    copy[key] = value;
+  }
+  return copy;
+};
+
+var validateGroupName = function validateGroupName(key, groupName) {
+  var groupNameType = type(groupName);
+  if (groupNameType === 'string') {
+    return groupName;
+  }
+  if (groupNameType === 'date' || groupNameType === 'number' || groupNameType === 'boolean') {
+    groupName = String(groupName);
+    log('WARNING: Non-string groupName, received type ' + groupNameType + ', coercing to string "' + groupName + '"');
+    return groupName;
+  }
+  if (groupNameType === 'array') {
+    // check for nested arrays or objects
+    var arrayCopy = [];
+    for (var i = 0; i < groupName.length; i++) {
+      var element = groupName[i];
+      var elemType = type(element);
+      if (elemType === 'array' || elemType === 'object') {
+        log('WARNING: Skipping nested ' + elemType + ' in array groupName');
+        continue;
+      } else if (elemType === 'string') {
+        arrayCopy.push(element);
+      } else if (elemType === 'date' || elemType === 'number' || elemType === 'boolean') {
+        element = String(element);
+        log('WARNING: Non-string groupName, received type ' + elemType + ', coercing to string "' + element + '"');
+        arrayCopy.push(element);
+      }
+    }
+    return arrayCopy;
+  }
+  log('WARNING: Non-string groupName, received type ' + groupNameType +
+        '. Please use strings or array of strings for groupName');
+};
+
 module.exports = {
   log: log,
   isEmptyString: isEmptyString,
   sessionStorageEnabled: sessionStorageEnabled,
   truncate: truncate,
+  validateGroups: validateGroups,
   validateInput: validateInput,
   validateProperties: validateProperties
 };