@segment/analytics-browser-actions-facebook-conversions-api-web 1.0.1-staging-0104ee0bb.0

package/src/send/fields.ts

@@ -0,0 +1,400 @@
+import type { InputField } from '@segment/actions-core'
+import { ACTION_SOURCES } from '../types'
+import { getDependenciesFor } from './depends-on'
+import { CURRENCY_ISO_CODES } from './constants'
+
+export const event_config: InputField = {
+    label: 'Event Configuration',
+    description: 'Specify the type of Facebook Conversions API event to send.',
+    type: 'object',
+    required: true,
+    additionalProperties: false,
+    properties: {
+        event_name: {
+            label: 'Event Name',
+            description: "Facebook Conversions API Event Name to send. Select 'Custom Event' to send a non standard event.",
+            type: 'string',
+            required: true,
+            choices: [
+                { label: 'Custom Event', value: 'CustomEvent' },
+                { label: 'Add Payment Info', value: 'AddPaymentInfo' },
+                { label: 'Add To Cart', value: 'AddToCart' },
+                { label: 'Add To Wishlist', value: 'AddToWishlist' },
+                { label: 'Complete Registration', value: 'CompleteRegistration' },
+                { label: 'Contact', value: 'Contact' },
+                { label: 'Customize Product', value: 'CustomizeProduct' },
+                { label: 'Donate', value: 'Donate' },
+                { label: 'Find Location', value: 'FindLocation' },
+                { label: 'Initiate Checkout', value: 'InitiateCheckout' },
+                { label: 'Lead', value: 'Lead' },
+                { label: 'Purchase', value: 'Purchase' },
+                { label: 'Schedule', value: 'Schedule' },
+                { label: 'Search', value: 'Search' },
+                { label: 'Start Trial', value: 'StartTrial' },
+                { label: 'Submit Application', value: 'SubmitApplication' },
+                { label: 'Subscribe', value: 'Subscribe' },
+                { label: 'View Content', value: 'ViewContent' }
+            ]
+        },
+        custom_event_name:{
+            label: 'Custom Event Name',
+            description: 'Custom event name to send to Facebook',
+            type: 'string',
+            depends_on: getDependenciesFor('custom_event_name')
+        },
+        show_fields: {
+            label: 'Show all fields',
+            description: 'Show all fields, even those which are not relevant to the selected Event Name.',
+            type: 'boolean',
+            default: false
+        }
+    },
+    default: {
+        show_fields: false,
+        custom_event_name: {'@path': '$.event'}
+    }
+}
+
+export const content_category: InputField = {
+    label: 'Content Category',
+    description: 'The category of the content associated with the event.',
+    type: 'string',
+    default: { '@path': '$.properties.category' },
+    depends_on: getDependenciesFor('content_category')
+}
+
+export const content_ids: InputField = {
+    label: 'Content IDs',
+    description: "Product IDs associated with the event, such as SKUs (e.g. ['ABC123', 'XYZ789']). Accepts a single string value or array of strings.",
+    type: 'string',
+    multiple: true,
+    allowNull: false,
+    minimum: 1,
+    depends_on: getDependenciesFor('content_ids'),
+    required: {
+        match: 'all',
+        conditions: [
+        {
+            fieldKey: 'event_config.event_name',
+            operator: 'is',
+            value: ['AddToCart', 'Purchase', 'ViewContent']
+        },
+        {
+            fieldKey: 'contents', 
+            operator: 'is_not',
+            value: undefined
+        },
+        {
+            fieldKey: 'contents', 
+            operator: 'is_not',
+            value: ''
+        }
+        ]
+    }
+}
+
+export const content_name: InputField = {
+    label: 'Content Name',
+    description: 'The name of the page or product associated with the event.',
+    type: 'string',
+    default: { '@path': '$.properties.name' },
+    depends_on: getDependenciesFor('content_name')
+}
+
+export const content_type: InputField = {
+    label: 'Content Type',
+    description:
+        'If the IDs being passed in content_ids or contents parameter are IDs of products, then the value should be product. If product group IDs are being passed, then the value should be product_group. If no content_type is provided, Meta will match the event to every item that has the same ID, independent of its type.',
+    type: 'string',
+    choices: [
+        { value: 'product', label: 'Product' },
+        { value: 'product_group', label: 'Product Group' }
+    ],
+    depends_on: getDependenciesFor('content_type')
+}
+
+export const contents: InputField = {
+    label: 'Contents',
+    description: 'A list of JSON objects that contain the product IDs associated with the event plus information about the products. ID and quantity are required fields.',
+    type: 'object',
+    multiple: true,
+    allowNull: false,
+    minimum: 1,
+    additionalProperties: true,
+    properties: {
+        id: {
+            label: 'ID',
+            description: 'The product ID of the purchased item.',
+            type: 'string',
+            required: true
+        },
+        quantity: {
+            label: 'Quantity',
+            description: 'The number of items purchased.',
+            type: 'integer',
+            required: true
+        },
+        item_price: {
+            label: 'Item Price',
+            description: 'The price of the item.',
+            type: 'number'
+        }
+    },
+    default: {
+        '@arrayPath': [
+          '$.properties.products',
+          {
+            id: { '@path': '$.id' },
+            quantity: { '@path': '$.quantity' },
+            item_price: { '@path': '$.price' }
+          }
+        ]
+    },
+    depends_on: getDependenciesFor('contents'),
+    required: {
+        match: 'all',
+        conditions: [
+        {
+            fieldKey: 'event_config.event_name',
+            operator: 'is',
+            value: ['AddToCart', 'Purchase', 'ViewContent']
+        },
+        {
+            fieldKey: 'content_ids', 
+            operator: 'is_not',
+            value: undefined
+        },
+        {
+            fieldKey: 'content_ids', 
+            operator: 'is_not',
+            value: ''
+        }
+        ]
+    }
+}    
+
+export const currency: InputField = {
+    label: 'Currency',
+    description: 'The currency for the value specified. Currency must be a valid ISO 4217 three-digit currency code.',
+    type: 'string',
+    default: { '@path': '$.properties.currency' },
+    depends_on: getDependenciesFor('currency'),
+    choices:(() => {
+        return [...CURRENCY_ISO_CODES].map(code => ({
+            value: code,
+            label: code
+        }))
+    })(),
+    required: {
+        match: 'all',
+        conditions: [
+            {
+                fieldKey: 'event_config.event_name',
+                operator: 'is',
+                value: 'Purchase'
+            }
+        ]
+    }
+}
+
+export const delivery_category: InputField = {
+    label: 'Delivery Category',
+    description: 'Category of the delivery',
+    type: 'string',
+    choices: [
+        { value: 'in_store', label: 'In Store' },
+        { value: 'curbside', label: 'Curbside' },
+        { value: 'home_delivery', label: 'Home Delivery' }
+    ],
+    default: 'home_delivery',
+    depends_on: getDependenciesFor('delivery_category')
+}
+
+export const num_items: InputField = {
+    label: 'Number of Items',
+    description: 'The number of items when checkout was initiated.',
+    type: 'integer',
+    default: { '@path': '$.properties.quantity' },
+    depends_on: getDependenciesFor('num_items')
+}
+
+export const predicted_ltv: InputField = {
+    label: 'Predicted LTV',
+    description: 'Predicted lifetime value of a subscriber as defined by the advertiser and expressed as an exact value.',
+    type: 'number',
+    depends_on: getDependenciesFor('predicted_ltv')
+}
+
+export const search_string: InputField = {
+    label: 'Search String',
+    description: 'The string entered by the user for the search.',
+    type: 'string',
+    default: { '@path': '$.properties.query' },
+    depends_on: getDependenciesFor('search_string')
+}
+
+export const status: InputField = {
+    label: 'Registration Status',
+    description: 'The status of the registration. true for completed registrations, false otherwise.',
+    type: 'boolean',
+    depends_on: getDependenciesFor('status')
+}
+
+export const value: InputField = {
+    label: 'Value',
+    description: 'A numeric value associated with this event. This could be a monetary value or a value in some other metric.',
+    type: 'number',
+    default: { '@path': '$.properties.currency' },
+    depends_on: getDependenciesFor('value'),
+    required: {
+        match: 'all',
+        conditions: [
+            {
+                fieldKey: 'event_config.event_name',
+                operator: 'is',
+                value: 'Purchase'
+            }
+        ]
+    }
+}
+
+export const custom_data: InputField = {
+    label: 'Custom Data',
+    description: 'The custom data object can be used to pass custom properties.',
+    type: 'object',
+    additionalProperties: true,
+    defaultObjectUI: 'keyvalue'
+}
+
+export const eventID: InputField = {
+    label: 'Event ID',
+    description: 'This ID can be any unique string. Event ID is used to deduplicate events sent by both Facebook Pixel and Conversions API.',
+    type: 'string',
+    default: { '@path': '$.messageId' }
+}
+
+export const eventSourceUrl: InputField = {
+    label: 'Event Source URL',
+    description: 'The URL of the page where the event occurred. Can be used to override the default URL taken from the current page.',
+    type: 'string',
+    default: { '@path': '$.context.page.url' }
+}
+
+export const actionSource: InputField = {
+  label: 'Action Source',
+  description: 'The source of the event. This can be used to specify where the event originated from.',
+  type: 'string',
+  choices: [
+    { label: 'Email', value: ACTION_SOURCES.email },
+    { label: 'Website', value: ACTION_SOURCES.website },
+    { label: 'App', value: ACTION_SOURCES.app },
+    { label: 'Phone Call', value: ACTION_SOURCES.phone_call },
+    { label: 'Chat', value: ACTION_SOURCES.chat },
+    { label: 'Physical Store', value: ACTION_SOURCES.physical_store },
+    { label: 'System Generated', value: ACTION_SOURCES.system_generated },
+    { label: 'Other', value: ACTION_SOURCES.other }
+  ],
+  default: ACTION_SOURCES.website
+}
+
+export const userData: InputField = {
+    label: 'User Data',
+    description: 'User data to be sent with the event. This can include hashed identifiers like email, phone number, etc.',
+    type: 'object',
+    properties: {
+        external_id: {
+            label: 'External ID',
+            description: 'A unique identifier for the user from your system',
+            type: 'string'
+        },
+        em: {
+            label: 'Email',
+            description: 'Email address of the user',
+            type: 'string',
+            format: 'email'
+        },
+        ph: {
+            label: 'Phone Number',
+            description: 'Phone number of the user',
+            type: 'string'
+        },
+        fn: {
+            label: 'First Name',
+            description: 'First name of the user',
+            type: 'string'  
+        },
+        ln: {
+            label: 'Last Name',
+            description: 'Last name of the user',
+            type: 'string'
+        },
+        ge: {
+            label: 'Gender',
+            description: 'Gender of the user. If unknown leave blank.',
+            type: 'string',
+            choices: [
+                { label: 'Male', value: 'm' },
+                { label: 'Female', value: 'f' }
+            ]
+        },
+        db: {
+            label: 'Date of Birth',
+            description: 'Date of birth of the user',
+            type: 'string'
+        },
+        ct: {
+            label: 'City',
+            description: 'City of the user',
+            type: 'string'
+        },
+        st: {
+            label: 'State',
+            description: 'State of the user. Two-letter state or province code for the United States, For example, "NY" for New York.',
+            type: 'string'
+        },
+        zp: {
+            label: 'ZIP/Postal Code',
+            description: 'ZIP or postal code of the user. For example, "94025" for Menlo Park, CA, or "10001" for New York City.',
+            type: 'string'
+        },
+        country: {
+            label: 'Country',
+            description: 'Country code of the user. This should be a valid ISO 3166-1 alpha-2 country code. For example, "US" for the United States.',
+            type: 'string'
+        }
+    },
+    default: {
+        external_id: { '@path': '$.context.traits.userId' },
+        em: { '@path': '$.context.traits.email' },
+        ph: { '@path': '$.context.traits.phone' },
+        fn: { '@path': '$.context.traits.first_name' },
+        ln: { '@path': '$.context.traits.last_name' },
+        ge: { '@path': '$.context.traits.gender' },
+        db: { '@path': '$.context.traits.birthday' },
+        ct: { '@path': '$.context.traits.address.city' },
+        st: { '@path': '$.context.traits.address.state' },
+        zp: { '@path': '$.context.traits.address.postal_code' },
+        country: { '@path': '$.context.traits.address.country' }
+    }
+}
+
+export const AllFields = {
+    event_config, 
+    content_category,
+    content_ids, 
+    content_name,
+    content_type, 
+    contents,
+    currency,
+    delivery_category,
+    num_items, 
+    predicted_ltv,
+    search_string,
+    status,
+    value,
+    custom_data,
+    eventID, 
+    eventSourceUrl, 
+    actionSource, 
+    userData
+}

package/src/send/generated-types.ts

@@ -0,0 +1,150 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * Specify the type of Facebook Conversions API event to send.
+   */
+  event_config: {
+    /**
+     * Facebook Conversions API Event Name to send. Select 'Custom Event' to send a non standard event.
+     */
+    event_name: string
+    /**
+     * Custom event name to send to Facebook
+     */
+    custom_event_name?: string
+    /**
+     * Show all fields, even those which are not relevant to the selected Event Name.
+     */
+    show_fields?: boolean
+  }
+  /**
+   * The category of the content associated with the event.
+   */
+  content_category?: string
+  /**
+   * Product IDs associated with the event, such as SKUs (e.g. ['ABC123', 'XYZ789']). Accepts a single string value or array of strings.
+   */
+  content_ids?: string[]
+  /**
+   * The name of the page or product associated with the event.
+   */
+  content_name?: string
+  /**
+   * If the IDs being passed in content_ids or contents parameter are IDs of products, then the value should be product. If product group IDs are being passed, then the value should be product_group. If no content_type is provided, Meta will match the event to every item that has the same ID, independent of its type.
+   */
+  content_type?: string
+  /**
+   * A list of JSON objects that contain the product IDs associated with the event plus information about the products. ID and quantity are required fields.
+   */
+  contents?: {
+    /**
+     * The product ID of the purchased item.
+     */
+    id: string
+    /**
+     * The number of items purchased.
+     */
+    quantity: number
+    /**
+     * The price of the item.
+     */
+    item_price?: number
+    [k: string]: unknown
+  }[]
+  /**
+   * The currency for the value specified. Currency must be a valid ISO 4217 three-digit currency code.
+   */
+  currency?: string
+  /**
+   * Category of the delivery
+   */
+  delivery_category?: string
+  /**
+   * The number of items when checkout was initiated.
+   */
+  num_items?: number
+  /**
+   * Predicted lifetime value of a subscriber as defined by the advertiser and expressed as an exact value.
+   */
+  predicted_ltv?: number
+  /**
+   * The string entered by the user for the search.
+   */
+  search_string?: string
+  /**
+   * The status of the registration. true for completed registrations, false otherwise.
+   */
+  status?: boolean
+  /**
+   * A numeric value associated with this event. This could be a monetary value or a value in some other metric.
+   */
+  value?: number
+  /**
+   * The custom data object can be used to pass custom properties.
+   */
+  custom_data?: {
+    [k: string]: unknown
+  }
+  /**
+   * This ID can be any unique string. Event ID is used to deduplicate events sent by both Facebook Pixel and Conversions API.
+   */
+  eventID?: string
+  /**
+   * The URL of the page where the event occurred. Can be used to override the default URL taken from the current page.
+   */
+  eventSourceUrl?: string
+  /**
+   * The source of the event. This can be used to specify where the event originated from.
+   */
+  actionSource?: string
+  /**
+   * User data to be sent with the event. This can include hashed identifiers like email, phone number, etc.
+   */
+  userData?: {
+    /**
+     * A unique identifier for the user from your system
+     */
+    external_id?: string
+    /**
+     * Email address of the user
+     */
+    em?: string
+    /**
+     * Phone number of the user
+     */
+    ph?: string
+    /**
+     * First name of the user
+     */
+    fn?: string
+    /**
+     * Last name of the user
+     */
+    ln?: string
+    /**
+     * Gender of the user. If unknown leave blank.
+     */
+    ge?: string
+    /**
+     * Date of birth of the user
+     */
+    db?: string
+    /**
+     * City of the user
+     */
+    ct?: string
+    /**
+     * State of the user. Two-letter state or province code for the United States, For example, "NY" for New York.
+     */
+    st?: string
+    /**
+     * ZIP or postal code of the user. For example, "94025" for Menlo Park, CA, or "10001" for New York City.
+     */
+    zp?: string
+    /**
+     * Country code of the user. This should be a valid ISO 3166-1 alpha-2 country code. For example, "US" for the United States.
+     */
+    country?: string
+  }
+}

package/src/send/index.ts

@@ -0,0 +1,64 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { AllFields } from './fields'
+import type { FBClient, FBStandardEventType, FBNonStandardEventType } from '../types'
+import { buildOptions } from './utils'
+import { getNotVisibleForEvent } from './depends-on'
+import { validate } from './validate'
+
+const action: BrowserActionDefinition<Settings, FBClient, Payload> = {
+  title: 'Send Event',
+  description: 'Send a Standard or Custom Event to Facebook Conversions API.',
+  platform: 'web',
+  fields: AllFields,
+  perform: (client, { payload, settings }) => {
+    const { pixelId } = settings
+    const { 
+        event_config: { custom_event_name, show_fields, event_name } = {},
+        eventID,
+        eventSourceUrl,
+        actionSource,
+        userData,
+        ...rest
+    } = payload
+
+    const isCustom = event_name === 'CustomEvent' ? true : false
+
+    if(isCustom){
+        validate(payload)
+    }
+
+    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 rest) {
+                delete rest[field as keyof typeof rest]
+            }
+        })
+    }
+
+    const options = buildOptions(payload)
+  
+    if(isCustom){
+      client(
+        'trackSingleCustom', 
+        pixelId,
+        custom_event_name as string,
+        { ...rest },
+        options
+      )
+    } else {
+      client(
+        'trackSingle', 
+        pixelId,
+        event_name as FBStandardEventType,
+        { ...rest },
+        options
+      )
+    }
+  }
+}
+
+export default action

package/src/send/utils.ts

@@ -0,0 +1,90 @@
+import { LDU, UserData, Options, ActionSource } from '../types'
+import { US_STATE_CODES, COUNTRY_CODES} from './constants'
+import { Payload } from './generated-types'
+
+export function getLDU(ldu: keyof typeof LDU) {
+    const lduObj = LDU[ldu]
+    return { country: lduObj.country, state: lduObj.state }
+}
+
+export function buildOptions(payload: Payload): Options | undefined {
+    const { eventID, eventSourceUrl, actionSource, userData } = payload    
+    
+    const options: Options = { 
+        eventID,
+        eventSourceUrl,
+        actionSource: actionSource as ActionSource | undefined,
+        userData: santizeUserData(userData as UserData) 
+    }
+
+    return Object.values(options).some(Boolean) ? options : undefined
+}
+
+export function santizeUserData(userData: UserData): UserData | undefined {
+    if(!userData){
+        return undefined 
+    }
+    userData.em = typeof userData.em === 'string' ? userData.em.toLowerCase().trim() : undefined // lowercase and trim whitespace
+    userData.ph = userData.ph ? userData.ph.replace(/\D/g, '') : undefined // remove non-numeric characters
+    userData.fn = userData.fn ? userData.fn.toLowerCase().trim() : undefined // lowercase and trim whitespace
+    userData.ln = userData.ln ? userData.ln.toLowerCase().trim() : undefined // lowercase and trim whitespace
+    userData.ge = userData.ge ? userData.ge.toLowerCase().trim() : undefined // lowercase and trim whitespace
+    userData.db = formatDate(userData.db) // format date to YYYYMMDD
+    userData.ct = userData.ct ? userData.ct.toLowerCase().replace(/\s+/g, '') : undefined // lowercase and replace any whitespace
+    userData.st = sanitizeState(userData.st) // lowercase 2 character state code 
+    userData.zp = userData.zp ? userData.zp.trim() : undefined 
+    userData.country = sanitizeCountry(userData.country) // lowercase 2 character country code 
+    return userData
+}
+
+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}`
+}
+
+function sanitizeState(state?: string): string | undefined {
+    if (typeof state !== 'string' || !state.trim()) {
+        return undefined
+    }
+
+    const normalized = state.replace(/\s+/g, '').toLowerCase()
+
+    const abbreviation = US_STATE_CODES.get(normalized)
+    if (abbreviation) {
+        return abbreviation
+    }
+
+    if (/^[a-z]{2}$/i.test(normalized)) {
+        return normalized.toLowerCase()
+    }
+
+    return undefined
+}
+
+function sanitizeCountry(country?: string): string | undefined {
+    if (typeof country !== 'string' || !country.trim()) {
+        return undefined
+    }
+
+    const normalized = country.replace(/\s+/g, '').toUpperCase()
+
+    const abbreviation = COUNTRY_CODES.get(normalized)
+    if (abbreviation) {
+        return abbreviation
+    }
+
+    if (/^[A-Z]{2}$/.test(normalized)) {
+        return normalized.toLowerCase()
+    }
+
+    return undefined
+}