feat: custom library options and setter (#443)

* Create option and setter for custom library version

* add docs

* change naming

* Add tests

* setter nit

* better assertion for library name

Author: jooohhn

src/amplitude-client.js

@@ -14,7 +14,6 @@ import UAParser from '@amplitude/ua-parser-js'; // Identifying device and browse
 import utils from './utils';
 import UUID from './uuid';
 import base64Id from './base64Id';
-import { version } from '../package.json';
 import DEFAULT_OPTIONS from './options';
 import getHost from './get-host';
 import baseCookie from './base-cookie';
@@ -1294,10 +1293,7 @@ AmplitudeClient.prototype._logEvent = function _logEvent(
       event_properties: utils.truncate(utils.validateProperties(eventProperties)),
       user_properties: utils.truncate(utils.validateProperties(userProperties)),
       uuid: UUID(),
-      library: {
-        name: 'amplitude-js',
-        version: version,
-      },
+      library: this.options.library,
       sequence_number: sequenceNumber, // for ordering events and identifys
       groups: utils.truncate(utils.validateGroups(groups)),
       group_properties: utils.truncate(utils.validateProperties(groupProperties)),
@@ -1841,7 +1837,19 @@ if (BUILD_COMPAT_2_0) {
  * @returns {number} version number
  * @example var amplitudeVersion = amplitude.__VERSION__;
  */
-AmplitudeClient.prototype.__VERSION__ = version;
+AmplitudeClient.prototype.__VERSION__ = function getVersion() {
+  return this.options.library.version;
+};
+
+/**
+ * Sets the library name and version. Default is `amplitude-js` and the version defined in package.json. Used if you're building another library on top of amplitude-js and want a custom data source value
+ * @public
+ * @param {string} name - Custom library name
+ * @param {string} version - Custom library version
+ */
+AmplitudeClient.prototype.setLibrary = function setLibrary(name, version) {
+  this.options.library = { name: name, version: version };
+};
 
 /**
  * Determines whether or not to push call to this._q or invoke it

src/options.js

@@ -1,6 +1,7 @@
 import Constants from './constants';
 import language from './language';
 import { AmplitudeServerZone } from './server-zone';
+import { version as libraryVersion } from '../package.json';
 
 /**
  * Options used when initializing Amplitude
@@ -24,6 +25,7 @@ import { AmplitudeServerZone } from './server-zone';
  * @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 {Object} [library=`{ name: 'amplitude-js', version: packageJsonVersion }`] -  Values for the library version
  * @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`, `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.
@@ -70,6 +72,10 @@ export default {
   includeReferrer: false,
   includeUtm: false,
   language: language.getLanguage(),
+  library: {
+    name: 'amplitude-js',
+    version: libraryVersion,
+  },
   logLevel: 'WARN',
   logAttributionCapturedEvent: false,
   optOut: false,

test/amplitude-client.js

@@ -4116,4 +4116,37 @@ describe('AmplitudeClient', function () {
       assert.equal(amplitude.options.apiEndpoint, constants.EVENT_LOG_EU_URL);
     });
   });
+
+  describe('custom library options', function () {
+    beforeEach(function () {
+      reset();
+    });
+    it('should use default library options', function () {
+      amplitude.init(apiKey);
+      amplitude.logEvent('Event Type 1');
+      const { name, version } = JSON.parse(queryString.parse(server.requests[0].requestBody).e)[0].library;
+      assert.equal(name, 'amplitude-js');
+      assert.equal(version, amplitude.options.library.version);
+    });
+
+    it('should change library when passed in options', function () {
+      const customLibrary = { name: 'test-library', version: '1.0-test' };
+      amplitude.init(apiKey, null, { library: customLibrary });
+      amplitude.logEvent('Event Type 1');
+      const { name, version } = JSON.parse(queryString.parse(server.requests[0].requestBody).e)[0].library;
+      assert.equal(name, 'test-library');
+      assert.equal(version, '1.0-test');
+    });
+
+    it('should change library when set with method', function () {
+      amplitude.init(apiKey);
+      amplitude.setLibrary('test-library', '1.0-test');
+      amplitude.logEvent('Event Type 2');
+
+      const { name, version } = JSON.parse(queryString.parse(server.requests[0].requestBody).e)[0].library;
+
+      assert.equal(name, 'test-library');
+      assert.equal(version, '1.0-test');
+    });
+  });
 });