feat: Added Fbclid config option (#338)

* Added Fbclid config option

* removed testing api key

* added new line at the end of test/amplitude-client.js

* added break line between functions in amplitude-client.js

* fixed lint issues

Author: jarrenpatao

src/amplitude-client.js

@@ -393,6 +393,7 @@ AmplitudeClient.prototype._trackParamsAndReferrer = function _trackParamsAndRefe
   let utmProperties;
   let referrerProperties;
   let gclidProperties;
+  let fbclidProperties;
   if (this.options.includeUtm) {
     utmProperties = this._initUtmData();
   }
@@ -402,11 +403,15 @@ AmplitudeClient.prototype._trackParamsAndReferrer = function _trackParamsAndRefe
   if (this.options.includeGclid) {
     gclidProperties = this._saveGclid(this._getUrlParams());
   }
+  if (this.options.includeFbclid) {
+    fbclidProperties = this._saveFbclid(this._getUrlParams());
+  }
   if (this.options.logAttributionCapturedEvent) {
     const attributionProperties = {
       ...utmProperties,
       ...referrerProperties,
       ...gclidProperties,
+      ...fbclidProperties,
     };
     if (Object.keys(attributionProperties).length > 0) {
       this.logEvent(Constants.ATTRIBUTION_EVENT, attributionProperties);
@@ -801,6 +806,20 @@ AmplitudeClient.prototype._saveGclid = function _saveGclid(urlParams) {
   return gclidProperties;
 };
 
+/**
+ * Try to fetch Facebook Fbclid from url params.
+ * @private
+ */
+AmplitudeClient.prototype._saveFbclid = function _saveFbclid(urlParams) {
+  var fbclid = utils.getQueryParam('fbclid', urlParams);
+  if (utils.isEmptyString(fbclid)) {
+    return;
+  }
+  var fbclidProperties = { fbclid: fbclid };
+  _sendParamsReferrerUserProperties(this, fbclidProperties);
+  return fbclidProperties;
+};
+
 /**
  * Try to fetch Amplitude device id from url params.
  * @private

src/options.js

@@ -29,18 +29,19 @@ if (BUILD_COMPAT_REACT_NATIVE) {
  * @property {number} [eventUploadPeriodMillis=`30000` (30 sec)] -  Amount of time in milliseconds that the SDK waits before uploading events if batchEvents is true.
  * @property {number} [eventUploadThreshold=`30`] -  Minimum number of events to batch together per request if batchEvents is true.
  * @property {boolean} [forceHttps=`true`] -  If `true`, the events will always be uploaded to HTTPS endpoint. Otherwise, it will use the embedding site's protocol.
+ * @property {boolean} [includeFbclid=`false`] -  If `true`, captures the fbclid URL parameter as well as the user's initial_fbclid via a setOnce operation.
  * @property {boolean} [includeGclid=`false`] -  If `true`, captures the gclid URL parameter as well as the user's initial_gclid via a setOnce operation.
  * @property {boolean} [includeReferrer=`false`] -  If `true`, captures the referrer and referring_domain for each session, as well as the user's initial_referrer and initial_referring_domain via a setOnce operation.
  * @property {boolean} [includeUtm=`false`] -  If `true`, finds UTM parameters in the query string or the _utmz cookie, parses, and includes them as user properties on all events uploaded. This also captures initial UTM parameters for each session via a setOnce operation.
  * @property {string} [language=The language determined by the browser] -  Custom language to set.
  * @property {string} [logLevel=`WARN`] -  Level of logs to be printed in the developer console. Valid values are 'DISABLE', 'ERROR', 'WARN', 'INFO'. To learn more about the different options, see below.
- * @property {boolean} [logAttributionCapturedEvent=`false`] - If `true`, the SDK will log an Amplitude event anytime new attribution values are captured from the user. **Note: These events count towards your event volume.** Event name being logged: [Amplitude] Attribution Captured. Event Properties that can be logged: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `referrer`, `referring_domain`, `gclid`. For UTM properties to be logged, `includeUtm` must be set to `true`. For the `referrer` and `referring_domain` properties to be logged, `includeReferrer` must be set to `true`. For the `gclid` property to be logged, `includeGclid` must be set to `true`.
+ * @property {boolean} [logAttributionCapturedEvent=`false`] - If `true`, the SDK will log an Amplitude event anytime new attribution values are captured from the user. **Note: These events count towards your event volume.** Event name being logged: [Amplitude] Attribution Captured. Event Properties that can be logged: `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content`, `referrer`, `referring_domain`, `gclid`, `fbclid`. For UTM properties to be logged, `includeUtm` must be set to `true`. For the `referrer` and `referring_domain` properties to be logged, `includeReferrer` must be set to `true`. For the `gclid` property to be logged, `includeGclid` must be set to `true`. For the `fbclid` property to be logged, `includeFbclid` must be set to `true`.
  * @property {boolean} [optOut=`false`] -  Whether or not to disable tracking for the current user.
  * @property {function} [onError=`() => {}`] - Function to call on error.
  * @property {string} [platform=`Web`|`iOS`|`Android`] -  Platform device is running on. `Web` is a browser (including mobile browsers). `iOS` and `Android` are relevant only for react-native apps.
  * @property {number} [savedMaxCount=`1000`] -  Maximum number of events to save in localStorage. If more events are logged while offline, then old events are removed.
  * @property {boolean} [saveEvents=`true`] -  If `true`, saves events to localStorage and removes them upon successful upload. *Note: Without saving events, events may be lost if the user navigates to another page before the events are uploaded.*
- * @property {boolean} [saveParamsReferrerOncePerSession=`true`] -  If `true`, then includeGclid, includeReferrer, and includeUtm will only track their respective properties once per session. New values that come in during the middle of the user's session will be ignored. Set to false to always capture new values.
+ * @property {boolean} [saveParamsReferrerOncePerSession=`true`] -  If `true`, then includeGclid, includeFbclid, includeReferrer, and includeUtm will only track their respective properties once per session. New values that come in during the middle of the user's session will be ignored. Set to false to always capture new values.
  * @property {boolean} [secureCookie=`false`] -  If `true`, the amplitude cookie will be set with the Secure flag.
  * @property {number} [sessionTimeout=`30*60*1000` (30 min)] -  The time between logged events before a new session starts in milliseconds.
  * @property {Object} [trackingOptions=`{ city: true, country: true, carrier: true, device_manufacturer: true, device_model: true, dma: true, ip_address: true, language: true, os_name: true, os_version: true, platform: true, region: true, version_name: true}`] - Type of data associated with a user.
@@ -63,6 +64,7 @@ export default {
   eventUploadPeriodMillis: 30 * 1000, // 30s
   eventUploadThreshold: 30,
   forceHttps: true,
+  includeFbclid: false,
   includeGclid: false,
   includeReferrer: false,
   includeUtm: false,

test/amplitude-client.js

@@ -3319,6 +3319,89 @@ describe('AmplitudeClient', function () {
     });
   });
 
+  describe('gatherFbclid', function () {
+    var clock;
+    beforeEach(function () {
+      clock = sinon.useFakeTimers(100);
+      amplitude.init(apiKey);
+      sinon.stub(amplitude, '_getUrlParams').returns('?utm_source=amplitude&utm_medium=email&fbclid=67890&gclid=12345');
+    });
+
+    afterEach(function () {
+      reset();
+      amplitude._getUrlParams.restore();
+      clock.restore();
+    });
+
+    it('should parse fbclid once per session', function () {
+      amplitude.init(apiKey, undefined, { includeFbclid: true });
+
+      // still same session, no fbclid sent
+      assert.lengthOf(server.requests, 0);
+      assert.lengthOf(amplitude._unsentEvents, 0);
+      assert.lengthOf(amplitude._unsentIdentifys, 0);
+
+      // advance the clock to force a new session
+      clock.tick(30 * 60 * 1000 + 1);
+      amplitude.init(apiKey, undefined, { includeFbclid: true, batchEvents: true, eventUploadThreshold: 2 });
+      amplitude.logEvent('Fbclid test event', {});
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(queryString.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 2);
+
+      // first event should be identify with Fbclid
+      assert.equal(events[0].event_type, '$identify');
+      assert.deepEqual(events[0].user_properties, {
+        $set: { fbclid: '67890' },
+        $setOnce: { initial_fbclid: '67890' },
+      });
+
+      // second event should be the test event with no fbclid information
+      assert.equal(events[1].event_type, 'Fbclid test event');
+      assert.deepEqual(events[1].user_properties, {});
+    });
+
+    it('should parse fbclid multiple times per session if configured', function () {
+      amplitude.init(apiKey, undefined, { includeFbclid: true, saveParamsReferrerOncePerSession: false });
+
+      // even though session is same, fbclid is sent again
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(queryString.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 1);
+      assert.equal(events[0].event_type, '$identify');
+      assert.deepEqual(events[0].user_properties, {
+        $set: { fbclid: '67890' },
+        $setOnce: { initial_fbclid: '67890' },
+      });
+    });
+
+    it('should log attribution event when fbclid is captured if configured', () => {
+      clock.tick(30 * 60 * 1000 + 1);
+      amplitude.init(apiKey, undefined, {
+        includeFbclid: true,
+        logAttributionCapturedEvent: true,
+        batchEvents: true,
+        eventUploadThreshold: 2,
+      });
+
+      assert.lengthOf(server.requests, 1);
+      var events = JSON.parse(queryString.parse(server.requests[0].requestBody).e);
+      assert.lengthOf(events, 2);
+
+      // first event should be identify with fbclid
+      assert.equal(events[0].event_type, '$identify');
+      assert.deepEqual(events[0].user_properties, {
+        $set: { fbclid: '67890' },
+        $setOnce: { initial_fbclid: '67890' },
+      });
+      // second event should be the attribution captured event with fbclid populated
+      assert.equal(events[1].event_type, constants.ATTRIBUTION_EVENT);
+      assert.deepEqual(events[1].event_properties, {
+        fbclid: '67890',
+      });
+    });
+  });
+
   describe('logRevenue', function () {
     beforeEach(function () {
       amplitude.init(apiKey);