Add opt out setting to disable logging for a user.

Author: allanca

README.md

@@ -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`:

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 + '/';

amplitude.min.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 + '/';

src/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);