NextAuth.js

Learn how to track lead conversion events with NextAuth.js and Dub

Conversion tracking require a Business plan subscription or higher.

When it comes to conversion tracking, a lead event happens when a user performs an action that indicates interest in your product or service. This could be anything from:

• Signing up for an account
• Adding a product to cart
• Joining a mailing list

In this guide, we will be focusing on tracking new user sign-ups for a SaaS application that uses NextAuth.js for user authentication.

Prerequisites

Before you get started, make sure you follow the Dub Conversions quickstart guide to get Dub Conversions set up for your links:

1. Enable conversion tracking for your links
2. Install the @dub/analytics client-side SDK
3. Install the Dub server-side SDK

Configure NextAuth.js Options

Then, set up your NextAuth.js configuration options to track lead conversion events using the dub TypeScript SDK.

Here’s how it works in a nutshell:

1. Use NextAuth’s signIn event to detect when there’s a new sign up.
2. If the user is a new sign up, check if the dub_id cookie is present.
3. If the dub_id cookie is present, send a lead event to Dub using dub.track.lead
4. Delete the dub_id cookie.

Under the hood, Dub records the user as a customer and associates them with the click event that they came from. The user’s unique ID is now the source of truth for all future events – hence why we don’t need the dub_id cookie anymore.

App Router

// app/api/auth/[...nextauth]/options.ts
import type { NextAuthOptions } from "next-auth";
import { cookies } from "next/headers";
import { dub } from "@/lib/dub";

export const authOptions: NextAuthOptions = {
  ...otherAuthOptions, // your other NextAuth options
  events: {
    async signIn(message) {
      // if it's a new sign up
      if (message.isNewUser) {
        const cookieStore = await cookies();
        // check if dub_id cookie is present
        const dub_id = cookieStore.get("dub_id")?.value;
        if (dub_id) {
          // send lead event to Dub
          await dub.track.lead({
            clickId: dub_id,
            eventName: "Sign Up",
            customerExternalId: user.id,
            customerName: user.name,
            customerEmail: user.email,
            customerAvatar: user.image,
          });
          // delete the cookies
          cookieStore.delete("dub_id");
          cookieStore.delete("dub_partner_data");
        }
      }
    },
  },
};

In NextAuth.js, the isNewUser flag will only be available if you’re using next-auth’s database implementation (otherwise it’ll return undefined). In that case, you should move the logic above to the signIn callback instead.

Here’s the full list of attributes you can pass when sending a lead event:

Property	Required	Description
clickId	Yes	The unique dub_id parameter that the lead conversion event is attributed to.
eventName	Yes	The name of the event. Example: “Sign up”.
customerExternalId	Yes	The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.
customerEmail	No	The email address of the customer. If not passed, a random email address will be generated.
customerName	No	The name of the customer. If not passed, a random name will be generated (e.g. “Big Red Caribou”).
customerAvatar	No	The avatar URL of the customer. If not passed, a random avatar URL will be generated.

Create a NextAuth.js Route Handler

Finally, import the authOptions variable you created earlier and use NextAuth to create a handler for your NextAuth.js routes.

App Router

// app/api/auth/[...nextauth]/index.ts
import { authOptions } from "./options";
import NextAuth from "next-auth";

const handler = NextAuth(authOptions);

export { handler as GET, handler as POST };

View your conversions

Once you’ve completed the setup, all your tracked conversions will show up in Dub Analytics. We provide 3 different views to help you understand your conversions:

• Time-series: A time-series view of the number clicks, leads and sales.

• Funnel chart: A funnel chart view visualizing the conversion & dropoff rates across the different steps in the conversion funnel (clicks → leads → sales).

• Real-time events stream: A real-time events stream of every single conversion event that occurs across all your links in your workspace.