@splitsoftware/splitio 10.17.3-rc.3 → 10.17.3-rc.4

package/src/index.js

@@ -1,17 +1,140 @@
-/**
-Copyright 2022 Split Software
+import ManagerFactory from './manager';
+import StorageFactory from './storage';
+import ReadinessGateFacade from './readiness';
+import SettingsFactory from './utils/settings';
+import Context from './utils/context';
+import keyParser from './utils/key/parser';
+import logFactory, { API } from './utils/logger';
+const log = logFactory('splitio');
+import tracker from './utils/timeTracker';
+import SplitFactoryOnline from './factory/online';
+import SplitFactoryOffline from './factory/offline';
+import sdkStatusManager from './readiness/statusManager';
+import { LOCALHOST_MODE } from './utils/constants';
+import { validateApiKey, validateKey, validateTrafficType } from './utils/inputValidation';
+import IntegrationsManagerFactory from './integrations';
+import ImpressionCounter from './impressions/counter';
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+const buildInstanceId = (key, trafficType) => `${key.matchingKey ? key.matchingKey : key}-${key.bucketingKey ? key.bucketingKey : key}-${trafficType !== undefined ? trafficType : ''}`;
 
-    http://www.apache.org/licenses/LICENSE-2.0
+export function SplitFactory(config) {
+  // Cache instances created per factory.
+  const clientInstances = {};
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-**/
+  // Tracking times. We need to do it here because we need the storage created.
+  const readyLatencyTrackers = {
+    splitsReadyTracker: tracker.start(tracker.TaskNames.SPLITS_READY),
+    segmentsReadyTracker: tracker.start(tracker.TaskNames.SEGMENTS_READY),
+    sdkReadyTracker: tracker.start(tracker.TaskNames.SDK_READY)
+  };
+  const context = new Context();
 
-export { SplitFactory } from './factory';
+  // Put settings config within context
+  const settings = SettingsFactory(config);
+  context.put(context.constants.SETTINGS, settings);
+
+  // We will just log and allow for the SDK to end up throwing an SDK_TIMEOUT event for devs to handle.
+  validateApiKey(settings.core.authorizationKey);
+
+  // Put readiness and statusManager within context
+  // Done before adding storage, to let it access readiness gate synchronously
+  const gateFactory = ReadinessGateFacade();
+  const readiness = gateFactory(settings.startup.readyTimeout);
+  context.put(context.constants.READINESS, readiness);
+  const statusManager = sdkStatusManager(context);
+  context.put(context.constants.STATUS_MANAGER, statusManager);
+
+  // Put storage config within context
+  const storage = StorageFactory(context);
+  context.put(context.constants.STORAGE, storage);
+
+  // Put counter
+  const impressionsCounter = new ImpressionCounter(); // Instantiates new counter for Impressions
+  context.put(context.constants.IMPRESSIONS_COUNTER, impressionsCounter);
+
+  // Put integrationsManager within context.
+  // It needs to access the storage, settings and potentially other pieces, so it's registered after them.
+  const integrationsManager = IntegrationsManagerFactory(context);
+  context.put(context.constants.INTEGRATIONS_MANAGER, integrationsManager);
+
+  // Define which type of factory to use
+  const splitFactory = settings.mode === LOCALHOST_MODE ? SplitFactoryOffline : SplitFactoryOnline;
+
+  const {
+    api: mainClientInstance,
+    metricCollectors: mainClientMetricCollectors
+  } = splitFactory(context, readyLatencyTrackers);
+
+  // It makes no sense to have multiple instances of the manager.
+  const managerInstance = ManagerFactory(storage.splits, context);
+
+  const parsedDefaultKey = keyParser(settings.core.key);
+  const defaultInstanceId = buildInstanceId(parsedDefaultKey, settings.core.trafficType);
+  clientInstances[defaultInstanceId] = mainClientInstance;
+
+  log.info('New Split SDK instance created.');
+
+  return {
+    // Split evaluation and event tracking engine
+    client(key, trafficType) {
+      if (key === undefined) {
+        log.debug('Retrieving default SDK client.');
+        return mainClientInstance;
+      }
+
+      if (typeof storage.shared != 'function') {
+        throw new Error('Shared Client not supported by the storage mechanism. Create isolated instances instead.');
+      }
+
+      // Validate the key value
+      const validKey = validateKey(key, 'Shared Client instantiation');
+      if (validKey === false) {
+        throw new Error('Shared Client needs a valid key.');
+      }
+
+      let validTrafficType;
+      if (trafficType !== undefined) {
+        validTrafficType = validateTrafficType(trafficType, 'Shared Client instantiation');
+        if (validTrafficType === false) {
+          throw new Error('Shared Client needs a valid traffic type or no traffic type at all.');
+        }
+      }
+      const instanceId = buildInstanceId(validKey, validTrafficType);
+
+      if (!clientInstances[instanceId]) {
+        const sharedSettings = settings.overrideKeyAndTT(validKey, validTrafficType);
+        const sharedContext = new Context();
+
+        const readiness = gateFactory(sharedSettings.startup.readyTimeout);
+        sharedContext.put(context.constants.READY_FROM_CACHE, context.get(context.constants.READY_FROM_CACHE, true));
+        sharedContext.put(context.constants.READINESS, readiness);
+        // for shared clients, the internal offset of added/removed SDK_READY callbacks is -1
+        sharedContext.put(context.constants.STATUS_MANAGER, sdkStatusManager(sharedContext, -1));
+        sharedContext.put(context.constants.SETTINGS, sharedSettings);
+        sharedContext.put(context.constants.STORAGE, storage.shared(sharedSettings));
+        sharedContext.put(context.constants.IMPRESSIONS_COUNTER, impressionsCounter);
+        // As shared clients reuse all the storage information, we don't need to check here if we
+        // will use offline or online mode. We should stick with the original decision.
+        clientInstances[instanceId] = splitFactory(sharedContext, false, mainClientMetricCollectors).api;
+
+        log.info('New shared client instance created.');
+      } else {
+        log.debug('Retrieving existing SDK client.');
+      }
+
+      return clientInstances[instanceId];
+    },
+
+    // Manager API to explore available information
+    manager() {
+      log.info('Manager instance retrieved.');
+      return managerInstance;
+    },
+
+    // Logger wrapper API
+    Logger: API,
+
+    // Expose SDK settings
+    settings
+  };
+}

package/src/integrations/browser.js

@@ -0,0 +1,57 @@
+import GaToSplit from './ga/GaToSplit';
+import SplitToGa from './ga/SplitToGa';
+import { GOOGLE_ANALYTICS_TO_SPLIT, SPLIT_TO_GOOGLE_ANALYTICS, SPLIT_IMPRESSION, SPLIT_EVENT } from '../utils/constants';
+
+/**
+ * Factory function for browser IntegrationsManager.
+ * The integrations manager instantiates integration modules, and bypass tracked events and impressions to them.
+ *
+ * @param {Context} context SplitFactory context
+ *
+ * @returns integration manager or null if `integrations` are not present in settings.
+ */
+const integrationsManagerFactory = context => {
+  const settings = context.get(context.constants.SETTINGS);
+
+  const listeners = [];
+
+  // No need to check if `settings.integrations` is an array. It was already validated in settings validation
+  settings.integrations.forEach(integrationOptions => {
+    const { type } = integrationOptions;
+    let integration;
+
+    switch (type) {
+      case GOOGLE_ANALYTICS_TO_SPLIT: {
+        const storage = context.get(context.constants.STORAGE);
+        const coreSettings = settings.core;
+        integration = GaToSplit(integrationOptions, storage, coreSettings);
+        break;
+      }
+
+      case SPLIT_TO_GOOGLE_ANALYTICS: {
+        integration = new SplitToGa(integrationOptions);
+        break;
+      }
+    }
+
+    if (integration && integration.queue)
+      listeners.push(integration);
+  });
+
+  // If `listeners` is empty, not return a integration manager
+  if (listeners.length === 0)
+    return;
+
+  // Exception safe methods: each integration module is responsable for handling errors
+  return {
+    handleImpression: function (impressionData) {
+      listeners.forEach(listener => listener.queue({ type: SPLIT_IMPRESSION, payload: impressionData }));
+    },
+    handleEvent: function (eventData) {
+      listeners.forEach(listener => listener.queue({ type: SPLIT_EVENT, payload: eventData }));
+    }
+  };
+
+};
+
+export default integrationsManagerFactory;

package/src/integrations/ga/GaToSplit.js

@@ -0,0 +1,278 @@
+import objectAssign from 'object-assign';
+import { isString, numberIsFinite, unicAsStrings } from '../../utils/lang';
+import logFactory from '../../utils/logger';
+import {
+  validateEvent,
+  validateEventValue,
+  validateEventProperties,
+  validateKey,
+  validateTrafficType,
+} from '../../utils/inputValidation';
+const logName = 'splitio-ga-to-split', logNameMapper = logName + ':mapper';
+const log = logFactory(logName);
+
+/**
+ * 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.
+ */
+function providePlugin(pluginName, pluginConstructor) {
+  // get reference to global command queue. Init it if not defined yet.
+  const gaAlias = window.GoogleAnalyticsObject || 'ga';
+  window[gaAlias] = window[gaAlias] || function (...args) {
+    (window[gaAlias].q = window[gaAlias].q || []).push(args);
+  };
+
+  // provides the plugin for use with analytics.js.
+  window[gaAlias]('provide', pluginName, pluginConstructor);
+}
+
+// Default mapping: object used for building the default mapper from hits to Split events
+const defaultMapping = {
+  eventTypeId: {
+    event: 'eventAction',
+    social: 'socialAction',
+  },
+  eventValue: {
+    event: 'eventValue',
+    timing: 'timingValue',
+  },
+  eventProperties: {
+    pageview: ['page'],
+    screenview: ['screenName'],
+    event: ['eventCategory', 'eventLabel'],
+    social: ['socialNetwork', 'socialTarget'],
+    timing: ['timingCategory', 'timingVar', 'timingLabel'],
+    exception: ['exDescription', 'exFatal'],
+  }
+};
+
+/**
+ * Build a mapper function based on a mapping object
+ *
+ * @param {object} mapping
+ */
+function mapperBuilder(mapping) {
+  return function (model) {
+    const hitType = model.get('hitType');
+
+    const eventTypeId = model.get(mapping.eventTypeId[hitType] || 'hitType');
+
+    const value = model.get(mapping.eventValue[hitType]);
+
+    const properties = {};
+    const fields = mapping.eventProperties[hitType];
+    if (fields) {
+      for (let i = 0; i < fields.length; i++) {
+        properties[fields[i]] = model.get(fields[i]);
+      }
+    }
+
+    return {
+      eventTypeId,
+      value,
+      properties,
+      timestamp: Date.now(),
+    };
+  };
+}
+
+// exposed for unit testing purposses.
+export const defaultMapper = mapperBuilder(defaultMapping);
+
+export const defaultPrefix = 'ga';
+
+/**
+ * Return a new list of identities removing invalid and duplicated ones.
+ *
+ * @param {Array} identities list of identities
+ * @returns list of valid and unique identities. The list might be empty if `identities` is not an array or all its elements are invalid.
+ */
+export function validateIdentities(identities) {
+  if (!Array.isArray(identities))
+    return [];
+
+  // Remove duplicated identities
+  const uniqueIdentities = unicAsStrings(identities);
+
+  // Filter based on rum-agent identities validator
+  return uniqueIdentities.filter(identity => {
+    if (!identity)
+      return false;
+
+    const maybeKey = identity.key;
+    const maybeTT = identity.trafficType;
+
+    if (!isString(maybeKey) && !numberIsFinite(maybeKey))
+      return false;
+    if (!isString(maybeTT))
+      return false;
+
+    return true;
+  });
+}
+
+/**
+ * Checks if EventData fields (except EventTypeId) are valid, and logs corresponding warnings.
+ * EventTypeId is validated separately.
+ *
+ * @param {EventData} data event data instance to validate. Precondition: data != undefined
+ * @returns {boolean} Whether the data instance is a valid EventData or not.
+ */
+export function validateEventData(eventData) {
+  if (!validateEvent(eventData.eventTypeId, logNameMapper))
+    return false;
+
+  if (validateEventValue(eventData.value, logNameMapper) === false)
+    return false;
+
+  const { properties } = validateEventProperties(eventData.properties, logNameMapper);
+  if (properties === false)
+    return false;
+
+  if (eventData.timestamp && !numberIsFinite(eventData.timestamp))
+    return false;
+
+  if (eventData.key && validateKey(eventData.key, logNameMapper) === false)
+    return false;
+
+  if (eventData.trafficTypeName && validateTrafficType(eventData.trafficTypeName, logNameMapper) === false)
+    return false;
+
+  return true;
+}
+
+const INVALID_PREFIX_REGEX = /^[^a-zA-Z0-9]+/;
+const INVALID_SUBSTRING_REGEX = /[^-_.:a-zA-Z0-9]+/g;
+/**
+ * Fixes the passed string value to comply with EventTypeId format, by removing invalid characters and truncating if necessary.
+ *
+ * @param {string} eventTypeId string value to fix.
+ * @returns {string} Fixed version of `eventTypeId`.
+ */
+export function fixEventTypeId(eventTypeId) {
+  // return the input eventTypeId if it cannot be fixed
+  if (!isString(eventTypeId) || eventTypeId.length === 0) {
+    return eventTypeId;
+  }
+
+  // replace invalid substrings and truncate
+  const fixed = eventTypeId
+    .replace(INVALID_PREFIX_REGEX, '')
+    .replace(INVALID_SUBSTRING_REGEX, '_');
+  const truncated = fixed.slice(0, 80);
+  if (truncated.length < fixed.length) log.warn('EventTypeId was truncated because it cannot be more than 80 characters long.');
+  return truncated;
+}
+
+/**
+ * GaToSplit integration.
+ * This function provides the SplitTracker plugin to ga command queue.
+ *
+ * @param {object} sdkOptions options passed at the SDK integrations settings
+ * @param {object} storage SDK storage passed to track events
+ * @param {object} coreSettings core settings used to define an identity if no one provided as SDK or plugin options
+ */
+function GaToSplit(sdkOptions, storage, coreSettings) {
+
+  const defaultOptions = {
+    prefix: defaultPrefix,
+    // We set default identities if key and TT are present in settings.core
+    identities: (coreSettings.key && coreSettings.trafficType) ?
+      [{ key: coreSettings.key, trafficType: coreSettings.trafficType }] :
+      undefined
+  };
+
+  class SplitTracker {
+
+    // Constructor for the SplitTracker plugin.
+    constructor(tracker, pluginOptions) {
+
+      // precedence of options: SDK options (config.integrations) overwrite pluginOptions (`ga('require', 'splitTracker', pluginOptions)`)
+      const opts = objectAssign({}, defaultOptions, sdkOptions, pluginOptions);
+
+      this.tracker = tracker;
+
+      // Validate identities
+      const validIdentities = validateIdentities(opts.identities);
+
+      if (validIdentities.length === 0) {
+        log.warn('No valid identities were provided. Please check that you are passing a valid list of identities or providing a traffic type at the SDK configuration.');
+        return;
+      }
+
+      const invalids = validIdentities.length - opts.identities.length;
+      if (invalids) {
+        log.warn(`${invalids} identities were discarded because they are invalid or duplicated. Identities must be an array of objects with key and trafficType.`);
+      }
+      opts.identities = validIdentities;
+
+      // Validate prefix
+      if (!isString(opts.prefix)) {
+        log.warn('The provided `prefix` was ignored since it is invalid. Please check that you are passing a string object as `prefix`.');
+        opts.prefix = undefined;
+      }
+
+      // Overwrite sendHitTask to perform plugin tasks:
+      // 1) filter hits
+      // 2) map hits to Split events
+      // 3) handle events, i.e., validate and send them to Split BE
+      const originalSendHitTask = tracker.get('sendHitTask');
+      tracker.set('sendHitTask', function (model) {
+        originalSendHitTask(model);
+
+        // filter hit if `hits` flag is false or if it comes from Split-to-GA integration
+        if (opts.hits === false || model.get('splitHit')) return;
+        try {
+          if (opts.filter && !opts.filter(model)) return;
+        } catch (err) {
+          log.warn(`GaToSplit custom filter threw: ${err}`);
+          return;
+        }
+
+        // map hit into an EventData instance
+        let eventData = defaultMapper(model);
+        if (opts.mapper) {
+          try {
+            eventData = opts.mapper(model, eventData);
+          } catch (err) {
+            log.warn(`GaToSplit custom mapper threw: ${err}`);
+            return;
+          }
+          if (!eventData)
+            return;
+        }
+
+        // Add prefix. Nothing is appended if the prefix is falsy, e.g. undefined or ''.
+        if (opts.prefix) eventData.eventTypeId = `${opts.prefix}.${eventData.eventTypeId}`;
+
+        eventData.eventTypeId = fixEventTypeId(eventData.eventTypeId);
+
+        if (!validateEventData(eventData))
+          return;
+
+        // Store the event
+        if (eventData.key && eventData.trafficTypeName) {
+          storage.events.track(eventData);
+        } else { // Store the event for each Key-TT pair (identities), if key and TT is not present in eventData
+          opts.identities.forEach(identity => {
+            const event = objectAssign({
+              key: identity.key,
+              trafficTypeName: identity.trafficType,
+            }, eventData);
+            storage.events.track(event);
+          });
+        }
+      });
+
+      log.info('Started GA-to-Split integration');
+    }
+
+  }
+
+  // Register the plugin, even if config is invalid, since, if not provided, it will block `ga` command queue.
+  providePlugin('splitTracker', SplitTracker);
+}
+
+export default GaToSplit;

package/src/integrations/ga/SplitToGa.js

@@ -0,0 +1,125 @@
+import logFactory from '../../utils/logger';
+import { uniq } from '../../utils/lang';
+import { SPLIT_IMPRESSION, SPLIT_EVENT } from '../../utils/constants';
+const log = logFactory('splitio-split-to-ga');
+
+class SplitToGa {
+
+  // Default mapper function.
+  static defaultMapper({ type, payload }) {
+    switch (type) {
+      case SPLIT_IMPRESSION:
+        return {
+          hitType: 'event',
+          eventCategory: 'split-impression',
+          eventAction: 'Evaluate ' + payload.impression.feature,
+          eventLabel: 'Treatment: ' + payload.impression.treatment + '. Targeting rule: ' + payload.impression.label + '.',
+          nonInteraction: true,
+        };
+      case SPLIT_EVENT:
+        return {
+          hitType: 'event',
+          eventCategory: 'split-event',
+          eventAction: payload.eventTypeId,
+          eventValue: payload.value,
+          nonInteraction: true,
+        };
+    }
+    return null;
+  }
+
+  // Util to access ga command queue, accounting for the possibility that it has been renamed.
+  static getGa() {
+    return typeof window !== 'undefined' ? window[window['GoogleAnalyticsObject'] || 'ga'] : undefined;
+  }
+
+  /**
+   * Validates if a given object is a UniversalAnalytics.FieldsObject instance, and logs a warning if not.
+   * It checks that the object contains a `hitType`, since it is the minimal field required to send the hit
+   * and avoid the GA error `No hit type specified. Aborting hit.`.
+   * Other validations (e.g., an `event` hitType must have a `eventCategory` and `eventAction`) are handled
+   * and logged (as warnings or errors depending the case) by GA debugger, but the hit is sent anyway.
+   *
+   * @param {UniversalAnalytics.FieldsObject} fieldsObject object to validate.
+   * @returns {boolean} Whether the data instance is a valid FieldsObject or not.
+   */
+  static validateFieldsObject(fieldsObject) {
+    if (fieldsObject && fieldsObject.hitType)
+      return true;
+
+    log.warn('your custom mapper returned an invalid FieldsObject instance. It must be an object with at least a `hitType` field.');
+    return false;
+  }
+
+  constructor(options) {
+
+    // Check if `ga` object is available
+    if (typeof SplitToGa.getGa() !== 'function') {
+      log.warn('`ga` command queue not found. No hits will be sent.');
+      // Return an empty object to avoid creating a SplitToGa instance
+      return {};
+    }
+
+    this.trackerNames = SplitToGa.defaultTrackerNames;
+
+    if (options) {
+      if (typeof options.filter === 'function') this.filter = options.filter;
+      if (typeof options.mapper === 'function') this.mapper = options.mapper;
+      // We strip off duplicated values if we received a `trackerNames` param.
+      // We don't warn if a tracker does not exist, since the user might create it after the SDK is initialized.
+      // Note: GA allows to create and get trackers using a string or number as tracker name, and does nothing if other types are used.
+      if (Array.isArray(options.trackerNames)) this.trackerNames = uniq(options.trackerNames);
+
+      // No need to validate `impressions` and `events` flags. Any other value than `false` is ignored.
+      this.impressions = options.impressions;
+      this.events = options.events;
+    }
+
+    log.info('Started Split-to-GA integration');
+  }
+
+  queue(data) {
+    // access ga command queue via `getGa` method, accounting for the possibility that
+    // the global `ga` reference was not yet mutated by analytics.js.
+    const ga = SplitToGa.getGa();
+    if (ga) {
+
+      if(this.impressions === false && data.type === SPLIT_IMPRESSION) return;
+      if(this.events === false && data.type === SPLIT_EVENT) return;
+
+      let fieldsObject;
+      try { // only try/catch filter and mapper, which might be defined by the user
+        // filter
+        if (this.filter && !this.filter(data))
+          return;
+
+        // map data into a FieldsObject instance
+        fieldsObject = SplitToGa.defaultMapper(data);
+        if (this.mapper) {
+          fieldsObject = this.mapper(data, fieldsObject);
+          // don't send the hit if it is falsy or invalid
+          if (!fieldsObject || !SplitToGa.validateFieldsObject(fieldsObject))
+            return;
+        }
+      } catch (err) {
+        log.warn(`SplitToGa queue method threw: ${err}. No hit was sent.`);
+        return;
+      }
+
+      // send the hit
+      this.trackerNames.forEach(trackerName => {
+        const sendCommand = trackerName ? `${trackerName}.send` : 'send';
+        // mark the hit as a Split one to avoid the loop.
+        fieldsObject.splitHit = true;
+        // Send to GA using our reference to the GA object.
+        ga(sendCommand, fieldsObject);
+      });
+    }
+  }
+
+}
+
+// A falsy object represents the default tracker
+SplitToGa.defaultTrackerNames = [''];
+
+export default SplitToGa;

package/src/integrations/node.js

@@ -0,0 +1,4 @@
+const integrationsManagerFactory = () => {
+};
+
+export default integrationsManagerFactory;

package/src/integrations/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "./node.js",
+  "browser": "./browser.js"
+}