update changelog and readme

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

@@ -229,6 +229,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. 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.
+
+```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,15 +545,15 @@ Amplitude.prototype.setUserId = function(userId) {
   }
 };
 
-Amplitude.prototype.setGroup = function(groupName, value) {
+Amplitude.prototype.setGroup = function(groupType, groupName) {
   if (!this._apiKeySet('setGroup()')) {
     return;
   }
 
   var groups = {};
-  groups[groupName] = value;
+  groups[groupType] = groupName;
 
-  var identify = new Identify().set(groupName, value);
+  var identify = new Identify().set(groupType, groupName);
   this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
 };
 

amplitude.min.js

@@ -439,15 +439,15 @@ Amplitude.prototype.setUserId = function(userId) {
   }
 };
 
-Amplitude.prototype.setGroup = function(groupName, value) {
+Amplitude.prototype.setGroup = function(groupType, groupName) {
   if (!this._apiKeySet('setGroup()')) {
     return;
   }
 
   var groups = {};
-  groups[groupName] = value;
+  groups[groupType] = groupName;
 
-  var identify = new Identify().set(groupName, value);
+  var identify = new Identify().set(groupType, groupName);
   this._logEvent(IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
 };