Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Retention (#75)

Bill Yangc453578c4ff5
diff --git a/client/src/api/analytics/useGetRetention.ts b/client/src/api/analytics/useGetRetention.ts
new file mode 100644
index 000000000..3036f5404
--- /dev/null
+++ b/client/src/api/analytics/useGetRetention.ts
@@ -0,0 +1,30 @@
+import { useQuery } from "@tanstack/react-query";
+import { BACKEND_URL } from "../../lib/const";
+import { useStore } from "../../lib/store";
+import { authedFetch } from "../utils";
+
+// Define the interface for processed retention data
+export interface ProcessedRetentionData {
+ cohorts: Record<string, { size: number; percentages: (number | null)[] }>;
+ maxPeriods: number;
+ mode: "day" | "week";
+ range: number;
+}
+
+export type RetentionMode = "day" | "week";
+
+export function useGetRetention(
+ mode: RetentionMode = "week",
+ range: number = 90
+) {
+ const { site } = useStore();
+ return useQuery<ProcessedRetentionData>({
+ queryKey: ["retention", site, mode, range],
+ queryFn: () =>
+ authedFetch(
+ `${BACKEND_URL}/retention/${site}?mode=${mode}&range=${range}`
+ )
+ .then((res) => res.json())
+ .then((data) => data.data),
+ });
+}
diff --git a/client/src/app/[site]/Header/Header.tsx b/client/src/app/[site]/Header/Header.tsx
index e4f504644..5ce2da126 100644
--- a/client/src/app/[site]/Header/Header.tsx
+++ b/client/src/app/[site]/Header/Header.tsx
@@ -65,6 +65,12 @@ export function Header() {
href={getTabPath("realtime")}
icon={<Radio size={20} />}
/>
+ <TabButton
+ label="Retention"
+ active={isActiveTab("retention")}
+ href={getTabPath("retention")}
+ icon={<ChartBarDecreasing size={20} />}
+ />
<TabButton
label="Reports"
active={isActiveTab("reports")}
diff --git a/client/src/app/[site]/retention/RetentionChart.tsx b/client/src/app/[site]/retention/RetentionChart.tsx
new file mode 100644
index 000000000..d74be483d
--- /dev/null
+++ b/client/src/app/[site]/retention/RetentionChart.tsx
@@ -0,0 +1,259 @@
+"use client";
+
+import { nivoTheme } from "@/lib/nivo";
+import {
+ ProcessedRetentionData,
+ RetentionMode,
+} from "../../../api/analytics/useGetRetention";
+import { ResponsiveLine } from "@nivo/line";
+import { useMemo } from "react";
+import { Skeleton } from "../../../components/ui/skeleton";
+import { DateTime } from "luxon";
+
+interface RetentionChartProps {
+ data: ProcessedRetentionData | undefined;
+ isLoading: boolean;
+ mode: RetentionMode;
+}
+
+// Vibrant color palette for different cohorts using Tailwind CSS HSL variables
+const cohortColors = [
+ "hsl(var(--accent-500))", // Primary accent color
+ "hsl(var(--green-500))", // Green
+ "hsl(var(--red-500))", // Red
+ "hsl(var(--blue-500))", // Blue
+ "hsl(var(--orange-500))", // Orange
+ "hsl(var(--purple-500))", // Purple
+ "hsl(var(--teal-500))", // Teal
+ "hsl(var(--amber-500))", // Amber
+ "hsl(var(--slate-600))", // Slate
+ "hsl(var(--red-600))", // Darker red
+ "hsl(var(--green-600))", // Darker green
+ "hsl(var(--blue-600))", // Darker blue
+ "hsl(var(--purple-600))", // Darker purple
+ "hsl(var(--teal-600))", // Darker teal
+];
+
+// Loading skeleton
+const RetentionChartSkeleton = () => (
+ <div className="h-[400px] flex items-center justify-center">
+ <div className="w-full space-y-3">
+ <Skeleton className="h-[300px] w-full bg-neutral-900 rounded-md animate-pulse" />
+ <div className="flex items-center justify-between px-6">
+ {Array.from({ length: 6 }).map((_, i) => (
+ <Skeleton
+ key={i}
+ className="h-4 w-12 bg-neutral-700/50 animate-pulse"
+ style={{
+ animationDelay: `${i * 100}ms`,
+ opacity: 0.3 + i * 0.1,
+ }}
+ />
+ ))}
+ </div>
+ </div>
+ </div>
+);
+
+export function RetentionChart({ data, isLoading, mode }: RetentionChartProps) {
+ // Get cohort keys once for both chart data and tooltip
+ const cohortKeys = useMemo(() => {
+ if (!data || !data.cohorts) return [];
+ return Object.keys(data.cohorts)
+ .sort((a, b) => b.localeCompare(a))
+ .slice(0, 12); // Limit to 12 most recent cohorts for better readability
+ }, [data]);
+
+ // Process data for the chart - organize by cohort
+ const chartData = useMemo(() => {
+ if (!data || !data.cohorts || cohortKeys.length === 0) {
+ return [];
+ }
+
+ // Format each cohort as a series (line)
+ return cohortKeys.map((cohortKey, index) => {
+ const cohortData = data.cohorts[cohortKey];
+
+ // Format the date label based on mode
+ let formattedDate: string;
+ if (mode === "day") {
+ formattedDate = DateTime.fromISO(cohortKey).toFormat("MMM dd");
+ } else {
+ // For weekly mode
+ const startDate = DateTime.fromISO(cohortKey);
+ const endDate = startDate.plus({ days: 6 });
+
+ // If same month, don't repeat month
+ if (startDate.month === endDate.month) {
+ formattedDate = `${startDate.toFormat("MMM dd")}-${endDate.toFormat(
+ "dd"
+ )}`;
+ } else {
+ formattedDate = `${startDate.toFormat("MMM dd")}-${endDate.toFormat(
+ "MMM dd"
+ )}`;
+ }
+ }
+
+ // Create data points for each period
+ const points = cohortData.percentages.map((percentage, periodIndex) => ({
+ x: periodIndex,
+ y: percentage ?? null,
+ }));
+
+ return {
+ id: formattedDate,
+ data: points.filter((point) => point.y !== null), // Remove null points
+ color: cohortColors[index % cohortColors.length],
+ };
+ });
+ }, [data, mode, cohortKeys]);
+
+ if (isLoading) {
+ return <RetentionChartSkeleton />;
+ }
+
+ if (!data || chartData.length === 0) {
+ return (
+ <div className="h-[400px] flex items-center justify-center">
+ <div className="text-neutral-400 text-sm">
+ No retention data available
+ </div>
+ </div>
+ );
+ }
+
+ // Calculate max Y value with a little headroom
+ const maxY = Math.min(
+ 100,
+ Math.max(
+ ...chartData.flatMap((series) =>
+ series.data.map((d) => (typeof d.y === "number" ? d.y : 0))
+ )
+ ) * 1.1
+ );
+
+ return (
+ <div className="h-[400px]">
+ <ResponsiveLine
+ data={chartData}
+ theme={nivoTheme}
+ margin={{ top: 20, right: 100, bottom: 30, left: 40 }}
+ xScale={{
+ type: "linear",
+ min: 0,
+ max: "auto",
+ }}
+ yScale={{
+ type: "linear",
+ min: 0,
+ max: maxY,
+ stacked: false,
+ }}
+ curve="linear"
+ axisBottom={{
+ tickSize: 5,
+ tickPadding: 5,
+ tickRotation: 0,
+ tickValues: chartData.length,
+ format: (value) => `${value}`,
+ }}
+ axisLeft={{
+ tickSize: 5,
+ tickPadding: 5,
+ tickRotation: 0,
+ format: (value) => `${value}%`,
+ }}
+ enableGridX={true}
+ gridXValues={Array.from({ length: data.maxPeriods + 1 }, (_, i) => i)}
+ colors={{ datum: "color" }}
+ useMesh={true}
+ pointSize={0}
+ legends={[
+ {
+ anchor: "right",
+ direction: "column",
+ justify: false,
+ translateX: 120,
+ translateY: 0,
+ itemsSpacing: 5,
+ itemDirection: "left-to-right",
+ itemWidth: 100,
+ itemHeight: 20,
+ itemOpacity: 0.85,
+ symbolSize: 12,
+ symbolShape: "circle",
+ symbolBorderColor: "rgba(0, 0, 0, .5)",
+ effects: [
+ {
+ on: "hover",
+ style: {
+ itemBackground: "rgba(0, 0, 0, .1)",
+ itemOpacity: 1,
+ },
+ },
+ ],
+ itemTextColor: "hsl(var(--neutral-200))",
+ },
+ ]}
+ tooltip={({ point }) => {
+ const value = point.data.y as number | null;
+ const xValue = point.data.x as number;
+
+ // Find the original cohort date by matching the formatted label
+ const cohortEntry = chartData.find(
+ (series) => series.id === point.serieId
+ );
+ const cohortIndex = cohortEntry ? chartData.indexOf(cohortEntry) : -1;
+ const originalCohortKey =
+ cohortIndex >= 0 && cohortKeys && cohortKeys[cohortIndex];
+
+ // Format full date for tooltip
+ let cohortDateDisplay = point.serieId;
+ if (originalCohortKey) {
+ if (mode === "day") {
+ cohortDateDisplay =
+ DateTime.fromISO(originalCohortKey).toFormat("MMM dd, yyyy");
+ } else {
+ const startDate = DateTime.fromISO(originalCohortKey);
+ const endDate = startDate.plus({ days: 6 });
+
+ if (startDate.month === endDate.month) {
+ cohortDateDisplay = `${startDate.toFormat(
+ "MMM dd"
+ )} - ${endDate.toFormat("dd, yyyy")}`;
+ } else if (startDate.year === endDate.year) {
+ cohortDateDisplay = `${startDate.toFormat(
+ "MMM dd"
+ )} - ${endDate.toFormat("MMM dd, yyyy")}`;
+ } else {
+ cohortDateDisplay = `${startDate.toFormat(
+ "MMM dd, yyyy"
+ )} - ${endDate.toFormat("MMM dd, yyyy")}`;
+ }
+ }
+ }
+
+ return (
+ <div className="text-sm bg-neutral-850 p-2 rounded-md border border-neutral-800 shadow-md">
+ <div
+ className="font-medium mb-1"
+ style={{ color: point.serieColor }}
+ >
+ Cohort: {cohortDateDisplay}
+ </div>
+ <div className="flex justify-between w-48 text-neutral-200">
+ <span>
+ {mode === "day" ? "Day" : "Week"} {xValue}
+ </span>
+ <span className="font-medium">
+ {value !== null ? `${value.toFixed(1)}%` : "-"}
+ </span>
+ </div>
+ </div>
+ );
+ }}
+ />
+ </div>
+ );
+}
diff --git a/client/src/app/[site]/retention/page.tsx b/client/src/app/[site]/retention/page.tsx
new file mode 100644
index 000000000..863e8d174
--- /dev/null
+++ b/client/src/app/[site]/retention/page.tsx
@@ -0,0 +1,400 @@
+"use client";
+
+import {
+ useGetRetention,
+ RetentionMode,
+} from "../../../api/analytics/useGetRetention";
+import { DateTime } from "luxon"; // Import Luxon for date formatting
+import { Fragment, useMemo, useState } from "react";
+import {
+ Card,
+ CardContent,
+ CardHeader,
+ CardTitle,
+} from "../../../components/ui/card";
+import { Tabs, TabsList, TabsTrigger } from "../../../components/ui/tabs";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "../../../components/ui/select";
+import { Label } from "../../../components/ui/label";
+import {
+ Tooltip,
+ TooltipContent,
+ TooltipProvider,
+ TooltipTrigger,
+} from "../../../components/ui/tooltip";
+import { HelpCircle } from "lucide-react";
+import { Skeleton } from "../../../components/ui/skeleton";
+import { RetentionChart } from "./RetentionChart";
+
+// Available time range options (in days)
+const RANGE_OPTIONS = [
+ { value: "7", label: "7 days" },
+ { value: "14", label: "14 days" },
+ { value: "30", label: "30 days" },
+ { value: "60", label: "60 days" },
+ { value: "90", label: "90 days" },
+ { value: "180", label: "6 months" },
+ { value: "365", label: "1 year" },
+];
+
+// Default number of periods and cohorts for skeleton
+const DEFAULT_SKELETON_PERIODS = 6;
+const DEFAULT_SKELETON_COHORTS = 8;
+
+// Dynamic color function that creates a smooth gradient based on retention percentage
+const getRetentionColor = (
+ percentage: number | null
+): { backgroundColor: string; textColor: string } => {
+ if (percentage === null || isNaN(percentage)) {
+ return {
+ backgroundColor: "hsl(var(--neutral-900))",
+ textColor: "transparent",
+ };
+ }
+
+ if (percentage === 0) {
+ return {
+ backgroundColor: "hsl(var(--neutral-850))",
+ textColor: "var(--text-dark, #262626)",
+ };
+ }
+
+ // Use a consistent blue hue
+ const hue = 210; // Fixed blue hue
+
+ // Use a consistent saturation
+ const saturation = 80; // Fixed high saturation
+
+ // Only vary the lightness based on retention percentage
+ // High retention = darker (lower lightness), low retention = lighter
+ // Scale from 85% (low retention) to 30% (high retention)
+ const lightness = Math.max(30, Math.min(85, 85 - percentage * 0.55));
+
+ // Determine text color (white for dark backgrounds, dark for light backgrounds)
+ const textColor = lightness < 50 ? "white" : "var(--text-dark, #262626)";
+
+ return {
+ backgroundColor: `hsl(${hue}, ${saturation}%, ${lightness}%)`,
+ textColor,
+ };
+};
+
+// Loading skeleton for the retention grid
+const RetentionGridSkeleton = () => {
+ const periodHeaders = Array.from(
+ { length: DEFAULT_SKELETON_PERIODS + 1 },
+ (_, i) => (i === 0 ? "Cohort" : `Week ${i - 1}`)
+ );
+
+ return (
+ <div className="overflow-x-auto">
+ <div
+ className="inline-grid gap-px bg-neutral-900 border border-neutral-800 rounded-lg shadow-lg"
+ style={{
+ gridTemplateColumns: `minmax(120px, auto) repeat(${DEFAULT_SKELETON_PERIODS}, minmax(90px, auto))`,
+ }}
+ >
+ {/* Header Row */}
+ {periodHeaders.map((header, i) => (
+ <div
+ key={`header-${i}`}
+ className={`p-3 font-semibold bg-neutral-900 text-center border-b border-neutral-700 ${
+ i === 0 ? "sticky left-0 z-10 border-r" : ""
+ }`}
+ >
+ <Skeleton className="h-4 w-16 mx-auto bg-neutral-700/50 animate-pulse" />
+ </div>
+ ))}
+
+ {/* Data Rows */}
+ {Array.from({ length: DEFAULT_SKELETON_COHORTS }).map((_, rowIndex) => (
+ <Fragment key={`row-${rowIndex}`}>
+ {/* Cohort Info Cell */}
+ <div className="p-3 bg-neutral-900 text-sm sticky left-0 z-10 border-r border-neutral-700">
+ <Skeleton className="h-4 w-24 mb-2 bg-neutral-700/50 animate-pulse" />
+ <Skeleton className="h-3 w-16 bg-neutral-700/50 animate-pulse" />
+ </div>
+ {/* Retention Cells */}
+ {Array.from({ length: DEFAULT_SKELETON_PERIODS }).map(
+ (_, cellIndex) => (
+ <div
+ key={`cell-${rowIndex}-${cellIndex}`}
+ className="m-[2px] p-3 flex items-center justify-center bg-neutral-800 rounded-md"
+ >
+ <Skeleton
+ className={`h-4 w-10 bg-neutral-700/50 animate-pulse`}
+ style={{
+ animationDelay: `${
+ (rowIndex * DEFAULT_SKELETON_PERIODS + cellIndex) * 50
+ }ms`,
+ }}
+ />
+ </div>
+ )
+ )}
+ </Fragment>
+ ))}
+ </div>
+ </div>
+ );
+};
+
+export default function RetentionPage() {
+ // State for the retention mode (day or week)
+ const [mode, setMode] = useState<RetentionMode>("week");
+ // State for the data time range (days)
+ const [timeRange, setTimeRange] = useState<number>(90);
+
+ // Use the updated hook without the limit parameter
+ const { data, isLoading, isError } = useGetRetention(mode, timeRange);
+
+ // Get sorted cohort keys (oldest first)
+ const cohortKeys = useMemo(
+ () =>
+ data?.cohorts
+ ? Object.keys(data.cohorts).sort((a, b) => a.localeCompare(b))
+ : [],
+ [data?.cohorts]
+ );
+
+ // Function to format date based on mode
+ const formatDate = (dateStr: string) => {
+ if (mode === "day") {
+ return DateTime.fromISO(dateStr).toFormat("MMM dd, yyyy");
+ } else {
+ // For weekly mode, show start and end dates of the week
+ const startDate = DateTime.fromISO(dateStr);
+ const endDate = startDate.plus({ days: 6 }); // End of week (7 days total)
+
+ // If same month, don't repeat month name
+ if (startDate.month === endDate.month) {
+ return `${startDate.toFormat("MMM dd")} - ${endDate.toFormat(
+ "dd, yyyy"
+ )}`;
+ } else if (startDate.year === endDate.year) {
+ // Different months, same year
+ return `${startDate.toFormat("MMM dd")} - ${endDate.toFormat(
+ "MMM dd, yyyy"
+ )}`;
+ } else {
+ // Different years
+ return `${startDate.toFormat("MMM dd, yyyy")} - ${endDate.toFormat(
+ "MMM dd, yyyy"
+ )}`;
+ }
+ }
+ };
+
+ // Labels for column headers based on mode
+ const getPeriodLabel = (index: number) => {
+ return mode === "day" ? `Day ${index}` : `Week ${index}`;
+ };
+
+ const handleModeChange = (newMode: string) => {
+ setMode(newMode as RetentionMode);
+ };
+
+ const handleRangeChange = (value: string) => {
+ setTimeRange(parseInt(value));
+ };
+
+ // Common filters for both views
+ const FilterControls = () => (
+ <div className="flex items-center gap-4 flex-wrap justify-end">
+ <div className="flex items-center gap-2">
+ <Label htmlFor="time-range" className="text-sm whitespace-nowrap">
+ Time Range:
+ <TooltipProvider>
+ <Tooltip>
+ <TooltipTrigger asChild>
+ <HelpCircle className="h-3.5 w-3.5 ml-1 inline-block text-neutral-400" />
+ </TooltipTrigger>
+ <TooltipContent>
+ <p className="w-[200px] text-xs">
+ Amount of historical data to include in the retention
+ calculation. All available periods within this timeframe will
+ be shown.
+ </p>
+ </TooltipContent>
+ </Tooltip>
+ </TooltipProvider>
+ </Label>
+ <Select
+ value={timeRange.toString()}
+ onValueChange={handleRangeChange}
+ disabled={isLoading}
+ >
+ <SelectTrigger id="time-range" className="w-28" size="sm">
+ <SelectValue placeholder="90 days" />
+ </SelectTrigger>
+ <SelectContent size="sm">
+ {RANGE_OPTIONS.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </div>
+ <Tabs value={mode} onValueChange={handleModeChange}>
+ <TabsList>
+ <TabsTrigger value="day" disabled={isLoading}>
+ Daily
+ </TabsTrigger>
+ <TabsTrigger value="week" disabled={isLoading}>
+ Weekly
+ </TabsTrigger>
+ </TabsList>
+ </Tabs>
+ </div>
+ );
+
+ // Render error state
+ if (isError) {
+ return (
+ <div className="pt-4">
+ <Card>
+ <CardHeader>
+ <CardTitle>User Retention</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <div className="p-8 text-center">
+ <div className="text-red-500 mb-2 font-medium">
+ Error loading retention data
+ </div>
+ <p className="text-neutral-500 text-sm">
+ There was a problem fetching the retention data. Please try
+ again later.
+ </p>
+ </div>
+ </CardContent>
+ </Card>
+ </div>
+ );
+ }
+
+ // Render empty state
+ if (data && (!data.cohorts || cohortKeys.length === 0)) {
+ return (
+ <div className="pt-4">
+ <Card>
+ <CardHeader>
+ <CardTitle>User Retention</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <div className="p-8 text-center">
+ <div className="text-neutral-300 mb-2 font-medium">
+ No retention data available
+ </div>
+ <p className="text-neutral-500 text-sm">
+ Try selecting a different time range or make sure you have
+ tracking data in the system.
+ </p>
+ </div>
+ </CardContent>
+ </Card>
+ </div>
+ );
+ }
+
+ const periodHeaders =
+ !isLoading && data
+ ? Array.from({ length: data.maxPeriods + 1 }, (_, i) => getPeriodLabel(i))
+ : [];
+
+ return (
+ <div className="pt-4">
+ {/* Single Card containing both chart and grid */}
+ <Card>
+ <CardHeader className="flex flex-row items-center justify-between pb-2">
+ <CardTitle>User Retention</CardTitle>
+ <FilterControls />
+ </CardHeader>
+ <CardContent className="space-y-6">
+ {/* Retention Chart */}
+ {isLoading ? (
+ <div className="h-[400px]">
+ <div className="w-full h-full space-y-3">
+ <Skeleton className="h-[350px] w-full bg-neutral-900 rounded-md animate-pulse" />
+ </div>
+ </div>
+ ) : data ? (
+ <RetentionChart data={data} isLoading={false} mode={mode} />
+ ) : null}
+
+ <div>
+ {isLoading ? (
+ <RetentionGridSkeleton />
+ ) : data ? (
+ <div className="overflow-x-auto">
+ <div
+ className="inline-grid gap-px bg-neutral-900 rounded-lg shadow-lg"
+ style={{
+ gridTemplateColumns: `minmax(120px, auto) repeat(${
+ data.maxPeriods + 1
+ }, minmax(90px, auto))`,
+ }}
+ >
+ {/* Header Row */}
+ <div className="p-2 text-sm font-semibold bg-neutral-900 text-neutral-100 text-center sticky left-0 z-10 border-b border-r border-neutral-700">
+ Cohort
+ </div>
+ {periodHeaders.map((header) => (
+ <div
+ key={header}
+ className="p-2 text-sm bg-neutral-900 text-neutral-100 text-center border-b border-neutral-700"
+ >
+ {header}
+ </div>
+ ))}
+
+ {/* Data Rows */}
+ {cohortKeys.map((cohortPeriod) => (
+ <Fragment key={cohortPeriod}>
+ {/* Cohort Info Cell */}
+ <div className="p-3 bg-neutral-900 text-sm sticky left-0 z-10 border-r border-neutral-800">
+ <div className="font-medium whitespace-nowrap text-neutral-100">
+ {formatDate(cohortPeriod)}
+ </div>
+ <div className="text-xs text-neutral-300 mt-1 whitespace-nowrap">
+ {data.cohorts[cohortPeriod].size.toLocaleString()}{" "}
+ users
+ </div>
+ </div>
+ {/* Retention Cells */}
+ {data.cohorts[cohortPeriod].percentages.map(
+ (percentage: number | null, index: number) => {
+ const { backgroundColor, textColor } =
+ getRetentionColor(percentage);
+ return (
+ <div
+ key={`${cohortPeriod}-period-${index}`}
+ className="m-[2px] p-3 text-center flex items-center justify-center font-medium transition-colors duration-150 bg-neutral-900 rounded-md"
+ style={{
+ backgroundColor,
+ color: textColor,
+ }}
+ >
+ {percentage !== null
+ ? `${percentage.toFixed(1)}%`
+ : "-"}
+ </div>
+ );
+ }
+ )}
+ </Fragment>
+ ))}
+ </div>
+ </div>
+ ) : null}
+ </div>
+ </CardContent>
+ </Card>
+ </div>
+ );
+}
diff --git a/server/src/api/getOverviewBucketed.ts b/server/src/api/getOverviewBucketed.ts
index 9e87dbeaa..fa46e300c 100644
--- a/server/src/api/getOverviewBucketed.ts
+++ b/server/src/api/getOverviewBucketed.ts
@@ -208,8 +208,6 @@ export async function getOverviewBucketed(
pastMinutes,
});
- console.info(query);
-
try {
const result = await clickhouse.query({
query,
diff --git a/server/src/api/getRetention.ts b/server/src/api/getRetention.ts
new file mode 100644
index 000000000..323ebd2fb
--- /dev/null
+++ b/server/src/api/getRetention.ts
@@ -0,0 +1,170 @@
+import { FastifyReply, FastifyRequest } from "fastify";
+import clickhouse from "../db/clickhouse/clickhouse.js";
+import { getUserHasAccessToSite } from "../lib/auth-utils.js";
+import { processResults } from "./utils.js";
+
+// Define the expected shape of a single data row from the query
+interface RetentionDataRow {
+ cohort_period: string;
+ period_difference: number;
+ cohort_size: number;
+ retained_users: number;
+ retention_percentage: number;
+}
+
+// Processed data structure for the frontend
+interface ProcessedRetentionData {
+ cohorts: Record<string, { size: number; percentages: (number | null)[] }>;
+ maxPeriods: number;
+ mode: "day" | "week";
+ range: number;
+}
+
+export const getRetention = async (
+ req: FastifyRequest<{
+ Params: { site: string };
+ Querystring: { mode?: string; range?: string };
+ }>,
+ res: FastifyReply
+) => {
+ const { site } = req.params;
+ const { mode = "week", range = "90" } = req.query; // Default to weekly mode and 90 days range
+
+ // Validate mode parameter
+ const retentionMode = mode === "day" ? "day" : "week";
+
+ // Validate range parameter (between 7-365 days)
+ const timeRange = Math.min(365, Math.max(7, parseInt(range) || 90));
+
+ const userHasAccessToSite = await getUserHasAccessToSite(req, site);
+ if (!userHasAccessToSite) {
+ return res.status(403).send({ error: "Forbidden" });
+ }
+
+ // Build the appropriate SQL based on the retention mode
+ const periodFunction = retentionMode === "day" ? "toDate" : "toStartOfWeek";
+ const periodDiffFunc = retentionMode === "day" ? "day" : "week";
+
+ const query = await clickhouse.query({
+ query: `
+WITH UserFirstPeriod AS (
+ SELECT
+ user_id,
+ ${periodFunction}(min(timestamp)${
+ retentionMode === "week" ? ", 1" : ""
+ }) AS cohort_period
+ FROM pageviews
+ WHERE site_id = {siteId:UInt16}
+ -- Use the configurable time range
+ AND timestamp >= addDays(today(), -{timeRange:UInt16})
+ GROUP BY user_id
+),
+PeriodActivity AS (
+ SELECT DISTINCT
+ user_id,
+ ${periodFunction}(timestamp${
+ retentionMode === "week" ? ", 1" : ""
+ }) AS activity_period
+ FROM pageviews
+ WHERE site_id = {siteId:UInt16}
+ -- Match the date range filter
+ AND timestamp >= addDays(today(), -{timeRange:UInt16})
+),
+CohortRetention AS (
+ SELECT
+ ufp.cohort_period,
+ dateDiff('${periodDiffFunc}', ufp.cohort_period, pa.activity_period) AS period_difference,
+ count(DISTINCT pa.user_id) AS retained_users
+ FROM UserFirstPeriod ufp
+ JOIN PeriodActivity pa ON ufp.user_id = pa.user_id
+ WHERE pa.activity_period >= ufp.cohort_period
+ GROUP BY
+ ufp.cohort_period,
+ period_difference
+),
+CohortSize AS (
+ SELECT
+ cohort_period,
+ count(DISTINCT user_id) AS total_users
+ FROM UserFirstPeriod
+ GROUP BY cohort_period
+)
+SELECT
+ cr.cohort_period,
+ cr.period_difference,
+ cs.total_users AS cohort_size,
+ cr.retained_users,
+ round(cr.retained_users * 100.0 / cs.total_users, 2) AS retention_percentage
+FROM CohortRetention cr
+JOIN CohortSize cs ON cr.cohort_period = cs.cohort_period
+ORDER BY
+ cr.cohort_period DESC,
+ cr.period_difference ASC;
+ `,
+ format: "JSONEachRow",
+ query_params: {
+ siteId: Number(site),
+ timeRange: timeRange,
+ },
+ });
+
+ const results = await processResults<RetentionDataRow>(query);
+
+ // Process data into a grid-friendly format
+ const processedData: ProcessedRetentionData = {
+ ...processRetentionData(results),
+ mode: retentionMode as "day" | "week",
+ range: timeRange,
+ };
+
+ return res.send({ data: processedData });
+};
+
+// Process raw retention data into a grid-friendly format
+function processRetentionData(
+ rawData: RetentionDataRow[]
+): Omit<ProcessedRetentionData, "mode" | "range"> {
+ if (!rawData || rawData.length === 0) {
+ return { cohorts: {}, maxPeriods: 0 };
+ }
+
+ const processedCohorts: Record<
+ string,
+ { size: number; percentages: (number | null)[] }
+ > = {};
+ let maxPeriodDiff = 0;
+
+ rawData.forEach((row) => {
+ if (!processedCohorts[row.cohort_period]) {
+ processedCohorts[row.cohort_period] = {
+ size: row.cohort_size,
+ percentages: [],
+ };
+ }
+ // Ensure array is long enough, filling gaps with null
+ while (
+ processedCohorts[row.cohort_period].percentages.length <=
+ row.period_difference
+ ) {
+ processedCohorts[row.cohort_period].percentages.push(null);
+ }
+ processedCohorts[row.cohort_period].percentages[row.period_difference] =
+ row.retention_percentage;
+
+ if (row.period_difference > maxPeriodDiff) {
+ maxPeriodDiff = row.period_difference;
+ }
+ });
+
+ // Ensure all percentage arrays have the same length for grid alignment
+ const finalMaxPeriods = Math.max(maxPeriodDiff, 0);
+
+ Object.values(processedCohorts).forEach((cohort) => {
+ // Ensure all cohorts have the same number of periods
+ while (cohort.percentages.length <= finalMaxPeriods) {
+ cohort.percentages.push(null);
+ }
+ });
+
+ return { cohorts: processedCohorts, maxPeriods: finalMaxPeriods };
+}
diff --git a/server/src/index.ts b/server/src/index.ts
index ff2ead02e..54d04fb82 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -33,6 +33,7 @@ import { initializeCronJobs } from "./cron/index.js";
import { getUserSubscription } from "./api/user/getUserSubscription.js";
import { getUserInfo } from "./api/getUserInfo.js";
import { getLiveSessionLocations } from "./api/getLiveSessionLocations.js";
+import { getRetention } from "./api/getRetention.js";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
@@ -127,6 +128,7 @@ server.get("/live-user-count/:site", getLiveUsercount);
server.get("/overview", getOverview);
server.get("/overview-bucketed", getOverviewBucketed);
server.get("/single-col", getSingleCol);
+server.get("/retention/:site", getRetention);
server.get("/site-has-data/:site", getSiteHasData);
server.get("/sessions", getSessions);
server.get("/session/:sessionId", getSession);