feat: added conversion api implementation

Author: mostafakamar2308

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.EventType }> = ({
+  eventName = IAnalytics.EventType.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;

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.EventType.PageView} />
     </body>
   );
 };

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.EventType;
+}) {
+  return api.analytics.trackFacebookEvents({
+    eventName: eventName,
+    eventSourceUrl: window.location.href,
+    fbc: formatFbc(fbclid),
+    customData: {
+      page: page,
+    },
+  });
+}

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,
+    });
+  }
+}

packages/atlas/src/api/index.ts

@@ -22,10 +22,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;
@@ -51,6 +53,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);

packages/types/src/analytics.ts

@@ -0,0 +1,29 @@
+export type ConversionEventPayload = {
+  eventName: EventType;
+  userId?: string;
+  fbc?: string;
+  eventSourceUrl?: string;
+  customData?: Record<string, string | number>;
+};
+
+export type ConversionEvent = {
+  event_name: EventType;
+  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 EventType {
+  PageView = "page-view",
+  Register = "register",
+  Login = "login",
+  Depth = "depth",
+  Engagement = "engagement",
+}

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";

packages/utils/package.json

@@ -117,6 +117,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"

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}`;
+}

services/server/.env.example

@@ -31,3 +31,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>"