updated readme

Author: djih

CHANGELOG.md

@@ -1,8 +1,10 @@
 ## Unreleased
 
+* Add support for user properties operations (set, setOnce, add, unset).
+
 ## 2.4.0 (September 4, 2015)
 
-* Add support for passing callback functions to logEvent
+* Add support for passing callback functions to logEvent.
 
 ## 2.3.0 (September 2, 2015)
 
@@ -11,7 +13,7 @@
 ## 2.2.1 (Aug 13, 2015)
 
 * Fix bug where multi-byte unicode characters were hashed improperly.
-* Add option to sent referrer information as user properties
+* Add option to send referrer information as user properties.
 
 ## 2.2.0 (May 5, 2015)
 

README.md

@@ -56,6 +56,48 @@ To add properties that are tracked in every event, you can set properties for a
     userProperties.key = "value";
     amplitude.setUserProperties(userProperties);
 
+# User Property Operations #
+
+The SDK supports the operations set, setOnce, unset, and add on individual user properties. The operations are declared via a provided `Identify` interface. Multiple operations can be chained together in a single `Identify` object. The `Identify` object is then passed to the Amplitude client to send to the server. The results of the operations will be visible immediately in the dashboard, and take effect for events logged after.
+
+1. `set`: this sets the value of a user property.
+
+    ```javascript
+    var identify = new amplitude.Identify().set('city', 'Boston, MA').set('country', 'United States');
+    amplitude.identify(identify);
+    ```
+
+2. `setOnce`: this sets the value of a user property only once. Subsequent `setOnce` operations on that user property will be ignored. In the following example, the city will be set once to `Boston, MA`, and the following setOnce to `San Francisco, CA` will be ignored:
+
+    ```javascript
+    var identify = new amplitude.Identify().setOnce('city', 'Boston, MA');
+    amplitude.identify(identify);
+
+    var identify = new amplitude.Identify().setOnce('city', 'San Francisco, CA');
+    amplitude.identify(identify);
+    ```
+
+3. `unset`: this will unset and remove a user property.
+
+    ```javascript
+    var identify = new amplitude.Identify().unset('city').unset('country');
+    amplitude.identify(identify);
+    ```
+
+4. `add`: this will increment a user property by some numerical value. If the user property does not have a value set yet, it will be initialized to 0 before being incremented.
+
+    ```javascript
+    var identify = new amplitude.Identify().add('karma', 1).add('friends', 1);
+    amplitude.identify(identify);
+    ```
+
+Note: if a user property is used in multiple operations on the same `Identify` object, only the first operation will be saved, and the rest will be ignored. In this example, only the set operation will be saved, and the add and unset will be ignored:
+
+    ```javascript
+    var identify = new amplitude.Identify().set('karma', 10).add('karma', 1).unset('karma');
+    amplitude.identify(identify);
+    ```
+
 # Tracking Revenue #
 
 To track revenue from a user, call

src/amplitude.js

@@ -321,16 +321,13 @@ Amplitude.prototype.setDeviceId = function(deviceId) {
 };
 
 Amplitude.prototype.setUserProperties = function(userProperties) {
-
   // convert userProperties into an identify call
   var identify = new Identify();
   for (var property in userProperties) {
     if (userProperties.hasOwnProperty(property)) {
       identify.set(property, userProperties[property]);
     }
   }
-
-  // _saveCookieData(this); ??
   this.identify(identify);
 };