Client-side click tracking

Track clicks on the client-side using query parameters

With the @dub/analytics script, you can track clicks on the client-side using query parameters (e.g. ?via=john, ?ref=jane).

A few use cases include:

• You’re using Dub Partners with dual-sided incentives and want to display a banner that says: “John referred you to Acme and gave you 25% off”
• You are migrating from an existing affiliate management platform (e.g. Rewardful) that uses query parameters to track conversions.
• You are running an ad on a platform like Google/Reddit that requires you to use your main site domain for the URL (no short links allowed) – so instead of using a short link, you can use a query parameter to track clicks.
• You have dynamically generated referral pages (e.g. Tesla) and want to track clicks using a trackClick() function inside your application code.

Quickstart

Here’s how you can enable client-side click-tracking with the @dub/analytics script:

1. Add a custom domain to your Dub workspace

   First, you’ll need to add a custom short link domain to your Dub workspace. You can use a domain you already own, or leverage our free .link domain offer to register a custom domain like yourcompany.link for free.

   This is the domain that you’ll use for your short links on Dub.

2. Allowlist your site's domain

   Then, you’ll need to allowlist your site’s domain to allow the client-side click events to be ingested by Dub. To do that, navigate to your workspace’s Analytics settings page and add your site’s domain to the Allowed Hostnames list.

   

   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.

   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!

3. Install the Dub client-side SDK

   Next, install the Dub client-side SDK and initialize it with the domain you added in the previous step.

   React/Next.js

   // install the package (e.g. npm install @dub/analytics)
   import { Analytics as DubAnalytics } from "@dub/analytics/react";
   
   export default function App() {
     return (
       <Layout>
         <DubAnalytics
           domainsConfig={{
             refer: "go.example.com", // the custom domain you're using on Dub for your short links
           }}
         />
         {/* Your app code here */}
       </Layout>
     );
   }
   

   Here’s the full list of parameters you can pass to the script:

   Parameters

   apiHost · url · default: "https://api.dub.co"

   The base URL for the Dub API. This is useful for setting up reverse proxies to avoid adblockers.

   attributionModel · first-click | last-click · default: "last-click"

   The attribution model to use for the analytics event. The following attribution models are available:

   • first-click: The first click model gives all the credit to the first touchpoint in the customer journey.
   • last-click: The last click model gives all the credit to the last touchpoint in the customer journey.

   cookieOptions · CookieOption Object

   Show properties

   domain · string

   Specifies the value for the Domain Set-Cookie attribute. This is useful for cross-domain tracking. Example: .example.com

   expires · integer · default: "90"

   Specifies the Date object to be the value for the Expires Set-Cookie attribute. Example: new Date('2024-12-31')

   expiresInDays · integer · default: "90"

   Specifies the number (in days) to be the value for the Expires Set-Cookie attribute. Example: 90

   path · string · default: "/"

   Specifies the value for the Path Set-Cookie attribute. By default, the path is considered the “default path”. Example: /

   domainsConfig · JSON-stringified object

   Configure the domains that Dub will track. The following properties are available:

   Show properties

   refer · string

   The Dub custom domain for referral program client-side click tracking (previously shortDomain). Example: refer.dub.co

   site · string

   The Dub short domain for tracking site visits. Example: site.dub.co

   outbound · string | string[]

   An array of domains for cross-domain tracking. When configured, the existing dub_id cookie will be automatically appended to all outbound links targeting these domains to enable cross-domain tracking across different applications. Example: ["dub.sh", "git.new"]

   queryParam · string · default: "via"

   The query parameter to listen to for client-side click-tracking (e.g. ?via=abc123).

   scriptProps · HTMLScriptElement Object

   Custom properties to pass to the script tag. Refer to MDN for all available options.

4. (Optional, but recommended): Set up a reverse proxy

   To avoid ad-blockers from blocking your click-tracking requests, we recommend setting up a reverse proxy.

   Refer to the Reverse-proxy support guide to learn how to set one up.

5. Verify your setup

   To verify that your click-tracking is working, run your website locally and append the URL with the unique key of your short link

   For example, if your short link is https://go.example.com/abc123, you’ll need to append ?via=abc123 to the URL.

   Once you’ve done that, check if the following is true:

   1. There is a successful /track/click request in your browser’s Network tab (and no errors in the Console tab).
   2. The dub_id cookie is being set upon a successful /track/click request.
   3. The click tracked correctly in the Events tab of your Dub workspace.

Automatically fetching partner and discount data

If you’re using Dub Partners with dual-sided incentives, the script will automatically fetch the partner and discount data for you when someone lands on your site via a valid referral link.

This data will be stored as a JSON-stringified object in the dub_partner_data cookie in the following format:

{
  "clickId": "xxx", // unique ID of the click event
  "partner": {
    "id": "pn_xxx", // unique ID of the partner on Dub
    "name": "John Doe", // name of the partner
    "image": "https://example.com/john.png" // avatar of the partner
  },
  "discount": {
    "id": "disc_xxx", // unique ID of the discount on Dub
    "amount": 25, // discount amount (either a percentage or a fixed amount)
    "type": "percentage", // type of the discount (either "percentage" or "fixed")
    "maxDuration": 3, // maximum duration of the discount in months
    "couponId": "XZuejd0Q", // Stripe coupon code
    "couponTestId": "2NMXz81x" // Stripe test coupon ID
  }
}

You can access partner and discount data in your application code using the useAnalytics() hook. If you’re working in a non-React environment, you can use the DubAnalytics object directly.

Here is a quick example of how you can display a discount banner using the useAnalytics() hook:

React/Next.js

// Display a banner that says: _"John referred you to Acme and gave you 25% off"_
import { useAnalytics } from "@dub/analytics/react";

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

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

  return (
    <div className="flex items-center gap-2">
      <img
        src={partner.image}
        alt={partner.name}
        className="size-6 rounded-full"
      />
      <p>
        {partner.name} referred you to Acme and gave you {discount.amount}{" "}
        {discount.type} off
      </p>
    </div>
  );
}

Here’s an example of how the discount banner will look like:

Manually tracking clicks with the trackClick() function

This is helpful for tracking clicks on:

• Dynamically generated referral pages (e.g. Tesla)
• Dynamic user-generated content/webpages:
  • Dub’s public analytics dashboards (e.g. app.dub.co/share/:slug)
  • Cal.com’s booking pages (e.g. cal.com/steven)
  • Tella’s video pages (e.g. tella.tv/video/:slug)

The trackClick() function allows you to manually trigger click events from your application code. This is useful when you want to track clicks that happen programmatically.

The trackClick() function accepts an object with the following parameters:

domain · string · required

The domain of the short link (e.g. getacme.link)

key · string · required

The short link slug (e.g. john)

Here’s how you can use the trackClick() function in your application:

React/Next.js

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

function BookingPage() {
  const router = useRouter();
  const { trackClick } = useAnalytics();

  // Extract the key from the URL path (e.g., /john -> john)
  const { slug: key } = router.query;

  useEffect(() => {
    if (key) {
      trackClick({
        domain: "getacme.link",
        key,
      });
    }
  }, [key, trackClick]);

  return <></>;
}

Differences from server-side click-tracking

Server-side click-tracking is enabled by default for all Dub links and come with the following attributes:

Attribute	Type	Description
timestamp	string	The timestamp of the click event
id	string	The unique ID of the click event
url	string	The destination URL that the link resolved to – this can vary if geo/device-targeting is enabled
continent	string	The continent of the user who clicked the link
country	string	The country of the user who clicked the link
city	string	The city of the user who clicked the link
device	string	The device of the user who clicked the link
browser	string	The browser of the user who clicked the link
os	string	The operating system of the user who clicked the link
referer	string	The referrer of the user who clicked the link
refererUrl	string	The full referrer URL of the user who clicked the link
qr	boolean	Whether the click event was triggered by a QR code scan
ip	string	The IP address of the user who clicked the link (non-EU users only)

These events happen on the server-side and cannot be blocked by browser extensions or ad-blockers, which improves the accuracy of your analytics data.