@splendidlabz/tracking 0.2.9 → 0.2.11

package/lib/fb/node.js

@@ -18,9 +18,27 @@ export default function FB({ pixelID, testEventCode, accessToken, framework }) {
     // 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 { pixel_id, test_event_code, user_data, ...rest } = props
+      const { context } = options
+
+      const {
+        p: { fbc, fbp },
+        o: userProps,
+      } = splitObject(user_data, ['fbc', 'fbp'])
+
+      const data = {
+        ...rest,
+        user_data: await normalizeUserData({
+          context,
+          framework,
+          userProps,
+          fbc,
+          fbp,
+        }),
+      }
+
       const body = {
-        data: [omitEmpty(rest)],
+        data: [omitEmpty(data)],
         test_event_code: test_event_code || testEventCode,
       }
       return this.sendCAPIRequest(body, { ...options, pixel_id })
@@ -44,8 +62,11 @@ export default function FB({ pixelID, testEventCode, accessToken, framework }) {
         )
       }
 
-      if (framework !== 'astro') {
-        throw new Error('Currently we only support the Astro framework')
+      const supportedFrameworks = ['astro', 'express', 'fastify', 'koa']
+      if (!supportedFrameworks.includes(framework)) {
+        throw new Error(
+          `Unsupported framework: ${framework}. Supported frameworks: ${supportedFrameworks.join(', ')}`,
+        )
       }
 
       const normalizedUserData = await normalizeUserData({
@@ -97,6 +118,9 @@ export default function FB({ pixelID, testEventCode, accessToken, framework }) {
   }
 }
 
+// ========================
+// Helper Functions
+// ========================
 function getEventParamDefaults(framework, context) {
   return {
     event_id: randomString(10),
@@ -108,11 +132,40 @@ function getEventParamDefaults(framework, context) {
 
 function getUrl(framework, context) {
   if (framework === 'astro') return context.url.href
+  if (framework === 'express') {
+    return context.protocol + '://' + context.get('host') + context.originalUrl
+  }
+  if (framework === 'fastify') {
+    return context.protocol + '://' + context.hostname + context.url
+  }
+  if (framework === 'koa') {
+    return context.protocol + '://' + context.host + context.url
+  }
 }
 
-async function normalizeUserData({ context, framework, userProps, fbc, fbp }) {
-  let ip, userAgent
+function getIP(framework, context) {
+  if (framework === 'astro') return context.clientAddress
+  if (framework === 'express')
+    return context.ip || context.connection?.remoteAddress
+  if (framework === 'fastify') return context.ip
+  if (framework === 'koa') return context.ip
+}
+
+function getUserAgent(framework, context) {
+  if (framework === 'astro') return context.request.headers.get('user-agent')
+  if (framework === 'express') return context.get('user-agent')
+  if (framework === 'fastify') return context.headers['user-agent']
+  if (framework === 'koa') return context.get('user-agent')
+}
 
+function getCookie(framework, context, name) {
+  if (framework === 'astro') return context.cookies.get(name)?.value
+  if (framework === 'express') return context.cookies?.[name]
+  if (framework === 'fastify') return context.cookies?.[name]
+  if (framework === 'koa') return context.cookies?.get(name)
+}
+
+async function normalizeUserData({ context, framework, userProps, fbc, fbp }) {
   const { p: userPropsToHash, o: otherUserProps } = splitObject(
     userProps,
     USER_PROPERTIES_TO_HASH,
@@ -120,13 +173,11 @@ async function normalizeUserData({ context, framework, userProps, fbc, fbp }) {
 
   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
-  }
+  // Get client data from context
+  const ip = getIP(framework, context)
+  const userAgent = getUserAgent(framework, context)
+  if (!fbp) fbp = getCookie(framework, context, '_fbp')
+  if (!fbc) fbc = getCookie(framework, context, '_fbc')
 
   const userData = omitEmpty({
     ...hashedProps,

package/lib/fb/readme.md

@@ -1,42 +1,43 @@
-Shared config
+Designed to provide a unified interface for Facebook Pixel and Conversion API.
+
+## Setup
+
+Config
 
 ```js
 export default {
   fb: {
     pixelID: 'PIXEL ID',
     testEventCode: 'TEST EVENT CODE',
+    capiEndpoint: '/api/tracking/facebook/',
+    accessToken: import.meta.env.FB_CAPI_TOKEN,
+    framework: 'astro', // or 'express', 'fastify', 'koa'
   },
 }
 ```
 
-Setup
+Browser
 
 ```js
 import FB from '@splendidlabz/tracking/fb/web'
-import config from './shared'
-
-export const fb = FB({
-  ...config.fb,
-  capiEndpoint: '/api/tracking/facebook/',
-})
+import config from './config'
+export const fb = FB(config.fb)
 ```
 
 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,
-})
+import config from './config'
+export const fb = FB(config.fb)
 ```
 
-Ads server for dedupe events
+Include API to dedupe events through CAPI
+
+**Astro:**
 
 ```js
+// /api/tracking/facebook/
 import { fb } from '@/services/tracking/node'
 import { JSONResponse, parseData } from '@splendidlabz/astro/server'
 export const prerender = false
@@ -49,6 +50,143 @@ export async function POST(context) {
 }
 ```
 
-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.
+**Express:**
+
+```js
+// Requires cookie-parser middleware for cookie support
+import express from 'express'
+import cookieParser from 'cookie-parser'
+import { fb } from './services/tracking/node.js'
+
+const app = express()
+app.use(express.json())
+app.use(cookieParser())
+
+app.post('/api/tracking/facebook', async (req, res) => {
+  const { response, error } = await fb.sendEvent(req.body)
+  if (response) return res.status(200).json(response.body)
+  if (error) return res.status(500).json(error)
+})
+```
+
+**Fastify:**
+
+```js
+// Requires @fastify/cookie plugin for cookie support
+import Fastify from 'fastify'
+import fastifyCookie from '@fastify/cookie'
+import { fb } from './services/tracking/node.js'
+
+const fastify = Fastify()
+await fastify.register(fastifyCookie)
+
+fastify.post('/api/tracking/facebook', async (request, reply) => {
+  const { response, error } = await fb.sendEvent(request.body)
+  if (response) return reply.status(200).send(response.body)
+  if (error) return reply.status(500).send(error)
+})
+```
+
+**Koa:**
+
+```js
+// Requires koa-bodyparser and koa-cookie middleware
+import Koa from 'koa'
+import bodyParser from 'koa-bodyparser'
+import cookie from 'koa-cookie'
+import { fb } from './services/tracking/node.js'
+
+const app = new Koa()
+app.use(bodyParser())
+app.use(cookie())
+
+app.use(async (ctx) => {
+  if (ctx.path === '/api/tracking/facebook' && ctx.method === 'POST') {
+    const { response, error } = await fb.sendEvent(ctx.request.body)
+    if (response) {
+      ctx.status = 200
+      ctx.body = response.body
+    }
+    if (error) {
+      ctx.status = 500
+      ctx.body = error
+    }
+  }
+})
+```
+
+## Usage
+
+Browser:
+
+```js
+fb.track('event_name', { ...props })
+```
+
+Node (requires passing the request context):
+
+**Astro:**
+
+```js
+fb.track('event_name', { context, ...props })
+```
+
+**Express:**
+
+```js
+app.post('/some-route', async (req, res) => {
+  await fb.track('event_name', { context: req, ...props })
+  res.json({ success: true })
+})
+```
+
+**Fastify:**
+
+```js
+fastify.post('/some-route', async (request, reply) => {
+  await fb.track('event_name', { context: request, ...props })
+  reply.send({ success: true })
+})
+```
+
+**Koa:**
+
+```js
+app.use(async (ctx) => {
+  if (ctx.path === '/some-route' && ctx.method === 'POST') {
+    await fb.track('event_name', { context: ctx, ...props })
+    ctx.body = { success: true }
+  }
+})
+```
+
+## Event Reference
+
+- [Standard Event Reference](https://developers.facebook.com/docs/meta-pixel/reference#standard-events)
+- [Advanced Matching Reference](https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching/)
+- [Conversion API Params Reference](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters)
+
+## Testing Your Implementation
+
+Go to `Events Manager > Datasets > Test Events` and copy your event tracking code. Add it to your config.
+
+**IMPORTANT**: Remove `testEventCode` after your tests! You don't want this in your production code.
+
+```js
+export default {
+  fb: {
+    pixelID: 'PIXEL ID',
+    testEventCode: 'TEST EVENT CODE',
+    // ...
+  },
+}
+```
+
+Under the same `Test Events` tab, enter a website to test with.
+
+- Note that localhost cannot be used for browser-testing — FB requires a valid domain
+- To test if server & browser events are deduplicated, use a local tunnel like ngrok.
+- Make sure your website — and your tunnel — is listed under your Pixel's allow list under
+  `Dataset > Settings > Allow list`. Feel free to remove the tunnel from the allow list after testing.
+
+- Context is to automatically get Client IP Address and User Agent.

package/lib/fb/web.js

@@ -1,12 +1,11 @@
 import { notEmpty, splitObject } from '@splendidlabz/utils'
 import { getCookie, randomString, sha256Hash } from '@splendidlabz/utils/dom'
+import zlFetch from 'zl-fetch'
 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 }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splendidlabz/tracking",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "Simple Tracking Helper",
   "type": "module",
   "files": [
@@ -20,7 +20,7 @@
   },
   "author": "Zell Liew <zellwk@gmail.com> (https://zellwk.com/)",
   "dependencies": {
-    "@splendidlabz/utils": "1.10.2",
+    "@splendidlabz/utils": "1.10.3",
     "posthog-js": "^1.234.6",
     "posthog-node": "^5.5.1",
     "zl-fetch": "^6.0.6"