Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Dub Integration Guide

This guide covers how to integrate Dub's attribution tracking into your own application — from installing the client-side script to tracking leads and sales on the server side.

Install the Client-Side Script

The Dub Analytics script (@dub/analytics) detects the dub_id query parameter and stores it as a first-party cookie. This cookie is what allows Dub to attribute conversion events back to the original link click.

React / Next.js

npm install @dub/analytics
Add the <Analytics /> component to your root layout:
import { Analytics as DubAnalytics } from "@dub/analytics/react";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <DubAnalytics apiHost="https://dub.strinkl.com/api" />
    </html>
  );
}

Manual (HTML)

<script
  src="https://www.dubcdn.com/analytics/script.js"
  defer
></script>

Configuration Options

PropTypeDefaultDescription
apiHoststringhttps://api.dub.coBase URL for the Dub API. Use your self-hosted instance if applicable.
attributionModel"first-click" | "last-click""last-click"Which touchpoint gets credit for the conversion.
publishableKeystring—Required for client-side conversion tracking.
cookieOptions.expiresInDaysnumber90Attribution window in days.
cookieOptions.domainstring—Set for cross-subdomain tracking (e.g. .example.com).
domainsConfig.referstring—Custom domain for client-side click tracking.
domainsConfig.outboundstring | string[]—Domains for cross-domain tracking.

Verify Installation

  1. Open browser console and type _dubAnalytics — you should see the analytics object
  2. Append ?dub_id=test to your URL and check that the dub_id cookie is set
  3. Check the Network tab for successful /track/click requests

Enable Conversion Tracking

Before tracking conversions, enable it on your links:
Navigate to your Dub workspace Settings → Tracking and toggle Workspace-level Conversion Tracking. All future links will have conversion tracking enabled.
Toggle Conversion Tracking in the Dub Link Builder when creating or editing a link.

Via API

await dub.links.create({
  url: "https://yoursite.com",
  trackConversion: true,
});

Configure Allowed Hostnames

From your workspace Settings → Tracking, add your site's domain to Allowed Hostnames. This ensures only authorized domains can send conversion events.
  • example.com — tracks traffic only from example.com
  • *.example.com — tracks traffic from all subdomains, but not the apex domain
Add localhost for local development. Remove it before going live.

Generate a Publishable Key

From Settings → Tracking, generate a Publishable Key. Pass it to the client-side script:
<DubAnalytics
  publishableKey="dub_pk_xxxxxxxx"
  apiHost="https://dub.strinkl.com/api"
/>

Track Lead Events

Track a lead when a user signs up, joins a mailing list, or completes any qualifying action.

Client-Side (from Thank-You Page)

import { useAnalytics } from "@dub/analytics/react";
import { useEffect } from "react";

export function ThankYouPage() {
  const { trackLead } = useAnalytics();

  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const email = params.get("email");

    if (email) {
      trackLead({
        eventName: "Sign Up",
        customerExternalId: email,
        customerEmail: email,
      });
    }
  }, [trackLead]);

  return <div>Thank you for signing up!</div>;
}

Client-Side (from Form)

import { useAnalytics } from "@dub/analytics/react";

export function SignUpForm() {
  const { trackLead } = useAnalytics();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    trackLead({
      eventName: "Sign Up",
      customerExternalId: email,
      customerName: name,
      customerEmail: email,
    });
  };

  return <form onSubmit={handleSubmit}>...</form>;
}
Server-side tracking is more reliable since it can't be blocked:
import { Dub } from "dub";

const dub = new Dub({ token: process.env.DUB_API_KEY });

await dub.track.lead({
  clickId: cookies.get("dub_id"),
  eventName: "Sign Up",
  customerExternalId: user.id,
  customerEmail: user.email,
  customerName: user.name,
});
For auth framework-specific guides:

Lead Event Properties

PropertyRequiredDescription
clickIdYesThe dub_id value from the cookie. Pass empty string for deferred tracking.
eventNameYesName of the event (e.g. "Sign Up").
customerExternalIdYesUnique customer ID in your system. Used for deduplication and future attribution.
customerNameNoCustomer name. Random name generated if omitted.
customerEmailNoCustomer email.
customerAvatarNoAvatar URL.
metadataNoAdditional data (max 10,000 characters).

Track Sale Events

Install the Dub Stripe integration in your Dub workspace. Pass the customer's external ID when creating checkout sessions:
const session = await stripe.checkout.sessions.create({
  metadata: {
    dubCustomerId: user.id,
  },
});
Dub receives a Stripe webhook and automatically tracks the sale.

Shopify Integration

Install the Dub Shopify app for automatic lead + sale event tracking.

Manual Server-Side

import { Dub } from "dub";

const dub = new Dub({ token: process.env.DUB_API_KEY });

await dub.track.sale({
  customerExternalId: user.id,
  amount: 5900, // in cents ($59.00)
  paymentProcessor: "stripe",
  invoiceId: "in_123",
  eventName: "Subscription creation",
});

Sale Event Properties

PropertyRequiredDescription
customerExternalIdYesCustomer ID matching the lead event.
amountYesSale amount in cents.
paymentProcessorNoe.g. "stripe", "shopify", "custom".
eventNameNoDefaults to "Purchase".
invoiceIdNoUsed as idempotency key.
currencyNoDefaults to "usd".
metadataNoAdditional sale data.

Client-Side Click Tracking

For dynamic pages where you can't use short links (e.g. referral pages, user-generated content), track clicks via query parameters.

Automatic (via ?via= parameter)

Configure your referral domain:
<DubAnalytics
  domainsConfig={{ refer: "go.yourcompany.link" }}
/>
When a visitor lands on https://yoursite.com?via=abc123, the script automatically tracks a click event.

Manual (trackClick())

import { useAnalytics } from "@dub/analytics/react";

function ReferralPage() {
  const { trackClick } = useAnalytics();

  useEffect(() => {
    const key = window.location.pathname.split("/").pop();
    if (key) {
      trackClick({ domain: "go.yourcompany.link", key });
    }
  }, [trackClick]);
}

Partner & Discount Data

When using Dub Partners with dual-sided incentives, partner and discount data is automatically stored in a dub_partner_data cookie:
import { useAnalytics } from "@dub/analytics/react";

function DiscountBanner() {
  const { partner, discount } = useAnalytics();

  if (!partner || !discount) return null;

  return (
    <div>
      <img src={partner.image} alt={partner.name} />
      <p>{partner.name} referred you — {discount.amount}{discount.type === "percentage" ? "%" : "$"} off</p>
    </div>
  );
}

Cross-Domain Tracking

Subdomain to Apex

If your script is on app.example.com but you need the cookie on example.com:
<DubAnalytics cookieOptions={{ domain: ".example.com" }} />

Across Different Domains

If your marketing site (example.sh) links to your app (example.com):
<DubAnalytics
  domainsConfig={{ outbound: ["example.com", "example.sh"] }}
/>
This automatically appends the dub_id to outbound links between these domains.

Direct Sale Tracking (Without Lead Event)

For one-time purchases without a signup flow, track sales directly with the click ID:
await dub.track.sale({
  clickId: cookies.get("dub_id"),
  customerExternalId: order.email,
  customerName: order.name,
  customerEmail: order.email,
  amount: 4900,
  invoiceId: order.id,
});

Resources

Powered byHolocron