Custom tracking

Prerequisites

Custom tracking rides on the built-in cloak.js SDK. Load it on any page you want to instrument (it's already injected on cloaked pages):

<script src="https://YOUR_HOST/api/public/cloak.js?k=YOUR_SITE_KEY" async></script>

Once loaded, window.ShieldGate is available globally.

1. Auto-tracked events (no code)

These fire automatically as long as the SDK is on the page:

• pageview — on load and on every SPA route change (pushState / replaceState / popstate / hashchange).
• click — on any <a>, <button>, [role="button"], or element with a data-track attribute.
• download — on links with download or a known file extension.
• step_viewed — when a new [data-sg-step] node appears (see Wizards below).

Naming a click without JS

<button data-track data-sg-name="hero_cta">Get started</button>
<a href="/pricing" data-sg-name="nav_pricing">Pricing</a>

data-sg-name becomes the event name in the dashboard. Any data-sg-* attribute is forwarded as event metadata.

2. Programmatic API

// Generic custom event
ShieldGate.track('signup_started', { plan: 'pro', source: 'hero' });

// Funnel step (URL didn't change)
ShieldGate.step('checkout:shipping', { cart_size: 3 });

// Named button click
ShieldGate.button('add_to_cart', { sku: 'ABC-123', price: 19.99 });

// Conversion (auto-attaches first-click attribution)
ShieldGate.conversion(19.99, { order_id: 'o_42', currency: 'USD' });

All calls are non-blocking, batched, and flushed on page hide via navigator.sendBeacon, so they survive fast navigations.

3. Wizards / multi-step flows (URL doesn't change)

Tag the currently visible step and the SDK emits step_viewed automatically:

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

It also detects these patterns without any tagging:

• [aria-current="step"]
• [role="tabpanel"][aria-hidden="false"][data-step]
• [data-state="active"][data-step] (shadcn / Radix Tabs, Accordion, Stepper)

4. First-click attribution

The SDK pins the first meaningful click of each session in sessionStorage. Every event afterwards carries the session id, and ShieldGate.conversion(...) automatically attaches the first-click record as first_click in the event metadata. You can also read it directly:

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

5. Where events show up

• Dashboard → Analytics → Event funnel — aggregated counts for pageview / click / download / custom.
• Sites → your site → Visitors → Events — full stream of every event with URL, visitor, geo and device.
• Sites → your site → Visitors → Custom — only your ShieldGate.track events (built-in types filtered out).
• Click a bar in Event funnel or a slice in the Verdict mix to drill down into the matching rows. Use Export CSV to download the underlying data.

6. Server-to-server conversions

When the conversion happens on your backend (offer network callback), use the postback endpoint instead of the JS API:

GET /api/public/postback/YOUR_SITE_KEY
     ?cid=CLICK_ID
     &payout=1.20
     &status=approved
     &sig=HMAC_SHA256(query, hmac_secret)

The cid is the click id we passed to your destination as {shieldgate_cid}. See Tracking & analytics for Voluum / Binom templates.

7. Naming conventions

• Use snake_case: signup_started, not SignupStarted.
• Prefix funnel steps with the flow: checkout:payment, onboarding:profile.
• Keep metadata keys stable — they become columns in CSV exports.
• Don't put PII (email, name) in event names or metadata.

Troubleshooting

• Nothing shows up — open DevTools → Network, look for POSTs to /api/public/track. If missing, the SDK isn't loaded; check the <script> tag and site key.
• Events land in "click" instead of custom — you're relying on data-track. Use ShieldGate.track(name) for a truly custom event type.
• SPA route changes not counted — confirm your router uses history.pushState. Hash routers work too.