nudgekit-analytics
v0.6.0
Published
Privacy-light web analytics for NudgeKit with tracking, heatmaps, replay, and a live visitors widget.
Downloads
1,870
Maintainers
mohdadnaanazamReadme
nudgekit-analytics
Privacy-light web analytics for NudgeKit. Drop-in tracking plus an optional public live-visitors widget.
Events are sent to https://api.nudgekit.app — no API URL configuration needed.
Install
npm i nudgekit-analytics
# pnpm i nudgekit-analytics
# yarn add nudgekit-analytics
# bun add nudgekit-analyticsNext.js (recommended)
Add the component to your root layout:
// app/layout.tsx
import { Analytics } from "nudgekit-analytics";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
{children}
<Analytics siteId="site_your_id" />
</body>
</html>
);
}Get siteId from NudgeKit Analytics → site → Settings.
React (SPA)
import { Analytics } from "nudgekit-analytics";
export default function App() {
return (
<>
{/* your app */}
<Analytics siteId="site_your_id" />
</>
);
}Live visitors widget (optional)
Add the public 30-minute widget anywhere on your React or Next.js site:
import { AnalyticsWidget } from "nudgekit-analytics";
export function LiveVisitors() {
return <AnalyticsWidget siteId="site_your_id" />;
}It renders a responsive dark card with total unique visitors, a 30-bar minute chart, the top three countries, and NudgeKit attribution. Data refreshes every 30 seconds and only aggregate counts are exposed—visitor and session ids are never returned.
Use it alongside <Analytics /> so visits are tracked:
<>
<Analytics siteId="site_your_id" />
<AnalyticsWidget siteId="site_your_id" />
</>Widget options
| Option | Default | Description |
|--------|---------|-------------|
| siteId | required | Public site id used by <Analytics /> |
| refreshIntervalMs | 30000 | Refresh frequency; 0 fetches once (minimum non-zero value: 10s) |
| accentColor | #df704a | Bar and live-dot color |
| title | Users in last 30 minutes | Custom card heading |
| showBranding | true | Show the “Powered by NudgeKit” footer |
| locale | browser locale | Number and chart-time locale |
| timeZone | browser time zone | IANA time zone for chart labels |
| baseUrl | NudgeKit API | Optional self-hosted/local API override |
| data | — | Controlled widget data; disables fetching and polling |
| className / style | — | Size and position the responsive widget |
| onError | — | Called if public widget data cannot be loaded |
<AnalyticsWidget
siteId="site_your_id"
accentColor="#14b8a6"
refreshIntervalMs={60_000}
style={{ maxWidth: 520 }}
/>Tracking options
| Option | Default | Description |
|--------|---------|-------------|
| siteId | required | Public site id from NudgeKit Analytics (e.g. site_xxx) |
| autoTrack | true | Initial pageview + SPA history changes |
| heartbeat | true | Online presence while tab is visible |
| heartbeatIntervalMs | 30000 | Heartbeat interval |
| timeoutMs | 10000 | Request timeout |
| heatmaps | off | Opt-in click + scroll capture (see below) |
Heatmaps (opt-in)
<Analytics
siteId="site_your_id"
heatmaps={{
sampleRate: 0.2, // customer default; use 1 for dogfood
captureText: false, // element labels off by default
includePaths: ["/"], // exact pathnames only
}}
/>Sampled heatmap sessions also send one privacy-masked DOM snapshot per visited path. Inputs and visible text are masked before upload. This lets the dashboard reconstruct authenticated/private page layouts without collecting login credentials or cookies. Use data-nk-snapshot-block to remove a sensitive subtree entirely.
Without heatmaps, behavior is unchanged from earlier versions.
Session replay (opt-in)
Record masked visitor sessions and view complete journeys in the NudgeKit dashboard:
<Analytics
siteId="site_your_id"
sessionReplay={{
sampleRate: 0.1,
includePaths: ["/", "/pricing"],
}}
/>Identify a signed-in visitor with your own stable, non-email user id:
import { identify, resetIdentity } from "nudgekit-analytics";
identify("user_123");
// On logout:
resetIdentity();Inputs are always masked. Add data-nk-snapshot-block to replace a sensitive subtree and data-nk-snapshot-ignore to ignore its mutations. Session replay is off unless sessionReplay is provided. Every recording has a hard 30-minute maximum; longer visits are split into fresh recording segments.
Imperative API
import { initAnalytics, track, trackPageview, destroyAnalytics } from "nudgekit-analytics";
await initAnalytics({ siteId: "site_xxx" });
await trackPageview();
await track("signup_completed", { plan: "free" });
destroyAnalytics();What is tracked
- pageview — on load + SPA history changes
- heartbeat — every 30s while the tab is visible (online count)
- event — a named custom conversion event sent with
track(name, properties) - view — one sampled behavior-view per allowed page path when heatmaps are enabled
- click — normalized click positions; form values are never captured
- scroll — 25/50/75/100% reach milestones
- page snapshot — one masked DOM state per sampled path for heatmap backgrounds
Give important elements a privacy-safe dashboard label without enabling general text capture:
<button data-nk-label="Hero signup CTA">Start free</button>- click / scroll — only when
heatmapsis enabled (batched)
Visitor id lives in localStorage. Session rotates after 30 minutes idle.
License
MIT