Introduction

Learn more about the @dub/analytics script and how to install it.

@dub/analytics is a lightweight (~1kb), open-source client-side script used for tracking conversions with Dub Conversions.

The script handles the detection of the dub_id query parameter and storing it as a first-party cookie, which will be used to attribute subsequent conversion events to the original link.

With the script, you can also track clicks on the client-side using query parameters (e.g. ?via=john). This gives you the flexibility to track clicks directly on your website or app, without needing to rely on link redirects.

Installation guides

Based on the framework or platform you’re using, you can install the script in different ways:

React

Add Dub Analytics to your React app.

Manual installation

Add Dub Analytics to your website.

Framer

Add Dub Analytics to your Framer site.

Shopify

Add Dub Analytics to your Shopify store.

WordPress

Add Dub Analytics to your WordPress site.

Webflow

Add Dub Analytics to your Webflow site.

Concepts

You can pass the following props to the @dub/analytics script to customize its behavior:

data-api-host · url · default: "https://api.dub.co"

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

data-attribution-model · 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.

data-cookie-options · JSON-stringified object

Custom properties to pass to the cookie. Refer to MDN’s Set-Cookie documentation for all available options.

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.

For example, to set the cookie window to 60 days (instead of the default 90 days), you can add the following to your script:

<script
  src="https://www.dubcdn.com/analytics/script.js"
  defer
  data-cookie-options='{"expiresInDays": 60}'
/>

path · string · default: "/"

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

data-domains · 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 data-short-domain). 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"

data-short-domain · string · deprecated

[Deprecated: Use data-domains.refer instead] The Dub custom domain for referral program client-side click tracking

data-query-param · string · default: "via"

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

Examples

Here are some code examples to learn how to use the script:

Cross-domain tracking

By default, the script already sets the dub_id cookie on a cross-domain level.

This means that if you have the script installed on your marketing site (e.g. example.com), the cookie will also be accessible when your user signs up for your app (e.g. app.example.com).

However, if you are installing the script on a subdomain (e.g. app.example.com), you will need to set the following option to make sure the cookie is accessible on the apex domain as well (e.g. example.com):

React

<DubAnalytics
  cookieOptions={{
    domain: ".example.com",
  }}
/>

The script also supports conversion tracking across entirely different domains.

This means that if you have the script installed on a separate domain (e.g. example.sh), you can use the outboundDomains prop to ensure that the dub_id cookie value is automatically appended to all outbound links targeting your main domain (e.g. example.com).

React

// install this script on both domains
<DubAnalytics
  domainsConfig={{
    outbound: ["example.com", "example.sh"],
  }}
/>

For outbound-domains support, you’ll need to use the script.outbound-domains.js variant of the script. Learn more about how script variants work.

Custom cookie window

By default, the script sets the dub_id cookie to expire in 90 days. You can customize this behavior by passing the cookieOptions prop to the script:

React

<DubAnalytics
  cookieOptions={{
    expiresInDays: 60, // setting the cookie to expire in 60 days
  }}
/>

Load the script via a reverse proxy

To avoid ad-blockers from blocking the @dub/analytics script, it is recommended to use a reverse proxy.

Depending on which backend framework you’re using, there are a few different ways to do this:

Next.js

// next.config.js
module.exports = {
  async rewrites() {
    return [
      {
        source: "/_proxy/dub/script.js",
        destination: "https://www.dubcdn.com/analytics/script.js",
      },
    ];
  },
};

Once you’ve set up your reverse proxy, don’t forget to update the scriptProps.src parameter in the <Analytics /> component to point to your proxy URL.

React/Next.js

import { Analytics as DubAnalytics } from "@dub/analytics/react";

export default function App() {
  return (
    <Layout>
      <DubAnalytics
        scriptProps={{
          src: "/_proxy/dub/script.js", // pointing to your reverse proxy
        }}
      />
      {/* Your app code here */}
    </Layout>
  );
}

Open-source examples

Here are some open-source code examples that you can referece:

Dub Analytics with Client-side Click Tracking + Reverse Proxy

See the full example on GitHub.

Dub Analytics with Geolocation

See the full example on GitHub.