πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Refactor funnel analytics to use sessions instead of visitors
Bill Yang4a01c7a2bd18
diff --git a/client/src/api/analytics/endpoints/funnels.ts b/client/src/api/analytics/endpoints/funnels.tsindex 5a1daacc4..ed6b58379 100644--- a/client/src/api/analytics/endpoints/funnels.ts+++ b/client/src/api/analytics/endpoints/funnels.ts@@ -49,7 +49,7 @@ export type SaveFunnelRequest = {export type FunnelResponse = {step_number: number;step_name: string;- visitors: number;+ sessions: number;conversion_rate: number;dropoff_rate: number;};diff --git a/client/src/app/[site]/funnels/components/Funnel.tsx b/client/src/app/[site]/funnels/components/Funnel.tsxindex 17862a3a4..422c52cc8 100644--- a/client/src/app/[site]/funnels/components/Funnel.tsx+++ b/client/src/app/[site]/funnels/components/Funnel.tsx@@ -14,7 +14,7 @@ import { useStore } from "../../../../lib/store";export type FunnelChartData = {stepName: string;- visitors: number;+ sessions: number;conversionRate: number;dropoffRate: number;stepNumber: number;@@ -58,12 +58,12 @@ function FunnelStepComponent({ step, index, steps, chartData, firstStep, siteIdconst { time } = useStore();const maxBarWidth = 100;- const ratio = firstStep?.visitors ? step.visitors / firstStep.visitors : 0;+ const ratio = firstStep?.sessions ? step.sessions / firstStep.sessions : 0;const barWidth = Math.max(ratio * maxBarWidth, 0);const prevStep = index > 0 ? chartData[index - 1] : null;- const droppedFromPrevious = prevStep ? prevStep.visitors - step.visitors : 0;- const dropoffPercent = prevStep ? (droppedFromPrevious / prevStep.visitors) * 100 : 0;+ const droppedFromPrevious = prevStep ? prevStep.sessions - step.sessions : 0;+ const dropoffPercent = prevStep ? (droppedFromPrevious / prevStep.sessions) * 100 : 0;const isFirstStep = index === 0;// Fetch sessions for "reached" mode@@ -134,7 +134,7 @@ function FunnelStepComponent({ step, index, steps, chartData, firstStep, siteId{/* Metrics */}<div className="shrink-0 min-w-[130px] mr-4 space-y-1"><div className="flex items-baseline">- <span className="text-base font-semibold">{step.visitors.toLocaleString()}</span>+ <span className="text-base font-semibold">{step.sessions.toLocaleString()}</span><span className="text-sm text-neutral-500 dark:text-neutral-400 ml-1">{t("sessions")}</span></div>{index !== 0 && (@@ -151,7 +151,7 @@ function FunnelStepComponent({ step, index, steps, chartData, firstStep, siteId<divclassName="absolute h-full rounded-md"style={{- width: `${(step.visitors / prevStep.visitors) * 100}%`,+ width: `${(step.sessions / prevStep.sessions) * 100}%`,background: `repeating-linear-gradient(45deg,rgba(16, 185, 129, 0.25),@@ -175,7 +175,7 @@ function FunnelStepComponent({ step, index, steps, chartData, firstStep, siteId<div className=" ml-4 p-4"><Tabs value={currentTab} onValueChange={val => setCurrentTab(val as "reached" | "dropped")}><TabsList className="mb-1">- <TabsTrigger value="reached">{t("Reached ({count})", { count: step.visitors.toLocaleString() })}</TabsTrigger>+ <TabsTrigger value="reached">{t("Reached ({count})", { count: step.sessions.toLocaleString() })}</TabsTrigger>{!isFirstStep && (<TabsTrigger value="dropped">{t("Dropped Off ({count})", { count: droppedFromPrevious.toLocaleString() })}</TabsTrigger>)}@@ -221,7 +221,7 @@ export function Funnel({ data, steps, isError, error, isPending }: FunnelProps)const chartData =data?.map(step => ({stepName: step.step_name,- visitors: step.visitors,+ sessions: step.sessions,conversionRate: step.conversion_rate,dropoffRate: step.dropoff_rate,stepNumber: step.step_number,diff --git a/client/src/app/[site]/user/[userId]/page.tsx b/client/src/app/[site]/user/[userId]/page.tsxindex 54c1f7bee..c5bad992f 100644--- a/client/src/app/[site]/user/[userId]/page.tsx+++ b/client/src/app/[site]/user/[userId]/page.tsx@@ -56,9 +56,14 @@ export default function UserPage() {const sessionsRef = useRef<HTMLDivElement>(null);const { data, isLoading } = useUserInfo(Number(site), userId);- const { data: sessionCount, isLoading: isLoadingCalendar } = useGetUserSessionCount(userId);+ // The route can still be a device fingerprint after that device has been+ // identified β the server resolves the alias for user info, so every other panel+ // has to query the identity it resolved to or they all come back empty. Anonymous+ // visitors have no identified_user_id, so they keep querying the route id.+ const queryUserId = data?.identified_user_id || userId;+ const { data: sessionCount, isLoading: isLoadingCalendar } = useGetUserSessionCount(queryUserId);const { data: sessionsData, isLoading: isLoadingSessions } = useGetSessions({- userId,+ userId: queryUserId,page: page,limit: LIMIT + 1,});@@ -143,8 +148,8 @@ export default function UserPage() {row-reverse puts the profile rail back on the left on desktop */}<div className="flex flex-col gap-4 lg:flex-row-reverse"><div className="flex-1 min-w-0 space-y-4">- <UserTopPages userId={userId} />- <UserJourneys userId={userId} />+ <UserTopPages userId={queryUserId} />+ <UserJourneys userId={queryUserId} /><div ref={sessionsRef} className="scroll-mt-4 space-y-3"><SessionsListsessions={sessions}@@ -153,7 +158,7 @@ export default function UserPage() {onPageChange={setPage}hasNextPage={hasNextPage}hasPrevPage={hasPrevPage}- userId={userId}+ userId={queryUserId}headerElement={<div className="flex items-center gap-2"><h2 className="text-sm font-medium text-neutral-700 dark:text-neutral-200">{t("Sessions")}</h2>diff --git a/client/src/app/rollup/components/MainSection/MainSection.tsx b/client/src/app/rollup/components/MainSection/MainSection.tsxindex 4083af34a..cfea18a41 100644--- a/client/src/app/rollup/components/MainSection/MainSection.tsx+++ b/client/src/app/rollup/components/MainSection/MainSection.tsx@@ -9,6 +9,7 @@ import { Skeleton } from "@/components/ui/skeleton";import { cn, formatSecondsAsMinutesAndSeconds } from "@/lib/utils";import { StatType, useStore } from "@/lib/store";import { useRollupBucketed } from "../../hooks/useRollupBucketed";+import { useRollupOverview } from "../../hooks/useRollupOverview";import { Chart } from "./Chart";type SiteRow = GetSitesFromOrgResponse["sites"][number];@@ -81,6 +82,12 @@ export function MainSection({bucket,lite,});+ // Stat cards read range totals; the chart reads the bucketed series.+ const { overviews, isLoading: isLoadingOverview } = useRollupOverview({+ siteIds,+ lite,+ });+ const statsLoading = isLoading || isLoadingOverview;const siteMetaById = useMemo(() => {const m = new Map<@@ -93,7 +100,10 @@ export function MainSection({return m;}, [sites]);- // Aggregate totals across all sites and time buckets.+ // Aggregate totals across sites from each site's range total, NOT by summing the+ // chart's buckets: a distinct-user count isn't additive over time, so summing+ // buckets counts anyone active on two days twice and makes the headline number+ // depend on the bucket size. Rates stay session-weighted across sites.const totals = useMemo(() => {let pageviews = 0;let sessions = 0;@@ -101,15 +111,14 @@ export function MainSection({let weightedBounce = 0;let weightedDuration = 0;let weightedPagesPerSession = 0;- for (const s of series) {- for (const b of s.data) {- pageviews += b.pageviews;- sessions += b.sessions;- users += b.users;- weightedBounce += b.bounce_rate * b.sessions;- weightedDuration += b.session_duration * b.sessions;- weightedPagesPerSession += b.pages_per_session * b.sessions;- }+ for (const o of overviews) {+ const d = o.data;+ pageviews += d.pageviews;+ sessions += d.sessions;+ users += d.users;+ weightedBounce += d.bounce_rate * d.sessions;+ weightedDuration += d.session_duration * d.sessions;+ weightedPagesPerSession += d.pages_per_session * d.sessions;}return {pageviews,@@ -119,7 +128,7 @@ export function MainSection({session_duration: sessions ? weightedDuration / sessions : 0,pages_per_session: sessions ? weightedPagesPerSession / sessions : 0,};- }, [series]);+ }, [overviews]);const getSelectedStatLabel = () => {switch (selectedStat) {@@ -149,26 +158,26 @@ export function MainSection({title={t("Unique Users")}id="users"value={totals.users}- isLoading={isLoading}+ isLoading={statsLoading}/><Stattitle={t("Sessions")}id="sessions"value={totals.sessions}- isLoading={isLoading}+ isLoading={statsLoading}/><Stattitle={t("Pageviews")}id="pageviews"value={totals.pageviews}- isLoading={isLoading}+ isLoading={statsLoading}/><Stattitle={t("Pages per Session")}id="pages_per_session"value={totals.pages_per_session}decimals={1}- isLoading={isLoading}+ isLoading={statsLoading}/><Stattitle={t("Bounce Rate")}@@ -176,14 +185,14 @@ export function MainSection({value={totals.bounce_rate}postfix="%"decimals={1}- isLoading={isLoading}+ isLoading={statsLoading}/><Stattitle={t("Session Duration")}id="session_duration"value={totals.session_duration}valueFormatter={formatSecondsAsMinutesAndSeconds}- isLoading={isLoading}+ isLoading={statsLoading}/></div></CardContent>diff --git a/client/src/app/rollup/hooks/useRollupOverview.ts b/client/src/app/rollup/hooks/useRollupOverview.tsnew file mode 100644index 000000000..6d2d0eaf4--- /dev/null+++ b/client/src/app/rollup/hooks/useRollupOverview.ts@@ -0,0 +1,72 @@+import { useQueries } from "@tanstack/react-query";+import {+ fetchOverview,+ fetchOverviewLite,+ GetOverviewResponse,+} from "@/api/analytics/endpoints";+import { buildApiParams } from "@/api/utils";+import { useStore } from "@/lib/store";++export type RollupOverview = {+ siteId: number;+ data: GetOverviewResponse;+};++export type UseRollupOverviewResult = {+ overviews: RollupOverview[];+ isLoading: boolean;+ isFetching: boolean;+ error: Error | null;+};++/**+ * Range totals per site, as opposed to the per-bucket series behind the chart.+ *+ * Unique users cannot be derived from the bucketed series: adding up per-bucket+ * distinct counts counts anyone active in two buckets twice, and the total then+ * moves when the bucket size changes. Only the server can count distinct users+ * over the whole range, so the stat cards read from here while the chart keeps+ * using the series. Users still can't be deduplicated *across* sites β identity+ * is per-site β so the total is a sum of per-site unique users.+ */+export function useRollupOverview({+ siteIds,+ lite = false,+}: {+ siteIds: number[];+ lite?: boolean;+}): UseRollupOverviewResult {+ const { time, filters, timezone } = useStore();+ // Lite endpoints don't accept filters; drop them so the request and the+ // query key stay clean.+ const effectiveFilters = lite ? undefined : filters;+ const params = buildApiParams(time, { filters: effectiveFilters });++ const queries = useQueries({+ queries: siteIds.map((siteId) => ({+ queryKey: [+ lite ? "rollup-overview-lite" : "rollup-overview",+ siteId,+ time,+ effectiveFilters,+ timezone,+ ],+ queryFn: () => {+ const fetcher = lite ? fetchOverviewLite : fetchOverview;+ return fetcher(siteId, params);+ },+ staleTime: 60_000,+ })),+ });++ const overviews: RollupOverview[] = queries+ .map((q, i) => ({ siteId: siteIds[i], data: q.data }))+ .filter((o): o is RollupOverview => !!o.data);++ return {+ overviews,+ isLoading: queries.some((q) => q.isLoading),+ isFetching: queries.some((q) => q.isFetching),+ error: (queries.find((q) => q.error)?.error as Error) ?? null,+ };+}diff --git a/docs/content/docs/api/funnel-dropoff.mdx b/docs/content/docs/api/funnel-dropoff.mdxindex bc9815b02..09cc860d0 100644--- a/docs/content/docs/api/funnel-dropoff.mdx+++ b/docs/content/docs/api/funnel-dropoff.mdx@@ -61,7 +61,7 @@ async function analyzeFunnel() {body: JSON.stringify({ steps: funnelSteps }),});const { data } = await res.json();- return data; // array of { step_number, step_name, visitors, conversion_rate, dropoff_rate }+ return data; // array of { step_number, step_name, sessions, conversion_rate, dropoff_rate }}```</Tab>@@ -101,17 +101,17 @@ A response looks like this β note that `dropoff_rate` is the percentage who le```json{"data": [- { "step_number": 1, "step_name": "Homepage", "visitors": 10000, "conversion_rate": 100, "dropoff_rate": 0 },- { "step_number": 2, "step_name": "Pricing", "visitors": 4500, "conversion_rate": 45, "dropoff_rate": 55 },- { "step_number": 3, "step_name": "Signup", "visitors": 1800, "conversion_rate": 18, "dropoff_rate": 60 },- { "step_number": 4, "step_name": "Complete", "visitors": 1080, "conversion_rate": 10.8, "dropoff_rate": 40 }+ { "step_number": 1, "step_name": "Homepage", "sessions": 10000, "conversion_rate": 100, "dropoff_rate": 0 },+ { "step_number": 2, "step_name": "Pricing", "sessions": 4500, "conversion_rate": 45, "dropoff_rate": 55 },+ { "step_number": 3, "step_name": "Signup", "sessions": 1800, "conversion_rate": 18, "dropoff_rate": 60 },+ { "step_number": 4, "step_name": "Complete", "sessions": 1080, "conversion_rate": 10.8, "dropoff_rate": 40 }]}```## Step 2 β Find the worst step-The leak isn't always the step with the fewest visitors β it's the step with the steepest **drop-off**. Pick the maximum `dropoff_rate`.+The leak isn't always the step with the fewest sessions β it's the step with the steepest **drop-off**. Pick the maximum `dropoff_rate`.<Tabs items={['JavaScript', 'Python']}><Tab value="JavaScript">diff --git a/docs/content/docs/api/funnels/analyze.mdx b/docs/content/docs/api/funnels/analyze.mdxindex 98181ebee..78345f901 100644--- a/docs/content/docs/api/funnels/analyze.mdx+++ b/docs/content/docs/api/funnels/analyze.mdx@@ -106,12 +106,16 @@ Accepts all [Common Parameters](/docs/api/getting-started#common-parameters) (tidescription: 'Step name',type: 'string',},- visitors: {+ sessions: {description: 'Number of sessions that reached this step',type: 'number',},+ visitors: {+ description: 'Deprecated alias of `sessions`, kept for backwards compatibility',+ type: 'number',+ },conversion_rate: {- description: 'Percentage of step 1 visitors who reached this step',+ description: 'Percentage of step 1 sessions that reached this step',type: 'number',typeDescription: 'Range: 0-100',},@@ -382,28 +386,28 @@ var data = await response.Content.ReadAsStringAsync();{"step_number": 1,"step_name": "Homepage",- "visitors": 10000,+ "sessions": 10000,"conversion_rate": 100,"dropoff_rate": 0},{"step_number": 2,"step_name": "Pricing",- "visitors": 4500,+ "sessions": 4500,"conversion_rate": 45,"dropoff_rate": 55},{"step_number": 3,"step_name": "Signup",- "visitors": 1800,+ "sessions": 1800,"conversion_rate": 18,"dropoff_rate": 60},{"step_number": 4,"step_name": "Complete",- "visitors": 720,+ "sessions": 720,"conversion_rate": 7.2,"dropoff_rate": 60}diff --git a/docs/content/docs/api/overview/live-visitors.mdx b/docs/content/docs/api/overview/live-visitors.mdxindex f27894cb5..7a211e306 100644--- a/docs/content/docs/api/overview/live-visitors.mdx+++ b/docs/content/docs/api/overview/live-visitors.mdx@@ -1,6 +1,6 @@---title: Get Live Visitors-description: Returns the count of unique active sessions within the specified time window. Useful for displaying real-time visitor counts.+description: Returns the count of unique active visitors within the specified time window. Useful for displaying real-time visitor counts.full: truemethod: GET---@@ -15,7 +15,9 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';GET /api/sites/:site/live-user-count```-Returns the count of unique active sessions within the specified time window. Useful for displaying real-time visitor counts.+Returns the count of unique active visitors within the specified time window. Useful for displaying real-time visitor counts.++Visitors are counted by identity where one is available (see [Identify Users](/docs/identify-users)) and by anonymous device otherwise, so one person who starts a second session inside the window still counts once.### Path Parameters@@ -34,10 +36,10 @@ Returns the count of unique active sessions within the specified time window. Us<TypeTabletype={{minutes: {- description: 'Time window in minutes to count active sessions',+ description: 'Time window in minutes to count active visitors',type: 'number',default: 5,- typeDescription: 'Sessions with activity within the last N minutes are considered "live"',+ typeDescription: 'Visitors with activity within the last N minutes are considered "live"',},}}/>@@ -47,7 +49,7 @@ Returns the count of unique active sessions within the specified time window. Us<TypeTabletype={{count: {- description: 'Number of unique active sessions',+ description: 'Number of unique active visitors',type: 'number',},}}diff --git a/server/src/api/analytics/funnels/getFunnel.ts b/server/src/api/analytics/funnels/getFunnel.tsindex d6a664804..fead99107 100644--- a/server/src/api/analytics/funnels/getFunnel.ts+++ b/server/src/api/analytics/funnels/getFunnel.ts@@ -13,7 +13,8 @@ type Funnel = {type FunnelResponse = {step_number: number;step_name: string;- visitors: number;+ /** Sessions that reached this step. Funnels are session-scoped, not person-scoped. */+ sessions: number;conversion_rate: number;dropoff_rate: number;};@@ -83,7 +84,7 @@ export const buildFunnelQuery = (query: FilterParams<{}>, siteId: number, steps:SELECT${index + 1} as step_number,${SqlString.escape(step.name || step.value)} as step_name,- count(DISTINCT session_id) as visitors+ count(DISTINCT session_id) as sessionsFROM Step${index + 1}`)@@ -94,16 +95,16 @@ export const buildFunnelQuery = (query: FilterParams<{}>, siteId: number, steps:SELECTs1.step_number,s1.step_name,- s1.visitors as visitors,- round(s1.visitors * 100.0 / first_step.visitors, 2) as conversion_rate,+ s1.sessions as sessions,+ round(s1.sessions * 100.0 / first_step.sessions, 2) as conversion_rate,CASEWHEN s1.step_number = 1 THEN 0- ELSE round((1 - (s1.visitors / prev_step.visitors)) * 100.0, 2)+ ELSE round((1 - (s1.sessions / prev_step.sessions)) * 100.0, 2)END as dropoff_rateFROM StepCounts s1- CROSS JOIN (SELECT visitors FROM StepCounts WHERE step_number = 1) as first_step+ CROSS JOIN (SELECT sessions FROM StepCounts WHERE step_number = 1) as first_stepLEFT JOIN (- SELECT step_number + 1 as next_step_number, visitors+ SELECT step_number + 1 as next_step_number, sessionsFROM StepCountsWHERE step_number < {stepNumber:Int32}) as prev_step ON s1.step_number = prev_step.next_step_number@@ -138,7 +139,9 @@ export async function getFunnel(},});- return reply.send({ data });+ // `visitors` is the pre-rename name of `sessions`, kept so existing API and+ // MCP consumers don't break. Deprecated: drop once consumers have migrated.+ return reply.send({ data: data.map(step => ({ ...step, visitors: step.sessions })) });} catch (error) {if (error instanceof AnalyticsQueryError) {request.log.error({ err: error.original }, "Error executing funnel query");diff --git a/server/src/api/analytics/getLiveUsercount.ts b/server/src/api/analytics/getLiveUsercount.tsindex 8da81630d..ea99f3dfa 100644--- a/server/src/api/analytics/getLiveUsercount.ts+++ b/server/src/api/analytics/getLiveUsercount.ts@@ -1,13 +1,16 @@import { FastifyReply, FastifyRequest } from "fastify";import { analyticsRoute, runAnalyticsQuery } from "./utils/analyticsQuery.js";+import { effectiveUserId } from "./utils/effectiveUserId.js";interface GetLiveUsercountRequest {Params: { siteId: string };Querystring: { minutes: number };}+// Counts people, not sessions: the label is "users online", and a visitor whose+// session lapses and restarts inside the window is one person, not two.export const buildLiveUsercountQuery = () =>- `SELECT COUNT(DISTINCT(session_id)) AS count FROM events WHERE timestamp > now() - interval {minutes:Int32} minute AND site_id = {siteId:Int32}`;+ `SELECT COUNT(DISTINCT ${effectiveUserId()}) AS count FROM events WHERE timestamp > now() - interval {minutes:Int32} minute AND site_id = {siteId:Int32}`;export const getLiveUsercount = analyticsRoute<GetLiveUsercountRequest>("live user count",diff --git a/server/src/api/analytics/sessions/getSessions.ts b/server/src/api/analytics/sessions/getSessions.tsindex 89d5772a6..963f5a46e 100644--- a/server/src/api/analytics/sessions/getSessions.ts+++ b/server/src/api/analytics/sessions/getSessions.ts@@ -4,6 +4,7 @@ import { getFilterStatement } from "../utils/getFilterStatement.js";import { SESSION_CHANNEL_AGG, SESSION_REFERRER_AGG } from "../utils/sessionAttribution.js";import { enrichWithTraits, getTimeStatement } from "../utils/utils.js";import { analyticsRoute, runAnalyticsQuery, QuerySpec } from "../utils/analyticsQuery.js";+import { matchesUser } from "../utils/effectiveUserId.js";export type GetSessionsResponse = {session_id: string;@@ -151,7 +152,7 @@ export const buildSessionsQuery = (query: GetSessionsRequest["Querystring"], sitFROM eventsWHEREsite_id = {siteId:Int32}- ${userId ? ` AND (events.user_id = {user_id:String} OR events.identified_user_id = {user_id:String})` : ""}+ ${userId ? ` AND ${matchesUser("{user_id:String}", "events")}` : ""}${sessionId ? ` AND events.session_id = {session_id:String}` : ""}${timeStatement}GROUP BYdiff --git a/server/src/api/analytics/users/getUserInfo.test.ts b/server/src/api/analytics/users/getUserInfo.test.tsnew file mode 100644index 000000000..aabf17a79--- /dev/null+++ b/server/src/api/analytics/users/getUserInfo.test.ts@@ -0,0 +1,133 @@+import { beforeEach, describe, expect, it, vi } from "vitest";++// Per-test state driving the mocked ClickHouse and Postgres reads.+const state = {+ // Rows keyed by the user id the query was run with.+ rowsByUserId: {} as Record<string, Record<string, unknown>[]>,+ // anonymousId -> identified user id, i.e. the userAliases table.+ aliases: {} as Record<string, string>,+ queriedUserIds: [] as string[],+};++vi.mock("../utils/analyticsQuery.js", () => ({+ runAnalyticsQuery: vi.fn(async ({ params }: { params: { userId: string } }) => {+ state.queriedUserIds.push(params.userId);+ return state.rowsByUserId[params.userId] ?? [];+ }),+}));++vi.mock("../../../db/postgres/postgres.js", () => ({+ db: {+ select: vi.fn((columns?: Record<string, unknown>) => ({+ from: () => ({+ // Linked-device lookups await where() directly; profile and alias lookups+ // chain .limit(1) first. Support both by returning a thenable with .limit.+ where: () => ({+ limit: async () => resolveAliasRows(columns),+ then: (resolve: (rows: unknown[]) => void) => resolve([]),+ }),+ }),+ })),+ },+}));++// The alias lookup is the only select that projects just { userId }; the traits+// select projects the whole row. Distinguishing them keeps the stub honest.+function resolveAliasRows(columns?: Record<string, unknown>) {+ const isAliasLookup = !!columns && Object.keys(columns).length === 1 && "userId" in columns;+ if (!isAliasLookup) return [];+ const identified = state.aliases[currentAnonymousId];+ return identified ? [{ userId: identified }] : [];+}++let currentAnonymousId = "";++vi.mock("../../../db/postgres/schema.js", () => ({+ userProfiles: { siteId: "site_id", userId: "user_id", traits: "traits" },+ userAliases: { siteId: "site_id", anonymousId: "anonymous_id", userId: "user_id", createdAt: "created_at" },+}));++vi.mock("drizzle-orm", () => ({+ and: (...args: unknown[]) => args,+ eq: (_col: unknown, value: unknown) => value,+}));++import { getUserInfo } from "./getUserInfo.js";++const makeReply = () => {+ const reply = {+ statusCode: 200,+ payload: undefined as unknown,+ status(code: number) {+ this.statusCode = code;+ return this;+ },+ send(payload: unknown) {+ this.payload = payload;+ return this;+ },+ };+ return reply;+};++const makeRequest = (userId: string) =>+ ({+ params: { siteId: "1", userId },+ query: {},+ log: { error: vi.fn() },+ }) as never;++const userRow = (identifiedUserId: string) => ({+ user_id: "fp1",+ identified_user_id: identifiedUserId,+ sessions: 3,+ pageviews: 12,+});++describe("getUserInfo alias fallback", () => {+ beforeEach(() => {+ state.rowsByUserId = {};+ state.aliases = {};+ state.queriedUserIds = [];+ currentAnonymousId = "";+ });++ it("serves the identity when the device's rows have all been backfilled to it", async () => {+ // The dashboard's Identify User action rewrites the device's whole history, so+ // the anonymous route id matches nothing afterwards.+ currentAnonymousId = "fp1";+ state.aliases = { fp1: "alice" };+ state.rowsByUserId = { alice: [userRow("alice")] };++ const reply = makeReply();+ await getUserInfo(makeRequest("fp1"), reply as never);++ expect(reply.statusCode).toBe(200);+ expect((reply.payload as { data: { identified_user_id: string } }).data.identified_user_id).toBe("alice");+ expect(state.queriedUserIds).toContain("fp1");+ expect(state.queriedUserIds).toContain("alice");+ });++ it("keeps serving a device's own anonymous activity instead of resolving early", async () => {+ // A shared fingerprint still has anonymous rows of its own even after one person+ // behind it is identified. That activity is what this route is about.+ currentAnonymousId = "fp1";+ state.aliases = { fp1: "alice" };+ state.rowsByUserId = { fp1: [userRow("")] };++ const reply = makeReply();+ await getUserInfo(makeRequest("fp1"), reply as never);++ expect(reply.statusCode).toBe(200);+ expect(state.queriedUserIds).not.toContain("alice");+ });++ it("still 404s a device that was never seen and has no alias", async () => {+ currentAnonymousId = "unknown";++ const reply = makeReply();+ await getUserInfo(makeRequest("unknown"), reply as never);++ expect(reply.statusCode).toBe(404);+ });+});diff --git a/server/src/api/analytics/users/getUserInfo.ts b/server/src/api/analytics/users/getUserInfo.tsindex 2e42088d6..876cb40cd 100644--- a/server/src/api/analytics/users/getUserInfo.ts+++ b/server/src/api/analytics/users/getUserInfo.ts@@ -6,6 +6,7 @@ import { userProfiles, userAliases } from "../../../db/postgres/schema.js";import { getFilterStatement } from "../utils/getFilterStatement.js";import { SESSION_CHANNEL_AGG, SESSION_REFERRER_AGG } from "../utils/sessionAttribution.js";import { getTimeStatement } from "../utils/utils.js";+import { matchesUser } from "../utils/effectiveUserId.js";import { runAnalyticsQuery } from "../utils/analyticsQuery.js";interface UserPageviewData {@@ -98,7 +99,7 @@ export const buildUserInfoQueries = (query: FilterParams, siteId: number) => {SELECT *FROM eventsWHERE- (events.identified_user_id = {userId:String} OR events.user_id = {userId:String})+ ${matchesUser("{userId:String}", "events")}AND site_id = {site:Int32}${timeStatement}${filterStatement}@@ -250,13 +251,9 @@ export async function getUserInfo(const { sessionsQuery, vitalsQuery, locationsQuery, devicesQuery } = buildUserInfoQueries(req.query, numericSiteId);- const chParams = {- userId,- site: siteId,- };-- try {- const [data, vitalsData, locations, devices, profileResult, aliasesResult] = await Promise.all([+ const loadUser = (effectiveUserId: string) => {+ const chParams = { userId: effectiveUserId, site: siteId };+ return Promise.all([runAnalyticsQuery<UserPageviewData>({ query: sessionsQuery, params: chParams }),runAnalyticsQuery<UserVitalsData>({ query: vitalsQuery, params: chParams }),runAnalyticsQuery<UserLocationBreakdown>({ query: locationsQuery, params: chParams }),@@ -265,7 +262,7 @@ export async function getUserInfo(db.select().from(userProfiles)- .where(and(eq(userProfiles.siteId, numericSiteId), eq(userProfiles.userId, userId)))+ .where(and(eq(userProfiles.siteId, numericSiteId), eq(userProfiles.userId, effectiveUserId))).limit(1),// Get linked devices (all anonymous IDs for this user) from Postgresdb@@ -274,8 +271,30 @@ export async function getUserInfo(created_at: userAliases.createdAt,}).from(userAliases)- .where(and(eq(userAliases.siteId, numericSiteId), eq(userAliases.userId, userId))),+ .where(and(eq(userAliases.siteId, numericSiteId), eq(userAliases.userId, effectiveUserId))),]);+ };++ try {+ let [data, vitalsData, locations, devices, profileResult, aliasesResult] = await loadUser(userId);++ // A device whose events have all been claimed by an identity β the dashboard's+ // "Identify User" action backfills the full history β no longer has anonymous+ // rows, so the anonymous branch of the query matches nothing. Follow the alias+ // rather than 404ing a route the operator was just looking at. Only on a miss:+ // while a shared fingerprint still has anonymous activity of its own, that+ // activity is what this route is about, and resolving early would put someone+ // else's identity on it.+ if (data.length === 0) {+ const alias = await db+ .select({ userId: userAliases.userId })+ .from(userAliases)+ .where(and(eq(userAliases.siteId, numericSiteId), eq(userAliases.anonymousId, userId)))+ .limit(1);+ if (alias.length > 0 && alias[0].userId !== userId) {+ [data, vitalsData, locations, devices, profileResult, aliasesResult] = await loadUser(alias[0].userId);+ }+ }// If no data found for userif (data.length === 0) {diff --git a/server/src/api/analytics/users/getUserSessionCount.ts b/server/src/api/analytics/users/getUserSessionCount.tsindex e531d1270..1fb880756 100644--- a/server/src/api/analytics/users/getUserSessionCount.ts+++ b/server/src/api/analytics/users/getUserSessionCount.ts@@ -1,6 +1,7 @@import { FastifyReply, FastifyRequest } from "fastify";import { getFilterStatement } from "../utils/getFilterStatement.js";import { analyticsRoute, runAnalyticsQuery } from "../utils/analyticsQuery.js";+import { matchesUser } from "../utils/effectiveUserId.js";import SqlString from "sqlstring";export interface GetUserSessionCountRequest {@@ -33,7 +34,7 @@ export const buildUserSessionCountQuery = (query: GetUserSessionCountRequest["QuFROM eventsWHEREsite_id = {siteId:Int32}- AND (user_id = {userId:String} OR identified_user_id = {userId:String})+ AND ${matchesUser("{userId:String}")}${filterStatement}GROUP BY dateORDER BY date ASCdiff --git a/server/src/api/analytics/utils/effectiveUserId.ts b/server/src/api/analytics/utils/effectiveUserId.tsindex 03a86fc86..1285db07b 100644--- a/server/src/api/analytics/utils/effectiveUserId.ts+++ b/server/src/api/analytics/utils/effectiveUserId.ts@@ -38,3 +38,26 @@ export const effectiveUserId = (tableAlias = "") => {* aggregate happens to see; that is no worse than the fingerprint they resolve to today.*/export const EFFECTIVE_SESSION_USER_ID = `COALESCE(NULLIF(anyIf(identified_user_id, identified_user_id != ''), ''), anyLast(user_id))`;++/**+ * Predicate for "these events belong to the user identified by `valueExpr`", where+ * the value may be either a custom user ID or an anonymous device fingerprint β+ * both appear in dashboard URLs and filters.+ *+ * The fingerprint branch is guarded on `identified_user_id = ''` for the same reason+ * the counts above key on identity: one fingerprint can cover many people behind a+ * shared IP and browser. Matching a fingerprint unguarded pulls in every identified+ * user who happens to sit behind it, so an anonymous visitor's profile would show a+ * whole office's activity. Anonymous rows belong to the device; identified rows+ * belong to the person. See deleteUser for the same predicate over an alias set.+ *+ * `valueExpr` must already be a bound parameter (`{userId:String}`) or an escaped+ * literal β it is interpolated verbatim.+ */+export const matchesUser = (valueExpr: string, tableAlias = "") => {+ const prefix = tableAlias ? `${tableAlias}.` : "";+ return `(${prefix}identified_user_id = ${valueExpr} OR (${prefix}user_id = ${valueExpr} AND ${prefix}identified_user_id = ''))`;+};++/** Exact complement of {@link matchesUser}, so equals/not_equals filters partition the rows. */+export const doesNotMatchUser = (valueExpr: string, tableAlias = "") => `NOT ${matchesUser(valueExpr, tableAlias)}`;diff --git a/server/src/api/analytics/utils/getFilterStatement.test.ts b/server/src/api/analytics/utils/getFilterStatement.test.tsindex 4b5875686..f62a75571 100644--- a/server/src/api/analytics/utils/getFilterStatement.test.ts+++ b/server/src/api/analytics/utils/getFilterStatement.test.ts@@ -232,31 +232,48 @@ describe("getFilterStatement", () => {});describe("User ID special handling", () => {- it("should check both user_id and identified_user_id for equals", () => {+ // A filter value can be either a custom user ID or an anonymous fingerprint.+ // The fingerprint branch is guarded on identified_user_id = '' so that filtering+ // by a fingerprint shared behind one IP+browser doesn't sweep in every identified+ // user sitting behind it.+ it("matches an identified user, or a device only while it is still anonymous", () => {const filters = JSON.stringify([{ parameter: "user_id", type: "equals", value: ["user123"] }]);const result = getFilterStatement(filters);- expect(result).toBe("AND (user_id = 'user123' OR identified_user_id = 'user123')");+ expect(result).toBe(+ "AND (identified_user_id = 'user123' OR (user_id = 'user123' AND identified_user_id = ''))"+ );});- it("should check both user_id and identified_user_id for not_equals", () => {+ it("negates exactly the equals predicate for not_equals", () => {const filters = JSON.stringify([{ parameter: "user_id", type: "not_equals", value: ["user123"] }]);const result = getFilterStatement(filters);- expect(result).toBe("AND (user_id != 'user123' AND identified_user_id != 'user123')");+ expect(result).toBe(+ "AND NOT (identified_user_id = 'user123' OR (user_id = 'user123' AND identified_user_id = ''))"+ );});it("should handle multiple user IDs with equals using OR", () => {const filters = JSON.stringify([{ parameter: "user_id", type: "equals", value: ["user1", "user2"] }]);const result = getFilterStatement(filters);- expect(result).toContain("user_id = 'user1' OR identified_user_id = 'user1'");- expect(result).toContain("user_id = 'user2' OR identified_user_id = 'user2'");+ expect(result).toContain("identified_user_id = 'user1' OR (user_id = 'user1' AND identified_user_id = '')");+ expect(result).toContain("identified_user_id = 'user2' OR (user_id = 'user2' AND identified_user_id = '')");expect(result).toContain(" OR ");});it("should handle multiple user IDs with not_equals using AND", () => {const filters = JSON.stringify([{ parameter: "user_id", type: "not_equals", value: ["user1", "user2"] }]);const result = getFilterStatement(filters);- expect(result).toContain("user_id != 'user1' AND identified_user_id != 'user1'");- expect(result).toContain("user_id != 'user2' AND identified_user_id != 'user2'");+ expect(result).toContain("NOT (identified_user_id = 'user1' OR (user_id = 'user1' AND identified_user_id = ''))");+ expect(result).toContain("NOT (identified_user_id = 'user2' OR (user_id = 'user2' AND identified_user_id = ''))");+ expect(result).toContain(" AND ");+ });++ it("does not attribute one person's identified events to a device fingerprint they share", () => {+ // The regression this guard exists for: alice and bob behind one corporate+ // proxy share fingerprint 'fp1'. Filtering on 'fp1' must not return alice's rows.+ const result = getFilterStatement(JSON.stringify([{ parameter: "user_id", type: "equals", value: ["fp1"] }]));+ expect(result).not.toMatch(/user_id = 'fp1'\s*\)\s*$/);+ expect(result).toContain("identified_user_id = ''");});});diff --git a/server/src/api/analytics/utils/getFilterStatement.ts b/server/src/api/analytics/utils/getFilterStatement.tsindex 7ddd71540..07f4c3833 100644--- a/server/src/api/analytics/utils/getFilterStatement.ts+++ b/server/src/api/analytics/utils/getFilterStatement.ts@@ -2,6 +2,7 @@ import SqlString from "sqlstring";import { filterParamSchema, validateFilters } from "./query-validation.js";import { SESSION_CHANNEL_AGG } from "./sessionAttribution.js";import { FilterParameter, FilterType } from "../types.js";+import { doesNotMatchUser, matchesUser } from "./effectiveUserId.js";// Options for customizing filter behaviorexport interface FilterStatementOptions {@@ -312,17 +313,17 @@ export function getFilterStatement(if (filter.value.length === 1) {const escapedValue = SqlString.escape(filter.value[0]);if (filter.type === "equals") {- return `(user_id = ${escapedValue} OR identified_user_id = ${escapedValue})`;+ return matchesUser(escapedValue);}- return `(user_id != ${escapedValue} AND identified_user_id != ${escapedValue})`;+ return doesNotMatchUser(escapedValue);}const conditions = filter.value.map(value => {const escapedValue = SqlString.escape(value);if (filter.type === "equals") {- return `(user_id = ${escapedValue} OR identified_user_id = ${escapedValue})`;+ return matchesUser(escapedValue);}- return `(user_id != ${escapedValue} AND identified_user_id != ${escapedValue})`;+ return doesNotMatchUser(escapedValue);});if (filter.type === "equals") {diff --git a/server/src/mcp/mcp.test.ts b/server/src/mcp/mcp.test.tsindex 1c89b38e6..346b9965d 100644--- a/server/src/mcp/mcp.test.ts+++ b/server/src/mcp/mcp.test.ts@@ -153,7 +153,10 @@ describe("mcp endpoint", () => {fastify.post("/sites/:siteId/funnels/analyze", async request => {captured.body = request.body;captured.query = request.query as Record<string, unknown>;- return { data: [{ step_number: 1, step_name: "Step 1", visitors: 10, conversion_rate: 100, dropoff_rate: 0 }] };+ // The API returns `sessions` plus the deprecated `visitors` alias.+ return {+ data: [{ step_number: 1, step_name: "Step 1", sessions: 10, visitors: 10, conversion_rate: 100, dropoff_rate: 0 }],+ };});fastify.get("/sites/:siteId/goals", async (_request, reply) => {diff --git a/server/src/mcp/tools/funnels.ts b/server/src/mcp/tools/funnels.tsindex e1dd62c04..274fa034d 100644--- a/server/src/mcp/tools/funnels.ts+++ b/server/src/mcp/tools/funnels.ts@@ -19,7 +19,9 @@ const funnelStepResult = z.object({step_number: z.number(),step_name: z.string(),- visitors: z.number(),+ sessions: z.number(),+ /** Deprecated alias of `sessions`. */+ visitors: z.number().optional(),conversion_rate: z.number(),dropoff_rate: z.number(),})@@ -50,7 +52,7 @@ export function registerFunnelTools(server: McpServer, api: RybbitApiClient, gua{title: "Analyze funnel",description:- "Compute a conversion funnel over ordered steps (pages, custom events, or autocaptured interactions). Returns per-step visitors, conversion_rate, and dropoff_rate. Does not save anything; use save_funnel to persist a definition.",+ "Compute a conversion funnel over ordered steps (pages, custom events, or autocaptured interactions). Returns per-step sessions (funnels are session-scoped), conversion_rate, and dropoff_rate. Does not save anything; use save_funnel to persist a definition.",inputSchema: {site_id: siteIdInput,steps: z.array(funnelStepInput).min(2).max(10).describe("Ordered funnel steps, first to last"),diff --git a/server/src/services/replay/sessionReplayQueryService.ts b/server/src/services/replay/sessionReplayQueryService.tsindex 2fdafc00b..0a09ff932 100644--- a/server/src/services/replay/sessionReplayQueryService.ts+++ b/server/src/services/replay/sessionReplayQueryService.ts@@ -8,6 +8,7 @@ import { processResults, getTimeStatement } from "../../api/analytics/utils/utilimport { FilterParams } from "@rybbit/shared";import { r2Storage } from "../storage/r2StorageService.js";import { getFilterStatement } from "../../api/analytics/utils/getFilterStatement.js";+import { matchesUser } from "../../api/analytics/utils/effectiveUserId.js";/*** Service responsible for querying/retrieving session replay data@@ -33,7 +34,7 @@ export class SessionReplayQueryService {const queryParams: any = { siteId, limit, offset };if (userId) {- whereConditions.push(`(user_id = {userId:String} OR identified_user_id = {userId:String})`);+ whereConditions.push(matchesUser("{userId:String}"));queryParams.userId = userId;}