TrackIQ SDK
Privacy-first, cookieless web analytics. Install the SDK, track pageviews, custom events and Core Web Vitals in minutes — GDPR compliant by default.
Introduction
TrackIQ is a privacy-first analytics platform: no third-party cookies, GDPR compliant out of the box. The @upperz/trackiq-sdk package is the web client — it collects pageviews, engagement signals and Core Web Vitals, and sends them to your TrackIQ project.
All the data it collects becomes visible in your TrackIQ dashboard — no configuration beyond installing the SDK.
What you get
Once the SDK is running, this is what shows up in your dashboard — no extra setup required.
Audience
Unique, new and returning visitors, session duration, bounce and deep-session rate, identified users once you call .identify(), plus a retention view with week-over-week cohort tables.
Behavior
Per-page views, entry/exit and scroll-completion rates, click and move heatmaps rendered from real cursor data, engagement (scroll depth, active time), and a feed of both automatic and custom events with conversion rates.
Performance
Core Web Vitals — LCP, INP, CLS, FCP, TTFB — with median and p75, broken down by page and device, plus good / needs-improvement / poor rate buckets.
Sources & geography
Channels (organic, direct, social, paid, email, referral), referrers and UTM campaigns, country- and city-level sessions, and a device/browser/OS/connection breakdown.
Installation
npm install @upperz/trackiq-sdkGet your API key
- 1Create an account at admin-trackiq.upperz.africa — 90 days free, no credit card required.
- 2Go to Settings → API Keys.
- 3Click Create key, and give it a name and a project name (e.g. "Production").
- 4Copy the raw key immediately.
The raw key is shown once. Only its SHA-256 hash is stored afterward — if you lose it, revoke it and create a new one.
Quick start
TrackIQ ships a framework-agnostic core plus wrappers for React, Next.js and Vue.
'use client'
import { TrackIQProvider } from '@upperz/trackiq-sdk/next'
export default function Providers({ children }: { children: React.ReactNode }) {
return (
<TrackIQProvider apiKey={process.env.NEXT_PUBLIC_TRACKIQ_API_KEY!}>
{children}
</TrackIQProvider>
)
}Configuration reference
Options accepted by new TrackIQ(config) and by every framework wrapper.
| Field | Type | Default | Description |
|---|---|---|---|
| apiKey | string | required | Public write key shown once at creation (format tk_live_...). Safe to expose client-side. |
| dataEndpoint | string | SDK-internal fallback | Ingestion API endpoint for behavioral data. Get the value for your environment from your project settings — don't rely on the built-in fallback. |
| selfHosted | boolean | false | Enable only for enterprise self-hosted deployments where data goes to your own server. Sends an anonymized consumption ping to TrackIQ cloud for license billing. |
| debug | boolean | false | Enable verbose console logging. |
| referrer | string | document.referrer | Override the referrer for this page. Required for correct pageview chaining in single-page apps. |
| consent | boolean | undefined | undefined | true tracks immediately, false tracks nothing, undefined shows the SDK's built-in consent banner. |
| consentBanner | ConsentBannerConfig | — | Customize the built-in consent banner. Only used when consent is undefined. |
Always pass dataEndpoint explicitly with the ingestion URL from your project settings — don't rely on the SDK's built-in fallback.
API reference
The TrackIQ instance is also exposed on window.trackiq, useful for calling it from inline HTML or outside your app's bundle.
trackiq.event(type: string, data?: Record<string, unknown>): voidTracks a custom business event.
trackiq.event('signup_completed', { plan: 'pro' })trackiq.identify(userId: string, userInfo?: Record<string, unknown>): voidLinks the current anonymous visitor to an authenticated user. Call right after login.
trackiq.identify('user_123', { email: 'jane@company.com', plan: 'pro' })trackiq.reset(): voidClears the linked user identity on logout. The visitor_id is preserved — it identifies the device, not the account.
trackiq.reset()trackiq.destroy(): voidRemoves all event listeners and flushes a final pageview. Call on SPA route changes or when a framework component unmounts.
trackiq.destroy()What's tracked automatically
- Pageviews, sent on page unload
- Scroll depth and 25/50/75/90% milestones
- Active / engaged time (idle after 30s, paused on hidden tabs)
- Mouse path (throttled, max 30 points per page)
- Exit intent
- Rage clicks (3+ clicks in the same area within 1s)
- Clicks, with selector and text
- Text selection (max 200 characters)
- Core Web Vitals — LCP, INP, CLS, FCP, TTFB
- Device, browser, network and locale context
Form field values (input, textarea, select, password) are never captured by click, text-selection or mouse-path tracking.
Self-hosted / enterprise
For enterprise plans running their own ingestion server, set selfHosted: true and point dataEndpoint at your own API. Behavioral data goes to your server; the SDK additionally sends a lightweight, anonymized consumption ping (a hash of your key, no behavioral data) to TrackIQ cloud for license billing.
new TrackIQ({
apiKey: 'tk_live_xxxxxxxxxxxx',
dataEndpoint: 'https://analytics.your-domain.com',
selfHosted: true,
})