castled-js-sdk 0.0.1 → 0.0.3

package/src/integrations/GA4/config.js

@@ -0,0 +1,296 @@
+const customParametersExclusion = [
+  'item_id',
+  'itemId',
+  'product_id',
+  'item_name',
+  'itemName',
+  'name',
+  'coupon',
+  'item_brand',
+  'itemBrand',
+  'brand',
+  'item_variant',
+  'itemVariant',
+  'variant',
+  'price',
+  'quantity',
+  'index',
+  'position',
+  'affiliation',
+  'discount',
+  'item_category',
+  'itemCategory',
+  'category',
+  'item_category2',
+  'item_category3',
+  'item_category4',
+  'item_category5',
+  'item_list_id',
+  'item_list_name',
+  'location_id',
+];
+
+const itemsArrayParams = [
+  { sourceKeys: ['product_id', 'itemId'], destKey: 'item_id' },
+  { sourceKeys: ['name', 'itemName'], destKey: 'item_name' },
+  { sourceKeys: 'coupon', destKey: 'coupon' },
+  { sourceKeys: ['brand', 'itemBrand'], destKey: 'item_brand' },
+  { sourceKeys: ['variant', 'itemVariant'], destKey: 'item_variant' },
+  { sourceKeys: 'price', destKey: 'price', metadata: { type: 'toNumber' } },
+  { sourceKeys: 'quantity', destKey: 'quantity', metadata: { type: 'toNumber' } },
+  { sourceKeys: 'position', destKey: 'index', metadata: { type: 'toNumber' } },
+  { sourceKeys: 'affiliation', destKey: 'affiliation' },
+  { sourceKeys: 'discount', destKey: 'discount' },
+  { sourceKeys: ['category', 'itemCategory'], destKey: 'item_category' },
+  { sourceKeys: 'item_category2', destKey: 'item_category2' },
+  { sourceKeys: 'item_category3', destKey: 'item_category3' },
+  { sourceKeys: 'item_category4', destKey: 'item_category4' },
+  { sourceKeys: 'item_category5', destKey: 'item_category5' },
+  { sourceKeys: 'item_list_id', destKey: 'item_list_id' },
+  { sourceKeys: 'item_list_name', destKey: 'item_list_name' },
+  { sourceKeys: 'location_id', destKey: 'location_id' },
+];
+
+const eventParams = {
+  method: { sourceKeys: 'properties.method', destKey: 'method' },
+  product_cart_shared_method: { sourceKeys: 'properties.share_via', destKey: 'method' },
+  currency: {
+    sourceKeys: 'properties.currency',
+    destKey: 'currency',
+    metadata: { defaultValue: 'USD' },
+  },
+  value: {
+    sourceKeys: ['properties.total', 'properties.value', 'properties.revenue', 'properties.price'],
+    destKey: 'value',
+    metadata: { type: 'toNumber' },
+  },
+  product_add_or_remove_value: {
+    sourceKeys: [
+      'properties.total',
+      'properties.value',
+      'properties.revenue',
+      {
+        operation: 'multiplication',
+        args: [
+          {
+            sourceKeys: 'properties.price',
+          },
+          {
+            sourceKeys: 'properties.quantity',
+            defaultVal: 1,
+          },
+        ],
+      },
+    ],
+    destKey: 'value',
+    metadata: { type: 'toNumber' },
+  },
+  search: { sourceKeys: 'properties.query', destKey: 'search_term' },
+  list_id: { sourceKeys: 'properties.list_id', destKey: 'item_list_id' },
+  list_name: { sourceKeys: 'properties.category', destKey: 'item_list_name' },
+  creative_name: {
+    sourceKeys: ['properties.creative_name', 'properties.creative'],
+    destKey: 'creative_name',
+  },
+  creative_slot: {
+    sourceKeys: ['properties.creative_slot', 'properties.position'],
+    destKey: 'creative_slot',
+  },
+  promotion_id: { sourceKeys: 'properties.promotion_id', destKey: 'promotion_id' },
+  promotion_name: {
+    sourceKeys: ['properties.promotion_name', 'properties.name'],
+    destKey: 'promotion_name',
+  },
+  coupon: { sourceKeys: 'properties.coupon', destKey: 'coupon' },
+  payment_method: { sourceKeys: 'properties.payment_method', destKey: 'payment_type' },
+  shipping_method: { sourceKeys: 'properties.shipping_method', destKey: 'shipping_tier' },
+  order_id: { sourceKeys: 'properties.order_id', destKey: 'transaction_id' },
+  shipping: {
+    sourceKeys: 'properties.shipping',
+    destKey: 'shipping',
+    metadata: { type: 'toNumber' },
+  },
+  tax: { sourceKeys: 'properties.tax', destKey: 'tax', metadata: { type: 'toNumber' } },
+  content_type: { sourceKeys: 'properties.content_type', destKey: 'content_type' },
+  item_id: {
+    sourceKeys: ['properties.item_id', 'properties.product_id', 'properties.sku'],
+    destKey: 'item_id',
+  },
+  cart_shared_item_id: {
+    sourceKeys: ['properties.item_id', 'properties.cart_id'],
+    destKey: 'item_id',
+  },
+  url: { sourceKeys: 'url', destKey: 'page_location' },
+  referrer: { sourceKeys: 'referrer', destKey: 'page_referrer' },
+  title: { sourceKeys: 'title', destKey: 'page_title' },
+};
+
+const eventsConfig = {
+  LOGIN: {
+    event: 'login',
+    mapping: [eventParams.method],
+  },
+  SIGN_UP: {
+    event: 'sign_up',
+    mapping: [eventParams.method],
+  },
+  GENERATE_LEAD: {
+    event: 'generate_lead',
+    mapping: [eventParams.currency, { ...eventParams.value, required: true }],
+  },
+  PRODUCTS_SEARCHED: {
+    event: 'search',
+    mapping: [eventParams.search],
+  },
+  PRODUCT_SEARCHED: {
+    event: 'search',
+    mapping: [eventParams.search],
+  },
+  PRODUCT_LIST_VIEWED: {
+    event: 'view_item_list',
+    itemList: 'YES',
+    mapping: [eventParams.list_id, eventParams.list_name],
+  },
+  PROMOTION_VIEWED: {
+    event: 'view_promotion',
+    itemList: 'YES',
+    mapping: [
+      eventParams.promotion_id,
+      eventParams.creative_slot,
+      eventParams.creative_name,
+      eventParams.promotion_name,
+    ],
+  },
+  PROMOTION_CLICKED: {
+    event: 'select_promotion',
+    itemList: 'NO',
+    mapping: [
+      eventParams.promotion_id,
+      eventParams.creative_slot,
+      eventParams.creative_name,
+      eventParams.promotion_name,
+    ],
+  },
+  PRODUCT_CLICKED: {
+    event: 'select_item',
+    item: 'YES',
+    mapping: [eventParams.list_id, eventParams.list_name],
+  },
+  PRODUCTS_CLICKED: {
+    event: 'select_item',
+    item: 'YES',
+    mapping: [eventParams.list_id, eventParams.list_name],
+  },
+  PRODUCT_VIEWED: {
+    event: 'view_item',
+    item: 'YES',
+    mapping: [eventParams.currency, { ...eventParams.value, required: true }],
+  },
+  PRODUCT_ADDED: {
+    event: 'add_to_cart',
+    itemList: 'NO',
+    item: 'YES',
+    mapping: [eventParams.currency, { ...eventParams.product_add_or_remove_value, required: true }],
+  },
+  PRODUCT_REMOVED: {
+    event: 'remove_from_cart',
+    itemList: 'NO',
+    item: 'YES',
+    mapping: [eventParams.currency, { ...eventParams.product_add_or_remove_value, required: true }],
+  },
+  CART_VIEWED: {
+    event: 'view_cart',
+    itemList: 'YES',
+    mapping: [eventParams.currency, { ...eventParams.value, required: true }],
+  },
+  CHECKOUT_STARTED: {
+    event: 'begin_checkout',
+    itemList: 'YES',
+    mapping: [eventParams.currency, eventParams.coupon, { ...eventParams.value, required: true }],
+  },
+  PAYMENT_INFO_ENTERED: {
+    event: 'add_payment_info',
+    itemList: 'YES',
+    mapping: [
+      eventParams.currency,
+      eventParams.coupon,
+      eventParams.payment_method,
+      { ...eventParams.value, required: true },
+    ],
+  },
+  CHECKOUT_STEP_COMPLETED: {
+    event: 'add_shipping_info',
+    itemList: 'YES',
+    mapping: [
+      eventParams.currency,
+      eventParams.coupon,
+      eventParams.shipping_method,
+      { ...eventParams.value, required: true },
+    ],
+  },
+  ORDER_COMPLETED: {
+    event: 'purchase',
+    itemList: 'YES',
+    mapping: [
+      eventParams.tax,
+      eventParams.coupon,
+      eventParams.shipping,
+      eventParams.currency,
+      { ...eventParams.value, required: true },
+      { ...eventParams.order_id, required: true },
+    ],
+  },
+  ORDER_REFUNDED: {
+    event: 'refund',
+    itemList: 'NO',
+    mapping: [
+      eventParams.tax,
+      eventParams.coupon,
+      eventParams.shipping,
+      eventParams.currency,
+      { ...eventParams.value, required: true },
+      { ...eventParams.order_id, required: true },
+    ],
+  },
+  PRODUCT_ADDED_TO_WISHLIST: {
+    event: 'add_to_wishlist',
+    itemList: 'NO',
+    item: 'YES',
+    mapping: [eventParams.currency, { ...eventParams.value, required: true }],
+  },
+  PRODUCT_SHARED: {
+    event: 'share',
+    mapping: [
+      eventParams.item_id,
+      eventParams.content_type,
+      eventParams.product_cart_shared_method,
+    ],
+  },
+  CART_SHARED: {
+    event: 'share',
+    mapping: [
+      eventParams.content_type,
+      eventParams.cart_shared_item_id,
+      eventParams.product_cart_shared_method,
+    ],
+  },
+  PAGE: {
+    event: 'page_view',
+    mapping: [eventParams.url, eventParams.title, eventParams.referrer],
+  },
+};
+
+const rootLevelProductsSupportedEventsList = [
+  eventsConfig.PRODUCT_CLICKED.event,
+  eventsConfig.PRODUCT_VIEWED.event,
+  eventsConfig.PRODUCT_ADDED.event,
+  eventsConfig.PRODUCT_REMOVED.event,
+  eventsConfig.PRODUCT_ADDED_TO_WISHLIST.event,
+];
+
+export {
+  eventsConfig,
+  itemsArrayParams,
+  customParametersExclusion,
+  rootLevelProductsSupportedEventsList,
+};

package/src/integrations/GA4/constants.js

@@ -0,0 +1,15 @@
+const NAME = 'GA4';
+const CNameMapping = {
+  [NAME]: NAME,
+  'Google Analytics 4': NAME,
+  'Google analytics 4': NAME,
+  'google analytics 4': NAME,
+  'Google Analytics4': NAME,
+  'Google analytics4': NAME,
+  'google analytics4': NAME,
+  'Google Analytics 4 (GA4)': NAME,
+  'google analytics 4 (ga4)': NAME,
+  GoogleAnalytics4: NAME,
+};
+
+export { NAME, CNameMapping };

package/src/integrations/GA4/index.js

@@ -0,0 +1 @@
+export { default as GA4 } from './browser';

package/src/integrations/GA4/utils.js

@@ -0,0 +1,329 @@
+import {
+  eventsConfig,
+  itemsArrayParams,
+  customParametersExclusion,
+  rootLevelProductsSupportedEventsList,
+} from './config';
+import logger from '../../utils/logUtil';
+import { isBlank, flattenJson } from '../../utils/commonUtils';
+import { isEmptyObject, constructPayload, extractCustomFields } from '../../utils/utils';
+
+/**
+ * Extracts last word after . from string
+ * properties.products -> products
+ * @param {*} key
+ * @returns
+ */
+const extractLastKey = (key) => key.split('.').pop();
+
+/**
+ * Validates weather to send userId property to GA4 or not
+ * @param {*} integrations
+ */
+const shouldSendUserId = (integrations) => integrations?.GA4?.sendUserId ?? true;
+
+/**
+ * Reserved event names cannot be used
+ * Ref - https://support.google.com/analytics/answer/13316687?hl=en#zippy=%2Cweb
+ * @param {*} name
+ */
+const isReservedEventName = (event) => {
+  const reservedEventNames = [
+    'click',
+    'error',
+    'scroll',
+    'form_start',
+    'form_submit',
+    'first_open',
+    'first_visit',
+    'app_remove',
+    'video_start',
+    'session_start',
+    'view_complete',
+    'file_download',
+    'video_progress',
+    'user_engagement',
+    'in_app_purchase',
+    'app_store_refund',
+    'app_store_subscription_cancel',
+    'app_store_subscription_renew',
+  ];
+
+  return reservedEventNames.includes(event);
+};
+
+/**
+ * Validates and formats the event name
+ * @param {*} eventName
+ * @returns
+ */
+const formatAndValidateEventName = (eventName) => {
+  if (!eventName || typeof eventName !== 'string') {
+    logger.error('Event name is required and should be a string');
+    return null;
+  }
+
+  /**
+   * Trim and replace spaces with '_'
+   * product searched -> product_searched
+   */
+  const trimmedEvent = eventName.trim().replace(/\s+/g, '_');
+
+  // Reserved event names are not allowed
+  if (isReservedEventName(trimmedEvent)) {
+    logger.error(`Reserved event name ${trimmedEvent} is not allowed`);
+    return null;
+  }
+
+  return trimmedEvent;
+};
+
+/**
+ * Remove arrays and objects from transformed payload
+ * @param {*} params
+ * @returns
+ */
+const removeInvalidParams = (params) =>
+  Object.fromEntries(
+    Object.entries(params).filter(
+      ([key, value]) => key === 'items' || (typeof value !== 'object' && !isBlank(value)),
+    ),
+  );
+
+/**
+ * Returns custom parameters for ga4 event payload
+ * @param {*} message
+ * @param {*} keys
+ * @param {*} exclusionFields
+ * @returns
+ */
+const getCustomParameters = (message, keys, exclusionFields) => {
+  let customParameters = {};
+  customParameters = extractCustomFields(message, customParameters, keys, exclusionFields);
+  // append in the params if any custom fields are passed after flattening the JSON
+  if (!isEmptyObject(customParameters)) {
+    customParameters = flattenJson(customParameters, '_', 'strict');
+  }
+  return customParameters;
+};
+
+/**
+ * Returns exclusion fields list
+ * @param {*} mapRootLevelPropertiesToGA4ItemsArray
+ * @param {*} mapping
+ * @param {*} event
+ * @returns
+ */
+const getExclusionFields = (mapRootLevelPropertiesToGA4ItemsArray, mapping, event) => {
+  // Exclude event properties which are already mapped
+  let exclusionFields = mapping.reduce((exclusionList, element) => {
+    const mappingSourceKeys = element.sourceKeys;
+
+    if (typeof mappingSourceKeys === 'string') {
+      exclusionList.push(extractLastKey(mappingSourceKeys));
+    } else if (Array.isArray(mappingSourceKeys)) {
+      mappingSourceKeys.forEach((item) => {
+        if (typeof item === 'string') {
+          exclusionList.push(extractLastKey(item));
+        }
+      });
+    }
+
+    return exclusionList;
+  }, []);
+
+  // We are mapping "products" to "items", so to remove redundancy we should not send products again
+  exclusionFields.push('products');
+
+  if (
+    mapRootLevelPropertiesToGA4ItemsArray &&
+    rootLevelProductsSupportedEventsList.includes(event)
+  ) {
+    // Exclude root-level properties (itemsArrayParams) which are already mapped
+    exclusionFields = exclusionFields.concat(customParametersExclusion);
+  }
+  return exclusionFields;
+};
+
+/**
+ * Creates and returns items array from products
+ * @param {*} message
+ * @param {*} isItemsRequired
+ * @returns
+ */
+const getItemList = (message) => {
+  const items = [];
+
+  const { properties } = message;
+  let products = properties?.products;
+  let isObject = false;
+
+  // Supporting products as an object
+  if (typeof products === 'object' && !Array.isArray(products)) {
+    isObject = true;
+    products = [products];
+  }
+
+  if (Array.isArray(products)) {
+    products.forEach((product, index) => {
+      let item = constructPayload(product, itemsArrayParams);
+      // take additional parameters apart from mapped one
+      const itemCustomProperties = extractCustomFields(
+        message,
+        {},
+        isObject ? ['properties.products'] : [`properties.products.${index}`],
+        customParametersExclusion,
+      );
+      if (!isEmptyObject(itemCustomProperties)) {
+        item = removeInvalidParams({
+          ...item,
+          ...flattenJson(itemCustomProperties, '_', 'strict'),
+        });
+      }
+
+      if (!isEmptyObject(item)) {
+        items.push(item);
+      }
+    });
+  }
+  return items;
+};
+
+/**
+ * Creates and returns items array from properties
+ * @param {*} message
+ * @param {*} isItemsRequired
+ * @returns
+ */
+const getItem = (message) => {
+  const { properties } = message;
+  const items = [];
+
+  // Only prepare items array if properties exists and it should have at least one key
+  if (properties && Object.keys(properties).length > 0) {
+    const item = constructPayload(properties, itemsArrayParams);
+    if (!isEmptyObject(item)) {
+      items.push(item);
+    }
+  }
+
+  return items;
+};
+
+/**
+ * Returns items array for ga4 event payload
+ * @param {*} message
+ * @param {*} eventConfig
+ * @returns
+ */
+const getItemsArray = (message, eventConfig) => {
+  const { itemList, item } = eventConfig;
+  let items = [];
+  let mapRootLevelPropertiesToGA4ItemsArray = false;
+
+  if (itemList && item) {
+    items = getItemList(message);
+
+    if (!(items && items.length > 0)) {
+      mapRootLevelPropertiesToGA4ItemsArray = true;
+      items = getItem(message);
+    }
+  } else if (item) {
+    // item
+    mapRootLevelPropertiesToGA4ItemsArray = true;
+    items = getItem(message);
+  } else if (itemList) {
+    // itemList
+    items = getItemList(message);
+  }
+
+  return { items, mapRootLevelPropertiesToGA4ItemsArray };
+};
+
+/**
+ * Returns ga4 standard event payload
+ * @param {*} message
+ * @param {*} eventConfig
+ * @returns
+ */
+const prepareStandardEventParams = (message, eventConfig) => {
+  const { event, mapping } = eventConfig;
+  let payload = constructPayload(message, mapping);
+
+  // Validation for required params
+  if (Array.isArray(mapping) && mapping.length > 0) {
+    const hasMissingRequiredValue = mapping.some((mappingItem) => {
+      if (!payload[mappingItem.destKey] && mappingItem.required) {
+        logger.error(`Missing required value from ${JSON.stringify(mappingItem.sourceKeys)}`);
+        return true;
+      }
+      return false;
+    });
+
+    if (hasMissingRequiredValue) {
+      return null;
+    }
+  }
+
+  const { items, mapRootLevelPropertiesToGA4ItemsArray } = getItemsArray(message, eventConfig);
+  const exclusionFields = getExclusionFields(mapRootLevelPropertiesToGA4ItemsArray, mapping, event);
+  const customParameters = getCustomParameters(message, ['properties'], exclusionFields);
+
+  if (items.length > 0) {
+    payload.items = items;
+  }
+
+  if (!isEmptyObject(customParameters)) {
+    payload = { ...payload, ...customParameters };
+  }
+
+  return payload;
+};
+
+/**
+ * Returns ga4 custom event payload
+ * @param {*} message
+ * @returns
+ */
+const prepareCustomEventParams = (message) => getCustomParameters(message, ['properties'], []);
+
+/**
+ * Returns ga4 track event name and transformed payload
+ * @param {*} message
+ * @param {*} eventName
+ * @returns
+ */
+const prepareParamsAndEventName = (message, eventName) => {
+  const eventConfig = eventsConfig[`${eventName.toUpperCase()}`];
+
+  // Part 1: prepare params
+  const params = eventConfig
+    ? prepareStandardEventParams(message, eventConfig)
+    : prepareCustomEventParams(message);
+
+  // Handle the case where required params are not present in the payload
+  if (!params) {
+    return null;
+  }
+
+  const validatedParams = removeInvalidParams(params);
+
+  // Part 2: prepare event name
+  const event = eventConfig ? eventConfig.event : eventName;
+
+  return { params: validatedParams, event };
+};
+
+export {
+  getItem,
+  getItemList,
+  getItemsArray,
+  extractLastKey,
+  shouldSendUserId,
+  getExclusionFields,
+  isReservedEventName,
+  getCustomParameters,
+  removeInvalidParams,
+  prepareParamsAndEventName,
+  formatAndValidateEventName,
+};