Merge pull request #38 from NillionNetwork/feat/utm

feat: utm tracking for signups

Author: psofiterol

src/app/api/createUser/route.ts

@@ -49,10 +49,23 @@ export async function POST(request: NextRequest) {
     }
 
     const creationTime = new Date().toISOString();
+
+    // Get UTM parameters from request body if provided
+    let utmData: USER_SCHEMA["utm"];
+    try {
+      const body = await request.json();
+      if (body.utm && Object.keys(body.utm).length > 0) {
+        utmData = body.utm;
+      }
+    } catch (_error) {
+      // If no body or invalid JSON, continue without UTM data
+    }
+
     const userData: USER_SCHEMA = {
       _id: recordId,
       provider: auth.authProvider,
       created_at: creationTime,
+      ...(utmData && { utm: utmData }),
     };
 
     await writeRecord(builder, process.env.USER_COLLECTION_ID, userData);

src/app/app/layout.tsx

@@ -8,6 +8,7 @@ import SidebarIcon from "@/components/chat/SidebarIcon";
 import SignInButton from "@/components/chat/SignInButton";
 import SignOutButton from "@/components/chat/SignOutButton";
 import SignUpButton from "@/components/chat/SignUpButton";
+import UserCreationHandler from "@/components/UserCreationHandler";
 import { AppProvider, useApp } from "@/contexts/AppContext";
 import { UnifiedAuthProvider, useAuth } from "@/contexts/UnifiedAuthProvider";
 import PrivyProvider from "@/providers/PrivyProvider";
@@ -66,6 +67,9 @@ function LayoutContent({ children }: { children: React.ReactNode }) {
       {authMode && (
         <AuthModal mode={authMode} onClose={() => setAuthMode(null)} />
       )}
+
+      {/* Handle automatic user creation in nilDB */}
+      <UserCreationHandler />
     </div>
   );
 }

src/app/page.tsx

@@ -1,11 +1,13 @@
 "use client";
 
 import { Download } from "lucide-react";
+import { useEffect } from "react";
 import Footer from "@/components/landingPage/Footer";
 import PWAInstallInstructionsModal from "@/components/PWAInstallInstructionsModal";
 import { Button } from "@/components/ui/button";
 import { Dialog, DialogTrigger } from "@/components/ui/dialog";
 import usePWAInstallInstructionsModal from "@/hooks/usePWAInstallInstructionsModal";
+import { captureAndStoreUTMParameters } from "@/utils/utmTracking";
 import FAQSection from "../components/landingPage/FAQSection";
 import FeaturesSection from "../components/landingPage/FeaturesSection";
 import Header from "../components/landingPage/Header";
@@ -19,6 +21,14 @@ export default function Home() {
     setIsPWAInstallInstructionsModalOpen,
   } = usePWAInstallInstructionsModal();
 
+  // Capture and store UTM parameters on landing page load
+  useEffect(() => {
+    const utmParams = captureAndStoreUTMParameters();
+    if (Object.keys(utmParams).length > 0) {
+      console.log("UTM parameters captured:", utmParams);
+    }
+  }, []);
+
   return (
     <main className="relative">
       <Header />

src/components/UserCreationHandler.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { useAuth } from "@/contexts/UnifiedAuthProvider";
+import { getUTMParametersForRegistration } from "@/utils/utmTracking";
+
+/**
+ * Component that automatically creates users in nilDB when they first access the app
+ * This handles both Supabase and Privy users who haven't been created in nilDB yet
+ */
+export default function UserCreationHandler() {
+  const { user } = useAuth();
+  const hasAttemptedCreation = useRef(false);
+
+  useEffect(() => {
+    // Only run if user is authenticated and we haven't attempted creation yet
+    if (!user?.isAuthenticated || !user?.id || hasAttemptedCreation.current) {
+      return;
+    }
+
+    hasAttemptedCreation.current = true;
+
+    const createUserInNilDB = async () => {
+      try {
+        // Get UTM parameters for user registration
+        const utmParams = getUTMParametersForRegistration();
+        const requestBody =
+          Object.keys(utmParams).length > 0 ? { utm: utmParams } : {};
+
+        const response = await fetch("/api/createUser", {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body:
+            Object.keys(requestBody).length > 0
+              ? JSON.stringify(requestBody)
+              : undefined,
+        });
+
+        const result = await response.json();
+
+        if (response.ok) {
+          if (result.userExists) {
+            console.log("User already exists in nilDB");
+          } else {
+            console.log("User created in nilDB successfully");
+          }
+        } else {
+          console.error("Error creating user in nilDB:", result.error);
+        }
+      } catch (error) {
+        console.error("Network error creating user in nilDB:", error);
+      }
+    };
+
+    // Small delay to ensure auth state is fully settled
+    const timeoutId = setTimeout(createUserInNilDB, 1000);
+
+    return () => clearTimeout(timeoutId);
+  }, [user?.isAuthenticated, user?.id]);
+
+  // This component doesn't render anything
+  return null;
+}

src/components/auth/WalletButton.tsx

@@ -1,6 +1,7 @@
 import { useLogin, usePrivy } from "@privy-io/react-auth";
 import { useRouter } from "next/navigation";
 import { useCallback, useEffect, useState } from "react";
+import { getUTMParametersForRegistration } from "@/utils/utmTracking";
 
 interface WalletButtonProps {
   onClose?: () => void;
@@ -20,9 +21,18 @@ function WalletButton({ onClose }: WalletButtonProps) {
         "Content-Type": "application/json",
       };
 
+      // Get UTM parameters for user registration
+      const utmParams = getUTMParametersForRegistration();
+      const requestBody =
+        Object.keys(utmParams).length > 0 ? { utm: utmParams } : {};
+
       const response = await fetch("/api/createUser", {
         method: "POST",
         headers,
+        body:
+          Object.keys(requestBody).length > 0
+            ? JSON.stringify(requestBody)
+            : undefined,
       });
 
       const result = await response.json();

src/contexts/UnifiedAuthProvider.tsx

@@ -5,6 +5,7 @@ import type { User } from "@supabase/supabase-js";
 import { useRouter } from "next/navigation";
 import { createContext, useContext, useEffect, useState } from "react";
 import { supabase } from "@/lib/supabase/client";
+import { getUTMParametersForRegistration } from "@/utils/utmTracking";
 
 interface UnifiedUser {
   id: string;
@@ -105,11 +106,26 @@ export function UnifiedAuthProvider({
     name: string,
     emailConsent: boolean,
   ) => {
+    // Get UTM parameters to include in email confirmation link
+    const utmParams = getUTMParametersForRegistration();
+
+    // Build the redirect URL with UTM parameters
+    let redirectUrl = `${window.location.origin}/app`;
+    if (Object.keys(utmParams).length > 0) {
+      const urlParams = new URLSearchParams();
+      Object.entries(utmParams).forEach(([key, value]) => {
+        if (value) {
+          urlParams.append(key, value);
+        }
+      });
+      redirectUrl += `?${urlParams.toString()}`;
+    }
+
     const { data, error } = await supabase.auth.signUp({
       email,
       password,
       options: {
-        emailRedirectTo: `${window.location.origin}/app`,
+        emailRedirectTo: redirectUrl,
         data: {
           name: name,
           email_consent: emailConsent,

src/lib/nildb/deleteRecord.ts

@@ -18,7 +18,7 @@ export async function deleteRecord(
   }
 
   const deleteRequest: DeleteDataRequest = {
-    collection: collectionId as any, // Cast to Uuid type
+    collection: collectionId,
     filter,
   };
 

src/types/schemas.ts

@@ -2,6 +2,13 @@ export interface USER_SCHEMA {
   _id: string;
   provider: string;
   created_at: string;
+  utm?: {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+  };
 }
 
 export interface CHAT_SCHEMA {

src/utils/utmTracking.ts

@@ -0,0 +1,133 @@
+/**
+ * UTM Tracking Utilities
+ * Handles extraction and storage of UTM parameters for user registration tracking
+ */
+
+export interface UTMParameters {
+  utm_source?: string;
+  utm_medium?: string;
+  utm_campaign?: string;
+  utm_term?: string;
+  utm_content?: string;
+}
+
+const UTM_STORAGE_KEY = "nilgpt_utm_params";
+
+/**
+ * Extracts UTM parameters from the current URL
+ */
+export function extractUTMParameters(): UTMParameters {
+  if (typeof window === "undefined") {
+    return {};
+  }
+
+  const urlParams = new URLSearchParams(window.location.search);
+  const utmParams: UTMParameters = {};
+
+  // Standard UTM parameters
+  const utmKeys = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+  ];
+
+  utmKeys.forEach((key) => {
+    const value = urlParams.get(key);
+    if (value) {
+      utmParams[key as keyof UTMParameters] = value;
+    }
+  });
+
+  return utmParams;
+}
+
+/**
+ * Stores UTM parameters in session storage
+ */
+export function storeUTMParameters(utmParams: UTMParameters): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  // Only store if there are actual UTM parameters
+  const hasUTMParams = Object.values(utmParams).some(
+    (value) => value !== undefined,
+  );
+
+  if (hasUTMParams) {
+    try {
+      sessionStorage.setItem(UTM_STORAGE_KEY, JSON.stringify(utmParams));
+    } catch (error) {
+      console.warn("Failed to store UTM parameters in session storage:", error);
+    }
+  }
+}
+
+/**
+ * Retrieves stored UTM parameters from session storage
+ */
+export function getStoredUTMParameters(): UTMParameters {
+  if (typeof window === "undefined") {
+    return {};
+  }
+
+  try {
+    const stored = sessionStorage.getItem(UTM_STORAGE_KEY);
+    if (stored) {
+      return JSON.parse(stored);
+    }
+  } catch (error) {
+    console.warn(
+      "Failed to retrieve UTM parameters from session storage:",
+      error,
+    );
+  }
+
+  return {};
+}
+
+/**
+ * Clears stored UTM parameters from session storage
+ */
+export function clearStoredUTMParameters(): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  try {
+    sessionStorage.removeItem(UTM_STORAGE_KEY);
+  } catch (error) {
+    console.warn("Failed to clear UTM parameters from session storage:", error);
+  }
+}
+
+/**
+ * Captures and stores UTM parameters from the current URL
+ * Call this on landing page load
+ */
+export function captureAndStoreUTMParameters(): UTMParameters {
+  const utmParams = extractUTMParameters();
+  storeUTMParameters(utmParams);
+  return utmParams;
+}
+
+/**
+ * Gets UTM parameters for user registration
+ * First tries to get from current URL, then falls back to stored parameters
+ * This handles the case where user comes from email confirmation with UTM params
+ */
+export function getUTMParametersForRegistration(): UTMParameters {
+  // First, try to get UTM parameters from current URL (for email confirmation flow)
+  const currentUrlParams = extractUTMParameters();
+
+  // If we have UTM params in current URL, use those and store them
+  if (Object.keys(currentUrlParams).length > 0) {
+    storeUTMParameters(currentUrlParams);
+    return currentUrlParams;
+  }
+
+  // Otherwise, fall back to stored parameters (for wallet signup flow)
+  return getStoredUTMParameters();
+}