Merge pull request #99 from amplitude/device_id_param

Device id param + log event with timestamp

Author: djih

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## 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.
+* Add configuration option `deviceIdFromUrlParam`, which when set to `true` will have the SDK parse device IDs from url parameter `amp_device_id` if available. Device IDs defined in the configuration options during init will take priority over device IDs from url parameters.
+
+### 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)

README.md

@@ -328,6 +328,7 @@ amplitude.getInstance().init('YOUR_API_KEY_HERE', null, {
 | cookieExpiration | number | The number of days after which the Amplitude cookie will expire | 365\*10 (10 years) |
 | cookieName | string | Custom name for the Amplitude cookie | 'amplitude_id' |
 | deviceId | string | Custom device ID to set. Note this is not recommended unless you really know what you are doing (like if you have your own system for tracking user devices) | Randomly generated UUID |
+| deviceIdFromUrlParam | boolean | If `true`, the SDK will parse device ID values from url parameter `amp_device_id` if available. Device IDs defined in the configuration options during init will take priority over device IDs from url parameters.
 | domain | string | Custom cookie domain | The top domain of the current page's url |
 | eventUploadPeriodMillis | number | Amount of time in milliseconds that the SDK waits before uploading events if `batchEvents` is `true`. | 30\*1000 (30 sec) |
 | eventUploadThreshold | number | Minimum number of events to batch together per request if `batchEvents` is `true`. | 30 |

amplitude.js

@@ -562,7 +562,9 @@ AmplitudeClient.prototype.init = function init(apiKey, opt_userId, opt_config, o
 
     // load deviceId and userId from input, or try to fetch existing value from cookie
     this.options.deviceId = (type(opt_config) === 'object' && type(opt_config.deviceId) === 'string' &&
-        !utils.isEmptyString(opt_config.deviceId) && opt_config.deviceId) || this.options.deviceId || UUID() + 'R';
+        !utils.isEmptyString(opt_config.deviceId) && opt_config.deviceId) ||
+        (this.options.deviceIdFromUrlParam && this._getDeviceIdFromUrlParam(this._getUrlParams())) ||
+        this.options.deviceId || UUID() + 'R';
     this.options.userId = (type(opt_userId) === 'string' && !utils.isEmptyString(opt_userId) && opt_userId) ||
         this.options.userId || null;
 
@@ -986,6 +988,14 @@ AmplitudeClient.prototype._saveGclid = function _saveGclid(urlParams) {
   _sendParamsReferrerUserProperties(this, gclidProperties);
 };
 
+/**
+ * Try to fetch Amplitude device id from url params.
+ * @private
+ */
+AmplitudeClient.prototype._getDeviceIdFromUrlParam = function _getDeviceIdFromUrlParam(urlParams) {
+  return utils.getQueryParam(Constants.AMP_DEVICE_ID_PARAM, urlParams);
+};
+
 /**
  * Parse the domain from referrer info
  * @private
@@ -1092,7 +1102,7 @@ AmplitudeClient.prototype.setGroup = function(groupType, groupName) {
   var groups = {};
   groups[groupType] = groupName;
   var identify = new Identify().set(groupType, groupName);
-  this._logEvent(Constants.IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
+  this._logEvent(Constants.IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null, null);
 };
 
 /**
@@ -1234,7 +1244,7 @@ AmplitudeClient.prototype.identify = function(identify_obj, opt_callback) {
     // only send if there are operations
     if (Object.keys(identify_obj.userPropertiesOperations).length > 0) {
       return this._logEvent(
-        Constants.IDENTIFY_EVENT, null, null, identify_obj.userPropertiesOperations, null, opt_callback
+        Constants.IDENTIFY_EVENT, null, null, identify_obj.userPropertiesOperations, null, null, opt_callback
         );
     }
   } else {
@@ -1263,7 +1273,7 @@ AmplitudeClient.prototype.setVersionName = function setVersionName(versionName)
  * Private logEvent method. Keeps apiProperties from being publicly exposed.
  * @private
  */
-AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventProperties, apiProperties, userProperties, groups, callback) {
+AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventProperties, apiProperties, userProperties, groups, timestamp, callback) {
   _loadCookieData(this); // reload cookie before each log event to sync event meta-data between windows and tabs
   if (!eventType || this.options.optOut) {
     if (type(callback) === 'function') {
@@ -1280,7 +1290,7 @@ AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventPropert
       eventId = this.nextEventId();
     }
     var sequenceNumber = this.nextSequenceNumber();
-    var eventTime = 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 +1378,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, opt_callback);
+  return this._logEvent(eventType, eventProperties, null, null, null, timestamp, opt_callback);
 };
 
 /**
@@ -1401,7 +1425,7 @@ AmplitudeClient.prototype.logEventWithGroups = function(eventType, eventProperti
     }
     return -1;
   }
-  return this._logEvent(eventType, eventProperties, null, null, groups, opt_callback);
+  return this._logEvent(eventType, eventProperties, null, null, groups, null, opt_callback);
 };
 
 /**
@@ -1463,7 +1487,7 @@ AmplitudeClient.prototype.logRevenue = function logRevenue(price, quantity, prod
     special: 'revenue_amount',
     quantity: quantity || 1,
     price: price
-  }, null, null, null);
+  }, null, null, null, null);
 };
 
 /**
@@ -1672,7 +1696,9 @@ module.exports = {
   REVENUE_PRODUCT_ID: '$productId',
   REVENUE_QUANTITY: '$quantity',
   REVENUE_PRICE: '$price',
-  REVENUE_REVENUE_TYPE: '$revenueType'
+  REVENUE_REVENUE_TYPE: '$revenueType',
+
+  AMP_DEVICE_ID_PARAM: 'amp_device_id'  // url param
 };
 
 }, {}],
@@ -4977,7 +5003,8 @@ module.exports = {
   eventUploadPeriodMillis: 30 * 1000, // 30s
   forceHttps: false,
   includeGclid: false,
-  saveParamsReferrerOncePerSession: true
+  saveParamsReferrerOncePerSession: true,
+  deviceIdFromUrlParam: false,
 };
 
 }, {"./language":29}],

amplitude.min.js

@@ -81,7 +81,9 @@ AmplitudeClient.prototype.init = function init(apiKey, opt_userId, opt_config, o
 
     // load deviceId and userId from input, or try to fetch existing value from cookie
     this.options.deviceId = (type(opt_config) === 'object' && type(opt_config.deviceId) === 'string' &&
-        !utils.isEmptyString(opt_config.deviceId) && opt_config.deviceId) || this.options.deviceId || UUID() + 'R';
+        !utils.isEmptyString(opt_config.deviceId) && opt_config.deviceId) ||
+        (this.options.deviceIdFromUrlParam && this._getDeviceIdFromUrlParam(this._getUrlParams())) ||
+        this.options.deviceId || UUID() + 'R';
     this.options.userId = (type(opt_userId) === 'string' && !utils.isEmptyString(opt_userId) && opt_userId) ||
         this.options.userId || null;
 
@@ -505,6 +507,14 @@ AmplitudeClient.prototype._saveGclid = function _saveGclid(urlParams) {
   _sendParamsReferrerUserProperties(this, gclidProperties);
 };
 
+/**
+ * Try to fetch Amplitude device id from url params.
+ * @private
+ */
+AmplitudeClient.prototype._getDeviceIdFromUrlParam = function _getDeviceIdFromUrlParam(urlParams) {
+  return utils.getQueryParam(Constants.AMP_DEVICE_ID_PARAM, urlParams);
+};
+
 /**
  * Parse the domain from referrer info
  * @private
@@ -611,7 +621,7 @@ AmplitudeClient.prototype.setGroup = function(groupType, groupName) {
   var groups = {};
   groups[groupType] = groupName;
   var identify = new Identify().set(groupType, groupName);
-  this._logEvent(Constants.IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null);
+  this._logEvent(Constants.IDENTIFY_EVENT, null, null, identify.userPropertiesOperations, groups, null, null);
 };
 
 /**
@@ -753,7 +763,7 @@ AmplitudeClient.prototype.identify = function(identify_obj, opt_callback) {
     // only send if there are operations
     if (Object.keys(identify_obj.userPropertiesOperations).length > 0) {
       return this._logEvent(
-        Constants.IDENTIFY_EVENT, null, null, identify_obj.userPropertiesOperations, null, opt_callback
+        Constants.IDENTIFY_EVENT, null, null, identify_obj.userPropertiesOperations, null, null, opt_callback
         );
     }
   } else {
@@ -782,7 +792,7 @@ AmplitudeClient.prototype.setVersionName = function setVersionName(versionName)
  * Private logEvent method. Keeps apiProperties from being publicly exposed.
  * @private
  */
-AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventProperties, apiProperties, userProperties, groups, callback) {
+AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventProperties, apiProperties, userProperties, groups, timestamp, callback) {
   _loadCookieData(this); // reload cookie before each log event to sync event meta-data between windows and tabs
   if (!eventType || this.options.optOut) {
     if (type(callback) === 'function') {
@@ -799,7 +809,7 @@ AmplitudeClient.prototype._logEvent = function _logEvent(eventType, eventPropert
       eventId = this.nextEventId();
     }
     var sequenceNumber = this.nextSequenceNumber();
-    var eventTime = 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 +897,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, opt_callback);
+  return this._logEvent(eventType, eventProperties, null, null, null, timestamp, opt_callback);
 };
 
 /**
@@ -920,7 +944,7 @@ AmplitudeClient.prototype.logEventWithGroups = function(eventType, eventProperti
     }
     return -1;
   }
-  return this._logEvent(eventType, eventProperties, null, null, groups, opt_callback);
+  return this._logEvent(eventType, eventProperties, null, null, groups, null, opt_callback);
 };
 
 /**
@@ -982,7 +1006,7 @@ AmplitudeClient.prototype.logRevenue = function logRevenue(price, quantity, prod
     special: 'revenue_amount',
     quantity: quantity || 1,
     price: price
-  }, null, null, null);
+  }, null, null, null, null);
 };
 
 /**

src/amplitude-client.js

@@ -24,5 +24,7 @@ module.exports = {
   REVENUE_PRODUCT_ID: '$productId',
   REVENUE_QUANTITY: '$quantity',
   REVENUE_PRICE: '$price',
-  REVENUE_REVENUE_TYPE: '$revenueType'
+  REVENUE_REVENUE_TYPE: '$revenueType',
+
+  AMP_DEVICE_ID_PARAM: 'amp_device_id'  // url param
 };

src/constants.js

@@ -22,5 +22,6 @@ module.exports = {
   eventUploadPeriodMillis: 30 * 1000, // 30s
   forceHttps: false,
   includeGclid: false,
-  saveParamsReferrerOncePerSession: true
+  saveParamsReferrerOncePerSession: true,
+  deviceIdFromUrlParam: false,
 };

src/options.js

@@ -132,6 +132,42 @@ describe('AmplitudeClient', function() {
       assert.equal(counter, 1);
     });
 
+    it ('should load the device id from url params if configured', function() {
+      var deviceId = 'aa_bb_cc_dd';
+      sinon.stub(amplitude, '_getUrlParams').returns('?utm_source=amplitude&utm_medium=email&gclid=12345&amp_device_id=aa_bb_cc_dd');
+      amplitude.init(apiKey, userId, {deviceIdFromUrlParam: true});
+      assert.equal(amplitude.options.deviceId, deviceId);
+
+      var cookieData = cookie.get(amplitude.options.cookieName);
+      assert.equal(cookieData.deviceId, deviceId);
+
+      amplitude._getUrlParams.restore();
+    });
+
+    it ('should not load device id from url params if not configured', function() {
+      var deviceId = 'aa_bb_cc_dd';
+      sinon.stub(amplitude, '_getUrlParams').returns('?utm_source=amplitude&utm_medium=email&gclid=12345&amp_device_id=aa_bb_cc_dd');
+      amplitude.init(apiKey, userId, {deviceIdFromUrlParam: false});
+      assert.notEqual(amplitude.options.deviceId, deviceId);
+
+      var cookieData = cookie.get(amplitude.options.cookieName);
+      assert.notEqual(cookieData.deviceId, deviceId);
+
+      amplitude._getUrlParams.restore();
+    });
+
+    it ('should prefer the device id in the config over the url params', function() {
+      var deviceId = 'dd_cc_bb_aa';
+      sinon.stub(amplitude, '_getUrlParams').returns('?utm_source=amplitude&utm_medium=email&gclid=12345&amp_device_id=aa_bb_cc_dd');
+      amplitude.init(apiKey, userId, {deviceId: deviceId, deviceIdFromUrlParam: true});
+      assert.equal(amplitude.options.deviceId, deviceId);
+
+      var cookieData = cookie.get(amplitude.options.cookieName);
+      assert.equal(cookieData.deviceId, deviceId);
+
+      amplitude._getUrlParams.restore();
+    });
+
     it ('should migrate deviceId, userId, optOut from localStorage to cookie on default instance', function() {
       var deviceId = 'test_device_id';
       var userId = 'test_user_id';
@@ -2049,6 +2085,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() {