Introduction

Dub Analytics (@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.

A diagram showing how click events are tracked in the conversion funnel

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:

Features#

The Dub Analytics script comes with the following features:

Properties#

You can pass the following props to the Dub Analytics script to customize its behavior:

data-api-hosturl#

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

Default: "https://api.dub.co"

data-attribution-modelfirst-click | 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.

Default: "last-click"

data-cookie-optionsJSON-stringified object#

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

Show properties

domainstring#

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

expiresinteger#

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

Default: "90"

expiresInDaysinteger#

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>

Default: "90"

pathstring#

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

Default: "/"

data-domainsJSON-stringified object#

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

Show properties

referstring#

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

sitestring#

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

outboundstring | 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-paramsstring[]#

An array of query parameters to listen to for client-side click-tracking (e.g. ?via=abc123).

Default: "[\"via\"]"

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.