@splendidlabz/tracking 0.1.20

package/lib/convertkit/client.js

@@ -0,0 +1,35 @@
+import { sessionStore } from '@splendidlabz/utils/dom'
+import zlFetch from 'zl-fetch'
+
+// Link this to Convertkit... if there is a convertkit id in the URL, identify the user with that id.
+export function getSubscriberID() {
+  // Get from Session Store
+  let ckid = sessionStore.get('ckid')
+  if (ckid) return ckid
+
+  // Get from URL
+  const url = new URL(window.location.href)
+  ckid = url.searchParams.get('ck_subscriber_id')
+
+  if (ckid) {
+    // Cleanup URL
+    url.searchParams.delete('ck_subscriber_id')
+    window.history.replaceState({}, '', url.href)
+    sessionStore.set('ckid', ckid)
+    return ckid
+  }
+}
+
+// Probably needs to have an initialize endpoint somewhere so can use easily... maybe include a config file or something and inject that in?
+// Problem now is whether I want to sell this part as well... if not then it becomes lehcheh.
+export async function getSubscriberInfo(id, { apiRoot }) {
+  // Get info from session store if available
+  let ckinfo = sessionStore.get('ckinfo')
+  if (ckinfo) return ckinfo
+
+  // Get from server otherwise
+  const response = await zlFetch(`${apiRoot}/ck/subscribers/${id}`)
+  ckinfo = response.body
+  sessionStore.set('ckinfo', ckinfo)
+  return ckinfo
+}

package/lib/convertkit/server.js

@@ -0,0 +1,24 @@
+import createError from 'http-errors'
+import zlFetch from 'zl-fetch'
+
+const SECRET = process.env.CONVERTKIT_API_SECRET
+
+export async function getSubscriber(id) {
+  const endpoint = `https://api.convertkit.com/v3/subscribers/${id}`
+
+  if (!accessToken) {
+    throw createError(
+      500,
+      'Convertkit API Secret is not provided in the environment variables.'
+    )
+    return
+  }
+
+  const response = await zlFetch(endpoint, {
+    query: {
+      api_secret: SECRET,
+    },
+  })
+
+  return response.body
+}

package/lib/fb/browser.js

@@ -0,0 +1,184 @@
+import { getCookie, randomString, sha256Hash } from '@splendidlabz/utils/dom'
+import { isEmpty, notEmpty, splitObject } from '@splendidlabz/utils'
+
+import { formatUserData } from './utils.js'
+import zlFetch from 'zl-fetch'
+
+// TODO: Figure a way to put the Pixel Code into the DOM... if possible!
+export default function FB({ pixelID, testEventCode, capiEndpoint }) {
+  const _fb = {
+    options: { pixelID, testEventCode, capiEndpoint },
+
+    // Initializes Facebook
+    init() {
+      !(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',
+      )
+      fbq('init', pixelID)
+    },
+
+    async sendEvent(eventName, props = {}) {
+      const eventData = await _fb.createFBEvent(eventName, props)
+
+      // Question whether we want to verbose log this thing in the future so users can know whether these events are sent.
+      _fb.sendPixelEvent(eventData)
+      return _fb.sendCAPIEvent(eventData)
+    },
+
+    async createFBEvent(eventName, props = {}) {
+      const { eventURL, actionSource, ...rest } = props
+
+      const { picked: userProperties, omitted: customData } = splitObject(
+        rest,
+        [...USER_PROPERTIES_TO_HASH, ...USER_PROPERTIES_NOT_TO_HASH],
+      )
+
+      const { picked: userPropsToHash, omitted: otherUserProps } = splitObject(
+        userProperties,
+        USER_PROPERTIES_TO_HASH,
+      )
+
+      const userData = {
+        ...(await formatUserData(userPropsToHash)),
+        ...otherUserProps,
+      }
+
+      const ret = {
+        // Data for both Pixel and CAPI
+        pixelID,
+        eventID: await randomString(),
+        eventName: eventName,
+        userData,
+        customData,
+
+        // Data for CAPI only
+        fbp: getCookie('_fbp'),
+        fbc: getCookie('_fbc'),
+        eventTime: Math.floor(new Date() / 1000),
+        eventURL: eventURL || window.location.href,
+        actionSource: actionSource || 'website',
+      }
+      if (testEventCode) ret.testEventCode = testEventCode
+
+      return ret
+    },
+
+    // Facebook Pixel Code
+    // Pixel Standard Reference
+    // https://developers.facebook.com/docs/meta-pixel/reference#standard-events
+    sendPixelEvent(data) {
+      const {
+        eventID,
+        eventName,
+        userData = {},
+        customData = {},
+        pixelID,
+      } = data
+      const props = { ...userData, ...customData }
+
+      let action = 'track'
+      let evtName = eventName
+      if (evtName === 'init') action = 'init'
+
+      // When we use fbq init, we have to add the pixelID instead of the event name as the 2nd parameter.
+      if (action === 'init') evtName = pixelID
+
+      // If the event is a custom event, we need to use `trackCustom` instead of `track`.
+      if (action !== 'init' && !standardEvents.includes(evtName))
+        action = 'trackCustom'
+
+      fbq(action, evtName, props, { eventID })
+    },
+
+    // CAPI Parameters: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
+    sendCAPIEvent(data) {
+      return zlFetch.post(capiEndpoint, { body: data })
+    },
+  }
+
+  return _fb
+}
+
+const standardEvents = [
+  '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/customer-information-parameters
+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
+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',
+]
+
+const CUSTOM_PROPERTIES = [
+  'content_category',
+  'content_ids',
+  'content_name',
+  'content_type',
+  'contents',
+  'currency',
+  'delivery_category',
+  'num_items',
+  'predicted_ltv',
+  'search_string',
+  'status',
+  'value',
+]

package/lib/fb/browser.test.js

@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+
+import FB from './browser.js'
+import { sha256Hash } from '@splendidlabz/utils/dom'
+
+describe('Facebook Event Props', _ => {
+  it('Basic Event Props', async _ => {
+    const fb = new FB({
+      pixelID: '123456789',
+      testEventCode: 'TEST123',
+      capiEndpoint: 'https://somewhere.com',
+    })
+
+    const eventData = await fb.createFBEvent('PageView', {})
+
+    expect(eventData).toHaveProperty('pixelID')
+    expect(eventData).toHaveProperty('eventID')
+    expect(eventData).toHaveProperty('eventName')
+    expect(eventData).toHaveProperty('eventURL')
+    expect(eventData).toHaveProperty('eventTime')
+    expect(eventData).toHaveProperty('actionSource')
+    expect(eventData).toHaveProperty('fbp')
+    expect(eventData).toHaveProperty('fbc')
+    expect(eventData).toHaveProperty('userData')
+    expect(eventData).toHaveProperty('customData')
+  })
+
+  it('Correctly splits userData and customData', async _ => {
+    const fb = new FB({
+      pixelID: '123456789',
+      testEventCode: 'TEST123',
+      capiEndpoint: 'https://somewhere.com',
+    })
+
+    const eventData = await fb.createFBEvent('Lead', {
+      email: 'abc@test.com',
+      firstName: 'ABC',
+      contents: [
+        { id: '22', quantity: 1 },
+        { id: '23', quantity: 1 },
+      ],
+    })
+
+    const { userData, customData } = eventData
+
+    expect(userData).toHaveProperty('em')
+    expect(userData).toHaveProperty('fn')
+    expect(customData).toEqual({
+      contents: [
+        { id: '22', quantity: 1 },
+        { id: '23', quantity: 1 },
+      ],
+    })
+  })
+
+  it('Hashing User Properties', async _ => {
+    const fb = new FB({
+      pixelID: '123456789',
+      testEventCode: 'TEST123',
+      capiEndpoint: 'https://somewhere.com',
+    })
+
+    const eventData = await fb.createFBEvent('Lead', {
+      email: 'zellwk@gmail.com',
+      firstName: 'Zell',
+      lastName: 'Liew',
+      birthdate: '19900101',
+      gender: 'm',
+      city: 'Singapore',
+      country: 'Singapore',
+      state: 'Singapore',
+      zip: '12345',
+    })
+
+    const { userData } = eventData
+
+    expect(userData).toEqual({
+      em: '5fc6517c0a210f60c685fa4e21c1c4a8a9862c55ed37f2db25cb4ae893f8e9a9',
+      fn: '07bea691e1173e5366d4ddf2c13103802b3f16441c81d6a19037a6d88118b46c',
+      ln: '555ba31c9795b7e549c88014751487db1310a2daaabd891555c3c34156e9e531',
+      db: 'd6165fc8037886424321260c0f9c2a76f7d8d545a02f95c70da9952a13299f33',
+      ge: '62c66a7a5dd70c3146618063c344e531e6d4b59e379808443ce962b3abd63c5a',
+      ct: '51e2a46721d104d9148d85b617833e7745fdbd6795cb0b502a5b6ea31d33378e',
+      country:
+        '88195283220112932b02b8aa03dc289106f478e998cadaeeea2e181f8aa1a01d',
+      st: '51e2a46721d104d9148d85b617833e7745fdbd6795cb0b502a5b6ea31d33378e',
+      zp: '5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5',
+    })
+  })
+
+  it('Not Hashing certain user properties', async _ => {
+    const fb = new FB({
+      pixelID: '123456789',
+      testEventCode: 'TEST123',
+      capiEndpoint: 'https://somewhere.com',
+    })
+
+    const eventData = await fb.createFBEvent('Lead', {
+      subscription_id: '123456789',
+      fb_login_id: '123456789',
+      lead_id: '123456789',
+      anon_id: '123456789',
+      madid: '123456789',
+      page_id: '123456789',
+      page_scoped_user_id: '123456789',
+      ctwa_clid: '123456789',
+      ig_account_id: '123456789',
+      ig_sid: '123456789',
+    })
+
+    const { userData } = eventData
+
+    expect(userData).toEqual({
+      subscription_id: '123456789',
+      fb_login_id: '123456789',
+      lead_id: '123456789',
+      anon_id: '123456789',
+      madid: '123456789',
+      page_id: '123456789',
+      page_scoped_user_id: '123456789',
+      ctwa_clid: '123456789',
+      ig_account_id: '123456789',
+      ig_sid: '123456789',
+    })
+  })
+})

package/lib/fb/server.js

@@ -0,0 +1,73 @@
+import createError from 'http-errors'
+import { formatUserData } from './utils.js'
+import zlFetch from 'zl-fetch'
+
+const accessToken = process.env.FB_ACCESS_TOKEN
+
+export async function sendConversionAPIRequest(req) {
+  const {
+    pixelID,
+    eventID,
+    eventName,
+    actionSource,
+    eventURL,
+    eventTime,
+    userData,
+    customData,
+    fbp,
+    fbc,
+    testEventCode,
+    ...rest
+  } = req.body
+
+  if (!accessToken) {
+    throw createError(
+      500,
+      'Facebook Access Token is not provided in the environment variables.'
+    )
+    return
+  }
+
+  // Don't send init event for CAPI
+  if (eventName === 'init') return
+
+  const outgoingData = [
+    {
+      event_id: eventID, // For deduplication
+      event_name: eventName,
+      action_source: actionSource,
+      event_source_url: eventURL,
+      event_time: eventTime,
+      user_data: {
+        ...userData,
+        client_ip_address: req.clientIp, // Checks if this works... if not, use ipify from the browser.
+        client_user_agent: req.headers['user-agent'],
+        fbc: fbc,
+        fbp: fbp,
+      },
+      custom_data: customData,
+
+      // Optional data processing stuff
+      opt_out: data.opt_out || false, //
+      data_processing_options: [],
+      data_processing_options_country: [],
+      data_processing_options_state: [],
+    },
+  ]
+
+  // Format CAPI Body
+  const body = {
+    data: outgoingData,
+    access_token: accessToken,
+  }
+
+  if (testEventCode) body.test_event_code = testEventCode
+
+  // Send the CAPI request
+  // Maybe need to update the version here somehow
+  return zlFetch('https://graph.facebook.com/v19.0/' + pixelID + '/events', {
+    method: 'post',
+    auth: accessToken,
+    body,
+  })
+}