@splendidlabz/tracking 0.1.22 → 0.2.1

package/lib/fb/consts.js

@@ -0,0 +1,425 @@
+export const STANDARD_EVENTS = [
+  'AddPaymentInfo',
+  'AddToCart',
+  'AddToWishlist',
+  'CompleteRegistration',
+  'Contact',
+  'CustomizeProduct',
+  'Donate',
+  'FindLocation',
+  'InitiateCheckout',
+  'Lead',
+  'Purchase',
+  'Schedule',
+  'Search',
+  'StartTrial',
+  'SubmitApplication',
+  'Subscribe',
+  'ViewContent',
+]
+
+// https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event/
+export const SERVER_EVENT_PARAMS = [
+  'event_name',
+  'event_time',
+  'user_data',
+  'custom_data',
+  'event_source_url',
+  'opt_out',
+  'event_id',
+  'action_source',
+  'data_processing_options',
+  'data_processing_options_country',
+  'data_processing_options_state',
+  'referrer_url',
+  'customer_segmentation',
+  'order_id',
+]
+
+export const APP_DATA_PARAMS = [
+  'advertiser_tracking_enabled',
+  'application_tracking_enabled',
+  'extinfo',
+  'campaign_ids',
+  'install_referrer',
+  'installer_package',
+  'url_schemes',
+  'windows_attribution_id',
+  'anon_id',
+  'madid',
+  'vendor_id',
+]
+
+// https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+export const USER_PROPERTIES_TO_HASH = [
+  'email',
+  'phone',
+  'firstName',
+  'lastName',
+  'birthdate',
+  'gender',
+  'city',
+  'state',
+  'zip',
+  'country',
+  'externalID',
+]
+
+// Other optional FB Stuff — doesn't seem very useful
+export const USER_PROPERTIES_NOT_TO_HASH = [
+  'subscription_id',
+  'fb_login_id',
+  'lead_id',
+  'anon_id',
+  'madid',
+  'page_id',
+  'page_scoped_user_id',
+  'ctwa_clid',
+  'ig_account_id',
+  'ig_sid',
+]
+
+export const USER_PROPERTIES = [
+  ...USER_PROPERTIES_TO_HASH,
+  ...USER_PROPERTIES_NOT_TO_HASH,
+]
+
+// https://developers.facebook.com/docs/meta-pixel/reference/
+export const CUSTOM_PROPERTIES = [
+  'content_category',
+  'content_ids',
+  'content_name',
+  'content_type',
+  'contents',
+  'currency',
+  'delivery_category',
+  'num_items',
+  'predicted_ltv',
+  'search_string',
+  'status',
+  'value',
+]
+
+export 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',
+}
+
+export 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/node.js

@@ -0,0 +1,141 @@
+import { mix, omitEmpty, splitObject } from '@splendidlabz/utils'
+import { randomString, sha256Hash } from '@splendidlabz/utils/node'
+import zlFetch from 'zl-fetch'
+import {
+  SERVER_EVENT_PARAMS,
+  USER_PROPERTIES,
+  USER_PROPERTIES_TO_HASH,
+} from './consts.js'
+import { formatUserData } from './utils.js'
+
+// https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/
+export default function FB({ pixelID, testEventCode, accessToken, framework }) {
+  framework = framework.toLowerCase()
+
+  if (!accessToken) throw new Error('Facebook Access Token required')
+
+  return {
+    // When used as API call — frontend would have done all the work
+    // So we can just send the body to the CAPI request
+    async sendEvent(props = {}, options = {}) {
+      const { pixel_id, test_event_code, ...rest } = props
+      const body = {
+        data: [omitEmpty(rest)],
+        test_event_code: test_event_code || testEventCode,
+      }
+      return this.sendCAPIRequest(body, { ...options, pixel_id })
+    },
+
+    async createEvent(eventName, props = {}, options = {}) {
+      const { context, ...p } = props
+      const { p: eventParams, o: r1 } = splitObject(p, SERVER_EVENT_PARAMS)
+      const { p: userProps, o: r2 } = splitObject(r1, USER_PROPERTIES)
+      const { fbc, fbp, ...rest } = r2
+
+      if (!framework) {
+        console.warn(
+          'Framework not provided. Several properties will not be created.',
+        )
+      }
+
+      if (!context) {
+        console.warn(
+          'Context not provided. Several properties will not be created.',
+        )
+      }
+
+      if (framework !== 'astro') {
+        throw new Error('Currently we only support the Astro framework')
+      }
+
+      const normalizedUserData = await normalizeUserData({
+        context,
+        framework,
+        userProps,
+        fbc,
+        fbp,
+      })
+
+      const data = omitEmpty(
+        mix(getEventParamDefaults(framework, context), eventParams, {
+          event_name: eventName,
+          user_data: normalizedUserData,
+          custom_data: rest,
+        }),
+      )
+
+      const body = omitEmpty({
+        test_event_code: testEventCode,
+        data: [data],
+      })
+
+      return body
+    },
+
+    // When used directly via backend
+    async track(eventName, props = {}, options = {}) {
+      const body = await this.createEvent(eventName, props, options)
+      return this.sendCAPIRequest(body, options)
+    },
+
+    async sendCAPIRequest(body, options) {
+      const { debug = false, dryRun = false, pixel_id } = options
+      const pixel = pixel_id || pixelID
+
+      if (debug) console.log(body)
+      if (dryRun) return
+
+      return zlFetch.post(
+        'https://graph.facebook.com/v19.0/' + pixel + '/events',
+        {
+          auth: accessToken,
+          body,
+          returnError: true,
+        },
+      )
+    },
+  }
+}
+
+function getEventParamDefaults(framework, context) {
+  return {
+    event_id: randomString(10),
+    action_source: 'website',
+    event_time: Math.floor(new Date() / 1000),
+    event_source_url: getUrl(framework, context),
+  }
+}
+
+function getUrl(framework, context) {
+  if (framework === 'astro') return context.url.href
+}
+
+async function normalizeUserData({ context, framework, userProps, fbc, fbp }) {
+  let ip, userAgent
+
+  const { p: userPropsToHash, o: otherUserProps } = splitObject(
+    userProps,
+    USER_PROPERTIES_TO_HASH,
+  )
+
+  const hashedProps = await formatUserData(userPropsToHash, sha256Hash)
+
+  // Get other client data
+  if (framework === 'astro') {
+    ip = context.clientAddress
+    userAgent = context.request.headers.get('user-agent')
+    if (!fbp) fbp = context.cookies.get('_fbp')?.value
+    if (!fbc) fbc = context.cookies.get('_fbc')?.value
+  }
+
+  const userData = omitEmpty({
+    ...hashedProps,
+    ...otherUserProps,
+    client_ip_address: ip,
+    client_user_agent: userAgent,
+    fbc,
+    fbp,
+  })
+
+  return userData
+}

package/lib/fb/readme.md

@@ -0,0 +1,54 @@
+Shared config
+
+```js
+export default {
+  fb: {
+    pixelID: 'PIXEL ID',
+    testEventCode: 'TEST EVENT CODE',
+  },
+}
+```
+
+Setup
+
+```js
+import FB from '@splendidlabz/tracking/fb/web'
+import config from './shared'
+
+export const fb = FB({
+  ...config.fb,
+  capiEndpoint: '/api/tracking/facebook/',
+})
+```
+
+Server
+
+```js
+import FB from '@splendidlabz/tracking/fb/node'
+import config from './shared'
+
+export const fb = FB({
+  ...config.fb,
+  framework: 'astro',
+  accessToken: import.meta.env.FB_CAPI_TOKEN,
+})
+```
+
+Ads server for dedupe events
+
+```js
+import { fb } from '@/services/tracking/node'
+import { JSONResponse, parseData } from '@splendidlabz/astro/server'
+export const prerender = false
+
+export async function POST(context) {
+  const body = await parseData(context)
+  const { response, error } = await fb.sendEvent(body)
+  if (response) return new JSONResponse(response.body, { status: 200 })
+  if (error) return new JSONResponse(error, { status: 500 })
+}
+```
+
+Other stuff necessary.... well... check Facebook docs ba.
+Perhaps should include a standard event list , or link to the docs.
+Should also notify that `PageView` is going to be tracked as a custom event.