Skip to main content
Version: current (0.9)

Next.js Integration

Integrate Lucia SDK into your Next.js application for behavioral tracking and attribution.

Installation​

Add the Lucia SDK script to your root layout using Next.js Script component:

app/layout.tsx

import Script from "next/script";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <head>
        <Script
          src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
          data-api-key={process.env.NEXT_PUBLIC_LUCIA_API_KEY}
          strategy="beforeInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Option 2: npm Package​

npm install lucia-sdk

app/layout.tsx

"use client";

import { useEffect } from "react";
import LuciaSDK from "lucia-sdk";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  useEffect(() => {
    LuciaSDK.init({
      apiKey: process.env.NEXT_PUBLIC_LUCIA_API_KEY!,
    });
  }, []);

  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Environment Variables​

Add your API key to .env.local:

NEXT_PUBLIC_LUCIA_API_KEY=your-api-key-here

Tracking Events​

Page Views​

Page views are automatically tracked when using the CDN method. For manual tracking:

"use client";

import { useEffect } from "react";
import { usePathname } from "next/navigation";
import LuciaSDK from "lucia-sdk";

export default function PageViewTracker() {
  const pathname = usePathname();

  useEffect(() => {
    LuciaSDK.pageView(pathname);
  }, [pathname]);

  return null;
}

Button Clicks​

"use client";

import LuciaSDK from "lucia-sdk";

export default function CTAButton() {
  const handleClick = async () => {
    await LuciaSDK.buttonClick("signup-cta");
    // Continue with your action
  };

  return <button onClick={handleClick}>Sign Up</button>;
}

Conversions​

"use client";

import LuciaSDK from "lucia-sdk";

export default function CheckoutButton({ amount }: { amount: number }) {
  const handlePurchase = async () => {
    await LuciaSDK.trackConversion("purchase", amount, {
      currency: "USD",
      product: "Pro Plan",
    });
  };

  return <button onClick={handlePurchase}>Complete Purchase</button>;
}

User Information​

"use client";

import { useEffect } from "react";
import LuciaSDK from "lucia-sdk";

export default function UserTracker({ userId, email }: { userId: string; email: string }) {
  useEffect(() => {
    LuciaSDK.userInfo(userId, { email });
  }, [userId, email]);

  return null;
}

Auto-Track Clicks​

Enable automatic click tracking on all buttons and links:

<Script
  src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
  data-api-key={process.env.NEXT_PUBLIC_LUCIA_API_KEY}
  data-auto-track-clicks="true"
  strategy="beforeInteractive"
/>

Server Components​

The Lucia SDK is a client-side library. When using Server Components, wrap SDK calls in Client Components or use the "use client" directive.

// components/TrackButton.tsx
"use client";

import LuciaSDK from "lucia-sdk";

export function TrackButton({ label, trackId }: { label: string; trackId: string }) {
  return (
    <button onClick={() => LuciaSDK.buttonClick(trackId)}>
      {label}
    </button>
  );
}
// app/page.tsx (Server Component)
import { TrackButton } from "@/components/TrackButton";

export default function Page() {
  return (
    <main>
      <h1>Welcome</h1>
      <TrackButton label="Get Started" trackId="hero-cta" />
    </main>
  );
}