Add click heatmaps report

Extracts click events from rrweb session-replay buffers at write time
into a new heatmap_event table (Prisma + ClickHouse). New /heatmaps
report shows a page picker plus an overlay of click density on the
dominant viewport, with an optional iframe of the live page behind.
This commit is contained in:
Mike Cao committed 2026-04-27 22:20:38 -07:00
1 parent 9da332c489
commit a6b13b71db
18 files changed
+831

No files matched your search

@@ -0,0 +1,79 @@
import { HEATMAP_EVENT_TYPE } from '@/lib/constants';
const RRWEB_TYPE_INCREMENTAL = 3;
const RRWEB_TYPE_META = 4;
const RRWEB_SOURCE_MOUSE_INTERACTION = 2;
const RRWEB_SOURCE_VIEWPORT_RESIZE = 4;
const RRWEB_MOUSE_CLICK = 2;
export interface ExtractedHeatmapEvent {
eventType: number;
nodeId: number | null;
x: number | null;
y: number | null;
viewportW: number | null;
viewportH: number | null;
scrollPct: number | null;
urlPath: string;
createdAt: Date;
}
function safePathname(href: unknown): string | null {
if (typeof href !== 'string') return null;
try {
return new URL(href).pathname || '/';
} catch {
return href.startsWith('/') ? href.split(/[?#]/)[0] : null;
}
}
export function extractHeatmapEvents(events: any[]): ExtractedHeatmapEvent[] {
if (!Array.isArray(events) || events.length === 0) return [];
let urlPath: string | null = null;
let viewportW: number | null = null;
let viewportH: number | null = null;
const out: ExtractedHeatmapEvent[] = [];
for (const ev of events) {
if (!ev || typeof ev !== 'object') continue;
if (ev.type === RRWEB_TYPE_META && ev.data) {
const path = safePathname(ev.data.href);
if (path) urlPath = path;
if (typeof ev.data.width === 'number') viewportW = ev.data.width;
if (typeof ev.data.height === 'number') viewportH = ev.data.height;
continue;
}
if (ev.type !== RRWEB_TYPE_INCREMENTAL || !ev.data) continue;
const d = ev.data;
if (d.source === RRWEB_SOURCE_VIEWPORT_RESIZE) {
if (typeof d.width === 'number') viewportW = d.width;
if (typeof d.height === 'number') viewportH = d.height;
continue;
}
if (
d.source === RRWEB_SOURCE_MOUSE_INTERACTION &&
d.type === RRWEB_MOUSE_CLICK &&
urlPath !== null
) {
out.push({
eventType: HEATMAP_EVENT_TYPE.click,
nodeId: typeof d.id === 'number' ? d.id : null,
x: typeof d.x === 'number' ? Math.round(d.x) : null,
y: typeof d.y === 'number' ? Math.round(d.y) : null,
viewportW,
viewportH,
scrollPct: null,
urlPath,
createdAt: new Date(typeof ev.timestamp === 'number' ? ev.timestamp : Date.now()),
});
}
}
return out;
}
+207
View File
@@ -0,0 +1,207 @@
import clickhouse from '@/lib/clickhouse';
import { HEATMAP_EVENT_TYPE } from '@/lib/constants';
import { CLICKHOUSE, PRISMA, runQuery } from '@/lib/db';
import prisma from '@/lib/prisma';
const FUNCTION_NAME = 'getHeatmap';
const POINT_LIMIT = 5000;
const PAGE_LIMIT = 100;
export interface HeatmapParameters {
startDate: Date;
endDate: Date;
urlPath?: string;
}
export interface HeatmapPage {
urlPath: string;
count: number;
sessions: number;
}
export interface HeatmapPoint {
nodeId: number | null;
x: number;
y: number;
viewportW: number;
viewportH: number;
count: number;
}
export interface HeatmapResult {
pages: HeatmapPage[];
points: HeatmapPoint[];
}
export async function getHeatmap(
websiteId: string,
parameters: HeatmapParameters,
): Promise<HeatmapResult> {
return runQuery({
[PRISMA]: () => relationalQuery(websiteId, parameters),
[CLICKHOUSE]: () => clickhouseQuery(websiteId, parameters),
});
}
async function relationalQuery(
websiteId: string,
{ startDate, endDate, urlPath }: HeatmapParameters,
): Promise<HeatmapResult> {
const { rawQuery } = prisma;
const pages: HeatmapPage[] = await rawQuery(
`
select
url_path as "urlPath",
count(*)::int as count,
count(distinct visit_id)::int as sessions
from heatmap_event
where website_id = {{websiteId::uuid}}
and event_type = {{eventType}}
and created_at between {{startDate}} and {{endDate}}
group by url_path
order by count desc
limit ${PAGE_LIMIT}
`,
{
websiteId,
eventType: HEATMAP_EVENT_TYPE.click,
startDate,
endDate,
},
FUNCTION_NAME,
);
if (!urlPath) {
return { pages, points: [] };
}
const rawPoints: HeatmapPoint[] = await rawQuery(
`
select
node_id as "nodeId",
x,
y,
viewport_w as "viewportW",
viewport_h as "viewportH",
count(*)::int as count
from heatmap_event
where website_id = {{websiteId::uuid}}
and event_type = {{eventType}}
and url_path = {{urlPath}}
and created_at between {{startDate}} and {{endDate}}
and x is not null
and y is not null
and viewport_w is not null
and viewport_h is not null
group by node_id, x, y, viewport_w, viewport_h
order by count desc
limit ${POINT_LIMIT}
`,
{
websiteId,
eventType: HEATMAP_EVENT_TYPE.click,
urlPath,
startDate,
endDate,
},
FUNCTION_NAME,
);
return { pages, points: rawPoints };
}
async function clickhouseQuery(
websiteId: string,
{ startDate, endDate, urlPath }: HeatmapParameters,
): Promise<HeatmapResult> {
const { rawQuery } = clickhouse;
const pageRows = await rawQuery<
{ urlPath: string; count: string | number; sessions: string | number }[]
>(
`
select
url_path as urlPath,
count() as count,
uniq(visit_id) as sessions
from heatmap_event
where website_id = {websiteId:UUID}
and event_type = {eventType:UInt8}
and created_at between {startDate:DateTime64} and {endDate:DateTime64}
group by url_path
order by count desc
limit ${PAGE_LIMIT}
`,
{
websiteId,
eventType: HEATMAP_EVENT_TYPE.click,
startDate,
endDate,
},
FUNCTION_NAME,
);
const pages: HeatmapPage[] = pageRows.map(p => ({
urlPath: p.urlPath,
count: Number(p.count),
sessions: Number(p.sessions),
}));
if (!urlPath) {
return { pages, points: [] };
}
const pointRows = await rawQuery<
{
nodeId: number | null;
x: number;
y: number;
viewportW: number;
viewportH: number;
count: string | number;
}[]
>(
`
select
node_id as nodeId,
x,
y,
viewport_w as viewportW,
viewport_h as viewportH,
count() as count
from heatmap_event
where website_id = {websiteId:UUID}
and event_type = {eventType:UInt8}
and url_path = {urlPath:String}
and created_at between {startDate:DateTime64} and {endDate:DateTime64}
and x is not null
and y is not null
and viewport_w is not null
and viewport_h is not null
group by node_id, x, y, viewport_w, viewport_h
order by count desc
limit ${POINT_LIMIT}
`,
{
websiteId,
eventType: HEATMAP_EVENT_TYPE.click,
urlPath,
startDate,
endDate,
},
FUNCTION_NAME,
);
const points: HeatmapPoint[] = pointRows.map(p => ({
nodeId: p.nodeId === null || p.nodeId === undefined ? null : Number(p.nodeId),
x: Number(p.x),
y: Number(p.y),
viewportW: Number(p.viewportW),
viewportH: Number(p.viewportH),
count: Number(p.count),
}));
return { pages, points };
}
@@ -0,0 +1,76 @@
import clickhouse from '@/lib/clickhouse';
import { uuid } from '@/lib/crypto';
import { CLICKHOUSE, PRISMA, runQuery } from '@/lib/db';
import kafka from '@/lib/kafka';
import prisma from '@/lib/prisma';
export interface HeatmapEventRow {
websiteId: string;
sessionId: string;
visitId: string;
urlPath: string;
eventType: number;
nodeId: number | null;
x: number | null;
y: number | null;
viewportW: number | null;
viewportH: number | null;
scrollPct: number | null;
createdAt: Date;
}
export async function saveHeatmapEvents(rows: HeatmapEventRow[]) {
if (!rows?.length) return;
return runQuery({
[PRISMA]: () => relationalQuery(rows),
[CLICKHOUSE]: () => clickhouseQuery(rows),
});
}
async function relationalQuery(rows: HeatmapEventRow[]) {
return prisma.client.heatmapEvent.createMany({
data: rows.map(r => ({
id: uuid(),
websiteId: r.websiteId,
sessionId: r.sessionId,
visitId: r.visitId,
urlPath: r.urlPath,
eventType: r.eventType,
nodeId: r.nodeId,
x: r.x,
y: r.y,
viewportW: r.viewportW,
viewportH: r.viewportH,
scrollPct: r.scrollPct,
createdAt: r.createdAt,
})),
});
}
async function clickhouseQuery(rows: HeatmapEventRow[]) {
const { insert, getUTCString } = clickhouse;
const { sendMessage } = kafka;
const messages = rows.map(r => ({
heatmap_event_id: uuid(),
website_id: r.websiteId,
session_id: r.sessionId,
visit_id: r.visitId,
url_path: r.urlPath,
event_type: r.eventType,
node_id: r.nodeId,
x: r.x,
y: r.y,
viewport_w: r.viewportW,
viewport_h: r.viewportH,
scroll_pct: r.scrollPct,
created_at: getUTCString(r.createdAt),
}));
if (kafka.enabled) {
return sendMessage('heatmap_event', messages);
}
return insert('heatmap_event', messages);
}
+3
View File
@@ -26,6 +26,9 @@ export * from './getValues';
export * from './getWebsiteDateRange';
export * from './getWebsiteStats';
export * from './getWeeklyTraffic';
export * from './heatmap/extractHeatmapEvents';
export * from './heatmap/getHeatmap';
export * from './heatmap/saveHeatmapEvents';
export * from './pageviews/getPageviewExpandedMetrics';
export * from './pageviews/getPageviewMetrics';
export * from './pageviews/getPageviewStats';