Client-side click-tracking

• You’re running a referral program with dual-sided incentives and want to display a banner that says: “John referred you to Acme and gave you 25% off”
• You have dynamically generated referral pages (e.g. Tesla) and want to track clicks using a trackClick() function inside your application code.
• You are migrating from an existing affiliate management platform (e.g. Rewardful) that uses query parameters to track conversions.

​

Quickstart

1

Add a custom domain to your CodeQR project

First, you’ll need to add a custom short link domain to your CodeQR project. 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 CodeQR.

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 CodeQR. To do that, navigate to your project’s Analytics settings page and add your site’s domain to the Allowed Hostnames list.

When testing things out locally, you can add localhost to the Allowed Hostnames list temporarily. This will allow local events to be ingested by CodeQR. Don’t forget to remove it once you’re ready to go live!

3

Install the CodeQR client-side SDK

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

React/Next.js

Other Frameworks

// install the package (e.g. npm install @codeqr/analytics)
import { Analytics as CodeQRAnalytics } from "@codeqr/analytics/react";

export default function App() {
  return (
    <Layout>
      <CodeQRAnalytics
        domainsConfig={{
          refer: "go.example.com", // the custom domain you're using on CodeQR 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.codeqr.io"

The base URL for the CodeQR 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 CodeQR will track. The following properties are available:

Show properties

​

refer

string

The CodeQR custom domain for referral program client-side click tracking (previously shortDomain). Example: refer.codeqr.io

​

site

string

The CodeQR short domain for tracking site visits. Example: site.codeqr.io

​

outbound

string | string[]

An array of domains for cross-domain tracking. When configured, the existing cq_id cookie will be automatically appended to all outbound links targeting these domains to enable cross-domain tracking across different applications. Example: ["codeqr.link", "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 linkFor 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 cq_id cookie is being set upon a successful /track/click request.
3. The click tracked correctly in the Events tab of your CodeQR project.

​

Manually tracking clicks with the trackClick() function

• Dynamically generated referral pages (e.g. Tesla)
• Dynamic user-generated content/webpages:
  • CodeQR’s public analytics dashboards (e.g. app.codeqr.io/share/:slug)
  • Tella’s video pages (e.g. tella.tv/video/:slug)

​

Differences from server-side click-tracking