Script Configuration

The Clickport tracker works out of the box with just the data-domain attribute, but there are several options for customizing its behavior.

Script attributes

The tracker reads configuration from attributes on the <script> tag:

data-domain

The primary way to associate events with your site. Set this to your registered domain without https:// or www.:

<script defer data-domain="example.com"
  src="https://clickport.io/tracker.js"></script>

If data-domain is omitted, the tracker falls back to location.hostname with www. stripped. This means it works without the attribute if your registered domain matches your actual hostname, but it's better to be explicit.

data-site

Authenticate with an API key instead of domain matching. This is useful when the page's hostname differs from your registered site domain (e.g. staging environments, embedded widgets, or third-party platforms):

<script defer data-site="ck_your_api_key_here"
  src="https://clickport.io/tracker.js"></script>

When data-site is present, it takes priority over data-domain. Generate API keys in your dashboard under Settings.

Tip: You can use both attributes together. data-site handles authentication while data-domain is still sent for display purposes.

cpConfig object

For more advanced configuration, define a window.cpConfig object before the tracker script loads:

<script>
  window.cpConfig = {
    api: 'https://your-proxy.example.com',
    key: 'ck_your_api_key_here',
    is_404: true
  };
</script>
<script defer data-domain="example.com"
  src="https://clickport.io/tracker.js"></script>

Available properties:

api - Override the API endpoint URL. Used for proxying the tracker through your own domain.
key - API key for authentication. Same as data-site but set via JavaScript. The data-site attribute takes priority if both are present.
is_404 - Force this page to be flagged as a 404 error page. By default, the tracker auto-detects 404s by checking if the page title contains "404" or "not found" (case-insensitive). Use this when your error page has a custom title.

Self-exclusion

Flip the Exclude my visits toggle on the Dashboard tab of the settings modal (gear icon). The dashboard opens your site in a new tab with ?clickport_exclude=1, and the tracker flips a localStorage flag on that device. Every future visit from that browser is skipped before sending any event. Repeat on each device and site you want to exclude.

You can also set the flag manually in the browser console:

localStorage.setItem('clickport_ignore', 'true')

Or visit https://yoursite.com/?clickport_exclude=1 directly on the device. To re-enable tracking, flip the toggle off, visit ?clickport_exclude=0, or run localStorage.removeItem('clickport_ignore').

See Exclude Your Visits for the full guide including team exclusion and troubleshooting.

What the tracker collects automatically

The tracker is composed of several modules that run automatically. No configuration is needed for any of these:

Pageviews

Every page load sends a pageview event with the current URL, referrer, viewport width, timezone, and any UTM parameters from the query string (utm_source, utm_medium, utm_campaign, utm_content, utm_term).

SPA navigation

The tracker intercepts history.pushState, history.replaceState, and the popstate event. When the URL changes, a new pageview is sent automatically. No extra configuration is needed for React, Vue, Next.js, Nuxt, Angular, or any other SPA framework. See SPA Tracking for edge cases.

Engagement

Active time on page and scroll depth are tracked continuously. The tracker measures active time (pausing when the tab is hidden or blurred) and records the maximum scroll depth as a percentage. This data is sent on page leave via pagehide and beforeunload events. See Engagement for how these metrics work.

Outbound links

Clicks on links pointing to external domains are tracked automatically. The tracker captures the destination URL and the link text. It also detects /go/ affiliate redirect links on your own domain. See Outbound Links.

File downloads

Clicks on links to downloadable files are tracked automatically. Detected file extensions: .pdf, .zip, .doc, .docx, .xls, .xlsx, .csv, .ppt, .pptx, .rar, .7z, .gz, .tar, .mp3, .mp4, .mov, .avi, .dmg, .exe.

Form submissions

When a form is submitted, the tracker sends an event with the form's id or name attribute. No form data is collected, only the identifier. See Forms.

Copy detection

When a visitor copies text on your page, the tracker sends an event with the first 200 characters of the copied text. This helps you understand which content visitors find most valuable.

404 detection

Pages with "404" or "not found" in the title are automatically flagged as error pages and appear in the Error Pages panel on the dashboard.

Sessions

Clickport uses browser-tab-based sessions. A session starts when a visitor opens your site in a new tab and ends when the tab is closed. There is no 30-minute inactivity timeout (unlike Google Analytics or Plausible). The session ID is stored in sessionStorage, which is automatically cleared when the tab closes.

Visitor identity is based on a daily-rotating anonymous ID that changes at midnight in your site's configured timezone. This means the same visitor gets a new ID each day, preserving privacy while still allowing same-day session tracking.

Proxying the tracker

If ad blockers are blocking the tracker on your site, you can serve it through your own domain. This involves two steps:

Serve the tracker file from your own URL (e.g. /js/analytics.js)
Proxy the API endpoint (/api/event) through your own server

Then configure the tracker to use your proxy:

<script>
  window.cpConfig = {
    api: 'https://example.com/stats'
  };
</script>
<script defer data-domain="example.com"
  src="/js/analytics.js"></script>

The api setting tells the tracker to send events to https://example.com/stats/api/event instead of https://clickport.io/api/event. Your proxy should forward these requests to https://clickport.io/api/event with the original headers and body intact.

Nginx example

location /stats/api/event {
    proxy_pass https://clickport.io/api/event;
    proxy_set_header Host clickport.io;
    proxy_set_header X-Forwarded-For $remote_addr;
}

location /js/analytics.js {
    proxy_pass https://clickport.io/tracker.js;
    proxy_set_header Host clickport.io;
    expires 5m;
}

Testing and development

The tracker auto-disables on localhost, 127.0.0.1, and file:// URLs. It also disables when it detects common testing and automation tools.

To force tracking during development:

<script>window.__CP_TEST__ = true;</script>
<script defer data-domain="yourdomain.com"
  src="https://clickport.io/tracker.js"></script>

Important: Remove the __CP_TEST__ flag before deploying to production. It bypasses all safety checks that prevent automated tools from generating fake traffic.

Script size

The full tracker (all modules) is under 5 KB gzipped. It loads with defer so it never blocks page rendering. There are no external dependencies, no cookies, and no localStorage usage beyond the optional self-exclusion flag.

Previous SPA Tracking Next Chrome Extension