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

package/src/send/functions.ts

@@ -1,185 +1,245 @@
-import { FBEvent, UserData, EventOptions, FBClient, FBStandardEventType, FBNonStandardEventType } from '../types'
+import { FBEvent, UserData, EventOptions, FBClient, FBStandardEventType, FBNonStandardEventType, FBClientParamBuilder, PIIType, PIIParamName } from '../types'
 import { Payload } from './generated-types'
 import { Settings } from '../generated-types'
 import { UniversalStorage, Analytics } from '@segment/analytics-next'
-import { US_STATE_CODES, COUNTRY_CODES, MAX_INIT_COUNT, INIT_COUNT_KEY, USER_DATA_KEY } from '../constants'
+import {US_STATE_CODES, COUNTRY_CODES, MAX_INIT_COUNT, INIT_COUNT_KEY, USER_DATA_KEY } from '../constants'
 import { storageFallback, setStorageInitCount } from '../functions'
 import { getNotVisibleForEvent } from './depends-on'
 
-export function send(client: FBClient, payload: Payload, settings: Settings, analytics: Analytics) {
-  const { pixelId } = settings
-  const { event_config: { custom_event_name, event_name } = {} } = payload
+export function send(client: FBClient, clientParamBuilder: FBClientParamBuilder | undefined, payload: Payload, settings: Settings, analytics: Analytics) {
+    const { pixelId } = settings
+    const { 
+        event_config: { 
+            custom_event_name, 
+            event_name 
+        } = {}
+    } = payload
 
-  const isCustom = event_name === 'CustomEvent' ? true : false
+    const isCustom = event_name === 'CustomEvent' ? true : false
 
-  const errorMessage = validate(payload)
+    const errorMessage = validate(payload)
 
-  if (errorMessage) {
-    console.warn(`${errorMessage}`)
-    return
-  }
-
-  const fbEvent = formatFBEvent(payload)
-
-  maybeSendUserData(client, payload, settings, analytics)
-
-  const options = formatOptions(payload)
-
-  if (isCustom) {
-    client('trackSingleCustom', pixelId, custom_event_name as string, { ...fbEvent }, options)
-  } else {
-    client('trackSingle', pixelId, event_name as FBStandardEventType, { ...fbEvent }, options)
-  }
+    if(errorMessage) {
+        console.warn(`${errorMessage}`)
+        return
+    }
+    
+    const fbEvent = formatFBEvent(payload)
+
+    maybeSendUserData(client, clientParamBuilder, payload, settings, analytics)
+
+    const options = formatOptions(payload)
+
+    if(isCustom){
+        client(
+            'trackSingleCustom', 
+            pixelId,
+            custom_event_name as string,
+            { ...fbEvent },
+            options
+        )
+    } 
+    else {
+        client(
+            'trackSingle', 
+            pixelId,
+            event_name as FBStandardEventType,
+            { ...fbEvent },
+            options
+        )
+    }
 }
 
 function validate(payload: Payload): string | undefined {
-  const {
-    event_config: { event_name },
-    content_ids,
-    contents
-  } = payload
-
-  if (['AddToCart', 'Purchase', 'ViewContent'].includes(event_name)) {
-    if (
-      (!content_ids || (Array.isArray(content_ids) && content_ids.length === 0)) &&
-      (!contents || (Array.isArray(contents) && contents.length === 0))
-    ) {
-      return `At least one of content_ids or contents is required for the ${event_name} event.`
-    }
-  }
-
-  return undefined
+    const { 
+        event_config: { event_name },
+        content_ids,
+        contents
+    } = payload
+
+    if(['AddToCart', 'Purchase', 'ViewContent'].includes(event_name)){
+        if ((!content_ids || (Array.isArray(content_ids) && content_ids.length === 0)) && (!contents || (Array.isArray(contents) && contents.length === 0))) {
+            return `At least one of content_ids or contents is required for the ${event_name} event.`
+        }
+    }
+
+    return undefined
 }
 
 function formatFBEvent(payload: Payload): FBEvent {
-  const {
-    content_category,
-    content_ids,
-    content_name,
-    content_type,
-    contents,
-    currency,
-    delivery_category,
-    num_items,
-    value,
-    predicted_ltv,
-    net_revenue,
-    custom_data,
-    event_config: { event_name, show_fields } = {}
-  } = payload
-
-  const fbEvent: FBEvent = {
-    ...(content_category ? { content_category } : {}),
-    ...(content_ids && Array.isArray(content_ids) && content_ids.length > 0 ? { content_ids } : {}),
-    ...(content_name ? { content_name } : {}),
-    ...(content_type ? { content_type } : {}),
-    ...(contents && Array.isArray(contents) && contents.length > 0 ? { contents } : {}),
-    ...(currency ? { currency } : {}),
-    ...(delivery_category ? { delivery_category } : {}),
-    ...(typeof num_items === 'number' ? { num_items } : {}),
-    ...(typeof value === 'number' ? { value } : {}),
-    ...(typeof predicted_ltv === 'number' ? { predicted_ltv } : {}),
-    ...(typeof net_revenue === 'number' ? { net_revenue } : {}),
-    ...(custom_data && Object.entries(custom_data).length > 0 ? { custom_data } : {})
-  }
-
-  if (show_fields === false) {
-    // If show_fields is false we delete values for fields which are hidden in the UI.
-    const fieldsToDelete = getNotVisibleForEvent(event_name as FBStandardEventType | FBNonStandardEventType)
-    fieldsToDelete.forEach((field) => {
-      if (field in fbEvent) {
-        delete fbEvent[field as keyof typeof fbEvent]
-      }
-    })
-  }
-
-  return Object.keys(fbEvent).length > 0 ? fbEvent : {}
+    const {
+        content_category,
+        content_ids,
+        content_name,
+        content_type,
+        contents,
+        currency,
+        delivery_category,
+        num_items,
+        value, 
+        predicted_ltv,
+        net_revenue, 
+        custom_data, 
+        event_config: { 
+            event_name, 
+            show_fields 
+        } = {}
+    } = payload
+
+    const fbEvent: FBEvent = {
+        ...(content_category ? { content_category } : {}),
+        ...(content_ids && Array.isArray(content_ids) && content_ids.length > 0 ? { content_ids } : {}),
+        ...(content_name ? { content_name } : {}),
+        ...(content_type ? { content_type } : {}),
+        ...(contents && Array.isArray(contents) && contents.length > 0 ? { contents } : {}),
+        ...(currency ? { currency } : {}),
+        ...(delivery_category ? { delivery_category } : {}),
+        ...(typeof num_items === 'number' ? { num_items } : {}),
+        ...(typeof value === 'number' ? { value } : {}),
+        ...(typeof predicted_ltv === 'number' ? { predicted_ltv } : {}),
+        ...(typeof net_revenue === 'number' ? { net_revenue } : {}),
+        ...(custom_data && Object.entries(custom_data).length > 0 ? { custom_data } : {})
+    }
+
+    if(show_fields === false){
+        // If show_fields is false we delete values for fields which are hidden in the UI. 
+        const fieldsToDelete = getNotVisibleForEvent(event_name as FBStandardEventType | FBNonStandardEventType)
+        fieldsToDelete.forEach(field => {
+            if (field in fbEvent) {
+                delete fbEvent[field as keyof typeof fbEvent]
+            }
+        })
+    }
+
+    return Object.keys(fbEvent).length > 0 ? fbEvent : {}
 }
 
 function formatOptions(payload: Payload): EventOptions | undefined {
-  const { eventID, eventSourceUrl } = payload
-  const options: EventOptions = {
-    ...(eventID ? { eventID } : {}),
-    ...(eventSourceUrl ? { eventSourceUrl } : {})
-  }
-  return Object.values(options).some(Boolean) ? options : undefined
+    const { eventID, eventSourceUrl } = payload    
+    const options: EventOptions = { 
+        ...(eventID ? { eventID } : {}),
+        ...(eventSourceUrl ? { eventSourceUrl } : {}),
+    }
+    return Object.values(options).some(Boolean) ? options : undefined
 }
 
-function maybeSendUserData(client: FBClient, payload: Payload, settings: Settings, analytics: Analytics) {
-  const { pixelId } = settings
-  const { userData } = payload
-  const userDataFormatted = formatUserData(userData)
+function maybeSendUserData(client: FBClient, clientParamBuilder: FBClientParamBuilder | undefined, payload: Payload, settings: Settings, analytics: Analytics) {
+    const { 
+        pixelId 
+    } = settings
+    const { 
+        userData 
+    } = payload
+    const userDataFormatted = formatUserData(userData, clientParamBuilder)
+
+    if(userDataFormatted) {
+        /* 
+            Facebook indicated that init should only trigger on a single page load up to max 2 times. 
+            When userData is created it gets added to storage and included in the next init call on page load. 
+            Facebook also advised to always send userData when it's available, even if it was collected via previous events. 
+        */
+        const storage = (analytics.storage as UniversalStorage<Record<string, string>>) ?? storageFallback
+        const initCountFromStorage: string | null = storage.get(INIT_COUNT_KEY)
+        const initCount: number | undefined = (initCountFromStorage && !isNaN(Number(initCountFromStorage))) 
+            ? parseInt(initCountFromStorage, 10) 
+            : undefined
+
+        if(typeof initCount === 'number' && initCount < MAX_INIT_COUNT) {
+            client('init', pixelId, userDataFormatted)
+            setStorageInitCount(analytics, initCount + 1)
+        }
+
+        storage.set(USER_DATA_KEY, JSON.stringify(userDataFormatted))
+    }
+} 
 
-  if (userDataFormatted) {
-    const storage = (analytics.storage as UniversalStorage<Record<string, string>>) ?? storageFallback
-    const initCountFromStorage: string | null = storage.get(INIT_COUNT_KEY)
-    const initCount: number | undefined =
-      initCountFromStorage && !isNaN(Number(initCountFromStorage)) ? parseInt(initCountFromStorage, 10) : undefined
+function formatUserData(userData: Payload['userData'], clientParamBuilder: FBClientParamBuilder | undefined): UserData | undefined {
+    if(!userData){
+        return undefined 
+    }
 
-    if (typeof initCount === 'number' && initCount < MAX_INIT_COUNT) {
-      client('init', pixelId, userDataFormatted)
-      setStorageInitCount(analytics, initCount + 1)
+    const {
+        external_id,
+        em, 
+        ph, 
+        fn, 
+        ln, 
+        ge, 
+        db, 
+        ct, 
+        st, 
+        zp, 
+        country,
+        fbp, 
+        fbc
+    } = userData
+    
+    let fbcValue = fbc ? fbc.trim() : undefined
+    let fbpValue = fbp ? fbp.trim() : undefined
+
+    if(clientParamBuilder){
+        clientParamBuilder.processAndCollectAllParams()
+        fbcValue = clientParamBuilder.getFbc() || fbcValue 
+        fbpValue = clientParamBuilder.getFbp() || fbpValue
+    }
+    
+    const ud: UserData = {
+        ...(formatPII(em, 'email', 'em', clientParamBuilder, (s) => s.toLowerCase().trim())),
+        ...(formatPII(ph, 'phone', 'ph', clientParamBuilder, (s) => s.replace(/\D/g, ''))),
+        ...(formatPII(fn, 'first_name', 'fn', clientParamBuilder, (s) => s.toLowerCase().trim())),
+        ...(formatPII(ln, 'last_name', 'ln', clientParamBuilder, (s) => s.toLowerCase().trim())),
+        ...(formatPII(ge, 'gender', 'ge', clientParamBuilder, (s) => (['m', 'f'].includes(s) ? s as 'm' | 'f' : undefined) ) as {ge: 'm'|'f'} || {}),
+        ...(formatPII(db, 'date_of_birth', 'db', clientParamBuilder, (s) => formatDate(s))),
+        ...(formatPII(ct, 'city', 'ct', clientParamBuilder, (s) => s.toLowerCase().replace(/\s+/g, ''))),
+        ...(formatPII(st, 'state', 'st', clientParamBuilder, (s) => fromMap(US_STATE_CODES, s))),
+        ...(formatPII(zp, 'zip_code', 'zp', clientParamBuilder, (s) => s.trim())),
+        ...(formatPII(country, 'country', 'country', clientParamBuilder, (s) => fromMap(COUNTRY_CODES, s))),
+        ...(formatPII(external_id, 'external_id', 'external_id', clientParamBuilder, (s) => s.trim())),
+        ...(fbcValue ? { fbc: fbcValue } : {}),
+        ...(fbpValue ? { fbp: fbpValue } : {})
     }
 
-    storage.set(USER_DATA_KEY, JSON.stringify(userDataFormatted))
-  }
+    if(Object.keys(ud).length === 0){
+        return undefined
+    }
+    return ud
 }
 
-function formatUserData(userData: Payload['userData']): UserData | undefined {
-  if (!userData) {
-    return undefined
-  }
-
-  const { external_id, em, ph, fn, ln, ge, db, ct, st, zp, country } = userData
-
-  const dbFormatted = formatDate(db)
-  const stFormatted = fromMap(US_STATE_CODES, st)
-  const countryFormatted = fromMap(COUNTRY_CODES, country)
-
-  const ud: UserData = {
-    ...(typeof em === 'string' ? { em: em.toLowerCase().trim() } : {}), // lowercase and trim whitespace
-    ...(typeof ph === 'string' ? { ph: ph.replace(/\D/g, '') } : {}), // remove non-numeric characters
-    ...(typeof fn === 'string' ? { fn: fn.toLowerCase().trim() } : {}), // lowercase and trim whitespace
-    ...(typeof ln === 'string' ? { ln: ln.toLowerCase().trim() } : {}), // lowercase and trim whitespace
-    ...(typeof ge === 'string' && ['m', 'f'].includes(ge) ? { ge: ge as 'm' | 'f' } : {}),
-    ...(typeof dbFormatted === 'string' ? { db: dbFormatted } : {}), // format date to YYYYMMDD
-    ...(typeof ct === 'string' ? { ct: ct.toLowerCase().replace(/\s+/g, '') } : {}), // lowercase and replace any whitespace
-    ...(typeof stFormatted === 'string' ? { st: stFormatted } : {}), // lowercase 2 character state code
-    ...(typeof zp === 'string' ? { zp: zp.trim() } : {}),
-    ...(typeof countryFormatted === 'string' ? { country: countryFormatted } : {}), // lowercase 2 character country code
-    ...(typeof external_id === 'string' ? { external_id: external_id.trim() } : {}) // trim whitespace
-  }
-
-  if (Object.keys(ud).length === 0) {
-    return undefined
-  }
-  return ud
+function formatPII<K extends PIIParamName, V extends string>(
+    value: string | undefined, 
+    piiType: PIIType, 
+    piiParamType: K, 
+    clientParamBuilder: FBClientParamBuilder | undefined, 
+    formatter: (s: string) => string | undefined
+): Partial<Record<K, V>> {    
+    if(!value) {
+        return {}
+    }
+    const val = clientParamBuilder?.getNormalizedAndHashedPII(value, piiType) ?? formatter(value)
+    return val ? ({ [piiParamType]: val as V } as Partial<Record<K, V>>) : {}
 }
 
 function formatDate(isoDate?: string): string | undefined {
-  if (!isoDate || typeof isoDate !== 'string') {
-    return undefined
-  }
-  const date = new Date(isoDate)
-  if (isNaN(date.getTime())) {
-    return undefined
-  }
-  const year = date.getUTCFullYear()
-  const month = (date.getUTCMonth() + 1).toString().padStart(2, '0')
-  const day = date.getUTCDate().toString().padStart(2, '0')
-  return `${year}${month}${day}`
+    if (!isoDate || typeof isoDate !== 'string') {
+        return undefined
+    }
+    const date = new Date(isoDate)
+    if (isNaN(date.getTime())) {
+        return undefined
+    }
+    const year = date.getUTCFullYear()
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, '0')
+    const day = date.getUTCDate().toString().padStart(2, '0')
+    return `${year}${month}${day}`
 }
 
 function fromMap(map: Map<string, string>, value?: string): string | undefined {
-  const cleaned = value
-    ?.toLowerCase()
-    .replace(/[^a-z]/g, '')
-    .trim()
-  if (!cleaned) {
-    return undefined
-  }
-  if (cleaned.length === 2 && Array.from(map.values()).includes(cleaned)) {
-    return cleaned
-  }
-  return map.get(cleaned) || undefined
-}
+    const cleaned = value?.toLowerCase().replace(/[^a-z]/g, '').trim()
+    if (!cleaned) {
+        return undefined
+    }
+    if(cleaned.length === 2 && Array.from(map.values()).includes(cleaned)) {
+        return cleaned
+    }
+    return map.get(cleaned) || undefined
+}

package/src/send/generated-types.ts

@@ -111,7 +111,7 @@ export interface Payload {
      */
     em?: string
     /**
-     * Phone number of the user
+     * Phone number of the user. Make sure to include the country code. For example, "15551234567" for a US number.
      */
     ph?: string
     /**
@@ -139,12 +139,20 @@ export interface Payload {
      */
     st?: string
     /**
-     * ZIP or postal code of the user. For example, "94025" for Menlo Park, CA, or "10001" for New York City.
+     * ZIP or postal code of the user. For example, U.S zip code: 94035, Australia zip code: 1987, France zip code: 75018, UK zip code: m11ae.
      */
     zp?: string
     /**
      * The country of the user. Facebook expects the 2-letter ISO 3166-1 alpha-2 country code. For example, "US" for the United States, or "GB" for the United Kingdom.
      */
     country?: string
+    /**
+     * Use this field to pass the Facebook browser cookie value (_fbp) associated with the user. If the "Format User Data with Parameter Builder" setting is enabled, Segment will automatically capture this value from the _fbp cookie.
+     */
+    fbp?: string
+    /**
+     * Use this field to pass The Facebook browser cookie value (_fbc) associated with the user. If the "Format User Data with Parameter Builder" setting is enabled, Segment will automatically capture this value from the _fbc cookie.
+     */
+    fbc?: string
   }
 }

package/src/send/index.ts

@@ -2,18 +2,18 @@ import type { BrowserActionDefinition } from '@segment/browser-destination-runti
 import type { Settings } from '../generated-types'
 import type { Payload } from './generated-types'
 import { AllFields } from './fields'
-import type { FBClient } from '../types'
+import type { FBClient, FBClientParamBuilder } from '../types'
 import { send } from './functions'
 
-const action: BrowserActionDefinition<Settings, FBClient, Payload> = {
+const action: BrowserActionDefinition<Settings, { fbq: FBClient, clientParamBuilder: FBClientParamBuilder | undefined }, Payload> = {
   title: 'Send Event',
   description: 'Send a Standard or Custom Event to Facebook Conversions API.',
   defaultSubscription: 'type = "track"',
   platform: 'web',
   fields: AllFields,
   perform: (client, { payload, settings, analytics }) => {
-    return send(client, payload, settings, analytics)
+    return send(client.fbq, client.clientParamBuilder, payload, settings, analytics)  
   }
 }
 
-export default action
+export default action

package/src/types.ts

@@ -1,6 +1,6 @@
 export interface WindowWithOptionalFbq extends Omit<Window, 'fbq' | '_fbq'> {
-  fbq?: FBClient
-  _fbq?: FBClient
+  fbq?: FBClient;
+  _fbq?: FBClient;
 }
 
 export type FBStandardEventType =
@@ -29,8 +29,8 @@ export type InitOptions = {
   agent?: string
 }
 
-export type EventOptions = {
-  eventID?: string
+export type EventOptions = { 
+  eventID?: string 
   eventSourceUrl?: string
 }
 
@@ -47,6 +47,8 @@ export type UserData = {
   st?: string // State (FB hashes with SHA-256)
   zp?: string // ZIP/Postal code (FB hashes with SHA-256)
   country?: string // Country code (FB hashes with SHA-256)
+  fbp?: string // Facebook browser pixel ID
+  fbc?: string // Facebook click ID
 }
 
 export type FBEvent = {
@@ -63,7 +65,7 @@ export type FBEvent = {
   currency?: string
   delivery_category?: string
   num_items?: number
-  value?: number
+  value?: number 
   custom_data?: {
     [k: string]: unknown
   }
@@ -78,26 +80,36 @@ export type FBClient = {
   callMethod?: (...args: unknown[]) => void
   (command: 'set', key: string, value: boolean, pixelId: string): void
   (command: 'dataProcessingOptions', options: string[], country?: number, state?: number): void
-  (command: 'init', pixelId: string, userData?: UserData, options?: InitOptions): void
+  (command: 'init', pixelId: string, userData?: UserData, options?: InitOptions ): void
   (command: 'trackSingle', pixelId: string, event: FBStandardEventType, params?: FBEvent, options?: EventOptions): void
   (command: 'trackSingleCustom', pixelId: string, event: string, params?: FBEvent, options?: EventOptions): void
 }
 
+export type FBClientParamBuilder = {
+  getNormalizedAndHashedPII: (value: string, piiType: PIIType) => string | undefined
+  processAndCollectAllParams: () => void 
+  getFbc: () => string | undefined
+  getFbp: () => string | undefined
+}
+
+export type PIIType = 'email' | 'phone' | 'first_name' | 'last_name' | 'gender' | 'date_of_birth' | 'city' | 'state' | 'zip_code' | 'country' | 'external_id'
+export type PIIParamName = 'em' | 'ph' | 'fn' | 'ln' | 'ge' | 'db' | 'ct' | 'st' | 'zp' | 'country' | 'external_id'
+
 export const LDU = {
-  Disabled: { key: 'Disabled', state: undefined, country: undefined },
-  GeolocationLogic: { key: 'GeolocationLogic', state: 0, country: 0 },
-  California: { key: 'California', state: 1000, country: 1 },
-  Colorado: { key: 'Colorado', state: 1001, country: 1 },
-  Connecticut: { key: 'Connecticut', state: 1002, country: 1 },
-  Florida: { key: 'Florida', state: 1003, country: 1 },
-  Oregon: { key: 'Oregon', state: 1004, country: 1 },
-  Texas: { key: 'Texas', state: 1005, country: 1 },
-  Montana: { key: 'Montana', state: 1006, country: 1 },
-  Delaware: { key: 'Delaware', state: 1007, country: 1 },
-  Nebraska: { key: 'Nebraska', state: 1008, country: 1 },
-  NewHampshire: { key: 'NewHampshire', state: 1009, country: 1 },
-  NewJersey: { key: 'NewJersey', state: 1010, country: 1 },
-  Minnesota: { key: 'Minnesota', state: 1011, country: 1 }
+  Disabled: {key: 'Disabled', state: undefined, country: undefined},
+  GeolocationLogic: {key: 'GeolocationLogic', state: 0, country: 0},
+  California: {key: 'California', state: 1000, country: 1},
+  Colorado: {key: 'Colorado', state: 1001, country: 1},
+  Connecticut: {key: 'Connecticut', state: 1002, country: 1},
+  Florida: {key: 'Florida', state: 1003, country: 1},
+  Oregon: {key: 'Oregon', state: 1004, country: 1},
+  Texas: {key: 'Texas', state: 1005, country: 1},
+  Montana: {key: 'Montana', state: 1006, country: 1},
+  Delaware: {key: 'Delaware', state: 1007, country: 1},
+  Nebraska: {key: 'Nebraska', state: 1008, country: 1},
+  NewHampshire: {key: 'NewHampshire', state: 1009, country: 1},
+  NewJersey: {key: 'NewJersey', state: 1010, country: 1},
+  Minnesota: {key: 'Minnesota', state: 1011, country: 1}
 } as const
 
-export type LDU = typeof LDU[keyof typeof LDU]
+export type LDU = typeof LDU[keyof typeof LDU]