@splendidlabz/tracking 0.1.21 → 0.2.0

package/lib/fb/utils.js

@@ -1,10 +1,11 @@
 import { isEmpty } from '@splendidlabz/utils'
-import { sha256Hash } from '@splendidlabz/utils/dom'
+import { COUNTRY_CODES, US_STATE_CODES } from './consts.js'
 
-export async function formatUserData(data) {
+export async function formatUserData(data, sha256HashFn) {
   if (isEmpty(data)) return {}
 
   // Lowercase all the values
+  // https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
   for (const [key, value] of Object.entries(data)) {
     data[key] = value.toLowerCase()
   }
@@ -24,349 +25,26 @@ export async function formatUserData(data) {
 
   const ret = {}
 
-  if (email) ret.em = await sha256Hash(email)
-  if (phone) ret.ph = await sha256Hash(phone)
-  if (firstName) ret.fn = await sha256Hash(firstName)
-  if (lastName) ret.ln = await sha256Hash(lastName)
-  if (birthdate) ret.db = await sha256Hash(birthdate)
-  if (gender) ret.ge = await sha256Hash(gender)
-  if (city) ret.ct = await sha256Hash(city.replace(' ', ''))
+  if (email) ret.em = await sha256HashFn(email)
+  if (phone) ret.ph = await sha256HashFn(phone)
+  if (firstName) ret.fn = await sha256HashFn(firstName)
+  if (lastName) ret.ln = await sha256HashFn(lastName)
+  if (birthdate) ret.db = await sha256HashFn(birthdate)
+  if (gender) ret.ge = await sha256HashFn(gender)
+  if (city) ret.ct = await sha256HashFn(city.replace(' ', ''))
 
   if (country) {
     const c = COUNTRY_CODES[country]
-    ret.country = await sha256Hash(c)
+    ret.country = await sha256HashFn(c)
 
     if (c === 'us' && state) {
-      ret.st = await sha256Hash(US_STATE_CODES[state])
+      ret.st = await sha256HashFn(US_STATE_CODES[state])
     }
+
     if (c !== 'us' && state) {
-      ret.st = await sha256Hash(state.replace(' ', '').replace('-', ''))
+      ret.st = await sha256HashFn(state.replace(' ', '').replace('-', ''))
     }
   }
-  if (zip) ret.zp = await sha256Hash(zip)
+  if (zip) ret.zp = await sha256HashFn(zip)
   return ret
 }
-
-const US_STATE_CODES = {
-  alabama: 'al',
-  alaska: 'ak',
-  'american samoa': 'as',
-  arizona: 'az',
-  arkansas: 'ar',
-  'baker island': 'bi',
-  california: 'ca',
-  colorado: 'co',
-  connecticut: 'ct',
-  delaware: 'de',
-  'district of columbia': 'dc',
-  florida: 'fl',
-  'federated states of micronesia': 'fm',
-  georgia: 'ga',
-  guam: 'gu',
-  hawaii: 'hi',
-  'howland island': 'hi',
-  idaho: 'id',
-  illinois: 'il',
-  indiana: 'in',
-  iowa: 'ia',
-  'jarvis island': 'ji',
-  'johnston atoll': 'ja',
-  kansas: 'ks',
-  kentucky: 'ky',
-  'kingman reef': 'kr',
-  louisiana: 'la',
-  maine: 'me',
-  'marshall islands': 'mh',
-  maryland: 'md',
-  massachusetts: 'ma',
-  michigan: 'mi',
-  'midway islands': 'mi',
-  minnesota: 'mn',
-  mississippi: 'ms',
-  missouri: 'mo',
-  montana: 'mt',
-  'navassa island': 'ni',
-  nebraska: 'ne',
-  nevada: 'nv',
-  'new hampshire': 'nh',
-  'new jersey': 'nj',
-  'new mexico': 'nm',
-  'new york': 'ny',
-  'north carolina': 'nc',
-  'north dakota': 'nd',
-  'northern mariana islands': 'mp',
-  ohio: 'oh',
-  oklahoma: 'ok',
-  oregon: 'or',
-  palau: 'pw',
-  'palmyra atoll': 'pa',
-  pennsylvania: 'pa',
-  'puerto rico': 'pr',
-  'rhode island': 'ri',
-  'south carolina': 'sc',
-  'south dakota': 'sd',
-  tennessee: 'tn',
-  texas: 'tx',
-  'u.s. minor outlying islands': 'um',
-  utah: 'ut',
-  vermont: 'vt',
-  virginia: 'va',
-  'virgin islands of the u.s.': 'vi',
-  'wake island': 'wi',
-  washington: 'wa',
-  'west virginia': 'wv',
-  wisconsin: 'wi',
-  wyoming: 'wy',
-}
-
-const COUNTRY_CODES = {
-  afghanistan: 'af',
-  'åland islands': 'ax',
-  albania: 'al',
-  algeria: 'dz',
-  'american samoa': 'as',
-  andorra: 'ad',
-  angola: 'ao',
-  anguilla: 'ai',
-  antarctica: 'aq',
-  'antigua and barbuda': 'ag',
-  argentina: 'ar',
-  armenia: 'am',
-  aruba: 'aw',
-  australia: 'au',
-  austria: 'at',
-  azerbaijan: 'az',
-  bahamas: 'bs',
-  bahrain: 'bh',
-  bangladesh: 'bd',
-  barbados: 'bb',
-  belarus: 'by',
-  belgium: 'be',
-  belize: 'bz',
-  benin: 'bj',
-  bermuda: 'bm',
-  bhutan: 'bt',
-  'bolivia (plurinational state of)': 'bo',
-  'bonaire, sint eustatius and saba': 'bq',
-  'bosnia and herzegovina': 'ba',
-  botswana: 'bw',
-  'bouvet island': 'bv',
-  brazil: 'br',
-  'british indian ocean territory': 'io',
-  'brunei darussalam': 'bn',
-  brunei: 'bn',
-  bulgaria: 'bg',
-  'burkina faso': 'bf',
-  burundi: 'bi',
-  'cabo verde': 'cv',
-  cambodia: 'kh',
-  cameroon: 'cm',
-  canada: 'ca',
-  'cayman islands': 'ky',
-  'central african republic': 'cf',
-  chad: 'td',
-  chile: 'cl',
-  china: 'cn',
-  'christmas island': 'cx',
-  'cocos (keeling) islands': 'cc',
-  colombia: 'co',
-  comoros: 'km',
-  'democratic republic of the congo': 'cd',
-  'cook islands': 'ck',
-  'costa rica': 'cr',
-  "côte d'ivoire": 'ci',
-  croatia: 'hr',
-  cuba: 'cu',
-  curaçao: 'cw',
-  cyprus: 'cy',
-  czechia: 'cz',
-  denmark: 'dk',
-  djibouti: 'dj',
-  dominica: 'dm',
-  'dominican republic': 'do',
-  ecuador: 'ec',
-  egypt: 'eg',
-  'el salvador': 'sv',
-  'equatorial guinea': 'gq',
-  eritrea: 'er',
-  estonia: 'ee',
-  eswatini: 'sz',
-  ethiopia: 'et',
-  'falkland islands': 'fk',
-  'faroe islands': 'fo',
-  fiji: 'fj',
-  finland: 'fi',
-  france: 'fr',
-  'french guiana': 'gf',
-  'french polynesia': 'pf',
-  'french southern territories': 'tf',
-  gabon: 'ga',
-  gambia: 'gm',
-  georgia: 'ge',
-  germany: 'de',
-  ghana: 'gh',
-  gibraltar: 'gi',
-  greece: 'gr',
-  greenland: 'gl',
-  grenada: 'gd',
-  guadeloupe: 'gp',
-  guam: 'gu',
-  guatemala: 'gt',
-  guernsey: 'gg',
-  guinea: 'gn',
-  'guinea-bissau': 'gw',
-  guyana: 'gy',
-  haiti: 'ht',
-  'heard island and mcdonald islands': 'hm',
-  'holy see': 'va',
-  honduras: 'hn',
-  'hong kong': 'hk',
-  hungary: 'hu',
-  iceland: 'is',
-  india: 'in',
-  indonesia: 'id',
-  iran: 'ir',
-  iraq: 'iq',
-  ireland: 'ie',
-  'isle of man': 'im',
-  israel: 'il',
-  italy: 'it',
-  jamaica: 'jm',
-  japan: 'jp',
-  jersey: 'je',
-  jordan: 'jo',
-  kazakhstan: 'kz',
-  kenya: 'ke',
-  kiribati: 'ki',
-  'north korea': 'kp',
-  'south korea': 'kr',
-  kuwait: 'kw',
-  kyrgyzstan: 'kg',
-  laos: 'la',
-  latvia: 'lv',
-  lebanon: 'lb',
-  lesotho: 'ls',
-  liberia: 'lr',
-  libya: 'ly',
-  liechtenstein: 'li',
-  lithuania: 'lt',
-  luxembourg: 'lu',
-  macao: 'mo',
-  madagascar: 'mg',
-  malawi: 'mw',
-  malaysia: 'my',
-  maldives: 'mv',
-  mali: 'ml',
-  malta: 'mt',
-  'marshall islands': 'mh',
-  martinique: 'mq',
-  mauritania: 'mr',
-  mauritius: 'mu',
-  mayotte: 'yt',
-  mexico: 'mx',
-  micronesia: 'fm',
-  moldova: 'md',
-  monaco: 'mc',
-  mongolia: 'mn',
-  montenegro: 'me',
-  montserrat: 'ms',
-  morocco: 'ma',
-  mozambique: 'mz',
-  myanmar: 'mm',
-  namibia: 'na',
-  nauru: 'nr',
-  nepal: 'np',
-  netherlands: 'nl',
-  'new caledonia': 'nc',
-  'new zealand': 'nz',
-  nicaragua: 'ni',
-  niger: 'ne',
-  nigeria: 'ng',
-  niue: 'nu',
-  'norfolk island': 'nf',
-  'north macedonia': 'mk',
-  'northern mariana islands': 'mp',
-  norway: 'no',
-  oman: 'om',
-  pakistan: 'pk',
-  palau: 'pw',
-  palestine: 'ps',
-  panama: 'pa',
-  'papua new guinea': 'pg',
-  paraguay: 'py',
-  peru: 'pe',
-  philippines: 'ph',
-  pitcairn: 'pn',
-  poland: 'pl',
-  portugal: 'pt',
-  'puerto rico': 'pr',
-  qatar: 'qa',
-  réunion: 're',
-  romania: 'ro',
-  'russian federation': 'ru',
-  rwanda: 'rw',
-  'saint barthélemy': 'bl',
-  'saint helena': 'sh',
-  'saint kitts and nevis': 'kn',
-  'saint lucia': 'lc',
-  'saint martin': 'mf',
-  'saint pierre and miquelon': 'pm',
-  'saint vincent and the grenadines': 'vc',
-  samoa: 'ws',
-  'san marino': 'sm',
-  'sao tome and principe': 'st',
-  'saudi arabia': 'sa',
-  senegal: 'sn',
-  serbia: 'rs',
-  seychelles: 'sc',
-  'sierra leone': 'sl',
-  singapore: 'sg',
-  'sint maarten': 'sx',
-  slovakia: 'sk',
-  slovenia: 'si',
-  'solomon islands': 'sb',
-  somalia: 'so',
-  'south africa': 'za',
-  'south georgia and the south sandwich islands': 'gs',
-  'south sudan': 'ss',
-  spain: 'es',
-  'sri lanka': 'lk',
-  sudan: 'sd',
-  suriname: 'sr',
-  'svalbard and jan mayen': 'sj',
-  sweden: 'se',
-  switzerland: 'ch',
-  'syrian arab republic': 'sy',
-  taiwan: 'tw',
-  tajikistan: 'tj',
-  tanzania: 'tz',
-  thailand: 'th',
-  'timor-leste': 'tl',
-  togo: 'tg',
-  tokelau: 'tk',
-  tonga: 'to',
-  'trinidad and tobago': 'tt',
-  tunisia: 'tn',
-  türkiye: 'tr',
-  turkmenistan: 'tm',
-  'turks and caicos islands': 'tc',
-  tuvalu: 'tv',
-  uganda: 'ug',
-  ukraine: 'ua',
-  'united arab emirates': 'ae',
-  'united kingdom': 'gb',
-  'united states minor outlying islands': 'um',
-  'united states': 'us',
-  uruguay: 'uy',
-  uzbekistan: 'uz',
-  vanuatu: 'vu',
-  venezuela: 've',
-  'viet nam': 'vn',
-  'british virgin islands': 'vg',
-  'u.s. virgin islands': 'vi',
-  'wallis and futuna': 'wf',
-  'western sahara': 'eh',
-  yemen: 'ye',
-  zambia: 'zm',
-  zimbabwe: 'zw',
-}

package/lib/fb/web.js

@@ -0,0 +1,148 @@
+import { notEmpty, splitObject } from '@splendidlabz/utils'
+import { getCookie, randomString, sha256Hash } from '@splendidlabz/utils/dom'
+import {
+  STANDARD_EVENTS,
+  USER_PROPERTIES,
+  USER_PROPERTIES_TO_HASH,
+} from './consts.js'
+
+import zlFetch from 'zl-fetch'
+import { formatUserData } from './utils.js'
+
+export default function FB({ pixelID, testEventCode, capiEndpoint }) {
+  return {
+    init: _ => initPixel(pixelID),
+
+    async createEvent(event_name, props = {}, options = {}) {
+      const { debug = false } = options
+      const { eventURL, actionSource, ...r } = props
+      const { p: userProperties, o: rest } = splitObject(r, USER_PROPERTIES)
+      const { p: userPropsToHash, o: otherUserProps } = splitObject(
+        userProperties,
+        USER_PROPERTIES_TO_HASH,
+      )
+
+      const user_data = {
+        ...(await formatUserData(userPropsToHash, sha256Hash)),
+        ...otherUserProps,
+      }
+
+      const eventID = await randomString()
+
+      const pixelData = {
+        pixelID,
+        eventID,
+        event_name,
+        user_data,
+        ...rest,
+      }
+
+      const capiData = {
+        pixel_id: pixelID,
+        event_id: eventID,
+        event_name,
+        event_time: Math.floor(new Date() / 1000),
+        event_source_url: eventURL || window.location.href,
+        action_source: actionSource || 'website',
+        user_data: {
+          ...user_data,
+          fbp: getCookie('_fbp'),
+          fbc: getCookie('_fbc'),
+        },
+        custom_data: rest,
+        test_event_code: testEventCode,
+      }
+
+      if (debug) {
+        console.log('Pixel Data', pixelData)
+        console.log('CAPI Data', capiData)
+      }
+
+      return { pixelData, capiData }
+    },
+
+    async track(event_name, props = {}, options = {}) {
+      const { debug = false, dryRun = false } = options
+      const { pixelData, capiData } = await this.createEvent(
+        event_name,
+        props,
+        options,
+      )
+
+      if (dryRun) return
+
+      this.sendPixelEvent(pixelData, options)
+      const { response, error } = await this.sendCAPIRequest(capiData)
+      if (debug) console.log('CAPI Response', response.body)
+      if (error) return Promise.reject(error)
+      return response.body
+    },
+
+    // Facebook Pixel Code
+    // Pixel Standard Reference
+    // https://developers.facebook.com/docs/meta-pixel/reference#standard-events
+    // For Advanced Matching when user data is available
+    // https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/
+    sendPixelEvent(data, { debug = false }) {
+      const { pixelID, eventID, event_name, user_data = {}, ...rest } = data
+      const hasUserData = notEmpty(user_data)
+
+      const props = rest
+
+      // For Advanced Matching we provide user data.
+      if (hasUserData) {
+        fbq('init', pixelID, user_data)
+        if (debug) console.log('init', pixelID, user_data)
+      }
+
+      // `init` uses pixelID as the second param
+      if (event_name === 'init') {
+        fbq('init', pixelID)
+        if (debug) console.log('init', pixelID)
+      } else {
+        // Otherwise we can track the event as normal
+        const action = STANDARD_EVENTS.includes(event_name)
+          ? 'track'
+          : 'trackCustom'
+        fbq(action, event_name, props, { eventID })
+        if (debug) console.log(action, event_name, props, { eventID })
+      }
+    },
+
+    // CAPI Parameters: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+    sendCAPIRequest(data) {
+      return zlFetch.post(capiEndpoint, { body: data })
+    },
+  }
+}
+
+function initPixel(pixelID) {
+  // eslint-disable-next-line
+  !(function (f, b, e, v, n, t, s) {
+    if (f.fbq) return
+    n = f.fbq = function () {
+      n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments)
+    }
+    if (!f._fbq) f._fbq = n
+    n.push = n
+    n.loaded = !0
+    n.version = '2.0'
+    n.queue = []
+    t = b.createElement(e)
+    t.async = !0
+    t.src = v
+    s = b.getElementsByTagName(e)[0]
+    s.parentNode.insertBefore(t, s)
+  })(
+    window,
+    document,
+    'script',
+    'https://connect.facebook.net/en_US/fbevents.js',
+  )
+
+  if (typeof window === 'undefined') {
+    throw new Error(`'init' can only be called in the browser`)
+  } else {
+    fbq('init', pixelID)
+  }
+}

package/lib/fb/web.test.js

@@ -0,0 +1,47 @@
+// @vitest-environment jsdom
+import { describe, expect, test } from 'vitest'
+import FB from './web.js'
+
+describe('Web FB', () => {
+  test('createEvent', async () => {
+    // Set up cookies
+    const fbp = 'fb.1.12345.67890'
+    const fbc = 'fb.1.54321.09876'
+    document.cookie = `_fbp=${fbp}`
+    document.cookie = `_fbc=${fbc}`
+
+    const fb = FB({ pixelID: '1234567890', testEventCode: 'test' })
+    const { pixelData, capiData } = await fb.createEvent('Test Event', {
+      firstName: 'John',
+      lastName: 'Wick',
+      custom: 'yay',
+    })
+
+    // Pixel Data Tests
+    expect(pixelData.pixelID).toBe('1234567890')
+    expect(pixelData.eventID).toBeDefined()
+    expect(pixelData.eventID).toBe(capiData.event_id)
+    expect(pixelData.event_name).toBe('Test Event')
+    expect(pixelData.user_data.fn).toBeDefined()
+    expect(pixelData.user_data.ln).toBeDefined()
+    expect(pixelData.user_data.fn).not.toBe('John')
+    expect(pixelData.user_data.ln).not.toBe('Wick')
+    expect(pixelData.custom).toBe('yay')
+
+    // Capi Data Tests
+    expect(capiData.pixel_id).toBe('1234567890')
+    expect(capiData.event_id).toBeDefined()
+    expect(capiData.event_id).toBe(pixelData.eventID)
+    expect(capiData.event_name).toBe('Test Event')
+    expect(capiData.event_time).toBeDefined()
+    expect(capiData.event_source_url).toBeDefined()
+    expect(capiData.action_source).toBeDefined()
+    expect(capiData.user_data.fn).toBeDefined()
+    expect(capiData.user_data.ln).toBeDefined()
+    expect(capiData.user_data.fn).not.toBe('John')
+    expect(capiData.user_data.ln).not.toBe('Wick')
+    expect(capiData.user_data.fbp).toBe(fbp)
+    expect(capiData.user_data.fbc).toBe(fbc)
+    expect(capiData.custom_data.custom).toBe('yay')
+  })
+})