Tracker (t.js)

t.js is the only client-side code you need to install. It captures referral parameters, writes first-party cookies, posts a click event on every page load, and exposes a small JavaScript API for things like custom events and the post-purchase recruit widget. The shipping bundle is 2.7 KB gzipped.

Install

<script async
  src="https://affiliate.cobalz.com/t.js"
  data-merchant="<YOUR_MERCHANT_UUID>"
  data-merchant-slug="<your-program-slug>"
></script>

Script attributes

• data-merchant — your merchant UUID (required). Find it on the dashboard's overview page.
• data-merchant-slug — your program slug. Optional, but required for window.cobz.recruit() to build a signup URL.
• data-api — override the API base if you're self-hosting. Defaults to https://affiliate.cobalz.com.
• data-cookie-days — first-party cookie TTL in days. Default 90. Capped at 365.

What it does on page load

• Reads ?ref, ?aff, or ?cobz from the URL and stores the value in a 90d cookie (_cobz_ref).
• Issues a session id (_cobz_sess) on first hit and mirrors it to localStorage.
• POSTs a pageview to /api/t/click with UTM params, referrer, viewport, user agent, language, and DNT flag.
• Uses navigator.sendBeacon when available; falls back to fetch(... {keepalive: true}).

Consent

The tracker honors three sources of consent, in order of precedence:

• Google Consent Mode v2 — checks window.dataLayer for the most recent consent.update call. analytics_storage=denied means cookies-only mode (no network beacon).
• GPC (Global Privacy Control) — navigator.globalPrivacyControl=true drops to cookies-only.
• DNT (Do Not Track) — navigator.doNotTrack='1' drops to cookies-only.

JavaScript API

After load, window.cobz exposes:

interface CobzApi {
  version: string;
  ref: string | null;       // current referral slug
  session: string | null;   // session id
  track(event: string, props?: Record<string, unknown>): void;
  pageview(): void;
  recruit(args?: { email?: string; name?: string;
                   headline?: string; body?: string; ctaText?: string }): void;
}

First-party redirect links

Every tracking link is served through a first-party redirect at /r/<merchant>/<link>. The click is recorded on our server before the browser is 302'd to the destination, so it counts even when the visitor blocks scripts or ads — the JS beacon is a progressive enhancement, not a requirement. The redirect also sets the same first-party _cobz_ref / _cobz_sess cookies the tracker reads.

Sub-IDs & click-IDs

Append sub1…sub5 to any link to segment your own traffic; the values are stored on the click and the session and surface in your reports. Paid-ad click identifiers (gclid, fbclid, ttclid, msclkid) are captured automatically on both the redirect and JS paths.

https://affiliate.cobalz.com/r/acme/spring-sale?sub1=youtube&sub2=video-42

Custom events

// On any meaningful interaction:
window.cobz?.track('cart_added', { sku: 'WIDGET-1', value: 49 });
window.cobz?.track('newsletter_signup');

Events POST to /api/t/event and land in the events table; they're queryable via the REST API.

Post-purchase recruit widget

On your order-confirmation page, call:

window.cobz?.recruit({
  email: '${order.customer.email}',
  name: '${order.customer.first_name}',
});

That opens a small modal inviting the customer to apply as an affiliate. Click-through opens your signup page with email + name prefilled. Customize the copy with the optionalheadline, body, and ctaText arguments.

Performance

• Bundle: 2.7 KB gzipped.
• SRI-pinned: every release includes an integrity hash in our changelog.
• Async: never blocks page load. The script tag itself uses async.
• One POST per page load (the click event). Custom events are also one POST each.