From 6588d13dd919f65b16338fea37e28af9635b5a9f Mon Sep 17 00:00:00 2001
From: Mostafa Kamar <moustafa.31011197@med.tanta.edu.eg>
Date: Tue, 10 Jun 2025 03:41:44 +0300
Subject: [PATCH] feat: added conversion api implementation

---
 .../components/Analytics/Conversion.tsx       | 28 ++++++++++
 apps/landing/components/Layout/Layout.tsx     |  3 +
 apps/landing/lib/analytics.ts                 | 22 ++++++++
 packages/atlas/src/api/analytics.ts           | 13 +++++
 packages/atlas/src/api/index.ts               |  3 +
 packages/types/src/analytics.ts               | 29 ++++++++++
 packages/types/src/index.ts                   |  1 +
 packages/utils/package.json                   |  4 ++
 packages/utils/src/analytics.ts               | 17 ++++++
 services/server/.env.example                  |  3 +
 services/server/.env.test                     |  3 +
 services/server/.env.test.ci                  |  5 +-
 services/server/src/constants.ts              |  5 ++
 services/server/src/handlers/analytics.ts     | 55 +++++++++++++++++++
 services/server/src/index.ts                  |  1 +
 services/server/src/routes/analytics.ts       |  8 +++
 services/server/src/routes/index.ts           |  2 +
 17 files changed, 201 insertions(+), 1 deletion(-)
 create mode 100644 apps/landing/components/Analytics/Conversion.tsx
 create mode 100644 apps/landing/lib/analytics.ts
 create mode 100644 packages/atlas/src/api/analytics.ts
 create mode 100644 packages/types/src/analytics.ts
 create mode 100644 packages/utils/src/analytics.ts
 create mode 100644 services/server/src/handlers/analytics.ts
 create mode 100644 services/server/src/routes/analytics.ts

diff --git a/apps/landing/components/Analytics/Conversion.tsx b/apps/landing/components/Analytics/Conversion.tsx
new file mode 100644
index 000000000..2bd9d0230
--- /dev/null
+++ b/apps/landing/components/Analytics/Conversion.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import { sendFacebookEvent } from "@/lib/analytics";
+import { IAnalytics } from "@litespace/types";
+import { usePathname, useSearchParams } from "next/navigation";
+import { useEffect } from "react";
+
+const Conversion: React.FC<{ eventName?: IAnalytics.EventName }> = ({
+  eventName = IAnalytics.EventName.PageView,
+}) => {
+  const searchParams = useSearchParams();
+  const path = usePathname();
+
+  useEffect(() => {
+    const fbclid = searchParams.get("fbclid");
+    if (!fbclid) return;
+
+    sendFacebookEvent({
+      page: path,
+      eventName,
+      fbclid,
+    });
+  }, [path, eventName, searchParams]);
+
+  return null;
+};
+
+export default Conversion;
diff --git a/apps/landing/components/Layout/Layout.tsx b/apps/landing/components/Layout/Layout.tsx
index 0109cbf1e..599c4a764 100644
--- a/apps/landing/components/Layout/Layout.tsx
+++ b/apps/landing/components/Layout/Layout.tsx
@@ -5,8 +5,10 @@ import cn from "classnames";
 import Navbar from "@/components/Layout/Navbar";
 import Sidebar from "@/components/Layout/Sidebar";
 import Footer from "@/components/Layout/Footer";
+import Conversion from "@/components/Analytics/Conversion";
 import clarity, { getCustomeId, sessionId } from "@/lib/clarity";
 import { usePathname } from "next/navigation";
+import { IAnalytics } from "@litespace/types";
 
 const Layout: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const [showSidebar, setShowSidebar] = useState(false);
@@ -27,6 +29,7 @@ const Layout: React.FC<{ children: React.ReactNode }> = ({ children }) => {
       {showSidebar ? <Sidebar hide={() => setShowSidebar(false)} /> : null}
       {children}
       <Footer />
+      <Conversion eventName={IAnalytics.EventName.PageView} />
     </body>
   );
 };
diff --git a/apps/landing/lib/analytics.ts b/apps/landing/lib/analytics.ts
new file mode 100644
index 000000000..31c6de57d
--- /dev/null
+++ b/apps/landing/lib/analytics.ts
@@ -0,0 +1,22 @@
+import { formatFbc } from "@litespace/utils/analytics";
+import { api } from "@/lib/api";
+import { IAnalytics } from "@litespace/types";
+
+export function sendFacebookEvent({
+  page,
+  eventName,
+  fbclid,
+}: {
+  page: string;
+  fbclid?: string | null;
+  eventName: IAnalytics.EventName;
+}) {
+  return api.analytics.trackFacebookEvents({
+    eventName: eventName,
+    eventSourceUrl: window.location.href,
+    fbc: formatFbc(fbclid),
+    customData: {
+      page: page,
+    },
+  });
+}
diff --git a/packages/atlas/src/api/analytics.ts b/packages/atlas/src/api/analytics.ts
new file mode 100644
index 000000000..7371eccb7
--- /dev/null
+++ b/packages/atlas/src/api/analytics.ts
@@ -0,0 +1,13 @@
+import { Base } from "@/lib/base";
+import { IAnalytics } from "@litespace/types";
+
+export class Analytics extends Base {
+  async trackFacebookEvents(
+    payload: IAnalytics.ConversionEventPayload
+  ): Promise<void> {
+    return this.post({
+      route: "/api/v1/analytics/fb/track",
+      payload,
+    });
+  }
+}
diff --git a/packages/atlas/src/api/index.ts b/packages/atlas/src/api/index.ts
index 0414ac668..0f6e8bb41 100644
--- a/packages/atlas/src/api/index.ts
+++ b/packages/atlas/src/api/index.ts
@@ -21,10 +21,12 @@ import { Fawry } from "@/api/fawry";
 import { ConfirmationCode } from "@/api/confirmationCode";
 import { Subscription } from "@/api/subscription";
 import { Transaction } from "@/api/transaction";
+import { Analytics } from "@/api/analytics";
 
 export class Api {
   public readonly user: User;
   public readonly auth: Auth;
+  public readonly analytics: Analytics;
   public readonly availabilitySlot: AvailabilitySlot;
   public readonly contactRequest: ContactRequest;
   public readonly plan: Plan;
@@ -49,6 +51,7 @@ export class Api {
     const client = createClient("api", server, token);
     this.user = new User(client);
     this.auth = new Auth(client);
+    this.analytics = new Analytics(client);
     this.availabilitySlot = new AvailabilitySlot(client);
     this.contactRequest = new ContactRequest(client);
     this.plan = new Plan(client);
diff --git a/packages/types/src/analytics.ts b/packages/types/src/analytics.ts
new file mode 100644
index 000000000..7ea3e49a7
--- /dev/null
+++ b/packages/types/src/analytics.ts
@@ -0,0 +1,29 @@
+export type ConversionEventPayload = {
+  eventName: EventName;
+  userId?: string;
+  fbc?: string;
+  eventSourceUrl?: string;
+  customData?: Record<string, string | number>;
+};
+
+export type ConversionEvent = {
+  event_name: EventName;
+  event_time: number;
+  event_source_url?: string;
+  custom_data?: Record<string, string | number>;
+  action_source: "website";
+  user_id?: string;
+  user_data: {
+    client_user_agent: string;
+    client_ip_address?: string;
+    fbc?: string;
+  };
+};
+
+export enum EventName {
+  PageView = "page-view",
+  Register = "register",
+  Login = "login",
+  Depth = "depth",
+  Engagement = "engagement",
+}
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index a09fd3ed0..c0a11cf6f 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -1,3 +1,4 @@
+export * as IAnalytics from "@/analytics";
 export * as IContactRequest from "@/contactRequest";
 export * as IConfirmationCode from "@/confirmationCode";
 export * as ISessionEvent from "@/sessionEvent";
diff --git a/packages/utils/package.json b/packages/utils/package.json
index 28e50030b..54c5d9857 100644
--- a/packages/utils/package.json
+++ b/packages/utils/package.json
@@ -118,6 +118,10 @@
       "import": "./dist/esm/plan.js",
       "require": "./dist/cjs/plan.js"
     },
+    "./analytics": {
+      "import": "./dist/esm/analytics.js",
+      "require": "./dist/cjs/analytics.js"
+    },
     "./filterQuery": {
       "import": "./dist/esm/filterQuery/index.js",
       "require": "./dist/cjs/filterQuery/index.js"
diff --git a/packages/utils/src/analytics.ts b/packages/utils/src/analytics.ts
new file mode 100644
index 000000000..1e5fa721c
--- /dev/null
+++ b/packages/utils/src/analytics.ts
@@ -0,0 +1,17 @@
+import { dayjs } from "@/dayjs";
+
+/**
+ * see docs for fbc: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/fbp-and-fbc
+ * @param fbclid parameter that is passed with the URL of an advertiser's website when a user
+ * clicks an ad on Facebook and/or Instagram. You get that from url search params
+ * @returns fbc which is a unique id for each user
+ */
+export function formatFbc(fbclid?: string | null) {
+  if (!fbclid) return undefined;
+
+  const host = window.location.hostname;
+  const hostIndex = host.startsWith("www.") ? 2 : 1;
+  const now = dayjs().valueOf();
+
+  return `fb.${hostIndex}.${now}.${fbclid}`;
+}
diff --git a/services/server/.env.example b/services/server/.env.example
index f6b2dff02..c83869107 100644
--- a/services/server/.env.example
+++ b/services/server/.env.example
@@ -29,3 +29,6 @@ MESSENGER_PASSWORD='litespace'
 
 LIVEKIT_API_KEY=devkey
 LIVEKIT_API_SECRET=secret
+
+CONVERSION_API_URL="https://graph.facebook.com/v22.0/1149846573218428/events"
+CONVERSION_API_ACCESS_TOKEN="<token>"
\ No newline at end of file
diff --git a/services/server/.env.test b/services/server/.env.test
index e3b30b800..d391accd2 100644
--- a/services/server/.env.test
+++ b/services/server/.env.test
@@ -29,3 +29,6 @@ MESSENGER_PASSWORD='litespace'
 
 LIVEKIT_API_KEY=devkey
 LIVEKIT_API_SECRET=secret
+
+CONVERSION_API_URL="https://graph.facebook.com/v22.0/1149846573218428/events"
+CONVERSION_API_ACCESS_TOKEN="<token>"
diff --git a/services/server/.env.test.ci b/services/server/.env.test.ci
index 0acc7a640..8e4e8a3bf 100644
--- a/services/server/.env.test.ci
+++ b/services/server/.env.test.ci
@@ -30,4 +30,7 @@ MESSENGER_USERNAME='litespace'
 MESSENGER_PASSWORD='litespace'
 
 LIVEKIT_API_KEY=devkey
-LIVEKIT_API_SECRET=secret
\ No newline at end of file
+LIVEKIT_API_SECRET=secret
+
+CONVERSION_API_URL="https://graph.facebook.com/v22.0/1149846573218428/events"
+CONVERSION_API_ACCESS_TOKEN="<token>"
\ No newline at end of file
diff --git a/services/server/src/constants.ts b/services/server/src/constants.ts
index 967f6e366..f3040a7c9 100644
--- a/services/server/src/constants.ts
+++ b/services/server/src/constants.ts
@@ -169,3 +169,8 @@ export const INTRO_VIDEO_EXPIRY_MONTHS = 3;
  * max size in megabytes
  */
 export const INTRO_VIDEO_MAX_FILE_SIZE = 400;
+
+export const conversionApiConfig = {
+  apiUrl: zod.string().url().trim().parse(process.env.CONVERSION_API_URL),
+  token: zod.string().trim().parse(process.env.CONVERSION_API_ACCESS_TOKEN),
+};
diff --git a/services/server/src/handlers/analytics.ts b/services/server/src/handlers/analytics.ts
new file mode 100644
index 000000000..9360db485
--- /dev/null
+++ b/services/server/src/handlers/analytics.ts
@@ -0,0 +1,55 @@
+import safeRequest from "express-async-handler";
+import { IAnalytics } from "@litespace/types";
+import { Request, Response } from "express";
+import zod from "zod";
+import dayjs from "@/lib/dayjs";
+import axios from "axios";
+import { conversionApiConfig } from "@/constants";
+
+// Pixel Docs:
+// https://developers.facebook.com/docs/marketing-api/conversions-api/using-the-api/
+// Parameters:
+// https://developers.facebook.com/docs/marketing-api/conversions-api/parameters
+
+const trackConversionEventPayload = zod.object({
+  eventName: zod.nativeEnum(IAnalytics.EventName),
+  userId: zod.string().optional(),
+  fbc: zod.string().optional(),
+  eventSourceUrl: zod.string().optional(),
+  customData: zod.object({}).optional(),
+});
+
+async function trackFacebookEvents(req: Request, res: Response) {
+  const body = trackConversionEventPayload.parse(req.body);
+  const ip = req.ip || req.socket.remoteAddress || "Unknown IP";
+
+  const event: IAnalytics.ConversionEvent = {
+    event_name: body.eventName,
+    user_data: {
+      client_user_agent: req.headers["user-agent"] || "Unknown",
+      client_ip_address: ip,
+      fbc: body.fbc,
+    },
+    event_time: dayjs.utc().unix(),
+    event_source_url: body.eventSourceUrl,
+    custom_data: body.customData,
+    action_source: "website",
+  };
+
+  await axios.post(
+    conversionApiConfig.apiUrl,
+    { data: [event] },
+    {
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${conversionApiConfig.token}`,
+      },
+    }
+  );
+
+  res.sendStatus(200);
+}
+
+export default {
+  trackFacebookEvents: safeRequest(trackFacebookEvents),
+};
diff --git a/services/server/src/index.ts b/services/server/src/index.ts
index cf9e599a3..a7f2a2efe 100644
--- a/services/server/src/index.ts
+++ b/services/server/src/index.ts
@@ -72,6 +72,7 @@ app.use(cors({ credentials: true, origin: isAllowedOrigin }));
 app.use(json());
 app.use(bodyParser.urlencoded({ extended: true }));
 app.use(authMiddleware({ jwtSecret }));
+app.use("/api/v1/analytics", routes.analytics);
 app.use("/api/v1/auth", routes.auth);
 app.use("/api/v1/contact-request", routes.contactRequest);
 app.use("/api/v1/user", routes.user(context));
diff --git a/services/server/src/routes/analytics.ts b/services/server/src/routes/analytics.ts
new file mode 100644
index 000000000..84100e62d
--- /dev/null
+++ b/services/server/src/routes/analytics.ts
@@ -0,0 +1,8 @@
+import { Router } from "express";
+import analytics from "@/handlers/analytics";
+
+const router = Router();
+
+router.post("/fb/track", analytics.trackFacebookEvents);
+
+export default router;
diff --git a/services/server/src/routes/index.ts b/services/server/src/routes/index.ts
index 53ad22170..acbf3f259 100644
--- a/services/server/src/routes/index.ts
+++ b/services/server/src/routes/index.ts
@@ -21,6 +21,7 @@ import confirmationCode from "@/routes/confirmationCode";
 import report from "@/routes/report";
 import demoSession from "@/routes/demoSession";
 import introVideo from "@/routes/introVideo";
+import analytics from "@/routes/analytics";
 
 export default {
   user,
@@ -42,6 +43,7 @@ export default {
   fawry,
   transaction,
   subscription,
+  analytics,
   confirmationCode,
   report,
   demoSession,