add tests and update readme

Author: Daniel Jih

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Unreleased
 
+* Add `logEventWithTimestamp` to allow logging events with a custom timestamp. The timestamp should a number representing the time in milliseconds since epoch. See [documentation](https://rawgit.com/amplitude/Amplitude-Javascript/master/documentation/AmplitudeClient.html) for more details.
+
+### 3.3.2 (October 28, 2016)
+
 * Updated our [UA-parser-js](https://github.com/amplitude/ua-parser-js) fork to properly parse the version number for Chrome Mobile browsers.
 
 ### 3.3.1 (October 26, 2016)

amplitude.js

@@ -1280,7 +1280,7 @@ AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventPropert
       eventId = this.nextEventId();
     }
     var sequenceNumber = this.nextSequenceNumber();
-    var eventTime = timestamp || new Date().getTime();
+    var eventTime = (type(timestamp) === 'number') ? timestamp : new Date().getTime();
     if (!this._sessionId || !this._lastEventTime || eventTime - this._lastEventTime > this.options.sessionTimeout) {
       this._sessionId = eventTime;
     }
@@ -1368,14 +1368,28 @@ AmplitudeClient.prototype._limitEventsQueued = function _limitEventsQueued(queue
  * @example amplitudeClient.logEvent('Clicked Homepage Button', {'finished_flow': false, 'clicks': 15});
  */
 AmplitudeClient.prototype.logEvent = function logEvent(eventType, eventProperties, opt_callback) {
+  return this.logEventWithTimestamp(eventType, eventProperties, null, opt_callback);
+};
+
+/**
+ * Log an event with eventType and eventProperties and a custom timestamp
+ * @public
+ * @param {string} eventType - name of event
+ * @param {object} eventProperties - (optional) an object with string keys and values for the event properties.
+ * @param {number} timesatmp - (optional) the custom timestamp as milliseconds since epoch.
+ * @param {Amplitude~eventCallback} opt_callback - (optional) a callback function to run after the event is logged.
+ * Note: the server response code and response body from the event upload are passed to the callback function.
+ * @example amplitudeClient.logEvent('Clicked Homepage Button', {'finished_flow': false, 'clicks': 15});
+ */
+AmplitudeClient.prototype.logEventWithTimestamp = function logEvent(eventType, eventProperties, timestamp, opt_callback) {
   if (!this._apiKeySet('logEvent()') || !utils.validateInput(eventType, 'eventType', 'string') ||
         utils.isEmptyString(eventType)) {
     if (type(opt_callback) === 'function') {
       opt_callback(0, 'No request sent');
     }
     return -1;
   }
-  return this._logEvent(eventType, eventProperties, null, null, null, null, opt_callback);
+  return this._logEvent(eventType, eventProperties, null, null, null, timestamp, opt_callback);
 };
 
 /**

amplitude.min.js

@@ -799,7 +799,7 @@ AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventPropert
       eventId = this.nextEventId();
     }
     var sequenceNumber = this.nextSequenceNumber();
-    var eventTime = timestamp || new Date().getTime();
+    var eventTime = (type(timestamp) === 'number') ? timestamp : new Date().getTime();
     if (!this._sessionId || !this._lastEventTime || eventTime - this._lastEventTime > this.options.sessionTimeout) {
       this._sessionId = eventTime;
     }
@@ -887,14 +887,28 @@ AmplitudeClient.prototype._limitEventsQueued = function _limitEventsQueued(queue
  * @example amplitudeClient.logEvent('Clicked Homepage Button', {'finished_flow': false, 'clicks': 15});
  */
 AmplitudeClient.prototype.logEvent = function logEvent(eventType, eventProperties, opt_callback) {
+  return this.logEventWithTimestamp(eventType, eventProperties, null, opt_callback);
+};
+
+/**
+ * Log an event with eventType and eventProperties and a custom timestamp
+ * @public
+ * @param {string} eventType - name of event
+ * @param {object} eventProperties - (optional) an object with string keys and values for the event properties.
+ * @param {number} timesatmp - (optional) the custom timestamp as milliseconds since epoch.
+ * @param {Amplitude~eventCallback} opt_callback - (optional) a callback function to run after the event is logged.
+ * Note: the server response code and response body from the event upload are passed to the callback function.
+ * @example amplitudeClient.logEvent('Clicked Homepage Button', {'finished_flow': false, 'clicks': 15});
+ */
+AmplitudeClient.prototype.logEventWithTimestamp = function logEvent(eventType, eventProperties, timestamp, opt_callback) {
   if (!this._apiKeySet('logEvent()') || !utils.validateInput(eventType, 'eventType', 'string') ||
         utils.isEmptyString(eventType)) {
     if (type(opt_callback) === 'function') {
       opt_callback(0, 'No request sent');
     }
     return -1;
   }
-  return this._logEvent(eventType, eventProperties, null, null, null, null, opt_callback);
+  return this._logEvent(eventType, eventProperties, null, null, null, timestamp, opt_callback);
 };
 
 /**

src/amplitude-client.js

@@ -2049,6 +2049,50 @@ describe('setVersionName', function() {
       assert.equal(events[0].event_type, 'testEvent');
       assert.isTrue(events[0].user_agent.indexOf(phantomJSUA) > -1);
     });
+
+    it('should allow logging event with custom timestamp', function() {
+      var timestamp = 2000;
+      amplitude.logEventWithTimestamp('test', null, timestamp, null);
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(querystring.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 1);
+
+      // verify the event is correct
+      var event = events[0];
+      assert.equal(event.event_type, 'test');
+      assert.equal(event.event_id, 1);
+      assert.equal(event.timestamp, timestamp);
+    });
+
+    it('should use current time if timestamp is null', function() {
+      var timestamp = 5000;
+      clock.tick(timestamp);
+      amplitude.logEventWithTimestamp('test', null, null, null);
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(querystring.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 1);
+
+      // verify the event is correct
+      var event = events[0];
+      assert.equal(event.event_type, 'test');
+      assert.equal(event.event_id, 1);
+      assert.isTrue(event.timestamp >= timestamp);
+    });
+
+    it('should use current time if timestamp is not valid form', function() {
+      var timestamp = 6000;
+      clock.tick(timestamp);
+      amplitude.logEventWithTimestamp('test', null, 'invalid', null);
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(querystring.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 1);
+
+      // verify the event is correct
+      var event = events[0];
+      assert.equal(event.event_type, 'test');
+      assert.equal(event.event_id, 1);
+      assert.isTrue(event.timestamp >= timestamp);
+    });
   });
 
   describe('optOut', function() {