Merge pull request #9 from amplitude/setOptOut

allanca · allanca · commit 0a57c0cb5657 · 2015-03-04T14:10:23.000-08:00
Add support for opting users out of logging
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Amplitude-Javascript
           b.async=true;b.src="https://d24n15hnbwhuhn.cloudfront.net/libs/amplitude-2.0.4-min.js";
           var g=a.getElementsByTagName("script")[0];g.parentNode.insertBefore(b,g);
           f._q=[];function e(i){f[i]=function(){f._q.push([i].concat(Array.prototype.slice.call(arguments,0)))}}
-          var c=["init","logEvent","setUserId","setUserProperties","setVersionName","setDomain","setDeviceId",
+          var c=["init","logEvent","setUserId",setUserProperties","setOptOut","setVersionName","setDomain","setDeviceId",
           "setGlobalUserProperties"];
           for(var d=0;d<c.length;d++){e(c[d])}h.amplitude=f})(window,document);
 
@@ -58,6 +58,20 @@ To add properties that are tracked in every event, you can set properties for a
     userProperties.key = "value";
     amplitude.setUserProperties(userProperties);
 
+
+# Opting User Out of Logging #
+
+You can turn off logging for a given user:
+
+    amplitude.setOptOut(true);
+
+No events will be saved or sent to the server while opt out is enabled. The opt out
+setting will persist across page loads. Calling
+
+    setOptOut(false)
+
+will reenable logging.
+
 # Configuration Options #
 
 You can configure Amplitude by passing an object as the third argument to the `init`:
diff --git a/amplitude.js b/amplitude.js
@@ -136,7 +136,8 @@ var DEFAULT_OPTIONS = {
   sessionTimeout: 30 * 60 * 1000,
   platform: 'Web',
   language: language.language,
-  includeUtm: false
+  includeUtm: false,
+  optOut: false
 };
 var LocalStorageKeys = {
   LAST_EVENT_ID: 'amplitude_lastEventId',
@@ -258,14 +259,18 @@ var _loadCookieData = function(scope) {
     if (cookieData.globalUserProperties) {
       scope.options.userProperties = cookieData.globalUserProperties;
     }
+    if (cookieData.optOut !== undefined) {
+      scope.options.optOut = cookieData.optOut;
+    }
   }
 };
 
 var _saveCookieData = function(scope) {
   Cookie.set(scope.options.cookieName, {
     deviceId: scope.options.deviceId,
     userId: scope.options.userId,
-    globalUserProperties: scope.options.userProperties
+    globalUserProperties: scope.options.userProperties,
+    optOut: scope.options.optOut
   });
 };
 
@@ -335,6 +340,16 @@ Amplitude.prototype.setUserId = function(userId) {
   }
 };
 
+Amplitude.prototype.setOptOut = function(enable) {
+  try {
+    this.options.optOut = enable;
+    _saveCookieData(this);
+    //log('set optOut=' + enable);
+  } catch (e) {
+    log(e);
+  }
+}
+
 Amplitude.prototype.setDeviceId = function(deviceId) {
   try {
     if (deviceId) {
@@ -370,7 +385,7 @@ Amplitude.prototype.setVersionName = function(versionName) {
 };
 
 Amplitude.prototype.logEvent = function(eventType, eventProperties) {
-  if (!eventType) {
+  if (!eventType || this.options.optOut) {
     return;
   }
   try {
@@ -425,7 +440,7 @@ Amplitude.prototype.logEvent = function(eventType, eventProperties) {
 };
 
 Amplitude.prototype.sendEvents = function() {
-  if (!this._sending) {
+  if (!this._sending && !this.options.optOut) {
     this._sending = true;
     var url = ('https:' == window.location.protocol ? 'https' : 'http') + '://' +
         this.options.apiEndpoint + '/';
diff --git a/amplitude.min.js b/amplitude.min.js
diff --git a/src/amplitude-snippet.js b/src/amplitude-snippet.js
@@ -12,8 +12,9 @@
       amplitude._q.push([fn].concat(Array.prototype.slice.call(arguments, 0)));
     };
   }
-  var funcs = ["init", "logEvent", "setUserId", "setUserProperties", "setVersionName", "setDomain", "setDeviceId",
-      "setGlobalUserProperties"];
+  var funcs = ["init", "logEvent", "setUserId", "setUserProperties", "setOptOut",
+               "setVersionName", "setDomain", "setDeviceId",
+               "setGlobalUserProperties"];
   for (var i = 0; i < funcs.length; i++) {
     proxy(funcs[i]);
   }
diff --git a/src/amplitude.js b/src/amplitude.js
@@ -26,7 +26,8 @@ var DEFAULT_OPTIONS = {
   sessionTimeout: 30 * 60 * 1000,
   platform: 'Web',
   language: language.language,
-  includeUtm: false
+  includeUtm: false,
+  optOut: false
 };
 var LocalStorageKeys = {
   LAST_EVENT_ID: 'amplitude_lastEventId',
@@ -148,14 +149,18 @@ var _loadCookieData = function(scope) {
     if (cookieData.globalUserProperties) {
       scope.options.userProperties = cookieData.globalUserProperties;
     }
+    if (cookieData.optOut !== undefined) {
+      scope.options.optOut = cookieData.optOut;
+    }
   }
 };
 
 var _saveCookieData = function(scope) {
   Cookie.set(scope.options.cookieName, {
     deviceId: scope.options.deviceId,
     userId: scope.options.userId,
-    globalUserProperties: scope.options.userProperties
+    globalUserProperties: scope.options.userProperties,
+    optOut: scope.options.optOut
   });
 };
 
@@ -225,6 +230,16 @@ Amplitude.prototype.setUserId = function(userId) {
   }
 };
 
+Amplitude.prototype.setOptOut = function(enable) {
+  try {
+    this.options.optOut = enable;
+    _saveCookieData(this);
+    //log('set optOut=' + enable);
+  } catch (e) {
+    log(e);
+  }
+}
+
 Amplitude.prototype.setDeviceId = function(deviceId) {
   try {
     if (deviceId) {
@@ -260,7 +275,7 @@ Amplitude.prototype.setVersionName = function(versionName) {
 };
 
 Amplitude.prototype.logEvent = function(eventType, eventProperties) {
-  if (!eventType) {
+  if (!eventType || this.options.optOut) {
     return;
   }
   try {
@@ -315,7 +330,7 @@ Amplitude.prototype.logEvent = function(eventType, eventProperties) {
 };
 
 Amplitude.prototype.sendEvents = function() {
-  if (!this._sending) {
+  if (!this._sending && !this.options.optOut) {
     this._sending = true;
     var url = ('https:' == window.location.protocol ? 'https' : 'http') + '://' +
         this.options.apiEndpoint + '/';
diff --git a/test/amplitude.js b/test/amplitude.js
@@ -187,6 +187,57 @@ describe('Amplitude', function() {
     });
   });
 
+  describe('optOut', function() {
+    beforeEach(function() {
+      amplitude.init(apiKey);
+    });
+
+    afterEach(function() {
+      reset();
+    });
+
+    it('should not send events while enabled', function() {
+      amplitude.setOptOut(true);
+      amplitude.logEvent('Event Type 1');
+      assert.lengthOf(server.requests, 0);
+    });
+
+    it('should not send saved events while enabled', function() {
+      amplitude.logEvent('Event Type 1');
+      assert.lengthOf(server.requests, 1);
+
+      amplitude._sending = false;
+      amplitude.setOptOut(true);
+      amplitude.init(apiKey);
+      assert.lengthOf(server.requests, 1);
+    });
+
+    it('should start sending events again when disabled', function() {
+      amplitude.setOptOut(true);
+      amplitude.logEvent('Event Type 1');
+      assert.lengthOf(server.requests, 0);
+
+      amplitude.setOptOut(false);
+      amplitude.logEvent('Event Type 1');
+      assert.lengthOf(server.requests, 1);
+
+      var events = JSON.parse(querystring.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 1);
+    });
+
+    it('should have state be persisted in the cookie', function() {
+      var amplitude = new Amplitude();
+      amplitude.init(apiKey);
+      assert.strictEqual(amplitude.options.optOut, false);
+
+      amplitude.setOptOut(true);
+
+      var amplitude2 = new Amplitude();
+      amplitude2.init(apiKey);
+      assert.strictEqual(amplitude2.options.optOut, true);
+    });
+  });
+
   describe('gatherUtm', function() {
     beforeEach(function() {
       amplitude.init(apiKey);
diff --git a/test/browser/amplitudejs.html b/test/browser/amplitudejs.html
@@ -16,7 +16,7 @@
             };
         }
 
-        var funcs = ["init", "logEvent", "setUserId", "setUserProperties", "setVersionName", "setDomain", "setGlobalUserProperties"];
+        var funcs = ["init", "logEvent", "setUserId", "setUserProperties", "setOptOut", "setVersionName", "setDomain", "setGlobalUserProperties"];
         for (var i = 0; i < funcs.length; i++) {
             proxy(funcs[i]);
         }
@@ -32,6 +32,7 @@
 <h3>Amplitude JS Test</h3>
 <ul>
     <li><a href="javascript:amplitude.setUserId('user01');">Set user ID</a></li>
+    <li><a href="javascript:amplitude.setOptOut(!amplitude.options.optOut);">Toggle opt out</a></li>
     <li><a href="javascript:amplitude.logEvent('clicked');">Log event</a></li>
     <li><a href="javascript:amplitude.logEvent('clicked button', {color: 'red;', shape: 'triangle', sides: 3});">Log
         event with event properties</a></li>

Original file line number	Diff line number	Diff line change
`@@ -12,8 +12,9 @@`
`12`	`12`	`amplitude._q.push([fn].concat(Array.prototype.slice.call(arguments, 0)));`
`13`	`13`	`};`
`14`	`14`	`}`
`15`		`- var funcs = ["init", "logEvent", "setUserId", "setUserProperties", "setVersionName", "setDomain", "setDeviceId",`
`16`		`- "setGlobalUserProperties"];`
	`15`	`+ var funcs = ["init", "logEvent", "setUserId", "setUserProperties", "setOptOut",`
	`16`	`+ "setVersionName", "setDomain", "setDeviceId",`
	`17`	`+ "setGlobalUserProperties"];`
`17`	`18`	`for (var i = 0; i < funcs.length; i++) {`
`18`	`19`	`proxy(funcs[i]);`
`19`	`20`	`}`