@segment/analytics-browser-actions-facebook-conversions-api-web 1.9.1-staging-99a2d468f.1 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segment/analytics-browser-actions-facebook-conversions-api-web",
-  "version": "1.9.1-staging-99a2d468f.1",
+  "version": "1.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,10 +16,10 @@
   },
   "typings": "./dist/esm",
   "dependencies": {
-    "@segment/browser-destination-runtime": "1.92.1-staging-d7d79cb56.0"
+    "@segment/browser-destination-runtime": "^1.93.0"
   },
   "peerDependencies": {
     "@segment/analytics-next": ">=1.55.0"
   },
-  "gitHead": "b0d4107e905b2c03e44256279967c576e6efca5b"
+  "gitHead": "bda78db80a4ab33f11968bea94336855d37d3805"
 }

package/src/__tests__/functions.test.ts

@@ -0,0 +1,159 @@
+import { initScript, setStorageInitCount, storageFallback } from '../functions'
+import { LDU } from '../types'
+
+describe('Facebook Conversions API Web - Main Functions', () => {
+  let mockAnalytics
+
+  beforeEach(() => {
+    // Reset window.fbq
+    delete window.fbq
+    delete window._fbq
+
+    mockAnalytics = {
+      storage: {
+        get: jest.fn(),
+        set: jest.fn()
+      }
+    }
+
+    // Mock localStorage
+    Storage.prototype.getItem = jest.fn()
+    Storage.prototype.setItem = jest.fn()
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  describe('initScript', () => {
+    it('should initialize Facebook Pixel with basic settings', () => {
+      const settings = {
+        pixelId: 'test-pixel-123',
+        ldu: LDU.Disabled.key
+      }
+
+      initScript(settings, mockAnalytics)
+
+      expect(window.fbq).toBeDefined()
+      expect(typeof window.fbq).toBe('function')
+    })
+
+    it('should set LDU to disabled when configured', () => {
+      const settings = {
+        pixelId: 'test-pixel-123',
+        ldu: LDU.Disabled.key
+      }
+
+      initScript(settings, mockAnalytics)
+
+      expect(window.fbq).toBeDefined()
+      expect(mockAnalytics.storage.set).toHaveBeenCalledWith('fb_pixel_init_count', '1')
+    })
+
+    it('should set LDU with California state when configured', () => {
+      const settings = {
+        pixelId: 'test-pixel-123',
+        ldu: LDU.California.key
+      }
+
+      initScript(settings, mockAnalytics)
+
+      expect(window.fbq).toBeDefined()
+      expect(mockAnalytics.storage.set).toHaveBeenCalledWith('fb_pixel_init_count', '1')
+    })
+
+    it('should disable push state when configured', () => {
+      const settings = {
+        pixelId: 'test-pixel-123',
+        ldu: LDU.Disabled.key,
+        disablePushState: true
+      }
+
+      initScript(settings, mockAnalytics)
+
+      expect(window.fbq.disablePushState).toBe(true)
+    })
+
+    it('should set init count in storage', () => {
+      const settings = {
+        pixelId: 'test-pixel-123',
+        ldu: LDU.Disabled.key
+      }
+
+      initScript(settings, mockAnalytics)
+
+      expect(mockAnalytics.storage.set).toHaveBeenCalledWith('fb_pixel_init_count', '1')
+    })
+
+    it('should initialize pixel with stored user data', () => {
+      const userData = {
+        em: 'test@example.com',
+        fn: 'John',
+        ln: 'Doe'
+      }
+
+      mockAnalytics.storage.get.mockReturnValue(JSON.stringify(userData))
+
+      const settings = {
+        pixelId: 'test-pixel-123',
+        ldu: LDU.Disabled.key
+      }
+
+      initScript(settings, mockAnalytics)
+
+      expect(window.fbq).toBeDefined()
+      expect(mockAnalytics.storage.get).toHaveBeenCalledWith('fb_user_data')
+    })
+  })
+
+  describe('setStorageInitCount', () => {
+    it('should set init count in storage', () => {
+      setStorageInitCount(mockAnalytics, 1)
+
+      expect(mockAnalytics.storage.set).toHaveBeenCalledWith('fb_pixel_init_count', '1')
+    })
+
+    it('should set init count to 2', () => {
+      setStorageInitCount(mockAnalytics, 2)
+
+      expect(mockAnalytics.storage.set).toHaveBeenCalledWith('fb_pixel_init_count', '2')
+    })
+  })
+
+  describe('storageFallback', () => {
+    it('should get value from localStorage', () => {
+      Storage.prototype.getItem.mockReturnValue('test-value')
+
+      const value = storageFallback.get('test-key')
+
+      expect(Storage.prototype.getItem).toHaveBeenCalledWith('test-key')
+      expect(value).toBe('test-value')
+    })
+
+    it('should return null if localStorage throws error', () => {
+      Storage.prototype.getItem.mockImplementation(() => {
+        throw new Error('Storage not available')
+      })
+
+      const value = storageFallback.get('test-key')
+
+      expect(value).toBeNull()
+    })
+
+    it('should set value in localStorage', () => {
+      storageFallback.set('test-key', 'test-value')
+
+      expect(Storage.prototype.setItem).toHaveBeenCalledWith('test-key', 'test-value')
+    })
+
+    it('should silently fail if localStorage.setItem throws error', () => {
+      Storage.prototype.setItem.mockImplementation(() => {
+        throw new Error('Storage not available')
+      })
+
+      expect(() => {
+        storageFallback.set('test-key', 'test-value')
+      }).not.toThrow()
+    })
+  })
+})

package/src/constants.ts

@@ -486,4 +486,4 @@ export const COUNTRY_CODES = new Map<string, string>([
   ['yemen', 'ye'],
   ['zambia', 'zm'],
   ['zimbabwe', 'zw']
-])
+])

package/src/functions.ts

@@ -1,52 +1,64 @@
-import { WindowWithOptionalFbq, InitOptions, LDU, UserData, FBClient } from './types'
+import { WindowWithOptionalFbq, InitOptions, LDU, UserData, FBClient} from './types'
 import type { Settings } from './generated-types'
-import { USER_DATA_KEY, INIT_COUNT_KEY } from './constants'
+import { USER_DATA_KEY, INIT_COUNT_KEY} from './constants'
 import { UniversalStorage, Analytics } from '@segment/analytics-next'
 
 export function initScript(settings: Settings, analytics: Analytics) {
-  const { pixelId, disablePushState, disableAutoConfig, disableFirstPartyCookies, agent, ldu } =
-    settings as Settings & { ldu: keyof typeof LDU }
-
-  ;(function (
-    f: WindowWithOptionalFbq,
-    b: Document,
-    e: 'script',
-    v: string,
-    n: FBClient | undefined = undefined,
-    t: HTMLScriptElement | undefined = undefined,
+  const { 
+    pixelId, 
+    disablePushState, 
+    disableAutoConfig, 
+    disableFirstPartyCookies,
+    agent,
+    ldu
+  } = settings as Settings & { ldu: keyof typeof LDU }
+
+  (function(
+    f: WindowWithOptionalFbq, 
+    b: Document, 
+    e: 'script', 
+    v: string, 
+    n: FBClient | undefined = undefined, 
+    t: HTMLScriptElement | undefined = undefined, 
     s: Element | null = null
-  ) {
-    if (f.fbq) return
-    n = f.fbq = function () {
+  ){
+    if (f.fbq) return;
+    n = f.fbq = function() {
       /* eslint-disable */
       // @ts-expect-error - n is defined by the time this executes
-      n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments)
+      n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);
       /* eslint-enable */
-    }
-    if (!f._fbq) f._fbq = n
-    n.push = n
-    n.loaded = true
-    n.version = '2.0'
-    n.queue = []
-    t = b.createElement(e)
-    t.async = true
-    t.src = v
-    s = b.getElementsByTagName(e)[0]
+    };
+    if (!f._fbq) f._fbq = n;
+    n.push = n;
+    n.loaded = true;
+    n.version = '2.0';
+    n.queue = [];
+    t = b.createElement(e);
+    t.async = true;
+    t.src = v;
+    s = b.getElementsByTagName(e)[0];
     if (s && s.parentNode) {
-      s.parentNode.insertBefore(t, s)
+      s.parentNode.insertBefore(t, s);
     }
-  })(window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js')
-
-  if (ldu === LDU.Disabled.key) {
+  })(
+    window, 
+    document, 
+    'script', 
+    'https://connect.facebook.net/en_US/fbevents.js'
+  );
+
+  if(ldu === LDU.Disabled.key) {
     window.fbq('dataProcessingOptions', [])
-  } else {
+  }
+  else {
     const lduObj = getLDU(ldu)
     window.fbq('dataProcessingOptions', ['LDU'], lduObj.country, lduObj.state)
   }
 
-  if (disablePushState) {
+  if(disablePushState) {
     window.fbq.disablePushState = true
-  }
+  } 
 
   if (disableAutoConfig) {
     window.fbq('set', 'autoConfig', false, pixelId)
@@ -57,13 +69,13 @@ export function initScript(settings: Settings, analytics: Analytics) {
   }
 
   const userData = getStoredUserData(analytics)
-  const options: InitOptions | undefined = agent ? { agent } : undefined
+  const options: InitOptions | undefined = ( agent ? { agent } : undefined)
   const initArgs: [string, UserData?, InitOptions?] = [pixelId]
 
   if (userData && Object.keys(userData).length > 0) {
-    initArgs.push(userData)
+    initArgs.push(userData);
     if (options) {
-      initArgs.push(options)
+      initArgs.push(options);
     }
   } else if (options) {
     initArgs.push(undefined, options)
@@ -72,9 +84,8 @@ export function initScript(settings: Settings, analytics: Analytics) {
   window.fbq('init', ...initArgs)
 
   setStorageInitCount(analytics, 1)
-  deleteStorageUserData(analytics)
 
-  if (!disablePushState) {
+  if(!disablePushState) {
     window.fbq('trackSingle', pixelId, 'PageView')
   }
 }
@@ -101,34 +112,24 @@ export function setStorageInitCount(analytics: Analytics, count: number) {
   storage.set(INIT_COUNT_KEY, `${count}`)
 }
 
-export function deleteStorageUserData(analytics: Analytics) {
-  const storage = (analytics.storage as UniversalStorage<Record<string, string>>) ?? storageFallback
-  storage.set(USER_DATA_KEY, '')
-}
-
-function getStoredUserData(analytics: Analytics): UserData | undefined {
-  const storage = (analytics.storage as UniversalStorage<Record<string, string>>) ?? storageFallback
-  const userDataFromStorage: string | null = storage.get(USER_DATA_KEY)
-  if (userDataFromStorage) {
-    try {
-      const parsed = JSON.parse(userDataFromStorage)
-      if (
-        !parsed ||
-        typeof parsed !== 'object' ||
-        Array.isArray(parsed) ||
-        Object.keys(parsed as object).length === 0
-      ) {
-        return undefined
-      }
-      return parsed as UserData
-    } catch {
-      return undefined
+function getStoredUserData(analytics: Analytics): UserData | undefined { 
+    const storage = (analytics.storage as UniversalStorage<Record<string, string>>) ?? storageFallback
+    const userDataFromStorage: string | null = storage.get(USER_DATA_KEY)
+    if(userDataFromStorage) {
+        try {
+            const parsed = JSON.parse(userDataFromStorage)
+            if(!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || Object.keys(parsed as object).length === 0) {
+                return undefined
+            }
+            return parsed as UserData
+        } catch {
+            return undefined
+        }
     }
-  }
-  return undefined
+    return undefined
 }
 
 function getLDU(ldu: keyof typeof LDU) {
-  const lduObj = LDU[ldu]
-  return { country: lduObj.country, state: lduObj.state }
-}
+    const lduObj = LDU[ldu]
+    return { country: lduObj.country, state: lduObj.state }
+}

package/src/generated-types.ts

@@ -25,4 +25,8 @@ export interface Settings {
    * Specify if and how Limited Data Use should apply.
    */
   ldu: string
+  /**
+   * If enabled, uses Facebook’s Parameter Builder library to help ensure that User Data values are properly formatted before being sent to Facebook.
+   */
+  formatUserDataWithParamBuilder?: boolean
 }

package/src/index.ts

@@ -3,17 +3,18 @@ import type { BrowserDestinationDefinition } from '@segment/browser-destination-
 import { browserDestination } from '@segment/browser-destination-runtime/shim'
 import send from './send'
 import { initScript } from './functions'
-import { FBClient, LDU } from './types'
+import { FBClient, FBClientParamBuilder, LDU } from './types'
 import { defaultValues } from '@segment/actions-core'
 
 declare global {
   interface Window {
-    fbq: FBClient
+    fbq: FBClient,
     _fbq: FBClient
+    clientParamBuilder: FBClientParamBuilder | undefined
   }
 }
 
-export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
+export const destination: BrowserDestinationDefinition<Settings, { fbq: FBClient, clientParamBuilder: FBClientParamBuilder | undefined }> = {
   name: 'Facebook Conversions Api Web',
   slug: 'actions-facebook-conversions-api-web',
   mode: 'device',
@@ -23,25 +24,22 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       description: 'The Pixel ID associated with your Facebook Pixel.',
       label: 'Pixel ID',
       type: 'string',
-      required: true
+      required: true  
     },
     disablePushState: {
-      description:
-        'If set to true, prevents Facebook Pixel from sending PageView events on history state changes. Set to true if you want to trigger PageView events manually via the pageView Action.',
+      description: "If set to true, prevents Facebook Pixel from sending PageView events on history state changes. Set to true if you want to trigger PageView events manually via the pageView Action.",
       label: 'Disable Push State',
       type: 'boolean',
       default: false
     },
     disableAutoConfig: {
-      description:
-        'Control whether Facebook’s Meta Pixel automatically collects additional page and button data to optimize ads and measurement. When this toggle is on, Auto Config is disabled and only basic pixel tracking will occur. Turning it off enables Auto Config, allowing the Pixel to automatically send page metadata and button interactions to improve ad delivery and reporting.',
+      description: "Control whether Facebook’s Meta Pixel automatically collects additional page and button data to optimize ads and measurement. When this toggle is on, Auto Config is disabled and only basic pixel tracking will occur. Turning it off enables Auto Config, allowing the Pixel to automatically send page metadata and button interactions to improve ad delivery and reporting.",
       label: 'Disable Auto Config',
       type: 'boolean',
       default: true
     },
     disableFirstPartyCookies: {
-      description:
-        'Control whether Facebook’s Meta Pixel uses first-party cookies. When this toggle is on, first-party cookies are disabled, enhancing user privacy. Turning it off enables the use of first-party cookies for more accurate tracking.',
+      description: "Control whether Facebook’s Meta Pixel uses first-party cookies. When this toggle is on, first-party cookies are disabled, enhancing user privacy. Turning it off enables the use of first-party cookies for more accurate tracking.",
       label: 'Disable First Party Cookies',
       type: 'boolean',
       default: false
@@ -58,8 +56,8 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       type: 'string',
       required: true,
       choices: [
-        { label: 'LDU disabled', value: LDU.Disabled.key },
-        { label: 'LDU enabled - Use Meta Geolocation Logic', value: LDU.GeolocationLogic.key },
+        { label: 'LDU disabled', value: LDU.Disabled.key},
+        { label: "LDU enabled - Use Meta Geolocation Logic", value: LDU.GeolocationLogic.key },
         { label: 'LDU enabled - California only', value: LDU.California.key },
         { label: 'LDU enabled - Colorado only', value: LDU.Colorado.key },
         { label: 'LDU enabled - Connecticut only', value: LDU.Connecticut.key },
@@ -74,14 +72,25 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
         { label: 'LDU enabled - Minnesota only', value: LDU.Minnesota.key }
       ],
       default: LDU.Disabled.key
+    }, 
+    formatUserDataWithParamBuilder: {
+      description: 'If enabled, uses Facebook’s Parameter Builder library to help ensure that User Data values are properly formatted before being sent to Facebook.',
+      label: 'Format User Data with Parameter Builder',
+      type: 'boolean',
+      default: true
     }
   },
   initialize: async ({ settings, analytics }, deps) => {
+    const { formatUserDataWithParamBuilder } = settings
     initScript(settings, analytics)
     await deps.resolveWhen(() => typeof window.fbq === 'function', 100)
-    return window.fbq
+    if(formatUserDataWithParamBuilder){
+      const script = `https://capi-automation.s3.us-east-2.amazonaws.com/public/client_js/capiParamBuilder/clientParamBuilder.bundle.js`
+      await deps.loadScript(script)
+      await deps.resolveWhen(() => typeof window.clientParamBuilder === 'object', 100)
+    }
+    return { fbq: window.fbq, clientParamBuilder: window.clientParamBuilder || undefined }
   },
-
   actions: {
     send
   },
@@ -90,7 +99,8 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       name: 'AddPaymentInfo',
       subscribe: 'event = "Payment Info Entered"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'AddPaymentInfo',
@@ -103,7 +113,8 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       name: 'AddToCart',
       subscribe: 'event = "Product Added"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'AddToCart',
@@ -118,12 +129,13 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
         value: { '@path': '$.properties.price' }
       },
       type: 'automatic'
-    },
+    },    
     {
       name: 'AddToWishlist',
       subscribe: 'event = "Product Added To Wishlist"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'AddToWishlist',
@@ -143,7 +155,8 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       name: 'CompleteRegistration',
       subscribe: 'event = "Signed Up"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'CompleteRegistration',
@@ -151,12 +164,13 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
         }
       },
       type: 'automatic'
-    },
+    }, 
     {
       name: 'InitiateCheckout',
       subscribe: 'event = "Checkout Started"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'InitiateCheckout',
@@ -184,13 +198,14 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       name: 'Purchase',
       subscribe: 'event = "Order Completed"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'Purchase',
           show_fields: false
         },
-        value: { '@path': '$.properties.revenue' },
+        value: { '@path': '$.properties.revenue' }, 
         custom_data: {
           order_id: { '@path': '$.properties.order_id' }
         }
@@ -201,7 +216,8 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       name: 'Search',
       subscribe: 'event = "Products Searched"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'Search',
@@ -220,7 +236,8 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
       name: 'ViewContent',
       subscribe: 'event = "Product Viewed"',
       partnerAction: 'send',
-      mapping: {
+      mapping: 
+      { 
         ...defaultValues(send.fields),
         event_config: {
           event_name: 'ViewContent',
@@ -230,7 +247,7 @@ export const destination: BrowserDestinationDefinition<Settings, FBClient> = {
           id: { '@path': '$.properties.product_id' },
           quantity: { '@path': '$.properties.quantity' },
           item_price: { '@path': '$.properties.price' }
-        },
+        }, 
         content_ids: { '@path': '$.properties.product_id' },
         value: { '@path': '$.properties.price' }
       },

package/src/send/__tests__/depends-on.test.ts

@@ -0,0 +1,28 @@
+import { getDependenciesFor } from '../depends-on'
+
+describe('depends-on getDependenciesFor', () => {
+  test('returns correct depends_on rules', () => {
+    const result = getDependenciesFor('delivery_category')
+    expect(true).toBe(true)
+    expect(result.match).toBe('any')
+    expect(result.conditions).toEqual(
+      [
+        {
+          fieldKey: 'event_config.show_fields',
+          operator: 'is',
+          value: 'true'
+        }, 
+        {
+          fieldKey: 'event_config.event_name',
+          operator: 'is',
+          value: 'Purchase'
+        }, 
+        {
+          fieldKey: 'event_config.event_name',
+          operator: 'is',
+          value: 'InitiateCheckout'
+        }
+      ]
+    )
+  })    
+})