Tracking & analytics

What gets tracked

• Decisions — every /decide call, with verdict and reason
• Pageviews — path, referrer, UTM tags, device, geo. SPA route changes (React Router / Vue Router / history.pushState / replaceState / popstate / hashchange) are captured instantly via history hooks — no polling.
• Clicks — every <a> / <button> when the SDK is loaded, including CSS selector, visible text, tag name, type/role, link href + target, name/data-sg-name, and the full page URL + title at click time
• Wizard / step transitions — automatic step_viewed whenever a matching DOM node appears or its state flips (see “Wizard tracking” below)
• Downloads — files linked from your pages
• Conversions — via postback or ShieldGate.conversion(...), with first-click attribution attached automatically
• Custom events — anything you send via ShieldGate.track

Where to see it

• Dashboard → Analytics — totals, trend charts, bot vs. human split
• Sites → your site → Visitors — live feed with session drill-down (click → step → conversion)
• Sites → your site → Stats — per-destination performance
• Admin → Monitoring — system-wide activity (admin only)

All views update in near-real time — under one second from event to screen — via a Postgres change stream (see /stream endpoints).

Client SDK API

Once tracker.js is on the page, a global window.ShieldGate object is exposed. Use it to record custom funnel steps, button clicks, and conversions from your app code:

// Fire a custom funnel event
ShieldGate.track('signup_started', { plan: 'pro' });

// Named step in a flow → emits 'step_viewed'
ShieldGate.step('checkout:shipping', { cart_size: 3 });

// Named button click → emits 'button_clicked'
ShieldGate.button('add_to_cart', { sku: 'ABC-123' });

// Record a conversion with first-click attribution
ShieldGate.conversion(19.99, { order_id: 'o_42' });

// Attribution helpers
ShieldGate.getFirstClick(); // { sel, ts, h, p, t } or null
ShieldGate.sessionId();     // current session id

First-click attribution

The SDK pins the first click of each session in sessionStorage. Every subsequent event carries the session id, and calling ShieldGate.conversion(...) automatically attaches the first-click record to the conversion event's metadata as first_click: { sel, ts, h, p, t }. The dashboard uses this to render the click → step → conversion path per visitor, and the CSV / NDJSON export includes it verbatim.

Wizard tracking (URL doesn't change)

Multi-step flows that swap panels without changing the URL are tracked automatically. The SDK observes the DOM and emits step_viewed whenever it sees a new match for any of these selectors:

• [data-sg-step="…"] (recommended — you control the name)
• [aria-current="step"]
• [role="tabpanel"][aria-hidden="false"][data-step]
• [data-state="active"][data-step] (matches shadcn/Radix Tabs, Accordion, Stepper)

Explicit tagging is easiest — just add the attribute to the visible step:

<section data-sg-step="checkout:payment">…</section>

You can also call ShieldGate.step('checkout:payment') manually when you'd rather not touch markup.

Conversion postbacks

Send conversions from your tracker or offer network:

GET /api/public/postback/YOUR_SITE_KEY
     ?cid=CLICK_ID
     &payout=1.20
     &status=approved
     &sig=HMAC_SHA256

The cid must match the click ID we passed to your destination (available as {shieldgate_cid} macro).

Voluum

Postback URL:
  https://your-host/api/public/postback/SITE_KEY?cid={clickid}&payout={payout}&status={status}&sig=...

Binom

Postback URL:
  https://your-host/api/public/postback/SITE_KEY?cid={clickid}&payout={revenue}&status=approved&sig=...

Session replay & heatmap

On Pro plans and above, ShieldGate records anonymized mouse-move / click paths per session. Open a session from Sites → Visitors and click Replay.

Retention

Exporting

Export events as CSV or NDJSON from Analytics → Export, or schedule a recurring export to S3-compatible storage in Admin → ML Data. Click rows include the full metadata JSON (tag, type, target, name, url, title, first_click flag).