feat(dashboard): improve OpenAI Ads signup attribution

Author: izadoesdev

apps/dashboard/.env.example

@@ -19,4 +19,6 @@ RESEND_API_KEY=your_resend_api_key
 NEXT_PUBLIC_API_URL=http://localhost:3001
 # OpenAI Ads browser pixel_id from Ads Manager, not the API data source id.
 NEXT_PUBLIC_OPENAI_ADS_PIXEL_ID=
+# Server-side OpenAI Ads Conversions API key from Ads Manager.
+OPENAI_ADS_CONVERSIONS_API_KEY=
 AUTUMN_SECRET_KEY=your_autumn_secret_key

apps/dashboard/app/(auth)/register/page.tsx

@@ -5,12 +5,12 @@ import Link from "next/link";
 import { parseAsString, useQueryState } from "nuqs";
 import { Suspense, useState } from "react";
 import { toast } from "sonner";
-import { measureOpenAiRegistrationCompleted } from "@/components/openai-ads-pixel";
+import { trackOpenAiRegistrationCompleted } from "@/components/openai-ads-pixel";
 import { GithubMark, GoogleMark } from "@/components/ui/brand-icons";
 import VisuallyHidden from "@/components/ui/visuallyhidden";
 import {
 	APP_EVENTS,
-	readUtmProperties,
+	readMarketingProperties,
 	storePendingSocialSignup,
 	type SignupEventProperties,
 	type SignupMethod,
@@ -60,7 +60,7 @@ function RegisterPageContent() {
 	const getSignupProperties = (
 		method: SignupMethod
 	): SignupEventProperties => ({
-		...readUtmProperties(new URLSearchParams(window.location.search)),
+		...readMarketingProperties(new URLSearchParams(window.location.search)),
 		method,
 		plan: selectedPlan || undefined,
 	});
@@ -110,7 +110,10 @@ function RegisterPageContent() {
 			fetchOptions: {
 				onSuccess: () => {
 					trackSignup(APP_EVENTS.signupCompleted, signupProperties);
-					measureOpenAiRegistrationCompleted();
+					trackOpenAiRegistrationCompleted({
+						email: formData.email,
+						properties: signupProperties,
+					});
 					toast.success(
 						"Account created! Please check your email to verify your account."
 					);

apps/dashboard/app/(main)/onboarding/page.tsx

@@ -2,7 +2,7 @@
 
 import { useRouter } from "next/navigation";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { measureOpenAiRegistrationCompleted } from "@/components/openai-ads-pixel";
+import { trackOpenAiRegistrationCompleted } from "@/components/openai-ads-pixel";
 import { useWebsitesLight } from "@/hooks/use-websites";
 import {
 	APP_EVENTS,
@@ -84,7 +84,7 @@ export default function OnboardingPage() {
 			trackAppEvent(APP_EVENTS.signupCompleted, signupProperties, {
 				flush: true,
 			});
-			measureOpenAiRegistrationCompleted();
+			trackOpenAiRegistrationCompleted({ properties: signupProperties });
 		}
 		trackAppEvent(APP_EVENTS.onboardingStarted);
 	}, []);

apps/dashboard/app/api/openai-ads/conversions/route.ts

@@ -0,0 +1,66 @@
+import { config } from "@databuddy/env/app";
+import { type NextRequest, NextResponse } from "next/server";
+import { z } from "zod";
+import { buildOpenAiRegistrationCompletedEvent } from "@/lib/openai-ads-conversions";
+
+const ConversionRequestSchema = z.object({
+	email: z.string().email().max(320).optional(),
+	eventId: z.string().min(1).max(160),
+	oppref: z.string().min(1).max(512).optional(),
+	sourceUrl: z.string().url().max(2048),
+});
+
+function readClientIp(headers: Headers): string | undefined {
+	const forwardedFor = headers.get("x-forwarded-for")?.split(",")[0]?.trim();
+	return forwardedFor || headers.get("x-real-ip")?.trim() || undefined;
+}
+
+async function readJson(request: NextRequest): Promise<unknown> {
+	try {
+		return await request.json();
+	} catch {
+		return null;
+	}
+}
+
+export async function POST(request: NextRequest) {
+	const pixelId = config.integrations.openAiAdsPixelId;
+	const apiKey = config.integrations.openAiAdsConversionsApiKey;
+
+	if (!(pixelId && apiKey)) {
+		return NextResponse.json({ skipped: true });
+	}
+
+	const parsed = ConversionRequestSchema.safeParse(await readJson(request));
+	if (!parsed.success) {
+		return NextResponse.json(
+			{ error: "Invalid conversion payload" },
+			{ status: 400 }
+		);
+	}
+
+	const event = buildOpenAiRegistrationCompletedEvent({
+		...parsed.data,
+		ipAddress: readClientIp(request.headers),
+		timestampMs: Date.now(),
+		userAgent: request.headers.get("user-agent") ?? undefined,
+	});
+
+	const response = await fetch(
+		`https://bzr.openai.com/v1/events?pid=${encodeURIComponent(pixelId)}`,
+		{
+			body: JSON.stringify({ events: [event], validate_only: false }),
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+			},
+			method: "POST",
+		}
+	);
+
+	if (!response.ok) {
+		return NextResponse.json({ ok: false }, { status: 502 });
+	}
+
+	return NextResponse.json({ ok: true });
+}

apps/dashboard/components/openai-ads-pixel.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "bun:test";
-import { isOpenAiAdsPixelHostAllowed } from "./openai-ads-pixel";
+import {
+	buildOpenAiRegistrationConversionPayload,
+	buildOpenAiRegistrationMeasureArgs,
+	isOpenAiAdsPixelHostAllowed,
+} from "./openai-ads-pixel";
 
 describe("isOpenAiAdsPixelHostAllowed", () => {
 	it("blocks local development hosts", () => {
@@ -14,4 +18,33 @@ describe("isOpenAiAdsPixelHostAllowed", () => {
 		expect(isOpenAiAdsPixelHostAllowed("app.databuddy.cc")).toBe(true);
 		expect(isOpenAiAdsPixelHostAllowed("staging.databuddy.cc")).toBe(true);
 	});
+
+	it("builds a registration payload with the OpenAI reference", () => {
+		expect(
+			buildOpenAiRegistrationConversionPayload({
+				email: "founder@example.com",
+				eventId: "conversion-1",
+				properties: {
+					method: "email",
+					oppref: "openai-reference",
+					utm_source: "openai_ads",
+				},
+				sourceUrl: "https://app.databuddy.cc/register?utm_source=openai_ads",
+			})
+		).toEqual({
+			email: "founder@example.com",
+			eventId: "conversion-1",
+			oppref: "openai-reference",
+			sourceUrl: "https://app.databuddy.cc/register?utm_source=openai_ads",
+		});
+	});
+
+	it("passes event_id as the pixel options argument for dedupe", () => {
+		expect(buildOpenAiRegistrationMeasureArgs("conversion-1")).toEqual([
+			"measure",
+			"registration_completed",
+			{ type: "customer_action" },
+			{ event_id: "conversion-1" },
+		]);
+	});
 });

apps/dashboard/components/openai-ads-pixel.tsx

@@ -2,10 +2,25 @@
 
 import { useEffect } from "react";
 import { publicConfig } from "@databuddy/env/public";
+import type { SignupEventProperties } from "@databuddy/shared/custom-events";
 
 const PIXEL_ID = publicConfig.integrations.openAiAdsPixelId;
 const SCRIPT_SRC = "https://bzrcdn.openai.com/sdk/oaiq.min.js";
 
+interface RegistrationConversionInput {
+	email?: string;
+	eventId?: string;
+	properties?: SignupEventProperties;
+	sourceUrl?: string;
+}
+
+interface RegistrationConversionPayload {
+	email?: string;
+	eventId: string;
+	oppref?: string;
+	sourceUrl: string;
+}
+
 type OpenAiAdsQueue = ((...args: unknown[]) => void) & {
 	q?: unknown[][];
 };
@@ -60,6 +75,38 @@ function initOpenAiQueue(): boolean {
 	return true;
 }
 
+function createRegistrationEventId(): string {
+	if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+		return crypto.randomUUID();
+	}
+
+	return `registration_completed_${Date.now()}_${Math.random()
+		.toString(36)
+		.slice(2)}`;
+}
+
+export function buildOpenAiRegistrationConversionPayload(
+	input: RegistrationConversionInput
+): RegistrationConversionPayload {
+	return {
+		...(input.email ? { email: input.email } : {}),
+		eventId: input.eventId ?? createRegistrationEventId(),
+		...(input.properties?.oppref ? { oppref: input.properties.oppref } : {}),
+		sourceUrl: input.sourceUrl ?? window.location.href,
+	};
+}
+
+export function buildOpenAiRegistrationMeasureArgs(
+	eventId?: string
+): unknown[] {
+	return [
+		"measure",
+		"registration_completed",
+		{ type: "customer_action" },
+		...(eventId ? [{ event_id: eventId }] : []),
+	];
+}
+
 export function OpenAiAdsPixel() {
 	useEffect(() => {
 		initOpenAiQueue();
@@ -68,12 +115,39 @@ export function OpenAiAdsPixel() {
 	return null;
 }
 
-export function measureOpenAiRegistrationCompleted() {
+export function measureOpenAiRegistrationCompleted(eventId?: string) {
 	if (!initOpenAiQueue()) {
 		return;
 	}
 
-	window.oaiq?.("measure", "registration_completed", {
-		type: "customer_action",
+	window.oaiq?.(...buildOpenAiRegistrationMeasureArgs(eventId));
+}
+
+export function sendOpenAiRegistrationCompletedConversion(
+	payload: RegistrationConversionPayload
+) {
+	if (
+		typeof window === "undefined" ||
+		!PIXEL_ID ||
+		!isOpenAiAdsPixelHostAllowed(window.location.hostname)
+	) {
+		return;
+	}
+
+	fetch("/api/openai-ads/conversions", {
+		body: JSON.stringify(payload),
+		headers: { "Content-Type": "application/json" },
+		keepalive: true,
+		method: "POST",
+	}).catch(() => {
+		// Signup should not depend on ad-platform reporting.
 	});
 }
+
+export function trackOpenAiRegistrationCompleted(
+	input: RegistrationConversionInput = {}
+) {
+	const payload = buildOpenAiRegistrationConversionPayload(input);
+	measureOpenAiRegistrationCompleted(payload.eventId);
+	sendOpenAiRegistrationCompletedConversion(payload);
+}

apps/dashboard/lib/app-events.test.ts

@@ -1,6 +1,36 @@
-import { describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it } from "bun:test";
 import { SIGNUP_METHODS } from "@databuddy/shared/custom-events";
-import { isSocialSignupMethod } from "./app-events";
+import {
+	consumePendingSocialSignup,
+	isSocialSignupMethod,
+	storePendingSocialSignup,
+} from "./app-events";
+
+const originalSessionStorage = globalThis.sessionStorage;
+
+function installSessionStorageMock() {
+	const storage = new Map<string, string>();
+
+	Object.defineProperty(globalThis, "sessionStorage", {
+		configurable: true,
+		value: {
+			getItem: (key: string) => storage.get(key) ?? null,
+			removeItem: (key: string) => {
+				storage.delete(key);
+			},
+			setItem: (key: string, value: string) => {
+				storage.set(key, value);
+			},
+		},
+	});
+}
+
+afterEach(() => {
+	Object.defineProperty(globalThis, "sessionStorage", {
+		configurable: true,
+		value: originalSessionStorage,
+	});
+});
 
 describe("isSocialSignupMethod", () => {
 	it("derives social methods from the shared signup method list", () => {
@@ -9,4 +39,29 @@ describe("isSocialSignupMethod", () => {
 			"social_google",
 		]);
 	});
+
+	it("preserves marketing attribution through pending social signup storage", () => {
+		installSessionStorageMock();
+
+		storePendingSocialSignup({
+			method: "social_google",
+			oppref: "openai-reference",
+			utm_campaign: "competitors",
+			utm_content: "ask_why_signups_dropped",
+			utm_medium: "paid",
+			utm_source: "openai_ads",
+			wolref: "web-origin-reference",
+		});
+
+		expect(consumePendingSocialSignup()).toEqual({
+			method: "social_google",
+			oppref: "openai-reference",
+			utm_campaign: "competitors",
+			utm_content: "ask_why_signups_dropped",
+			utm_medium: "paid",
+			utm_source: "openai_ads",
+			wolref: "web-origin-reference",
+		});
+		expect(consumePendingSocialSignup()).toBeNull();
+	});
 });

apps/dashboard/lib/app-events.ts

@@ -10,12 +10,16 @@ import type {
 	SignupMethod,
 } from "@databuddy/shared/custom-events";
 import {
+	MARKETING_PARAM_KEYS,
 	SIGNUP_METHODS,
-	UTM_PARAM_KEYS,
 	isSignupMethod,
 } from "@databuddy/shared/custom-events";
 
-export { APP_EVENTS, readUtmProperties } from "@databuddy/shared/custom-events";
+export {
+	APP_EVENTS,
+	readMarketingProperties,
+	readUtmProperties,
+} from "@databuddy/shared/custom-events";
 export type {
 	SignupEventProperties,
 	SignupMethod,
@@ -94,7 +98,7 @@ function readStoredSignupProperties(
 		properties.plan = plan;
 	}
 
-	for (const key of UTM_PARAM_KEYS) {
+	for (const key of MARKETING_PARAM_KEYS) {
 		const param = trimStoredString(source[key]);
 		if (param) {
 			properties[key] = param;