Introduction

@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:

​

Concepts

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

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

​

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):

<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).

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

​

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:

<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.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.

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: