Iurii Tracks: GA4 Server-Side Tracking + Meta CAPI in Next.js

// lib/analytics/ga4.ts
import { cookies } from "next/headers";
 
interface GA4Identifiers {
  clientId: string | null;
  sessionId: string | null;
}
 
export async function getGA4Identifiers(measurementId: string): Promise<GA4Identifiers> {
  const cookieStore = await cookies();
 
  // _ga cookie format: GA1.1.1234567890.1234567890
  // The client_id is everything after "GA1.1."
  const gaCookie = cookieStore.get("_ga")?.value;
  const clientId = gaCookie ? gaCookie.split(".").slice(2).join(".") : null;
 
  // Session cookie format: GS1.1.1234567890.1.1.1234567890.60.0.0
  // The session_id is the third segment
  const sessionCookieName = `_ga_${measurementId.replace("G-", "")}`;
  const sessionCookie = cookieStore.get(sessionCookieName)?.value;
  const sessionId = sessionCookie ? sessionCookie.split(".")[2] : null;
 
  return { clientId, sessionId };
}

// lib/analytics/ga4.ts (continued)
 
interface GA4PurchaseParams {
  transactionId: string;
  value: number; // In actual currency units (not cents)
  currency: string; // ISO 4217: "EUR", "USD"
  items: GA4Item[];
  coupon?: string;
}
 
interface GA4Item {
  itemId: string;
  itemName: string;
  price: number;
  quantity: number;
}
 
interface GA4EventPayload {
  clientId: string;
  sessionId?: string;
  events: GA4Event[];
}
 
interface GA4Event {
  name: string;
  params: Record<string, unknown>;
}
 
const GA4_API_ENDPOINT = "https://www.google-analytics.com/mp/collect";
 
export async function sendGA4PurchaseEvent(
  identifiers: GA4Identifiers,
  purchase: GA4PurchaseParams
): Promise<void> {
  if (!identifiers.clientId) {
    // No client_id means we can't attribute this to a session.
    // Log it, but don't throw — tracking failure should never block checkout.
    console.warn("[GA4] Missing client_id, skipping server-side event");
    return;
  }
 
  const payload: GA4EventPayload = {
    clientId: identifiers.clientId,
    // session_id ties the event to the right session in GA4 reporting
    ...(identifiers.sessionId && {
      events: [], // placeholder — replaced below
    }),
    events: [
      {
        name: "purchase",
        params: {
          // session_id must be inside the event params, not at the top level
          ...(identifiers.sessionId && { session_id: identifiers.sessionId }),
          transaction_id: purchase.transactionId,
          value: purchase.value,
          currency: purchase.currency,
          coupon: purchase.coupon,
          items: purchase.items.map((item) => ({
            item_id: item.itemId,
            item_name: item.itemName,
            price: item.price,
            quantity: item.quantity,
          })),
        },
      },
    ],
  };
 
  const url = new URL(GA4_API_ENDPOINT);
  url.searchParams.set("measurement_id", process.env.NEXT_PUBLIC_GA4_MEASUREMENT_ID!);
  url.searchParams.set("api_secret", process.env.GA4_API_SECRET!);
 
  const response = await fetch(url.toString(), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
 
  if (!response.ok) {
    // GA4 Measurement Protocol returns 204 on success, errors are rare
    // but worth logging for debugging
    console.error(`[GA4] Measurement Protocol error: ${response.status}`);
  }
}

// lib/analytics/meta-capi.ts
import crypto from "crypto";
 
// Normalize and hash a PII value per Meta's requirements
function hashPII(value: string): string {
  return crypto.createHash("sha256").update(value.toLowerCase().trim()).digest("hex");
}
 
// Phone: strip all non-digit characters, include country code
function hashPhone(phone: string): string {
  const normalized = phone.replace(/\D/g, "");
  return crypto.createHash("sha256").update(normalized).digest("hex");
}

// lib/analytics/meta-capi.ts (continued)
 
interface MetaUserData {
  email?: string;
  phone?: string;
  firstName?: string;
  lastName?: string;
  city?: string;
  countryCode?: string; // ISO 3166-1 alpha-2 lowercase: "fi", "de"
  postalCode?: string;
  clientIpAddress?: string; // From request headers
  clientUserAgent?: string; // From request headers
  fbp?: string; // _fbp cookie value
  fbc?: string; // _fbc cookie value (click ID)
}
 
interface MetaPurchaseEvent {
  eventId: string; // Used for deduplication — must match client-side pixel
  eventSourceUrl: string; // The URL where the purchase happened
  userData: MetaUserData;
  value: number; // In actual currency units
  currency: string; // ISO 4217 uppercase: "EUR"
  orderId: string;
}
 
const META_CAPI_ENDPOINT = "https://graph.facebook.com/v20.0";
 
export async function sendMetaPurchaseEvent(event: MetaPurchaseEvent): Promise<void> {
  const { userData } = event;
 
  // Build user_data object — only include fields we have
  const hashedUserData: Record<string, string | undefined> = {
    ...(userData.email && { em: hashPII(userData.email) }),
    ...(userData.phone && { ph: hashPhone(userData.phone) }),
    ...(userData.firstName && { fn: hashPII(userData.firstName) }),
    ...(userData.lastName && { ln: hashPII(userData.lastName) }),
    ...(userData.city && { ct: hashPII(userData.city) }),
    ...(userData.countryCode && { country: hashPII(userData.countryCode.toLowerCase()) }),
    ...(userData.postalCode && { zp: hashPII(userData.postalCode) }),
    // IP and user agent are NOT hashed — Meta uses them as-is
    ...(userData.clientIpAddress && { client_ip_address: userData.clientIpAddress }),
    ...(userData.clientUserAgent && { client_user_agent: userData.clientUserAgent }),
    // Cookie values — not hashed
    ...(userData.fbp && { fbp: userData.fbp }),
    ...(userData.fbc && { fbc: userData.fbc }),
  };
 
  const payload = {
    data: [
      {
        event_name: "Purchase",
        // Unix timestamp in seconds
        event_time: Math.floor(Date.now() / 1000),
        // The URL where the conversion happened
        event_source_url: event.eventSourceUrl,
        // action_source tells Meta this came from a server, not a browser
        action_source: "website",
        // event_id is critical for deduplication — see next section
        event_id: event.eventId,
        user_data: hashedUserData,
        custom_data: {
          value: event.value,
          currency: event.currency,
          order_id: event.orderId,
        },
      },
    ],
    // test_event_code: "TEST12345", // Uncomment during development
  };
 
  const pixelId = process.env.META_PIXEL_ID!;
  const accessToken = process.env.META_CAPI_ACCESS_TOKEN!;
 
  const response = await fetch(
    `${META_CAPI_ENDPOINT}/${pixelId}/events?access_token=${accessToken}`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    }
  );
 
  if (!response.ok) {
    const error = await response.json();
    console.error("[Meta CAPI] Error:", JSON.stringify(error));
  }
}

// lib/analytics/meta-capi.ts (continued)
 
import { cookies, headers } from "next/headers";
 
export async function getMetaIdentifiers(): Promise<
  Pick<MetaUserData, "fbp" | "fbc" | "clientIpAddress" | "clientUserAgent">
> {
  const cookieStore = await cookies();
  const headersList = await headers();
 
  return {
    fbp: cookieStore.get("_fbp")?.value,
    fbc: cookieStore.get("_fbc")?.value,
    // X-Forwarded-For contains the real client IP when behind a proxy/CDN
    clientIpAddress:
      headersList.get("x-forwarded-for")?.split(",")[0].trim() ??
      headersList.get("x-real-ip") ??
      undefined,
    clientUserAgent: headersList.get("user-agent") ?? undefined,
  };
}

// lib/analytics/event-id.ts
import { randomUUID } from "crypto";
 
// Generate at checkout initiation, store in session storage client-side
// and in your order/payment record server-side
export function generateEventId(): string {
  return randomUUID();
}

// app/checkout/success/page.tsx — Client Component
"use client";
 
import { useEffect } from "react";
 
interface SuccessPageProps {
  eventId: string; // Passed from the Server Component via props
  orderId: string;
  value: number;
  currency: string;
}
 
export function TrackPurchaseClient({ eventId, orderId, value, currency }: SuccessPageProps) {
  useEffect(() => {
    // Facebook Pixel — eventID parameter enables deduplication with CAPI
    if (typeof window !== "undefined" && window.fbq) {
      window.fbq(
        "track",
        "Purchase",
        {
          value,
          currency,
          order_id: orderId,
        },
        {
          eventID: eventId, // Must match what you send to CAPI
        }
      );
    }
 
    // GA4 — use the same transaction_id for deduplication
    if (typeof window !== "undefined" && window.gtag) {
      window.gtag("event", "purchase", {
        transaction_id: orderId, // GA4 deduplicates on transaction_id
        value,
        currency,
      });
    }
  }, [eventId, orderId, value, currency]);
 
  return null;
}

// lib/analytics/track-purchase.ts
import { sendGA4PurchaseEvent, getGA4Identifiers } from "./ga4";
import { sendMetaPurchaseEvent, getMetaIdentifiers } from "./meta-capi";
 
interface PurchaseTrackingParams {
  orderId: string;
  transactionId: string; // Stripe PaymentIntent ID
  eventId: string; // The shared event ID for deduplication
  value: number; // In actual currency units (not cents)
  currency: string;
  items: Array<{ id: string; name: string; price: number; quantity: number }>;
  customer: {
    email: string;
    firstName?: string;
    lastName?: string;
    city?: string;
    countryCode?: string;
    postalCode?: string;
  };
  eventSourceUrl: string; // e.g., "https://pikkuna.fi/checkout/success"
}
 
export async function trackServerSidePurchase(params: PurchaseTrackingParams): Promise<void> {
  const ga4Identifiers = getGA4Identifiers(process.env.NEXT_PUBLIC_GA4_MEASUREMENT_ID!);
  const metaIdentifiers = getMetaIdentifiers();
 
  // Fire both in parallel — neither should block the other
  await Promise.allSettled([
    sendGA4PurchaseEvent(ga4Identifiers, {
      transactionId: params.transactionId,
      value: params.value,
      currency: params.currency,
      items: params.items.map((item) => ({
        itemId: item.id,
        itemName: item.name,
        price: item.price,
        quantity: item.quantity,
      })),
    }),
    sendMetaPurchaseEvent({
      eventId: params.eventId,
      eventSourceUrl: params.eventSourceUrl,
      value: params.value,
      currency: params.currency,
      orderId: params.orderId,
      userData: {
        email: params.customer.email,
        firstName: params.customer.firstName,
        lastName: params.customer.lastName,
        city: params.customer.city,
        countryCode: params.customer.countryCode,
        postalCode: params.customer.postalCode,
        ...metaIdentifiers,
      },
    }),
  ]);
 
  // Promise.allSettled means tracking errors never throw —
  // a failed GA4 call will not roll back your order
}

// workers/order-processor.ts (excerpt)
import { trackServerSidePurchase } from "@/lib/analytics/track-purchase";
 
// Inside your BullMQ worker handler:
const order = await fetchOrderDetails(paymentIntentId);
 
// Create the order, run the pipeline steps...
const { invoiceNumber, trackingNumber } = await processOrder(order);
 
// Fire analytics — after the order is committed, never blocking it
await trackServerSidePurchase({
  orderId: order.id,
  transactionId: order.stripePaymentIntentId,
  eventId: order.analyticsEventId, // Generated at checkout, stored on order
  value: order.totalAmount / 100,
  currency: order.currency.toUpperCase(),
  items: order.lineItems,
  customer: {
    email: order.customerEmail,
    firstName: order.customerFirstName,
    lastName: order.customerLastName,
    city: order.shippingAddress.city,
    countryCode: order.shippingAddress.country.toLowerCase(),
    postalCode: order.shippingAddress.postalCode,
  },
  eventSourceUrl: `https://pikkuna.fi/checkout/success`,
});