added batchEvents option

Author: djih

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## Unreleased
 
+* Add setting to batch events to send to in a single request.
+
 ## 2.2.1 (Aug 13, 2015)
 
 * Fix bug where multi-byte unicode characters were hashed improperly.

README.md

@@ -97,6 +97,8 @@ You can configure Amplitude by passing an object as the third argument to the `i
 | uploadBatchSize | Maximum number of events to send to the server per request. | 100 |
 | includeUtm | If `true`, finds utm parameters in the query string or the __utmz cookie, parses, and includes them as user propeties on all events uploaded. | `false` |
 | includeReferrer | If `true`, includes `referrer` and `referring_domain` as user propeties on all events uploaded. | `false` |
+| batchEvents | If `true`, events are uploaded only when the number of unsent events is greater than `eventUploadThreshold`. | `false` |
+| eventUploadThreshold | Minimum number of events to send to the server per request if `batchEvents` is `true`. | 30 |
 
 
 # Advanced #

amplitude.js

@@ -139,7 +139,9 @@ var DEFAULT_OPTIONS = {
   saveEvents: true,
   sessionTimeout: 30 * 60 * 1000,
   unsentKey: 'amplitude_unsent',
-  uploadBatchSize: 100
+  uploadBatchSize: 100,
+  batchEvents: false,
+  eventUploadThreshold: 30
 };
 var LocalStorageKeys = {
   LAST_EVENT_ID: 'amplitude_lastEventId',
@@ -188,10 +190,14 @@ Amplitude.prototype.init = function(apiKey, opt_userId, opt_config) {
       if (opt_config.includeReferrer !== undefined) {
         this.options.includeReferrer = !!opt_config.includeReferrer;
       }
+      if (opt_config.batchEvents !== undefined) {
+        this.options.batchEvents = !!opt_config.batchEvents;
+      }
       this.options.platform = opt_config.platform || this.options.platform;
       this.options.language = opt_config.language || this.options.language;
       this.options.sessionTimeout = opt_config.sessionTimeout || this.options.sessionTimeout;
       this.options.uploadBatchSize = opt_config.uploadBatchSize || this.options.uploadBatchSize;
+      this.options.eventUploadThreshold = opt_config.eventUploadThreshold || this.options.eventUploadThreshold;
       this.options.savedMaxCount = opt_config.savedMaxCount || this.options.savedMaxCount;
     }
 
@@ -222,7 +228,7 @@ Amplitude.prototype.init = function(apiKey, opt_userId, opt_config) {
         }
       }
     }
-    if (this._unsentEvents.length > 0) {
+    if (this.shouldSendEvents()) {
       this.sendEvents();
     }
 
@@ -255,6 +261,13 @@ Amplitude.prototype.nextEventId = function() {
   return this._eventId;
 };
 
+Amplitude.prototype.shouldSendEvents = function() {
+  var batchEvents = this.options.batchEvents;
+  var numEvents = this._unsentEvents.length;
+  var threshold = this.options.eventUploadThreshold;
+  return (!batchEvents && numEvents > 0) || (batchEvents && numEvents >= threshold);
+};
+
 var _loadCookieData = function(scope) {
   var cookieData = Cookie.get(scope.options.cookieName);
   if (cookieData) {
@@ -477,7 +490,9 @@ Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperti
       this.saveEvents();
     }
 
-    this.sendEvents();
+    if (this.shouldSendEvents()){
+      this.sendEvents();
+    }
 
     return eventId;
   } catch (e) {
@@ -557,7 +572,7 @@ Amplitude.prototype.sendEvents = function() {
           }
 
           // Send more events if any queued during previous send.
-          if (scope._unsentEvents.length > 0) {
+          if (scope.shouldSendEvents()) {
             scope.sendEvents();
           }
         } else if (status === 413) {

amplitude.min.js

@@ -27,7 +27,9 @@ var DEFAULT_OPTIONS = {
   saveEvents: true,
   sessionTimeout: 30 * 60 * 1000,
   unsentKey: 'amplitude_unsent',
-  uploadBatchSize: 100
+  uploadBatchSize: 100,
+  batchEvents: false,
+  eventUploadThreshold: 30
 };
 var LocalStorageKeys = {
   LAST_EVENT_ID: 'amplitude_lastEventId',
@@ -76,10 +78,14 @@ Amplitude.prototype.init = function(apiKey, opt_userId, opt_config) {
       if (opt_config.includeReferrer !== undefined) {
         this.options.includeReferrer = !!opt_config.includeReferrer;
       }
+      if (opt_config.batchEvents !== undefined) {
+        this.options.batchEvents = !!opt_config.batchEvents;
+      }
       this.options.platform = opt_config.platform || this.options.platform;
       this.options.language = opt_config.language || this.options.language;
       this.options.sessionTimeout = opt_config.sessionTimeout || this.options.sessionTimeout;
       this.options.uploadBatchSize = opt_config.uploadBatchSize || this.options.uploadBatchSize;
+      this.options.eventUploadThreshold = opt_config.eventUploadThreshold || this.options.eventUploadThreshold;
       this.options.savedMaxCount = opt_config.savedMaxCount || this.options.savedMaxCount;
     }
 
@@ -110,7 +116,7 @@ Amplitude.prototype.init = function(apiKey, opt_userId, opt_config) {
         }
       }
     }
-    if (this._unsentEvents.length > 0) {
+    if (this.shouldSendEvents()) {
       this.sendEvents();
     }
 
@@ -143,6 +149,13 @@ Amplitude.prototype.nextEventId = function() {
   return this._eventId;
 };
 
+Amplitude.prototype.shouldSendEvents = function() {
+  var batchEvents = this.options.batchEvents;
+  var numEvents = this._unsentEvents.length;
+  var threshold = this.options.eventUploadThreshold;
+  return (!batchEvents && numEvents > 0) || (batchEvents && numEvents >= threshold);
+};
+
 var _loadCookieData = function(scope) {
   var cookieData = Cookie.get(scope.options.cookieName);
   if (cookieData) {
@@ -365,7 +378,9 @@ Amplitude.prototype._logEvent = function(eventType, eventProperties, apiProperti
       this.saveEvents();
     }
 
-    this.sendEvents();
+    if (this.shouldSendEvents()){
+      this.sendEvents();
+    }
 
     return eventId;
   } catch (e) {
@@ -445,7 +460,7 @@ Amplitude.prototype.sendEvents = function() {
           }
 
           // Send more events if any queued during previous send.
-          if (scope._unsentEvents.length > 0) {
+          if (scope.shouldSendEvents()) {
             scope.sendEvents();
           }
         } else if (status === 413) {

src/amplitude.js

@@ -260,7 +260,7 @@ describe('Amplitude', function() {
       assert.deepEqual(amplitude2._unsentEvents, []);
     });
 
-    it('should batch events sent', function() {
+    it('should limit events sent', function() {
       amplitude.init(apiKey, null, {uploadBatchSize: 10});
 
       amplitude._sending = true;
@@ -287,6 +287,30 @@ describe('Amplitude', function() {
       assert.deepEqual(events[5].event_properties, {index: 100});
     });
 
+    it('should batch events sent', function() {
+      var threshold = 10;
+      var additional = threshold/2;
+      amplitude.init(apiKey, null, {batchEvents: true, eventUploadThreshold: threshold});
+
+      for (var i = 0; i < (threshold + additional); i++) {
+        amplitude.logEvent('Event', {index: i});
+      }
+
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(querystring.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, threshold);
+      assert.deepEqual(events[0].event_properties, {index: 0});
+      assert.deepEqual(events[9].event_properties, {index: 9});
+
+      server.respondWith('success');
+      server.respond();
+
+      assert.lengthOf(server.requests, 1);
+      var unsentEvents = amplitude._unsentEvents;
+      assert.lengthOf(unsentEvents, additional);
+      assert.deepEqual(unsentEvents[additional - 1].event_properties, {index: threshold + additional - 1});
+    });
+
     it('should back off on 413 status', function() {
       amplitude.init(apiKey, null, {uploadBatchSize: 10});