@splitsoftware/splitio-commons 1.5.1-rc.2 → 1.5.1-rc.3

package/CHANGES.txt

@@ -1,4 +1,5 @@
-1.6.0 (July XX, 2022)
+1.6.0 (July 21, 2022)
+- Added `autoRequire` configuration option to the Google Analytics to Split integration, which takes care of requiring the splitTracker plugin on trackers dynamically created by Google tag managers (See https://help.split.io/hc/en-us/articles/360040838752#set-up-with-gtm-and-gtag.js).
 - Updated browser listener to push remaining impressions and events on 'visibilitychange' and 'pagehide' DOM events, instead of 'unload', which is not reliable in mobile and modern Web browsers (See https://developer.chrome.com/blog/page-lifecycle-api/#legacy-lifecycle-apis-to-avoid).
 - Updated the synchronization flow to be more reliable in the event of an edge case generating delay in cache purge propagation, keeping the SDK cache properly synced.
 - Bugfixing - Removed js-yaml dependency to avoid issues in Node v14 when installing third-party dependencies that also uses js-yaml as a transitive dependency (Related to issue https://github.com/splitio/javascript-client/issues/662)

package/cjs/integrations/ga/GaToSplit.js

@@ -10,23 +10,24 @@ var logNameMapper = 'ga-to-split:mapper';
 /**
  * Provides a plugin to use with analytics.js, accounting for the possibility
  * that the global command queue has been renamed or not yet defined.
- * @param {string} pluginName The plugin name identifier.
- * @param {Function} pluginConstructor The plugin constructor function.
+ * @param window Reference to global object.
+ * @param pluginName The plugin name identifier.
+ * @param pluginConstructor The plugin constructor function.
+ * @param log Logger instance.
+ * @param autoRequire If true, log error when auto-require script is not detected
  */
-function providePlugin(pluginName, pluginConstructor) {
+function providePlugin(window, pluginName, pluginConstructor, log, autoRequire) {
     // get reference to global command queue. Init it if not defined yet.
-    // @ts-expect-error
     var gaAlias = window.GoogleAnalyticsObject || 'ga';
     window[gaAlias] = window[gaAlias] || function () {
-        var args = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            args[_i] = arguments[_i];
-        }
-        (window[gaAlias].q = window[gaAlias].q || []).push(args);
+        (window[gaAlias].q = window[gaAlias].q || []).push(arguments);
     };
     // provides the plugin for use with analytics.js.
-    // @ts-expect-error
     window[gaAlias]('provide', pluginName, pluginConstructor);
+    if (autoRequire && (!window[gaAlias].q || window[gaAlias].q.push === [].push)) {
+        // Expecting spy on ga.q push method but not found
+        log.error(logPrefix + 'integration is configured to autorequire the splitTracker plugin, but the necessary script does not seem to have run. Please check the docs.');
+    }
 }
 // Default mapping: object used for building the default mapper from hits to Split events
 var defaultMapping = {
@@ -246,6 +247,6 @@ function GaToSplit(sdkOptions, params) {
         return SplitTracker;
     }());
     // Register the plugin, even if config is invalid, since, if not provided, it will block `ga` command queue.
-    providePlugin('splitTracker', SplitTracker);
+    providePlugin(window, 'splitTracker', SplitTracker, log, sdkOptions.autoRequire);
 }
 exports.GaToSplit = GaToSplit;

package/esm/integrations/ga/GaToSplit.js

@@ -7,23 +7,24 @@ var logNameMapper = 'ga-to-split:mapper';
 /**
  * Provides a plugin to use with analytics.js, accounting for the possibility
  * that the global command queue has been renamed or not yet defined.
- * @param {string} pluginName The plugin name identifier.
- * @param {Function} pluginConstructor The plugin constructor function.
+ * @param window Reference to global object.
+ * @param pluginName The plugin name identifier.
+ * @param pluginConstructor The plugin constructor function.
+ * @param log Logger instance.
+ * @param autoRequire If true, log error when auto-require script is not detected
  */
-function providePlugin(pluginName, pluginConstructor) {
+function providePlugin(window, pluginName, pluginConstructor, log, autoRequire) {
     // get reference to global command queue. Init it if not defined yet.
-    // @ts-expect-error
     var gaAlias = window.GoogleAnalyticsObject || 'ga';
     window[gaAlias] = window[gaAlias] || function () {
-        var args = [];
-        for (var _i = 0; _i < arguments.length; _i++) {
-            args[_i] = arguments[_i];
-        }
-        (window[gaAlias].q = window[gaAlias].q || []).push(args);
+        (window[gaAlias].q = window[gaAlias].q || []).push(arguments);
     };
     // provides the plugin for use with analytics.js.
-    // @ts-expect-error
     window[gaAlias]('provide', pluginName, pluginConstructor);
+    if (autoRequire && (!window[gaAlias].q || window[gaAlias].q.push === [].push)) {
+        // Expecting spy on ga.q push method but not found
+        log.error(logPrefix + 'integration is configured to autorequire the splitTracker plugin, but the necessary script does not seem to have run. Please check the docs.');
+    }
 }
 // Default mapping: object used for building the default mapper from hits to Split events
 var defaultMapping = {
@@ -240,5 +241,5 @@ export function GaToSplit(sdkOptions, params) {
         return SplitTracker;
     }());
     // Register the plugin, even if config is invalid, since, if not provided, it will block `ga` command queue.
-    providePlugin('splitTracker', SplitTracker);
+    providePlugin(window, 'splitTracker', SplitTracker, log, sdkOptions.autoRequire);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/splitio-commons",
-  "version": "1.5.1-rc.2",
+  "version": "1.5.1-rc.3",
   "description": "Split Javascript SDK common components",
   "main": "cjs/index.js",
   "module": "esm/index.js",

package/src/integrations/ga/GaToSplit.ts

@@ -19,20 +19,26 @@ const logNameMapper = 'ga-to-split:mapper';
 /**
  * Provides a plugin to use with analytics.js, accounting for the possibility
  * that the global command queue has been renamed or not yet defined.
- * @param {string} pluginName The plugin name identifier.
- * @param {Function} pluginConstructor The plugin constructor function.
+ * @param window Reference to global object.
+ * @param pluginName The plugin name identifier.
+ * @param pluginConstructor The plugin constructor function.
+ * @param log Logger instance.
+ * @param autoRequire If true, log error when auto-require script is not detected
  */
-function providePlugin(pluginName: string, pluginConstructor: Function) {
+function providePlugin(window: any, pluginName: string, pluginConstructor: Function, log: ILogger, autoRequire?: boolean) {
   // get reference to global command queue. Init it if not defined yet.
-  // @ts-expect-error
   const gaAlias = window.GoogleAnalyticsObject || 'ga';
-  window[gaAlias] = window[gaAlias] || function (...args: any[]) { // @ts-expect-error
-    (window[gaAlias].q = window[gaAlias].q || []).push(args);
+  window[gaAlias] = window[gaAlias] || function () {
+    (window[gaAlias].q = window[gaAlias].q || []).push(arguments);
   };
 
   // provides the plugin for use with analytics.js.
-  // @ts-expect-error
   window[gaAlias]('provide', pluginName, pluginConstructor);
+
+  if (autoRequire && (!window[gaAlias].q || window[gaAlias].q.push === [].push)) {
+    // Expecting spy on ga.q push method but not found
+    log.error(logPrefix + 'integration is configured to autorequire the splitTracker plugin, but the necessary script does not seem to have run. Please check the docs.');
+  }
 }
 
 // Default mapping: object used for building the default mapper from hits to Split events
@@ -284,5 +290,5 @@ export function GaToSplit(sdkOptions: GoogleAnalyticsToSplitOptions, params: IIn
   }
 
   // Register the plugin, even if config is invalid, since, if not provided, it will block `ga` command queue.
-  providePlugin('splitTracker', SplitTracker);
+  providePlugin(window, 'splitTracker', SplitTracker, log, sdkOptions.autoRequire);
 }

package/src/integrations/ga/autoRequire.js

@@ -0,0 +1,33 @@
+/* eslint-disable no-undef */
+/**
+ * Auto-require script to use with GoogleAnalyticsToSplit integration
+ */
+(function (w, g, o) {
+  w[o] = w[o] || g;
+  w[g] = w[g] || function () { w[g].q.push(arguments); };
+  w[g].q = w[g].q || [];
+
+  var trackerNames = {};
+  function name(arg) { return typeof arg === 'object' && typeof arg.name === 'string' && arg.name; }
+
+  function processCommand(command) { // Queue a `require` command if v is a `create` command
+    if (command && command[0] === 'create') {
+      var trackerName = name(command[1]) || name(command[2]) || name(command[3]) || (typeof command[3] === 'string' ? command[3] : undefined); // Get tracker name
+
+      if (!trackerNames[trackerName]) {
+        trackerNames[trackerName] = true;
+        w[g]((trackerName ? trackerName + '.' : '') + 'require', 'splitTracker'); // Auto-require
+      }
+    }
+  }
+
+  w[g].q.forEach(processCommand); // Process already queued commands
+
+  var originalPush = w[g].q.push;
+  w[g].q.push = function (command) { // Spy new queued commands
+    var result = originalPush.apply(this, arguments);
+    processCommand(command);
+    return result;
+  };
+
+})(window, 'ga', 'GoogleAnalyticsObject');

package/src/integrations/ga/types.ts

@@ -53,13 +53,24 @@ export interface GoogleAnalyticsToSplitOptions {
    * If not provided, events are sent using the key and traffic type provided at SDK config
    */
   identities?: Identity[],
+  /**
+   * Optional flag to log an error if the `auto-require` script is not detected.
+   * The auto-require script automatically requires the `splitTracker` plugin for created trackers,
+   * and should be placed right after your Google Analytics, Google Tag Manager or gtag.js script tag.
+   *
+   * @see {@link https://help.split.io/hc/en-us/articles/360040838752#set-up-with-gtm-and-gtag.js}
+   *
+   * @property {boolean} autoRequire
+   * @default false
+   */
+  autoRequire?: boolean,
 }
 
 /**
  * Enable 'Google Analytics to Split' integration, to track Google Analytics hits as Split events.
  * Used by the browser variant of the isomorphic JS SDK.
  *
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#google-analytics-to-split}
+ * @see {@link https://help.split.io/hc/en-us/articles/360040838752#google-analytics-to-split}
  */
 export interface IGoogleAnalyticsToSplitConfig extends GoogleAnalyticsToSplitOptions {
   type: 'GOOGLE_ANALYTICS_TO_SPLIT'
@@ -129,7 +140,7 @@ export interface SplitToGoogleAnalyticsOptions {
  * Enable 'Split to Google Analytics' integration, to track Split impressions and events as Google Analytics hits.
  * Used by the browser variant of the isomorphic JS SDK.
  *
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#split-to-google-analytics}
+ * @see {@link https://help.split.io/hc/en-us/articles/360040838752#split-to-google-analytics}
  */
 export interface ISplitToGoogleAnalyticsConfig extends SplitToGoogleAnalyticsOptions {
   type: 'SPLIT_TO_GOOGLE_ANALYTICS'

package/types/integrations/ga/types.d.ts

@@ -52,12 +52,23 @@ export interface GoogleAnalyticsToSplitOptions {
      * If not provided, events are sent using the key and traffic type provided at SDK config
      */
     identities?: Identity[];
+    /**
+     * Optional flag to log an error if the `auto-require` script is not detected.
+     * The auto-require script automatically requires the `splitTracker` plugin for created trackers,
+     * and should be placed right after your Google Analytics, Google Tag Manager or gtag.js script tag.
+     *
+     * @see {@link https://help.split.io/hc/en-us/articles/360040838752#set-up-with-gtm-and-gtag.js}
+     *
+     * @property {boolean} autoRequire
+     * @default false
+     */
+    autoRequire?: boolean;
 }
 /**
  * Enable 'Google Analytics to Split' integration, to track Google Analytics hits as Split events.
  * Used by the browser variant of the isomorphic JS SDK.
  *
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#google-analytics-to-split}
+ * @see {@link https://help.split.io/hc/en-us/articles/360040838752#google-analytics-to-split}
  */
 export interface IGoogleAnalyticsToSplitConfig extends GoogleAnalyticsToSplitOptions {
     type: 'GOOGLE_ANALYTICS_TO_SPLIT';
@@ -125,7 +136,7 @@ export interface SplitToGoogleAnalyticsOptions {
  * Enable 'Split to Google Analytics' integration, to track Split impressions and events as Google Analytics hits.
  * Used by the browser variant of the isomorphic JS SDK.
  *
- * @see {@link https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK#split-to-google-analytics}
+ * @see {@link https://help.split.io/hc/en-us/articles/360040838752#split-to-google-analytics}
  */
 export interface ISplitToGoogleAnalyticsConfig extends SplitToGoogleAnalyticsOptions {
     type: 'SPLIT_TO_GOOGLE_ANALYTICS';