add option to parse device id from url params

Author: Daniel Jih

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 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. DeviceIds defined in the configuration options during init will take priority over device Ids from url parameters.
 
 ### 3.3.2 (October 28, 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
@@ -1686,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
 };
 
 }, {}],
@@ -4991,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

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