update readme and validate groups

Author: djih

README.md

@@ -251,15 +251,15 @@ This SDK automatically grabs useful data about the browser, including browser ty
 
 ### 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.
+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.
 
-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.
+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. 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 can be in orgId: 15, and she also plays sport: soccer. Now when querying, you can Count By both orgId and sport (although as separate queries). **You are allowed to set up to 5 different groupTypes per user.** Any more than that will be ignored from the Count By Distinct query UI, although they will still appear as user properties for that user.
+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', 'tennis');
+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`).

amplitude.js

@@ -199,15 +199,15 @@ Amplitude.prototype.init = function init(apiKey, opt_userId, opt_config, opt_cal
         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.validateProperties(groups);
+        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.validateProperties(identifyGroups);
+        this._unsentIdentifys[j].groups = utils.validateGroups(identifyGroups);
       }
 
       this._sendEventsIfReady(); // try sending unsent events
@@ -661,16 +661,17 @@ Amplitude.prototype.setUserId = function setUserId(userId) {
 };
 
 /**
- * Designate which groups a user belongs to. Note: this will also set groupType:
- * groupName as a user property. You can call setGroup multiple times with different groupTypes to
- * add a user to different groups. Note: each user is allowed to be in up to 5 groups. Any more
- * than that will be ignored from the Count by Distinct query UI, although they will still appear
- * in the the user properties for that user.
- * See the [SDK Readme]{@link https://github.com/amplitude/Amplitude-Javascript##setting-groups} for more information.
+ * 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} groupName - the name of the group (ex: 15)
- * @example: amplitude.setGroup('orgId', 15); // this adds the current user to orgId 15.
+ * @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') ||
@@ -680,7 +681,6 @@ Amplitude.prototype.setGroup = function(groupType, groupName) {
 
   var groups = {};
   groups[groupType] = groupName;
-
   var identify = new Identify().set(groupType, groupName);
   this._logEvent(Constants.IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
 };
@@ -814,7 +814,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) {
@@ -878,7 +878,7 @@ Amplitude.prototype._logEvent = function _logEvent(eventType, eventProperties, a
         version: version
       },
       sequence_number: sequenceNumber, // for ordering events and identifys
-      groups: utils.truncate(utils.validateProperties(groups))
+      groups: utils.truncate(utils.validateGroups(groups))
       // country: null
     };
 
@@ -946,15 +946,16 @@ Amplitude.prototype.logEvent = function logEvent(eventType, eventProperties, opt
  * 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
+ * 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.
+ * @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.logEvent('Clicked Homepage Button', {'finished_flow': false, 'clicks': 15});
+ * @example amplitude.logEventWithGroups('Clicked Button', null, {'orgId': 24});
  */
 Amplitude.prototype.logEventWithGroups = function(eventType, eventProperties, groups, opt_callback) {
   if (!this._apiKeySet('logEventWithGroup()') ||
@@ -2294,8 +2295,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
@@ -2339,11 +2340,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
 };

amplitude.min.js

@@ -184,7 +184,7 @@ <h4 class="name" id="__VERSION__"><span class="type-signature"></span>__VERSION_
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line1068">line 1068</a>
+        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line1069">line 1069</a>
     </li></ul></dd>
 
 
@@ -1173,7 +1173,8 @@ <h5>Parameters:</h5>
 
 
 
-            <td class="description last">(optional) an object with string groupType: groupName values for the event being logged.</td>
+            <td class="description last">(optional) an object with string groupType: groupName values for the event being logged.
+groupName can be a string or an array of strings.</td>
         </tr>
 
 
@@ -1238,7 +1239,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line853">line 853</a>
+        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line854">line 854</a>
     </li></ul></dd>
 
 
@@ -1420,7 +1421,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line880">line 880</a>
+        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line881">line 881</a>
     </li></ul></dd>
 
 
@@ -1783,7 +1784,7 @@ <h4 class="name" id="setGlobalUserProperties"><span class="type-signature"></spa
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line1058">line 1058</a>
+        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line1059">line 1059</a>
     </li></ul></dd>
 
 
@@ -1821,11 +1822,12 @@ <h4 class="name" id="setGroup"><span class="type-signature"></span>setGroup<span
 
 
 <div class="description">
-    Designate which groups a user belongs to. Note: this will also set groupType:
-groupName as a user property. You can call setGroup multiple times with different groupTypes to
-add a user to different groups. Note: each user is allowed to be in up to 5 groups. Any more
-than that will be ignored from the Count by Distinct query UI, although they will still appear
-in the the user properties for that user.
+    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 <a href="https://github.com/amplitude/Amplitude-Javascript#setting-groups">SDK Readme</a> for more information.
 </div>
 
@@ -1891,16 +1893,10 @@ <h5>Parameters:</h5>
             <td class="type">
 
 
-<span class="param-type">number</span>
-|
-
 <span class="param-type">string</span>
 |
 
 <span class="param-type">list</span>
-|
-
-<span class="param-type">object</span>
 
 
 
@@ -1910,7 +1906,7 @@ <h5>Parameters:</h5>
 
 
 
-            <td class="description last">the name of the group (ex: 15)</td>
+            <td class="description last">the name of the group (ex: 15), or a list of names of the groups</td>
         </tr>
 
 
@@ -1951,7 +1947,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line569">line 569</a>
+        <a href="amplitude.js.html">amplitude.js</a>, <a href="amplitude.js.html#line570">line 570</a>
     </li></ul></dd>
 
 
@@ -2726,7 +2722,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Amplitude
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.0</a> on Wed Apr 06 2016 01:23:04 GMT-0700 (PDT)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.0</a> on Thu Apr 07 2016 00:36:52 GMT-0700 (PDT)
 </footer>
 
 <script> prettyPrint(); </script>

documentation/Amplitude.html

@@ -1295,7 +1295,7 @@ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Amplitude
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.0</a> on Wed Apr 06 2016 01:23:04 GMT-0700 (PDT)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.4.0</a> on Thu Apr 07 2016 00:36:52 GMT-0700 (PDT)
 </footer>
 
 <script> prettyPrint(); </script>