Revert "Revert "Set group""

Author: djih

CHANGELOG.md

@@ -3,6 +3,7 @@
 * Add support for passing callback function to identify.
 * Add support for prepend user property operation.
 * Keep sessions and event metadata in sync across multiple windows/tabs.
+* Add support for setting groups for users and events.
 
 ### 2.9.1 (March 6, 2016)
 

README.md

@@ -240,6 +240,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 (based on something like an orgId). For example you can designate user Joe to be in orgId 10, while Sue is in orgId 15. When performing an event segmentation query, you can then select Count By: orgId, 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.
+
+In the above example, 'orgId' is a `groupType`, and the value 10 or 15 is the `groupName`. Another example of a `groupType` could a sport that the user participates in, and possible `groupNames` within that type would be tennis, baseball, etc.
+
+You can use `setGroup(groupType, groupName)` to designate which groups a user belongs to. Few things 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.** For example if Joe was in orgId 10, and you call `setGroup('orgId', 20)`, 20 would replace 10. You can also call `setGroup` multiple times with different groupTypes to add a user to different groups. For example Sue is in orgId: 15, and she also plays sport: soccer. Now when querying, you can Count By both orgId and sport. **You are allowed to set up to 5 different groupTypes per user.** Any more than that will be ignored from the query UI, although they will still appear as user properties.
+
+```javascript
+amplitude.setGroup('orgId', 15);
+amplitude.setGroup('sport', '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.js

@@ -545,6 +545,18 @@ Amplitude.prototype.setUserId = function(userId) {
   }
 };
 
+Amplitude.prototype.setGroup = function(groupType, groupName) {
+  if (!this._apiKeySet('setGroup()')) {
+    return;
+  }
+
+  var groups = {};
+  groups[groupType] = groupName;
+
+  var identify = new Identify().set(groupType, groupName);
+  this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
+};
+
 Amplitude.prototype.setOptOut = function(enable) {
   if (!this._apiKeySet('setOptOut()')) {
     return;
@@ -620,7 +632,7 @@ Amplitude.prototype.identify = function(identify, callback) {
   }
 
   if (identify instanceof Identify && Object.keys(identify.userPropertiesOperations).length > 0) {
-    this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, callback);
+    this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, null, callback);
   } else if (callback && type(callback) === 'function') {
     callback(0, 'No request sent');
   }
@@ -664,7 +676,7 @@ var _truncateValue = function(value) {
 /**
  * Private logEvent method. Keeps apiProperties from being publicly exposed.
  */
-Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperties, userProperties, callback) {
+Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperties, userProperties, groups, callback) {
   if (type(callback) !== 'function') {
     callback = null;
   }
@@ -700,6 +712,7 @@ Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperti
 
     apiProperties = apiProperties || {};
     eventProperties = eventProperties || {};
+    groups = groups || {};
     var event = {
       device_id: this.options.deviceId,
       user_id: this.options.userId || this.options.deviceId,
@@ -721,7 +734,8 @@ Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperti
         name: 'amplitude-js',
         version: version
       },
-      sequence_number: sequenceNumber // for ordering events and identifys
+      sequence_number: sequenceNumber, // for ordering events and identifys
+      groups: this._truncate(utils.validateProperties(groups))
       // country: null
     };
 
@@ -762,7 +776,17 @@ Amplitude.prototype.logEvent = function(eventType, eventProperties, callback) {
     }
     return -1;
   }
-  return this._logEvent(eventType, eventProperties, null, null, callback);
+  return this._logEvent(eventType, eventProperties, null, null, null, callback);
+};
+
+Amplitude.prototype.logEventWithGroups = function(eventType, eventProperties, groups, callback) {
+  if (!this._apiKeySet('logEventWithGroup()')) {
+    if (callback && type(callback) === 'function') {
+      callback(0, 'No request sent');
+    }
+    return -1;
+  }
+  return this._logEvent(eventType, eventProperties, null, null, groups, callback);
 };
 
 // Test that n is a number or a numeric value.
@@ -782,7 +806,7 @@ Amplitude.prototype.logRevenue = function(price, quantity, product) {
     special: 'revenue_amount',
     quantity: quantity || 1,
     price: price
-  });
+  }, null, null, null);
 };
 
 /**

amplitude.min.js

@@ -439,6 +439,18 @@ Amplitude.prototype.setUserId = function(userId) {
   }
 };
 
+Amplitude.prototype.setGroup = function(groupType, groupName) {
+  if (!this._apiKeySet('setGroup()')) {
+    return;
+  }
+
+  var groups = {};
+  groups[groupType] = groupName;
+
+  var identify = new Identify().set(groupType, groupName);
+  this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
+};
+
 Amplitude.prototype.setOptOut = function(enable) {
   if (!this._apiKeySet('setOptOut()')) {
     return;
@@ -514,7 +526,7 @@ Amplitude.prototype.identify = function(identify, callback) {
   }
 
   if (identify instanceof Identify && Object.keys(identify.userPropertiesOperations).length > 0) {
-    this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, callback);
+    this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, null, callback);
   } else if (callback && type(callback) === 'function') {
     callback(0, 'No request sent');
   }
@@ -558,7 +570,7 @@ var _truncateValue = function(value) {
 /**
  * Private logEvent method. Keeps apiProperties from being publicly exposed.
  */
-Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperties, userProperties, callback) {
+Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperties, userProperties, groups, callback) {
   if (type(callback) !== 'function') {
     callback = null;
   }
@@ -594,6 +606,7 @@ Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperti
 
     apiProperties = apiProperties || {};
     eventProperties = eventProperties || {};
+    groups = groups || {};
     var event = {
       device_id: this.options.deviceId,
       user_id: this.options.userId || this.options.deviceId,
@@ -615,7 +628,8 @@ Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperti
         name: 'amplitude-js',
         version: version
       },
-      sequence_number: sequenceNumber // for ordering events and identifys
+      sequence_number: sequenceNumber, // for ordering events and identifys
+      groups: this._truncate(utils.validateProperties(groups))
       // country: null
     };
 
@@ -656,7 +670,17 @@ Amplitude.prototype.logEvent = function(eventType, eventProperties, callback) {
     }
     return -1;
   }
-  return this._logEvent(eventType, eventProperties, null, null, callback);
+  return this._logEvent(eventType, eventProperties, null, null, null, callback);
+};
+
+Amplitude.prototype.logEventWithGroups = function(eventType, eventProperties, groups, callback) {
+  if (!this._apiKeySet('logEventWithGroup()')) {
+    if (callback && type(callback) === 'function') {
+      callback(0, 'No request sent');
+    }
+    return -1;
+  }
+  return this._logEvent(eventType, eventProperties, null, null, groups, callback);
 };
 
 // Test that n is a number or a numeric value.
@@ -676,7 +700,7 @@ Amplitude.prototype.logRevenue = function(price, quantity, product) {
     special: 'revenue_amount',
     quantity: quantity || 1,
     price: price
-  });
+  }, null, null, null);
 };
 
 /**

src/amplitude.js

@@ -534,6 +534,36 @@ describe('Amplitude', function() {
     });
   });
 
+  describe('setGroup', function() {
+
+    beforeEach(function() {
+      reset();
+      amplitude.init(apiKey);
+    });
+
+    afterEach(function() {
+      reset();
+    });
+
+    it('should generate an identify event with groups set', function() {
+      amplitude.setGroup('orgId', 15);
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(querystring.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 1);
+
+      // verify identify event
+      var identify = events[0];
+      assert.equal(identify.event_type, '$identify');
+      assert.deepEqual(identify.user_properties, {
+        '$set': {'orgId': 15},
+      });
+      assert.deepEqual(identify.event_properties, {});
+      assert.deepEqual(identify.groups, {
+        'orgId': 15,
+      });
+    });
+  });
+
   describe('setDeviceId', function() {
 
     beforeEach(function() {
@@ -1646,6 +1676,49 @@ describe('Amplitude', function() {
       assert.equal(amplitude2._unsentIdentifys[0]['sequence_number'], sequenceNumber + 4);
       assert.equal(amplitude1._unsentEvents[2]['sequence_number'], sequenceNumber +  5);
     });
+
+    it('should handle groups input', function() {
+      var counter = 0;
+      var value = -1;
+      var message = '';
+      var callback = function (status, response) {
+        counter++;
+        value = status;
+        message = response;
+      };
+
+      var eventProperties = {
+        'key': 'value'
+      };
+
+      var groups = {
+        'group1': 'value1',
+        'group2': 'value2',
+      }
+
+      amplitude.logEventWithGroups('Test', eventProperties, groups, callback);
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(querystring.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 1);
+
+      // verify event is correctly formatted
+      var event = events[0];
+      assert.equal(event.event_type, 'Test');
+      assert.equal(event.event_id, 1);
+      assert.deepEqual(event.user_properties, {});
+      assert.deepEqual(event.event_properties, eventProperties);
+      assert.deepEqual(event.groups, groups);
+
+      // verify callback behavior
+      assert.equal(counter, 0);
+      assert.equal(value, -1);
+      assert.equal(message, '');
+      server.respondWith('success');
+      server.respond();
+      assert.equal(counter, 1);
+      assert.equal(value, 200);
+      assert.equal(message, 'success');
+    });
   });
 
   describe('optOut', function() {