Merge pull request #42 from amplitude/append_operation

Append operation

Author: djih

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## Unreleased
 
 * Add getSessionId helper method to fetch the current sessionId.
+* Add support for append user property operation.
 
 ## 2.7.0 (December 1, 2015)
 

README.md

@@ -97,6 +97,13 @@ The SDK supports the operations `set`, `setOnce`, `unset`, and `add` on individu
     amplitude.identify(identify);
     ```
 
+5. `append`: this will append a value or values to a user property. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are appended. If the user property has an existing value and it is not a list, it will be converted into a list with the new value appended.
+
+    ```javascript
+    var identify = new amplitude.Identify().append('ab-tests', 'new-user-test').append('some_list', [1, 2, 3, 4, 'values']);
+    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

amplitude-segment-snippet.min.js

@@ -1,6 +1,6 @@
 (function(t,e){var n=t.amplitude||{};var r=function(){this._q=[];return this};function s(t){
 r.prototype[t]=function(){this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
-return this}}var i=["add","set","setOnce","unset"];for(var o=0;o<i.length;o++){s(i[o]);
-}n.Identify=r;n._q=[];function a(t){n[t]=function(){n._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
+return this}}var i=["add","append","set","setOnce","unset"];for(var o=0;o<i.length;o++){
+s(i[o])}n.Identify=r;n._q=[];function a(t){n[t]=function(){n._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
 }}var u=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify"];
 for(var c=0;c<u.length;c++){a(u[c])}t.amplitude=n})(window,document);

amplitude-snippet.min.js

@@ -1,9 +1,9 @@
 (function(t,e){var n=t.amplitude||{};var r=e.createElement("script");r.type="text/javascript";
 r.async=true;r.src="https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.7.0-min.gz.js";
 r.onload=function(){t.amplitude.runQueuedFunctions()};var s=e.getElementsByTagName("script")[0];
-s.parentNode.insertBefore(r,s);var i=function(){this._q=[];return this};function o(t){
+s.parentNode.insertBefore(r,s);var i=function(){this._q=[];return this};function a(t){
 i.prototype[t]=function(){this._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
-return this}}var a=["add","set","setOnce","unset"];for(var u=0;u<a.length;u++){o(a[u]);
-}n.Identify=i;n._q=[];function c(t){n[t]=function(){n._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
-}}var l=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify"];
-for(var p=0;p<l.length;p++){c(l[p])}t.amplitude=n})(window,document);
+return this}}var o=["add","append","set","setOnce","unset"];for(var u=0;u<o.length;u++){
+a(o[u])}n.Identify=i;n._q=[];function c(t){n[t]=function(){n._q.push([t].concat(Array.prototype.slice.call(arguments,0)));
+}}var p=["init","logEvent","logRevenue","setUserId","setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId","setGlobalUserProperties","identify"];
+for(var l=0;l<p.length;l++){c(p[l])}t.amplitude=n})(window,document);

amplitude.js

@@ -3486,6 +3486,7 @@ var type = require('./type');
  */
 
 var AMP_OP_ADD = '$add';
+var AMP_OP_APPEND = '$append';
 var AMP_OP_SET = '$set';
 var AMP_OP_SET_ONCE = '$setOnce';
 var AMP_OP_UNSET = '$unset';
@@ -3508,6 +3509,11 @@ Identify.prototype.add = function(property, value) {
   return this;
 };
 
+Identify.prototype.append = function(property, value) {
+  this._addOperation(AMP_OP_APPEND, property, value);
+  return this;
+};
+
 Identify.prototype.set = function(property, value) {
   this._addOperation(AMP_OP_SET, property, value);
   return this;

amplitude.min.js

@@ -13,7 +13,7 @@
       this._q.push([fn].concat(Array.prototype.slice.call(arguments, 0))); return this;
     };
   }
-  var identifyFuncs = ['add', 'set', 'setOnce', 'unset'];
+  var identifyFuncs = ['add', 'append', 'set', 'setOnce', 'unset'];
   for (var i = 0; i < identifyFuncs.length; i++) {
     proxyIdentify(identifyFuncs[i]);
   }

src/amplitude-snippet.js

@@ -7,6 +7,7 @@ var type = require('./type');
  */
 
 var AMP_OP_ADD = '$add';
+var AMP_OP_APPEND = '$append';
 var AMP_OP_SET = '$set';
 var AMP_OP_SET_ONCE = '$setOnce';
 var AMP_OP_UNSET = '$unset';
@@ -29,6 +30,11 @@ Identify.prototype.add = function(property, value) {
   return this;
 };
 
+Identify.prototype.append = function(property, value) {
+  this._addOperation(AMP_OP_APPEND, property, value);
+  return this;
+};
+
 Identify.prototype.set = function(property, value) {
   this._addOperation(AMP_OP_SET, property, value);
   return this;

src/identify.js

@@ -16,7 +16,7 @@
           this._q.push([fn].concat(Array.prototype.slice.call(arguments, 0))); return this;
         };
       }
-      var identifyFuncs = ['add', 'set', 'setOnce', 'unset'];
+      var identifyFuncs = ['add', 'append', 'set', 'setOnce', 'unset'];
       for (var i = 0; i < identifyFuncs.length; i++) {
         proxyIdentify(identifyFuncs[i]);
       }

test/browser/amplitudejs.html

@@ -106,6 +106,41 @@ describe('Identify', function() {
     assert.deepEqual([property1, property2], identify.properties);
   });
 
+  it ('should append properties', function () {
+    var property1 = 'var value';
+    var value1 = 'testValue';
+
+    var property2 = 'float value';
+    var value2 = 0.123;
+
+    var property3 = 'bool value';
+    var value3 = true;
+
+    var property4 = 'json value';
+    var value4 = {};
+
+    var property5 = 'list value';
+    var value5 = [1, 2, 'test'];
+
+    var identify = new Identify().append(property1, value1).append(property2, value2);
+    identify.append(property3, value3).append(property4, value4).append(property5, value5);
+
+    // identify should ignore this since duplicate key
+    identify.setOnce(property1, value3);
+
+    var expected = {
+      '$append': {}
+    }
+    expected['$append'][property1] = value1;
+    expected['$append'][property2] = value2;
+    expected['$append'][property3] = value3;
+    expected['$append'][property4] = value4;
+    expected['$append'][property5] = value5;
+
+    assert.deepEqual(expected, identify.userPropertiesOperations);
+    assert.deepEqual([property1, property2, property3, property4, property5], identify.properties);
+  });
+
   it ('should allow multiple operations', function () {
     var property1 = 'string value';
     var value1 = 'testValue';
@@ -118,14 +153,18 @@ describe('Identify', function() {
 
     var property4 = 'json value';
 
+    var property5 = 'list value';
+    var value5 = [1, 2, 'test'];
+
     var identify = new Identify().setOnce(property1, value1).add(property2, value2);
-    identify.set(property3, value3).unset(property4);
+    identify.set(property3, value3).unset(property4).append(property5, value5);
 
     // identify should ignore this since duplicate key
     identify.set(property4, value3);
 
     var expected = {
       '$add': {},
+      '$append': {},
       '$set': {},
       '$setOnce': {},
       '$unset': {}
@@ -134,9 +173,10 @@ describe('Identify', function() {
     expected['$add'][property2] = value2;
     expected['$set'][property3] = value3;
     expected['$unset'][property4] = '-';
+    expected['$append'][property5] = value5;
 
     assert.deepEqual(expected, identify.userPropertiesOperations);
-    assert.deepEqual([property1, property2, property3, property4], identify.properties);
+    assert.deepEqual([property1, property2, property3, property4, property5], identify.properties);
   });
 
   it ('should disallow duplicate properties', function () {