Skip to content

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

add event tracking

Bill Yangfcdbe1429fa8
diff --git a/server/public/script.js b/server/public/script.js
index 7ba9a031a..4b60bee31 100644
--- a/server/public/script.js
+++ b/server/public/script.js
@@ -9,10 +9,13 @@
return;
}
- const SITE_ID = scriptTag.getAttribute("site-id");
+ const SITE_ID =
+ scriptTag.getAttribute("data-site-id") || scriptTag.getAttribute("site-id");
if (!SITE_ID || isNaN(Number(SITE_ID))) {
- console.error("Please provide a valid site ID");
+ console.error(
+ "Please provide a valid site ID using the data-site-id attribute"
+ );
return;
}
@@ -21,6 +24,9 @@
? Math.max(0, parseInt(scriptTag.getAttribute("data-debounce")))
: 500;
+ // Check if automatic URL tracking should be disabled
+ const autoTrackURLs = scriptTag.getAttribute("data-auto-track") !== "false";
+
// Debounce function
function debounce(func, wait) {
let timeout;
@@ -30,8 +36,19 @@
};
}
- // Track pageview (core functionality)
- const trackPageview = () => {
+ // Unified tracking function for all event types
+ const track = (eventType = "pageview", eventName = "", properties = {}) => {
+ // Validate event data
+ if (
+ eventType === "custom_event" &&
+ (!eventName || typeof eventName !== "string")
+ ) {
+ console.error(
+ "Event name is required and must be a string for custom events"
+ );
+ return;
+ }
+
const url = new URL(window.location.href);
const payload = {
site_id: SITE_ID,
@@ -43,11 +60,16 @@
language: navigator.language,
page_title: document.title,
referrer: document.referrer,
+ event_type: eventType,
+ event_name: eventName,
+ properties:
+ eventType === "custom_event" ? JSON.stringify(properties) : undefined,
};
- console.log(payload);
+ console.log(`${eventType} event:`, payload);
- fetch(`${ANALYTICS_HOST}/track/pageview`, {
+ // Use the new unified endpoint
+ fetch(`${ANALYTICS_HOST}/track`, {
method: "POST",
headers: {
"Content-Type": "application/json",
@@ -58,34 +80,42 @@
}).catch(console.error);
};
+ // Helper function for pageviews
+ const trackPageview = () => track("pageview");
+
// Create debounced version with configured duration
const debouncedTrackPageview =
debounceDuration > 0
? debounce(trackPageview, debounceDuration)
: trackPageview;
- // History API override
- const originalPushState = history.pushState;
- const originalReplaceState = history.replaceState;
+ // Only set up automatic URL change tracking if not disabled
+ if (autoTrackURLs) {
+ // History API override
+ const originalPushState = history.pushState;
+ const originalReplaceState = history.replaceState;
- history.pushState = function (...args) {
- originalPushState.apply(this, args);
- debouncedTrackPageview();
- };
+ history.pushState = function (...args) {
+ originalPushState.apply(this, args);
+ debouncedTrackPageview();
+ };
- history.replaceState = function (...args) {
- originalReplaceState.apply(this, args);
- debouncedTrackPageview();
- };
+ history.replaceState = function (...args) {
+ originalReplaceState.apply(this, args);
+ debouncedTrackPageview();
+ };
- // Handle navigation events
- window.addEventListener("popstate", debouncedTrackPageview);
+ // Handle navigation events
+ window.addEventListener("popstate", debouncedTrackPageview);
+ }
// Expose API
window.frogstats = {
- trackPageview: debouncedTrackPageview,
- // Add direct access to non-debounced version if needed
- _trackImmediately: trackPageview,
+ // Core tracking function
+ track,
+ // Helper functions for backward compatibility and convenience
+ pageview: trackPageview,
+ event: (name, properties = {}) => track("custom_event", name, properties),
};
// Initial pageview
diff --git a/server/src/db/clickhouse/clickhouse.ts b/server/src/db/clickhouse/clickhouse.ts
index d23e2cdce..29644d9a6 100644
--- a/server/src/db/clickhouse/clickhouse.ts
+++ b/server/src/db/clickhouse/clickhouse.ts
@@ -30,7 +30,10 @@ export const initializeClickhouse = async () => {
iso_3166_2 LowCardinality(String),
screen_width UInt16,
screen_height UInt16,
- device_type LowCardinality(String)
+ device_type LowCardinality(String),
+ event_type LowCardinality(String) DEFAULT 'pageview',
+ event_name String,
+ properties String
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(timestamp)
diff --git a/server/src/index.ts b/server/src/index.ts
index f42940a65..50bbf66d8 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -25,7 +25,7 @@ import { cleanupOldSessions } from "./db/postgres/session-cleanup.js";
import { allowList, loadAllowedDomains } from "./lib/allowedDomains.js";
import { auth } from "./lib/auth.js";
import { mapHeaders } from "./lib/auth-utils.js";
-import { trackPageView } from "./tracker/trackPageView.js";
+import { trackEvent } from "./tracker/trackEvent.js";
import { listOrganizationMembers } from "./api/listOrganizationMembers.js";
import { getUserOrganizations } from "./api/user/getUserOrganizations.js";
import { initializeCronJobs } from "./cron/index.js";
@@ -142,8 +142,11 @@ server.get(
server.get("/user/organizations", getUserOrganizations);
server.get("/user/subscription", getUserSubscription);
-// Track pageview endpoint
-server.post("/track/pageview", trackPageView);
+// Track endpoints
+server.post("/track/pageview", trackEvent);
+server.post("/track/event", trackEvent);
+// New unified endpoint
+server.post("/track", trackEvent);
const start = async () => {
try {
diff --git a/server/src/tracker/pageviewQueue.ts b/server/src/tracker/pageviewQueue.ts
index 173419290..3a83e0881 100644
--- a/server/src/tracker/pageviewQueue.ts
+++ b/server/src/tracker/pageviewQueue.ts
@@ -10,6 +10,9 @@ type TotalPayload = TrackingPayload & {
ua: UAParser.IResult;
referrer: string;
ipAddress: string;
+ event_type?: string;
+ event_name?: string;
+ properties?: string;
};
class PageviewQueue {
@@ -82,6 +85,9 @@ class PageviewQueue {
country: countryCode,
iso_3166_2:
countryCode && regionCode ? countryCode + "-" + regionCode : "",
+ event_type: pv.event_type || "pageview",
+ event_name: pv.event_name || "",
+ properties: pv.properties,
};
});
diff --git a/server/src/tracker/trackEvent.ts b/server/src/tracker/trackEvent.ts
new file mode 100644
index 000000000..ffc2cecfc
--- /dev/null
+++ b/server/src/tracker/trackEvent.ts
@@ -0,0 +1,71 @@
+import { FastifyReply, FastifyRequest } from "fastify";
+import { TrackingPayload } from "../types.js";
+import {
+ BaseTrackingPayload,
+ createBasePayload,
+ getExistingSession,
+ isSiteOverLimit,
+ processTrackingEvent,
+} from "./trackingUtils.js";
+
+// Extended type for tracking payloads with event data
+export interface EventTrackingPayload extends BaseTrackingPayload {
+ event_type: "pageview" | "custom_event";
+ event_name?: string; // Required for custom_event, optional for pageview
+ properties?: string;
+}
+
+// Unified handler for all events (pageviews and custom events)
+export async function trackEvent(
+ request: FastifyRequest<{ Body: EventTrackingPayload }>,
+ reply: FastifyReply
+) {
+ try {
+ // Check if the site has exceeded its monthly limit
+ if (isSiteOverLimit(request.body.site_id)) {
+ console.log(
+ `[Tracking] Skipping event for site ${request.body.site_id} - over monthly limit`
+ );
+ return reply
+ .status(200)
+ .send("Site over monthly limit, event not tracked");
+ }
+
+ // Validate event data based on type
+ const eventType = request.body.event_type || "pageview";
+
+ // Ensure custom events have an event name
+ if (eventType === "custom_event" && !request.body.event_name) {
+ return reply.status(400).send({
+ success: false,
+ error: "Event name is required for custom events",
+ });
+ }
+
+ // Create base payload for the event
+ const payload = createBasePayload(
+ request,
+ eventType as "pageview" | "custom_event"
+ );
+
+ // Get existing session
+ const existingSession = await getExistingSession(payload.userId);
+
+ // Process the event (isPageview = true for pageview events)
+ await processTrackingEvent(
+ payload,
+ existingSession,
+ eventType === "pageview"
+ );
+
+ return reply.status(200).send({
+ success: true,
+ });
+ } catch (error) {
+ console.error("Error tracking event:", error);
+ return reply.status(500).send({
+ success: false,
+ error: "Failed to track event",
+ });
+ }
+}
diff --git a/server/src/tracker/trackPageView.ts b/server/src/tracker/trackPageView.ts
deleted file mode 100644
index b95739d7b..000000000
--- a/server/src/tracker/trackPageView.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-import crypto from "crypto";
-import { eq } from "drizzle-orm";
-import { FastifyReply, FastifyRequest } from "fastify";
-import UAParser, { UAParser as userAgentParser } from "ua-parser-js";
-import { db, sql } from "../db/postgres/postgres.js";
-import { activeSessions } from "../db/postgres/schema.js";
-import { TrackingPayload } from "../types.js";
-import { getDeviceType, getIpAddress, getUserId } from "../utils.js";
-
-import { sitesOverLimit } from "../cron/monthly-usage-checker.js";
-import { pageviewQueue } from "./pageviewQueue.js";
-
-type TotalPayload = TrackingPayload & {
- userId: string;
- timestamp: string;
- sessionId: string;
- ua: UAParser.IResult;
- referrer: string;
- ipAddress: string;
-};
-
-// Extended type for database active sessions
-type ActiveSession = {
- session_id: string;
- site_id: number | null;
- user_id: string;
- pageviews: number;
- hostname: string | null;
- start_time: Date | null;
- last_activity: Date | null;
- entry_page: string | null;
- exit_page: string | null;
- device_type: string | null;
- screen_width: number | null;
- screen_height: number | null;
- browser: string | null;
- operating_system: string | null;
- language: string | null;
- referrer: string | null;
-};
-
-const getExistingSession = async (
- userId: string
-): Promise<ActiveSession | null> => {
- // We need to use the raw SQL query here since we're selecting into a specific type
- const [existingSession] = await sql<ActiveSession[]>`
- SELECT * FROM active_sessions WHERE user_id = ${userId}
- `;
- return existingSession;
-};
-
-const updateSession = async (
- pageview: TotalPayload,
- existingSession: ActiveSession | null
-) => {
- if (existingSession) {
- // Update session with Drizzle
- await db
- .update(activeSessions)
- .set({
- lastActivity: new Date(pageview.timestamp),
- pageviews: (existingSession.pageviews || 0) + 1,
- })
- .where(eq(activeSessions.userId, pageview.userId));
- return;
- }
-
- // Insert new session with Drizzle
- const insertData = {
- sessionId: pageview.sessionId,
- siteId:
- typeof pageview.site_id === "string"
- ? parseInt(pageview.site_id, 10)
- : pageview.site_id,
- userId: pageview.userId,
- hostname: pageview.hostname || null,
- startTime: new Date(pageview.timestamp || Date.now()),
- lastActivity: new Date(pageview.timestamp || Date.now()),
- pageviews: 1,
- entryPage: pageview.pathname || null,
- deviceType: getDeviceType(
- pageview.screenWidth,
- pageview.screenHeight,
- pageview.ua
- ),
- screenWidth: pageview.screenWidth || null,
- screenHeight: pageview.screenHeight || null,
- browser: pageview.ua.browser.name || null,
- operatingSystem: pageview.ua.os.name || null,
- language: pageview.language || null,
- referrer: pageview.referrer || null,
- };
-
- await db.insert(activeSessions).values(insertData);
-};
-
-export async function trackPageView(
- request: FastifyRequest<{ Body: TrackingPayload }>,
- reply: FastifyReply
-) {
- try {
- // Check if the site has exceeded its monthly limit
- if (sitesOverLimit.has(Number(request.body.site_id))) {
- console.log(
- `[Tracking] Skipping pageview for site ${request.body.site_id} - over monthly limit`
- );
- return reply
- .status(200)
- .send("Site over monthly limit, pageview not tracked");
- }
-
- const userAgent = request.headers["user-agent"] || "";
- const ipAddress = getIpAddress(request);
- const userId = getUserId(ipAddress, userAgent);
- const existingSession = await getExistingSession(userId);
-
- const payload = {
- ...request.body,
- ipAddress: ipAddress,
- timestamp: new Date().toISOString(),
- ua: userAgentParser(userAgent),
- userId: userId,
- sessionId: existingSession?.session_id || crypto.randomUUID(),
- };
-
- pageviewQueue.add(payload);
- await updateSession(payload, existingSession);
-
- return reply.status(200).send();
- } catch (error) {
- request.log.error(error);
- return reply.status(500).send({
- success: false,
- error: "Failed to track pageview",
- });
- }
-}
diff --git a/server/src/tracker/trackingUtils.ts b/server/src/tracker/trackingUtils.ts
new file mode 100644
index 000000000..4f22434ed
--- /dev/null
+++ b/server/src/tracker/trackingUtils.ts
@@ -0,0 +1,152 @@
+import crypto from "crypto";
+import { eq } from "drizzle-orm";
+import { FastifyRequest } from "fastify";
+import UAParser, { UAParser as userAgentParser } from "ua-parser-js";
+import { db, sql } from "../db/postgres/postgres.js";
+import { activeSessions } from "../db/postgres/schema.js";
+import { TrackingPayload } from "../types.js";
+import { getDeviceType, getIpAddress, getUserId } from "../utils.js";
+import { pageviewQueue } from "./pageviewQueue.js";
+import { sitesOverLimit } from "../cron/monthly-usage-checker.js";
+
+// Define extended payload types
+export type BaseTrackingPayload = TrackingPayload & {
+ event_type?: string;
+ event_name?: string;
+ properties?: string;
+};
+
+export type TotalTrackingPayload = BaseTrackingPayload & {
+ userId: string;
+ timestamp: string;
+ sessionId: string;
+ ua: UAParser.IResult;
+ referrer: string;
+ ipAddress: string;
+};
+
+// Extended type for database active sessions
+export type ActiveSession = {
+ session_id: string;
+ site_id: number | null;
+ user_id: string;
+ pageviews: number;
+ hostname: string | null;
+ start_time: Date | null;
+ last_activity: Date | null;
+ entry_page: string | null;
+ exit_page: string | null;
+ device_type: string | null;
+ screen_width: number | null;
+ screen_height: number | null;
+ browser: string | null;
+ operating_system: string | null;
+ language: string | null;
+ referrer: string | null;
+};
+
+// Check if site is over the monthly limit
+export function isSiteOverLimit(siteId: number | string): boolean {
+ return sitesOverLimit.has(Number(siteId));
+}
+
+// Get existing user session
+export async function getExistingSession(
+ userId: string
+): Promise<ActiveSession | null> {
+ const [existingSession] = await sql<ActiveSession[]>`
+ SELECT * FROM active_sessions WHERE user_id = ${userId}
+ `;
+ return existingSession;
+}
+
+// Create base tracking payload from request
+export function createBasePayload(
+ request: FastifyRequest,
+ eventType: "pageview" | "custom_event" = "pageview"
+): TotalTrackingPayload {
+ const userAgent = request.headers["user-agent"] || "";
+ const ipAddress = getIpAddress(request);
+ const userId = getUserId(ipAddress, userAgent);
+
+ return {
+ ...(request.body as BaseTrackingPayload),
+ event_type: eventType,
+ ipAddress: ipAddress,
+ timestamp: new Date().toISOString(),
+ ua: userAgentParser(userAgent),
+ userId: userId,
+ sessionId: crypto.randomUUID(), // Will be replaced if session exists
+ };
+}
+
+// Update session for both pageviews and events
+export async function updateSession(
+ payload: TotalTrackingPayload,
+ existingSession: ActiveSession | null,
+ isPageview: boolean = true
+): Promise<void> {
+ if (existingSession) {
+ // Update session with Drizzle
+ const updateData: any = {
+ lastActivity: new Date(payload.timestamp),
+ };
+
+ // Only increment pageviews count for actual pageviews
+ if (isPageview) {
+ updateData.pageviews = (existingSession.pageviews || 0) + 1;
+ }
+
+ await db
+ .update(activeSessions)
+ .set(updateData)
+ .where(eq(activeSessions.userId, payload.userId));
+ return;
+ }
+
+ // Insert new session with Drizzle
+ const insertData = {
+ sessionId: payload.sessionId,
+ siteId:
+ typeof payload.site_id === "string"
+ ? parseInt(payload.site_id, 10)
+ : payload.site_id,
+ userId: payload.userId,
+ hostname: payload.hostname || null,
+ startTime: new Date(payload.timestamp || Date.now()),
+ lastActivity: new Date(payload.timestamp || Date.now()),
+ pageviews: isPageview ? 1 : 0,
+ entryPage: payload.pathname || null,
+ deviceType: getDeviceType(
+ payload.screenWidth,
+ payload.screenHeight,
+ payload.ua
+ ),
+ screenWidth: payload.screenWidth || null,
+ screenHeight: payload.screenHeight || null,
+ browser: payload.ua.browser.name || null,
+ operatingSystem: payload.ua.os.name || null,
+ language: payload.language || null,
+ referrer: payload.referrer || null,
+ };
+
+ await db.insert(activeSessions).values(insertData);
+}
+
+// Process tracking event and add to queue
+export async function processTrackingEvent(
+ payload: TotalTrackingPayload,
+ existingSession: ActiveSession | null,
+ isPageview: boolean = true
+): Promise<void> {
+ // If session exists, use its ID instead of generated one
+ if (existingSession) {
+ payload.sessionId = existingSession.session_id;
+ }
+
+ // Add to queue for processing
+ await pageviewQueue.add(payload);
+
+ // Update session data
+ await updateSession(payload, existingSession, isPageview);
+}