Skip to content

🐸 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.ts
index 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.tsx
index 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, siteId
const { 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
<div
className="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.tsx
index 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">
<SessionsList
sessions={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.tsx
index 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}
/>
<Stat
title={t("Sessions")}
id="sessions"
value={totals.sessions}
- isLoading={isLoading}
+ isLoading={statsLoading}
/>
<Stat
title={t("Pageviews")}
id="pageviews"
value={totals.pageviews}
- isLoading={isLoading}
+ isLoading={statsLoading}
/>
<Stat
title={t("Pages per Session")}
id="pages_per_session"
value={totals.pages_per_session}
decimals={1}
- isLoading={isLoading}
+ isLoading={statsLoading}
/>
<Stat
title={t("Bounce Rate")}
@@ -176,14 +185,14 @@ export function MainSection({
value={totals.bounce_rate}
postfix="%"
decimals={1}
- isLoading={isLoading}
+ isLoading={statsLoading}
/>
<Stat
title={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.ts
new file mode 100644
index 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.mdx
index 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.mdx
index 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) (ti
description: '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.mdx
index 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: true
method: 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
<TypeTable
type={{
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
<TypeTable
type={{
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.ts
index 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 sessions
FROM Step${index + 1}
`
)
@@ -94,16 +95,16 @@ export const buildFunnelQuery = (query: FilterParams<{}>, siteId: number, steps:
SELECT
s1.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,
CASE
WHEN 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_rate
FROM 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_step
LEFT JOIN (
- SELECT step_number + 1 as next_step_number, visitors
+ SELECT step_number + 1 as next_step_number, sessions
FROM StepCounts
WHERE 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.ts
index 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.ts
index 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"], sit
FROM events
WHERE
site_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 BY
diff --git a/server/src/api/analytics/users/getUserInfo.test.ts b/server/src/api/analytics/users/getUserInfo.test.ts
new file mode 100644
index 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.ts
index 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 events
WHERE
- (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 Postgres
db
@@ -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 user
if (data.length === 0) {
diff --git a/server/src/api/analytics/users/getUserSessionCount.ts b/server/src/api/analytics/users/getUserSessionCount.ts
index 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["Qu
FROM events
WHERE
site_id = {siteId:Int32}
- AND (user_id = {userId:String} OR identified_user_id = {userId:String})
+ AND ${matchesUser("{userId:String}")}
${filterStatement}
GROUP BY date
ORDER BY date ASC
diff --git a/server/src/api/analytics/utils/effectiveUserId.ts b/server/src/api/analytics/utils/effectiveUserId.ts
index 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.ts
index 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.ts
index 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 behavior
export 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.ts
index 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.ts
index 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.ts
index 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/util
import { 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;
}