live users count tracking with heartbeat

Author: OmerKat

src/modules/analytics.ts

@@ -11,11 +11,14 @@ import {
 import { getSharedInstance } from "../utils/sharedInstance";
 import type { AuthModule } from "./auth.types";
 
+export const USER_HEARTBEAT_EVENT_NAME = "__user_heartbeat_event__";
+
 const defaultConfiguration: AnalyticsModuleOptions = {
   enabled: true,
   maxQueueSize: 1000,
   throttleTime: 1000,
   batchSize: 30,
+  heartBeatInterval: 60 * 1000,
 };
 
 ///////////////////////////////////////////////
@@ -29,10 +32,11 @@ const analyticsSharedState = getSharedInstance(
   () => ({
     requestsQueue: [] as TrackEventData[],
     isProcessing: false,
+    isHeartBeatProcessing: false,
     sessionContext: null as SessionContext | null,
     config: {
       ...defaultConfiguration,
-      ...getAnalyticsModuleOptionsFromUrlParams(),
+      ...getAnalyticsModuleOptionsFromLocalStorage(),
     } as Required<AnalyticsModuleOptions>,
   })
 );
@@ -55,19 +59,9 @@ export const createAnalyticsModule = ({
   // prevent overflow of events //
   const { enabled, maxQueueSize, throttleTime, batchSize } =
     analyticsSharedState.config;
-
+  let clearHeartBeatProcessor: (() => void) | undefined = undefined;
   const trackBatchUrl = `${serverUrl}/api/apps/${appId}/analytics/track/batch`;
 
-  const getSessionContext = async () => {
-    if (!analyticsSharedState.sessionContext) {
-      const user = await userAuthModule.me();
-      analyticsSharedState.sessionContext = {
-        user_id: user.id,
-      };
-    }
-    return analyticsSharedState.sessionContext;
-  };
-
   const batchRequestFallback = async (events: AnalyticsApiRequestData[]) => {
     await axiosClient.request({
       method: "POST",
@@ -77,49 +71,25 @@ export const createAnalyticsModule = ({
   };
 
   const flush = async (eventsData: TrackEventData[]) => {
-    const sessionContext_ = await getSessionContext();
+    const sessionContext_ = await getSessionContext(userAuthModule);
     const events = eventsData.map(
       transformEventDataToApiRequestData(sessionContext_)
     );
     const beaconPayload = JSON.stringify({ events });
-
-    if (
-      typeof navigator === "undefined" ||
-      beaconPayload.length > 60000 ||
-      !navigator.sendBeacon(trackBatchUrl, beaconPayload)
-    ) {
-      // beacon didn't work, fallback to axios
-      await batchRequestFallback(events);
-    }
-  };
-
-  const onDocHidden = () => {
-    stopAnalyticsProcessor();
-    //  flush entire queue on visibility change and hope for the best //
-    const eventsData = analyticsSharedState.requestsQueue.splice(0);
-    flush(eventsData);
-  };
-
-  const onDocVisible = () => {
-    startAnalyticsProcessor(flush, {
-      throttleTime,
-      batchSize,
-    });
-  };
-
-  const onVisibilityChange = () => {
-    if (typeof window === "undefined") return;
-    if (document.visibilityState === "hidden") {
-      onDocHidden();
-    } else if (document.visibilityState === "visible") {
-      onDocVisible();
+    try {
+      if (
+        typeof navigator === "undefined" ||
+        beaconPayload.length > 60000 ||
+        !navigator.sendBeacon(trackBatchUrl, beaconPayload)
+      ) {
+        // beacon didn't work, fallback to axios
+        await batchRequestFallback(events);
+      }
+    } catch {
+      // TODO: think about retries if needed
     }
   };
 
-  if (typeof window !== "undefined" && enabled) {
-    window.addEventListener("visibilitychange", onVisibilityChange);
-  }
-
   const startProcessing = () => {
     if (!enabled) return;
     startAnalyticsProcessor(flush, {
@@ -140,14 +110,47 @@ export const createAnalyticsModule = ({
     startProcessing();
   };
 
-  const cleanup = () => {
+  const onDocVisible = () => {
+    startAnalyticsProcessor(flush, {
+      throttleTime,
+      batchSize,
+    });
+    clearHeartBeatProcessor = startHeartBeatProcessor(track);
+  };
+
+  const onDocHidden = () => {
+    stopAnalyticsProcessor();
+    //  flush entire queue on visibility change and hope for the best //
+    const eventsData = analyticsSharedState.requestsQueue.splice(0);
+    flush(eventsData);
+    clearHeartBeatProcessor?.();
+  };
+
+  const onVisibilityChange = () => {
     if (typeof window === "undefined") return;
-    window.removeEventListener("visibilitychange", onVisibilityChange);
+    if (document.visibilityState === "hidden") {
+      onDocHidden();
+    } else if (document.visibilityState === "visible") {
+      onDocVisible();
+    }
+  };
+
+  const cleanup = () => {
     stopAnalyticsProcessor();
+    clearHeartBeatProcessor?.();
+    if (typeof window !== "undefined") {
+      window.removeEventListener("visibilitychange", onVisibilityChange);
+    }
   };
 
   // start the flusing process ///
   startProcessing();
+  // start the heart beat processor //
+  clearHeartBeatProcessor = startHeartBeatProcessor(track);
+  // start the visibility change listener //
+  if (typeof window !== "undefined" && enabled) {
+    window.addEventListener("visibilitychange", onVisibilityChange);
+  }
 
   return {
     track,
@@ -178,19 +181,31 @@ async function startAnalyticsProcessor(
     analyticsSharedState.requestsQueue.length > 0
   ) {
     const requests = analyticsSharedState.requestsQueue.splice(0, batchSize);
-    if (requests.length > 0) {
-      try {
-        await handleTrack(requests);
-      } catch (error) {
-        // TODO: think about retries if needed
-        console.error("Error processing analytics request:", error);
-      }
-    }
+    requests.length && (await handleTrack(requests));
     await new Promise((resolve) => setTimeout(resolve, throttleTime));
   }
   analyticsSharedState.isProcessing = false;
 }
 
+function startHeartBeatProcessor(track: (params: TrackEventParams) => void) {
+  if (
+    analyticsSharedState.isHeartBeatProcessing ||
+    (analyticsSharedState.config.heartBeatInterval ?? 0) < 10
+  ) {
+    return () => {};
+  }
+
+  analyticsSharedState.isHeartBeatProcessing = true;
+  const interval = setInterval(() => {
+    track({ eventName: USER_HEARTBEAT_EVENT_NAME });
+  }, analyticsSharedState.config.heartBeatInterval);
+
+  return () => {
+    clearInterval(interval);
+    analyticsSharedState.isHeartBeatProcessing = false;
+  };
+}
+
 function getEventIntrinsicData(): TrackEventIntrinsicData {
   return {
     timestamp: new Date().toISOString(),
@@ -208,14 +223,31 @@ function transformEventDataToApiRequestData(sessionContext: SessionContext) {
   });
 }
 
-export function getAnalyticsModuleOptionsFromUrlParams():
+let sessionContextPromise: Promise<SessionContext> | null = null;
+async function getSessionContext(userAuthModule: AuthModule) {
+  if (!analyticsSharedState.sessionContext) {
+    if (!sessionContextPromise) {
+      sessionContextPromise = userAuthModule
+        .me()
+        .then((user) => ({
+          user_id: user.id,
+        }))
+        .catch(() => ({
+          user_id: "unknown: error getting session context",
+        }));
+    }
+    analyticsSharedState.sessionContext = await sessionContextPromise;
+  }
+  return analyticsSharedState.sessionContext;
+}
+
+export function getAnalyticsModuleOptionsFromLocalStorage():
   | AnalyticsModuleOptions
   | undefined {
   if (typeof window === "undefined") return undefined;
-  const urlParams = new URLSearchParams(window.location.search);
-  const jsonString = urlParams.get("analytics");
-  if (!jsonString) return undefined;
   try {
+    const jsonString = localStorage.getItem("base44_analytics_config");
+    if (!jsonString) return undefined;
     return JSON.parse(jsonString);
   } catch {
     return undefined;

src/modules/analytics.types.ts

@@ -41,6 +41,8 @@ export type AnalyticsModuleOptions = {
   maxQueueSize?: number;
   throttleTime?: number;
   batchSize?: number;
+  // used for live users count tracking
+  heartBeatInterval?: number;
 };
 
 export type AnalyticsModule = {

tests/unit/analytics.test.ts

@@ -50,6 +50,7 @@ describe("Analytics Module", () => {
       maxQueueSize: 1000,
       throttleTime: 1000,
       batchSize: 2,
+      heartBeatInterval: undefined,
     };
 
     base44 = createClient({