Introduction

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

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

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.

If you’re using Dub Partners, this script also lets you 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

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

React

Manual installation

Framer

Shopify

WordPress

Webflow

Google Tag Manager

Features

The @dub/analytics script comes with the following features:

• Conversion-tracking
• Client-side click-tracking
• Cross-domain tracking
• Reverse-proxy support

Properties

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}'
></script>

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-query-param · string · default: "via"

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

Open-source examples

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

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.