castled-js-sdk 0.0.1 → 0.0.2

package/src/integrations/FacebookPixel/browser.js

@@ -0,0 +1,313 @@
+/* eslint-disable func-names */
+/* eslint-disable prefer-rest-params */
+/* eslint-disable prefer-spread */
+/* eslint-disable no-underscore-dangle */
+/* eslint-disable class-methods-use-this */
+import each from '@ndhoule/each';
+import sha256 from 'crypto-js/sha256';
+import logger from '../../utils/logUtil';
+import ScriptLoader from '../../utils/ScriptLoader';
+import {
+  merge,
+  getEventId,
+  buildPayLoad,
+  eventHelpers,
+  formatRevenue,
+  getContentType,
+  getHashedStatus,
+  getContentCategory,
+  getProductContentAndId,
+  getProductListViewedEventParams,
+  getProductsContentsAndContentIds,
+} from './utils';
+import { getHashFromArray } from '../../utils/commonUtils';
+import { NAME, traitsMapper, reserveTraits } from './constants';
+import { constructPayload } from '../../utils/utils';
+
+class FacebookPixel {
+  constructor(config, analytics, destinationInfo) {
+    if (analytics.logLevel) {
+      logger.setLogLevel(analytics.logLevel);
+    }
+    this.blacklistPiiProperties = config.blacklistPiiProperties;
+    this.categoryToContent = config.categoryToContent || [];
+    this.pixelId = config.pixelId;
+    this.eventsToEvents = config.eventsToEvents;
+    this.valueFieldIdentifier = config.valueFieldIdentifier;
+    this.advancedMapping = config.advancedMapping;
+    this.traitKeyToExternalId = config.traitKeyToExternalId;
+    this.legacyConversionPixelId = config.legacyConversionPixelId || [];
+    this.userIdAsPixelId = config.userIdAsPixelId || [];
+    this.whitelistPiiProperties = config.whitelistPiiProperties;
+    this.useUpdatedMapping = config.useUpdatedMapping;
+    this.name = NAME;
+    this.analytics = analytics;
+    ({
+      shouldApplyDeviceModeTransformation: this.shouldApplyDeviceModeTransformation,
+      propagateEventsUntransformedOnError: this.propagateEventsUntransformedOnError,
+      destinationId: this.destinationId,
+    } = destinationInfo ?? {});
+  }
+
+  init() {
+    logger.debug('===in init FbPixel===');
+
+    window._fbq = function () {
+      if (window.fbq.callMethod) {
+        window.fbq.callMethod.apply(window.fbq, arguments);
+      } else {
+        window.fbq.queue.push(arguments);
+      }
+    };
+
+    window.fbq = window.fbq || window._fbq;
+    window.fbq.push = window.fbq;
+    window.fbq.loaded = true;
+    window.fbq.disablePushState = true; // disables automatic pageview tracking
+    window.fbq.allowDuplicatePageViews = true; // enables fb
+    window.fbq.version = '2.0';
+    window.fbq.queue = [];
+    if (this.advancedMapping) {
+      if (this.useUpdatedMapping) {
+        const userData = {
+          context: {
+            traits: { ...this.analytics.getUserTraits() },
+          },
+          userId: this.analytics.getUserId(),
+          anonymousId: this.analytics.getAnonymousId(),
+        };
+
+        const userPayload = constructPayload(userData, traitsMapper);
+        // here we are sending other traits apart from the reserved ones.
+        reserveTraits.forEach((element) => {
+          delete userData.context?.traits[element];
+        });
+
+        this.userPayload = { ...userPayload, ...userData.context.traits };
+
+        if (this.userPayload.external_id) {
+          this.userPayload.external_id = sha256(this.userPayload.external_id).toString();
+        }
+      } else {
+        this.userPayload = { ...this.analytics.getUserTraits() };
+      }
+      window.fbq('init', this.pixelId, this.userPayload);
+    } else {
+      window.fbq('init', this.pixelId);
+    }
+    ScriptLoader('fbpixel-integration', 'https://connect.facebook.net/en_US/fbevents.js');
+  }
+
+  isLoaded() {
+    logger.debug('in FBPixel isLoaded');
+    return !!(window.fbq && window.fbq.callMethod);
+  }
+
+  isReady() {
+    logger.debug('in FBPixel isReady');
+    return !!(window.fbq && window.fbq.callMethod);
+  }
+
+  page(htElement) {
+    const { properties } = htElement.message;
+    window.fbq('track', 'PageView', properties, {
+      eventID: getEventId(htElement.message),
+    });
+  }
+
+  track(htElement) {
+    const self = this;
+    const { event } = htElement.message;
+    const properties = eventHelpers.getProperties(htElement.message);
+    const {
+      id,
+      sku,
+      name,
+      price,
+      query,
+      revenue,
+      products,
+      quantity,
+      contentName,
+      product_id: productId,
+      product_name: productName,
+    } = properties;
+    let { value, category, currency } = properties;
+
+    const revValue = formatRevenue(revenue);
+    eventHelpers.validateRevenue(revValue);
+    currency = eventHelpers.getCurrency(currency);
+    const payload = buildPayLoad(
+      htElement,
+      this.whitelistPiiProperties,
+      this.blacklistPiiProperties,
+      getHashedStatus(htElement.message, this.name),
+    );
+
+    const standard = this.eventsToEvents;
+    const legacy = this.legacyConversionPixelId;
+    const standardTo = getHashFromArray(standard);
+    const legacyTo = getHashFromArray(legacy);
+    const useValue = this.valueFieldIdentifier === 'properties.value';
+    const prodId = eventHelpers.getProdId(productId, sku, id);
+    value = eventHelpers.getFormattedRevenue(revValue, value);
+    // check for category data type
+    if (category && !getContentCategory(category)) {
+      return;
+    }
+    category = getContentCategory(category);
+    const derivedEventID = getEventId(htElement.message);
+
+    if (event === 'Product List Viewed') {
+      const { contentIds, contentType, contents } = getProductListViewedEventParams(properties);
+
+      const productInfo = {
+        content_ids: contentIds,
+        content_type: getContentType(htElement, contentType, this.categoryToContent),
+        contents,
+        content_category: eventHelpers.getCategory(category),
+        content_name: contentName,
+        value,
+        currency,
+      };
+
+      this.makeTrackSignalCall(
+        self.pixelId,
+        'ViewContent',
+        merge(productInfo, payload),
+        derivedEventID,
+      );
+      this.makeTrackSignalCalls(self.pixelId, event, legacyTo, derivedEventID, {
+        currency,
+        value: revValue,
+      });
+    } else if (event === 'Product Viewed' || event === 'Product Added') {
+      const { contents, contentIds } = getProductContentAndId(prodId, quantity, price);
+
+      const productInfo = {
+        content_ids: contentIds,
+        content_type: getContentType(htElement, 'product', this.categoryToContent),
+        content_name: eventHelpers.getProdName(productName, name),
+        content_category: eventHelpers.getCategory(category),
+        currency,
+        value: eventHelpers.getValue(useValue, value, price),
+        contents,
+      };
+
+      this.makeTrackSignalCall(
+        self.pixelId,
+        eventHelpers.getEventName(event),
+        merge(productInfo, payload),
+        derivedEventID,
+      );
+      this.makeTrackSignalCalls(self.pixelId, event, legacyTo, derivedEventID, {
+        currency,
+        value: productInfo.value,
+      });
+    } else if (event === 'Order Completed') {
+      const contentType = getContentType(htElement, 'product', this.categoryToContent);
+      const { contents, contentIds } = getProductsContentsAndContentIds(products, quantity, price);
+
+      // ref: https://developers.facebook.com/docs/meta-pixel/implementation/marketing-api#purchase
+      // "trackSingle" feature is :
+      // https://developers.facebook.com/ads/blog/post/v2/2017/11/28/event-tracking-with-multiple-pixels-tracksingle/
+
+      const productInfo = {
+        content_ids: contentIds,
+        content_type: contentType,
+        currency,
+        value: revValue,
+        contents,
+        num_items: contentIds.length,
+        content_name: contentName,
+      };
+
+      this.makeTrackSignalCall(
+        self.pixelId,
+        'Purchase',
+        merge(productInfo, payload),
+        derivedEventID,
+      );
+      this.makeTrackSignalCalls(self.pixelId, event, legacyTo, derivedEventID, {
+        currency,
+        value: revValue,
+      });
+    } else if (event === 'Products Searched') {
+      const { contents, contentIds } = getProductContentAndId(prodId, quantity, price);
+
+      const productInfo = {
+        content_ids: contentIds,
+        content_category: eventHelpers.getCategory(category),
+        currency,
+        value,
+        contents,
+        search_string: query,
+      };
+
+      this.makeTrackSignalCall(self.pixelId, 'Search', merge(productInfo, payload), derivedEventID);
+      this.makeTrackSignalCalls(self.pixelId, event, legacyTo, derivedEventID, { currency, value });
+    } else if (event === 'Checkout Started') {
+      let contentCategory = category;
+      const { contents, contentIds } = getProductsContentsAndContentIds(products, quantity, price);
+      if (Array.isArray(products) && !contentCategory && products[0] && products[0].category) {
+        contentCategory = products[0].category;
+      }
+
+      const productInfo = {
+        content_ids: contentIds,
+        content_type: getContentType(htElement, 'product', this.categoryToContent),
+        content_category: contentCategory,
+        currency,
+        value: revValue,
+        contents,
+        num_items: contentIds.length,
+      };
+
+      this.makeTrackSignalCall(
+        self.pixelId,
+        'InitiateCheckout',
+        merge(productInfo, payload),
+        derivedEventID,
+      );
+      this.makeTrackSignalCalls(self.pixelId, event, legacyTo, derivedEventID, {
+        currency,
+        value: revValue,
+      });
+    } else {
+      logger.debug('inside custom');
+      if (eventHelpers.isCustomEventNotMapped(standardTo, legacyTo, event)) {
+        logger.debug('inside custom not mapped');
+        payload.value = revValue;
+        window.fbq('trackSingleCustom', self.pixelId, event, payload, {
+          eventID: derivedEventID,
+        });
+      } else {
+        payload.value = revValue;
+        payload.currency = currency;
+        this.makeTrackSignalCalls(self.pixelId, event, standardTo, derivedEventID, payload);
+        this.makeTrackSignalCalls(self.pixelId, event, legacyTo, derivedEventID, {
+          currency,
+          value: revValue,
+        });
+      }
+    }
+  }
+
+  makeTrackSignalCalls(pixelId, event, array, derivedEventID, payload) {
+    each((val, key) => {
+      if (key === event.toLowerCase()) {
+        window.fbq('trackSingle', pixelId, val, payload, {
+          eventID: derivedEventID,
+        });
+      }
+    }, array);
+  }
+
+  makeTrackSignalCall(pixelId, event, payload, derivedEventID) {
+    window.fbq('trackSingle', pixelId, event, payload, {
+      eventID: derivedEventID,
+    });
+  }
+}
+
+export default FacebookPixel;

package/src/integrations/FacebookPixel/constants.js

@@ -0,0 +1,77 @@
+const NAME = 'FACEBOOK_PIXEL';
+const CNameMapping = {
+  [NAME]: NAME,
+  'FB Pixel': NAME,
+  'Facebook Pixel': NAME,
+  'facebook pixel': NAME,
+  fbpixel: NAME,
+  FBPIXEL: NAME,
+  FB_PIXEL: NAME,
+};
+
+const traitsMapper = [
+  {
+    destKey: 'external_id',
+    sourceKeys: ['userId', 'context.traits.userId', 'context.traits.id', 'anonymousId'],
+  },
+  {
+    destKey: 'em',
+    sourceKeys: 'context.traits.email',
+  },
+  {
+    destKey: 'ph',
+    sourceKeys: 'context.traits.phone',
+  },
+  {
+    destKey: 'ge',
+    sourceKeys: 'context.traits.gender',
+  },
+  {
+    destKey: 'db',
+    sourceKeys: 'context.traits.birthday',
+  },
+  {
+    destKey: 'ln',
+    sourceKeys: ['context.traits.lastname', 'context.traits.lastName', 'context.traits.last_name'],
+  },
+  {
+    destKey: 'fn',
+    sourceKeys: [
+      'context.traits.firstname',
+      'context.traits.firstName',
+      'context.traits.first_name',
+    ],
+  },
+  {
+    destKey: 'ct',
+    sourceKeys: ['context.traits.address.city', 'context.traits.city'],
+  },
+  {
+    destKey: 'st',
+    sourceKeys: ['context.traits.address.state', 'context.traits.state'],
+  },
+  {
+    destKey: 'zp',
+    sourceKeys: ['context.traits.address.zip', 'context.traits.zip'],
+  },
+  {
+    destKey: 'country',
+    sourceKeys: ['context.traits.address.country', 'context.traits.country'],
+  },
+];
+
+const reserveTraits = [
+  'email',
+  'lastName',
+  'firstName',
+  'phone',
+  'external_id',
+  'city',
+  'birthday',
+  'gender',
+  'street',
+  'zip',
+  'country',
+];
+
+export { traitsMapper, CNameMapping, NAME, reserveTraits };

package/src/integrations/FacebookPixel/index.js

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

package/src/integrations/FacebookPixel/utils.js

@@ -0,0 +1,310 @@
+import is from 'is';
+import get from 'get-value';
+import sha256 from 'crypto-js/sha256';
+import logger from '../../utils/logUtil';
+import { isDefined } from '../../utils/commonUtils';
+
+function getEventId(message) {
+  return (
+    get(message, 'traits.event_id') ||
+    get(message, 'context.traits.event_id') ||
+    get(message, 'properties.event_id') ||
+    message.messageId
+  );
+}
+
+/**
+ * This method gets content category
+ *
+ * @param {*} category
+ * @returns The content category as a string
+ */
+const getContentCategory = (category) => {
+  let contentCategory = category;
+  if (Array.isArray(contentCategory)) {
+    contentCategory = contentCategory.map(String).join(',');
+  }
+  if (
+    contentCategory &&
+    typeof contentCategory !== 'string' &&
+    typeof contentCategory !== 'object'
+  ) {
+    contentCategory = String(contentCategory);
+  }
+  if (
+    contentCategory &&
+    typeof contentCategory !== 'string' &&
+    !Array.isArray(contentCategory) &&
+    typeof contentCategory === 'object'
+  ) {
+    logger.error("'properties.category' must be either be a string or an array");
+    return;
+  }
+  // eslint-disable-next-line consistent-return
+  return contentCategory;
+};
+
+const getHashedStatus = (message, integrationName) => {
+  const val = get(message, `integrations.${integrationName}.hashed`);
+  return val;
+};
+
+const buildPayLoad = (
+  htElement,
+  configWhilistedProperties,
+  configBlacklistedProperties,
+  hashedPii,
+) => {
+  const dateFields = [
+    'checkinDate',
+    'checkoutDate',
+    'departingArrivalDate',
+    'departingDepartureDate',
+    'returningArrivalDate',
+    'returningDepartureDate',
+    'travelEnd',
+    'travelStart',
+  ];
+  const defaultPiiProperties = [
+    'email',
+    'firstName',
+    'lastName',
+    'gender',
+    'city',
+    'country',
+    'phone',
+    'state',
+    'zip',
+    'birthday',
+  ];
+  const whitelistPiiProperties = configWhilistedProperties || [];
+  const blacklistPiiProperties = configBlacklistedProperties || [];
+
+  /**
+   * shouldPropBeHashedMap = {
+   * <blacklisted_property_name>: <hash_required_boolean>,
+   * }
+   */
+
+  const shouldPropBeHashedMap = blacklistPiiProperties.reduce((acc, currProp) => {
+    acc[currProp.blacklistPiiProperties] = currProp.blacklistPiiHash;
+    return acc;
+  }, {});
+  const whitelistPiiPropertiesNames = whitelistPiiProperties.map(
+    (propObject) => propObject.whitelistPiiProperties,
+  );
+
+  const { properties } = htElement.message;
+
+  const payload = Object.entries(properties).reduce((acc, [currPropName, currPropValue]) => {
+    const isPropertyPii =
+      defaultPiiProperties.includes(currPropName) ||
+      Object.prototype.hasOwnProperty.call(shouldPropBeHashedMap, currPropName);
+
+    const isProperyWhiteListed = whitelistPiiPropertiesNames.includes(currPropName);
+
+    const isDateProp = dateFields.includes(currPropName) && is.date(currPropValue);
+
+    if (isDateProp) {
+      [acc[currPropName]] = currPropValue.toISOString().split('T');
+    }
+
+    if (shouldPropBeHashedMap[currPropName] && typeof currPropValue === 'string') {
+      acc[currPropName] = hashedPii ? currPropValue.toString() : sha256(currPropValue).toString();
+    } else if ((!isPropertyPii || isProperyWhiteListed) && !isDateProp) {
+      acc[currPropName] = currPropValue;
+    } else {
+      logger.debug(
+        `[Facebook Pixel] PII Property '${currPropValue}' is neither hashed nor whitelisted and will be ignored`,
+      );
+    }
+
+    return acc;
+  }, {});
+  return payload;
+};
+
+const merge = (obj1, obj2) => {
+  const res = {};
+
+  // All properties of obj1
+  Object.keys(obj1).forEach((propObj1) => {
+    if (Object.prototype.hasOwnProperty.call(obj1, propObj1)) {
+      res[propObj1] = obj1[propObj1];
+    }
+  });
+
+  // Extra properties of obj2
+  Object.keys(obj2).forEach((propObj2) => {
+    if (
+      Object.prototype.hasOwnProperty.call(obj2, propObj2) &&
+      !Object.prototype.hasOwnProperty.call(res, propObj2)
+    ) {
+      res[propObj2] = obj2[propObj2];
+    }
+  });
+
+  return res;
+};
+
+/**
+ * Returns formatted revenue
+ * @param {*} revenue
+ * @returns
+ */
+const formatRevenue = (revenue) => {
+  const parsedRevenue = parseFloat(revenue);
+  const formattedRevenue = Number.isNaN(parsedRevenue) ? 0 : parseFloat(parsedRevenue.toFixed(2));
+
+  if (Number.isNaN(formattedRevenue)) {
+    logger.error('Revenue could not be converted to a number');
+  }
+
+  return formattedRevenue;
+};
+
+/**
+ * Get the Facebook Content Type
+ *
+ * Can be `product`, `destination`, `flight` or `hotel`.
+ *
+ * This can be overridden within the message
+ * `options.integrations.FACEBOOK_PIXEL.contentType`, or alternatively you can
+ * set the "Map Categories to Facebook Content Types" setting within
+ * RudderStack config and then set the corresponding commerce category in
+ * `track()` properties.
+ *
+ * https://www.facebook.com/business/help/606577526529702?id=1205376682832142
+ * @param {*} htElement
+ * @param {*} defaultValue
+ * @param {*} categoryToContent
+ * @returns
+ */
+const getContentType = (htElement, defaultValue, categoryToContent) => {
+  // Get the message-specific override if it exists in the options parameter of `track()`
+  const contentTypeMessageOverride = htElement.message.integrations?.FACEBOOK_PIXEL?.contentType;
+  if (contentTypeMessageOverride) return contentTypeMessageOverride;
+
+  // Otherwise check if there is a replacement set for all Facebook Pixel
+  // track calls of this category
+  const { category } = htElement.message.properties;
+  if (category) {
+    const categoryMapping = categoryToContent?.find((i) => i.from === category);
+    if (categoryMapping?.to) return categoryMapping.to;
+  }
+
+  // Otherwise return the default value
+  return defaultValue;
+};
+
+/**
+ * Returns contents, contentIds for products
+ * @param {*} products
+ * @param {*} quantity
+ * @param {*} price
+ * @returns
+ */
+const getProductsContentsAndContentIds = (products, quantity, price) => {
+  const contents = products
+    ? products
+        .filter((product) => product)
+        .map(({ product_id: prodId, sku, id, quantity: productQuantity, price: productPrice }) => {
+          const productId = prodId || sku || id;
+          return isDefined(productId)
+            ? {
+                id: productId,
+                quantity: productQuantity || quantity || 1,
+                item_price: productPrice || price,
+              }
+            : null;
+        })
+        .filter((content) => content !== null)
+    : [];
+
+  const contentIds = contents.map((content) => content.id);
+
+  return { contents, contentIds };
+};
+
+/**
+ * Returns contents, contentIds for single product
+ * @param {*} prodId
+ * @param {*} quantity
+ * @param {*} price
+ * @returns
+ */
+const getProductContentAndId = (prodId, quantity, price) => {
+  const contents = [];
+  const contentIds = [];
+
+  if (prodId) {
+    contentIds.push(prodId);
+    contents.push({
+      id: prodId,
+      quantity,
+      item_price: price,
+    });
+  }
+
+  return { contents, contentIds };
+};
+
+/**
+ * Returns product list viewed event params
+ * @param {*} properties
+ * @returns
+ */
+const getProductListViewedEventParams = (properties) => {
+  const { products, category, quantity, price } = properties;
+
+  const { contents, contentIds } = getProductsContentsAndContentIds(products, quantity, price);
+
+  let contentType;
+  if (contentIds.length > 0) {
+    contentType = 'product';
+  } else if (category) {
+    contentIds.push(category);
+    contents.push({
+      id: category,
+      quantity: 1,
+    });
+    contentType = 'product_group';
+  }
+
+  return { contentIds, contentType, contents };
+};
+
+/**
+ * Helper functions object
+ */
+const eventHelpers = {
+  getCategory: (category) => category || '',
+  getCurrency: (currency) => currency || 'USD',
+  getProperties: (message) => message?.properties || {},
+  getProdId: (productId, sku, id) => productId || sku || id,
+  getProdName: (productName, name) => productName || name || '',
+  getFormattedRevenue: (revValue, value) => revValue || formatRevenue(value),
+  getEventName: (event) => (event === 'Product Viewed' ? 'ViewContent' : 'AddToCart'),
+  getValue: (useValue, value, price) => (useValue ? value : formatRevenue(price)),
+  isCustomEventNotMapped: (standardTo, legacyTo, event) =>
+    !standardTo[event?.toLowerCase()] && !legacyTo[event?.toLowerCase()],
+  validateRevenue: (revValue) => {
+    if (!isDefined(revValue)) {
+      logger.error("'properties.revenue' could not be converted to a number");
+    }
+  },
+};
+
+export {
+  merge,
+  getEventId,
+  buildPayLoad,
+  eventHelpers,
+  formatRevenue,
+  getContentType,
+  getHashedStatus,
+  getContentCategory,
+  getProductContentAndId,
+  getProductListViewedEventParams,
+  getProductsContentsAndContentIds,
+};