> ## Documentation Index
> Fetch the complete documentation index at: https://dub-mintlify-update-supabase-lead-tracking-guide-82850.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Client-side conversion tracking

> Learn how to use the @dub/analytics script to track conversion events on the client-side

`@dub/analytics` is a client-side script for [tracking conversion events](/conversions/quickstart) with Dub.

By default, the script handles the detection of the `dub_id` query parameter and storing it as a first-party cookie:

<Frame>
  <img className="rounded-lg border border-gray-100" src="https://assets.dub.co/help/conversion-click-event.png" alt="A diagram showing how click events are tracked in the conversion funnel" />
</Frame>

Then, when a conversion event occurs (e.g. a user signs up for an account), you can check for the `dub_id` cookie and attribute the conversion to the original click by [tracking a lead event](/conversions/leads/introduction).

<Frame>
  <img className="rounded-lg border border-gray-100" src="https://assets.dub.co/help/conversion-lead-event.png" alt="A diagram showing how lead events are tracked in the conversion funnel" />
</Frame>

Finally, when the user completes a purchase (e.g. subscribing to a plan, purchasing a product, etc.), you can [track a sale event](/conversions/sales/introduction). Under the hood, Dub will automatically attribute the sale to the original link click.

<Frame>
  <img className="rounded-lg border border-gray-100" src="https://assets.dub.co/help/conversion-sale-event.png" alt="A diagram showing how sale events are tracked in the conversion funnel" />
</Frame>

## Quickstart

First, you'll need to enable conversion tracking for your Dub links to be able to start tracking conversions:

<Tip>
  If you're using [Dub Partners](/partners/quickstart), you can skip this step
  since partner links will have conversion tracking enabled by default.
</Tip>

<AccordionGroup>
  <Accordion title="Option 1: On a workspace-level">
    To enable conversion tracking for all future links in a workspace, you can do the following:
    To enable conversion tracking for all future links in a workspace, you can do the following:

    1. Navigate to your [workspace's Analytics settings page](https://app.dub.co/settings/analytics).
    2. Toggle the **Workspace-level Conversion Tracking** switch to enable conversion tracking for the workspace.

    <Frame>
      <img src="https://mintcdn.com/dub-mintlify-update-supabase-lead-tracking-guide-82850/QGUHh3r7hC2NS4u-/images/conversions/enable-conversion-tracking-workspace.png?fit=max&auto=format&n=QGUHh3r7hC2NS4u-&q=85&s=d2bc96cd4bcc8e47c0e086746df630c8" alt="Enabling conversion tracking for a workspace" width="1364" height="557" data-path="images/conversions/enable-conversion-tracking-workspace.png" />
    </Frame>

    This option will enable conversion tracking in the [Dub Link Builder](https://dub.co/help/article/dub-link-builder) for all future links.
  </Accordion>

  <Accordion title="Option 2: On a link-level">
    If you don't want to enable conversion tracking for all your links in a workspace, you can also opt to enable it on a link-level.

    To enable conversion tracking for a specific link, open the [Dub Link Builder](https://dub.co/help/article/dub-link-builder) for a link and toggle the **Conversion Tracking** switch.

    <Frame>
      <img src="https://mintcdn.com/dub-mintlify-update-supabase-lead-tracking-guide-82850/QGUHh3r7hC2NS4u-/images/conversions/enable-conversion-tracking.png?fit=max&auto=format&n=QGUHh3r7hC2NS4u-&q=85&s=d9a83ac168f69997b97cd6e068cd38b1" alt="Enabling conversion tracking for a link" width="2345" height="908" data-path="images/conversions/enable-conversion-tracking.png" />
    </Frame>

    <Tip>
      You can also use the `C` keyboard shortcut when inside the link builder to
      quickly enable conversion tracking for a given link.
    </Tip>
  </Accordion>

  <Accordion title="Option 3: Via the API">
    Alternatively, you can also enable conversion tracking programmatically via the [Dub API](/api-reference/introduction). All you need to do is pass `trackConversion: true` when creating or updating a link:

    <CodeGroup>
      ```javascript Node.js
      const link = await dub.links.create({
        url: "https://dub.co",
        trackConversion: true,
      });
      ```

      ```python Python
      link = d.links.create(url="https://dub.co", track_conversion=True)
      ```

      ```go Go
      link, err := d.Links.Create(ctx, &dub.CreateLinkRequest{
          URL: "https://dub.co",
          TrackConversion: true,
      })
      ```

      ```ruby Ruby
      s.links.create_many(
        ::OpenApiSDK::Operations::CreateLinkRequest.new(
          url: "https://dub.co",
          track_conversion: true,
        )
      )
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

***

Then, you'll need to install the Dub client-side script and set up the necessary configuration for client-side conversion tracking:

<Steps>
  <Step title="Generate your publishable key">
    Before you can track conversions on the client-side, you need to generate a [publishable key](/api-reference/publishable-keys) from your Dub workspace.

    To do that, navigate to your [workspace's Analytics settings page](https://app.dub.co/settings/analytics) and generate a new publishable key under the **Publishable Key** section.

    <Frame>
      <img src="https://mintcdn.com/dub-mintlify-update-supabase-lead-tracking-guide-82850/QGUHh3r7hC2NS4u-/images/conversions/publishable-key.png?fit=max&auto=format&n=QGUHh3r7hC2NS4u-&q=85&s=ee782d102636779750e1f1f984589178" alt="Enabling conversion tracking for a workspace" width="3292" height="1520" data-path="images/conversions/publishable-key.png" />
    </Frame>
  </Step>

  <Step title="Allowlist your site's domain">
    Then, you'll need to allowlist your site's domain to allow the client-side conversion events to be ingested by Dub.

    To do that, navigate to your [workspace's Analytics settings page](https://app.dub.co/settings/analytics) and add your site's domain to the **Allowed Hostnames** list.

    This provides an additional layer of security by ensuring only authorized domains can track conversions using your publishable key.

    <Frame>
      <img src="https://mintcdn.com/dub-mintlify-update-supabase-lead-tracking-guide-82850/QGUHh3r7hC2NS4u-/images/conversions/allowed-hostnames.png?fit=max&auto=format&n=QGUHh3r7hC2NS4u-&q=85&s=e3d9cbc2d83f784265a33d26c4d93a46" alt="Enabling conversion tracking for a workspace" width="3308" height="1522" data-path="images/conversions/allowed-hostnames.png" />
    </Frame>

    You can group your hostnames when adding them to the allow list:

    * `example.com`: Tracks traffic **only** from `example.com`.
    * `*.example.com`: Tracks traffic from **all subdomains** of `example.com`, but **not** from `example.com` itself.

    <Tip>
      When testing things out locally, you can add `localhost` to the **Allowed
      Hostnames** list temporarily. This will allow local events to be ingested by
      Dub. Don't forget to remove it once you're ready to go live!
    </Tip>
  </Step>

  <Step title="Install @dub/analytics package">
    Next, install the Dub analytics script in your application.

    You can install the `@dub/analytics` script in several different ways:

    <CardGroup>
      <Card title="React" icon="react" href="/sdks/client-side/installation-guides/react" horizontal />

      <Card title="Manual installation" icon="browser" href="/sdks/client-side/installation-guides/manual" horizontal />

      <Card
        title="Framer"
        icon={
  <svg
    width="74"
    height="111"
    viewBox="0 0 74 111"
    fill="none"
    xmlns="http://www.w3.org/2000/svg"
    className="w-7 h-7"
  >
    <path d="M0 0H73.8374V36.9892H36.9187L0 0Z" fill="#eb5611" />
    <path d="M0 36.989H36.9187L73.8374 73.9796H0V36.989Z" fill="#eb5611" />
    <path d="M0 73.9797H36.9187V110.97L0 73.9797Z" fill="#eb5611" />
  </svg>
}
        href="/sdks/client-side/installation-guides/framer"
        horizontal
      />

      <Card title="Shopify" icon="shopify" href="/sdks/client-side/installation-guides/shopify" horizontal />

      <Card title="WordPress" icon="wordpress" href="/sdks/client-side/installation-guides/wordpress" horizontal />

      <Card title="Webflow" icon="webflow" href="/sdks/client-side/installation-guides/webflow" horizontal />

      <Card title="Google Tag Manager" icon="google" href="/sdks/client-side/installation-guides/google-tag-manager" horizontal />
    </CardGroup>

    You must configure the **publishable key** you generated in step 1 when installing the analytics script. Without this key, client-side conversion tracking will not work.

    <CodeGroup>
      ```typescript React
      import { Analytics as DubAnalytics } from '@dub/analytics/react';

      export default function RootLayout({
        children,
      }) {
        return (
          <html lang="en">
            <body className={inter.className}>{children}</body>
            <DubAnalytics
              ...
              publishableKey="dub_pk_xxxxxxxx" // Replace with your publishable key
            />
          </html>
        );
      }
      ```

      ```html Other
      <script>
        !(function (c, n) {
          c[n] =
            c[n] ||
            function () {
              (c[n].q = c[n].q || []).push(arguments);
            };
          ["trackClick", "trackLead", "trackSale"].forEach(
            (t) => (c[n][t] = (...a) => c[n](t, ...a))
          );
          var s = document.createElement("script");
          s.defer = 1;
          s.src = "https://dubcdn.com/analytics/script.conversion-tracking.js";
          s.setAttribute("data-publishable-key", "dub_pk_xxxxxxxx"); // Replace with your publishable key
          document.head.appendChild(s);
        })(window, "dubAnalytics");
      </script>
      ```
    </CodeGroup>
  </Step>
</Steps>

## Client-side lead tracking

Once the analytics script is installed, you can start tracking lead events in your application on the client-side.

Here are the quickstart examples for tracking lead events:

<CodeGroup>
  ```typescript React
  import { useAnalytics } from "@dub/analytics/react";
  import { useState } from "react";

  export function SignUpForm() {
    const { trackLead } = useAnalytics();
    const [name, setName] = useState("");
    const [email, setEmail] = useState("");
    const handleSubmit = (e: React.FormEvent) => {
      e.preventDefault();

      // Track the lead event
      trackLead({
        eventName: "Sign Up",
        customerExternalId: email,
        customerName: name,
        customerEmail: email,
      });
    };

    return (
      <form onSubmit={handleSubmit}>
        <input
          type="text"
          value={name}
          onChange={(e) => setName(e.target.value)}
          required
        />
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          required
        />
        <button type="submit">Sign Up</button>
      </form>
    );
  }
  ```

  ```html Other
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Sign Up</title>
    </head>
    <body>
      <form id="signupForm">
        <input type="text" id="name" required />
        <input type="email" id="email" required />
        <button type="submit">Sign Up</button>
      </form>

      <script>
        document
          .getElementById("signupForm")
          .addEventListener("submit", function (e) {
            e.preventDefault();

            const name = document.getElementById("name").value;
            const email = document.getElementById("email").value;

            // Track the lead event
            dubAnalytics.trackLead({
              eventName: "Sign Up",
              customerExternalId: email,
              customerName: name,
              customerEmail: email,
            });
          });
      </script>
    </body>
  </html>
  ```
</CodeGroup>

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

| Property             | Required | Description                                                                                                                                                                                                                                                                                                                                                                       |
| :------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clickId`            | **Yes**  | The unique ID of the click that the lead conversion event is attributed to. You can read this value from `dub_id` cookie. If an empty string is provided (i.e. if you're using [tracking a deferred lead event](/conversions/leads/deferred)), Dub will try to find an existing customer with the provided `customerExternalId` and use the `clickId` from the customer if found. |
| `eventName`          | **Yes**  | The name of the lead event to track. Can also be used as a unique identifier to associate a given lead event for a customer for a subsequent sale event (via the `leadEventName` prop in `/track/sale`).                                                                                                                                                                          |
| `customerExternalId` | **Yes**  | The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.                                                                                                                                                                                                                                                          |
| `customerName`       | No       | The name of the customer. If not passed, a random name will be generated (e.g. "Big Red Caribou").                                                                                                                                                                                                                                                                                |
| `customerEmail`      | No       | The email address of the customer.                                                                                                                                                                                                                                                                                                                                                |
| `customerAvatar`     | No       | The avatar URL of the customer.                                                                                                                                                                                                                                                                                                                                                   |
| `mode`               | No       | The mode to use for tracking the lead event. `async` will not block the request; `wait` will block the request until the lead event is fully recorded in Dub; `deferred` will defer the lead event creation to a subsequent request.                                                                                                                                              |
| `metadata`           | No       | Additional metadata to be stored with the lead event. Max 10,000 characters.                                                                                                                                                                                                                                                                                                      |

**When to track leads**

You should track lead events after successful user actions such as:

* User registration or account creation
* Newsletter subscription
* Contact form submission
* Demo request or trial signup
* Download of gated content

Ensure the event is triggered **only after the backend confirms the action was completed successfully**. This guarantees accurate lead data and prevents false or incomplete entries.

## Client-side sale tracking

Once the analytics script is installed, you can start tracking sale events in your application on the client-side.

<CodeGroup>
  ```typescript React
  import { useAnalytics } from "@dub/analytics/react";
  import { useState } from "react";

  export function CheckoutForm() {
    const { trackSale } = useAnalytics();
    // …
  }
    const handleSubmit = (e: React.FormEvent) => {
      e.preventDefault();

      // Track the sale event
      trackSale({
        eventName: "Purchase",
        customerExternalId: "cus_RBfbD57H",
        amount: 5000, // $50.00
        invoiceId: "in_1MtHbELkdIwH",
      });
    };

    return (
      <form onSubmit={handleSubmit}>
        ...
      </form>
    );
  }
  ```

  ```html Other
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Checkout</title>
    </head>
    <body>
      <form id="checkoutForm">
        ...
        <button type="submit">Checkout</button>
      </form>

      <script>
        document.getElementById("checkoutForm").addEventListener("submit", function (e) {
          e.preventDefault();

          // Track the sale event
          dubAnalytics.trackSale({
            eventName: "Purchase",
            customerExternalId: "cus_RBfbD57H",
            amount: 5000, // $50.00
            invoiceId: "in_1MtHbELkdIwH",
          });
        });
      </script>
    </body>
  </html>
  ```
</CodeGroup>

Here are the properties you can include when sending a sale event:

| Property             | Required | Description                                                                                                                                            |
| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `customerExternalId` | **Yes**  | The unique ID of the customer in your system. Will be used to identify and attribute all future events to this customer.                               |
| `amount`             | **Yes**  | The amount of the sale in cents.                                                                                                                       |
| `paymentProcessor`   | No       | The payment processor that processed the sale (e.g. [Stripe](/conversions/sales/stripe), [Shopify](/conversions/sales/shopify)). Defaults to "custom". |
| `eventName`          | No       | The name of the event. Defaults to "Purchase".                                                                                                         |
| `invoiceId`          | No       | The invoice ID of the sale. Can be used as a idempotency key – only one sale event can be recorded for a given invoice ID.                             |
| `currency`           | No       | The currency of the sale. Defaults to "usd".                                                                                                           |
| `metadata`           | No       | An object containing additional information about the sale.                                                                                            |

**When to track sale**

Track sale events only after a user successfully completes a purchase or payment-related action, such as:

* Completing a checkout or order
* Subscription payment
* Invoice payment
* Any paid trial or demo conversion

Ensure the event is triggered **only after the backend confirms the payment was successful**. This guarantees accurate sale data and prevents false or incomplete entries.