Custom-Events | Analytics module

Author: OmerKat

src/client.ts

@@ -15,6 +15,7 @@ import type {
   CreateClientConfig,
   CreateClientOptions,
 } from "./client.types.js";
+import { createAnalyticsModule } from "./modules/analytics.js";
 
 // Re-export client types
 export type { Base44Client, CreateClientConfig, CreateClientOptions };
@@ -144,6 +145,11 @@ export function createClient(config: CreateClientConfig): Base44Client {
     }),
     appLogs: createAppLogsModule(axiosClient, appId),
     users: createUsersModule(axiosClient, appId),
+    analytics: createAnalyticsModule({
+      axiosClient,
+      appId,
+      options: options?.analytics,
+    }),
     cleanup: () => {
       if (socket) {
         socket.disconnect();

src/client.types.ts

@@ -6,6 +6,7 @@ import type { ConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
 import type { AgentsModule } from "./modules/agents.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
+import type { AnalyticsModuleOptions } from "./modules/analytics.types.js";
 
 /**
  * Options for creating a Base44 client.
@@ -15,6 +16,7 @@ export interface CreateClientOptions {
    * Optional error handler that will be called whenever an API error occurs.
    */
   onError?: (error: Error) => void;
+  analytics?: AnalyticsModuleOptions;
 }
 
 /**

src/modules/analytics.ts

@@ -0,0 +1,121 @@
+import { AxiosInstance } from "axios";
+import {
+  TrackEventParams,
+  TrackEventData,
+  AnalyticsApiRequestData,
+  AnalyticsApiBatchRequest,
+  TrackEventIntrinsicData,
+  AnalyticsModuleOptions,
+} from "./analytics.types";
+import {
+  getSharedInstance,
+  getSharedInstanceRefCount,
+} from "../utils/singleton";
+
+///////////////////////////////////////////////
+//// shared queue for analytics events     ////
+///////////////////////////////////////////////
+type AnalyticsSharedState = {
+  requestsQueue: TrackEventData[];
+};
+
+const ANALYTICS_SHARED_STATE_NAME = "analytics";
+// shared state//
+const analyticsSharedState = getSharedInstance<AnalyticsSharedState>(
+  ANALYTICS_SHARED_STATE_NAME,
+  () => ({
+    requestsQueue: [],
+  })
+);
+///////////////////////////////////////////////
+
+export interface AnalyticsModuleArgs {
+  axiosClient: AxiosInstance;
+  appId: string;
+  options?: AnalyticsModuleOptions;
+}
+
+export const createAnalyticsModule = ({
+  axiosClient,
+  appId,
+  options,
+}: AnalyticsModuleArgs) => {
+  // prevent overflow of events //
+  const MAX_QUEUE_SIZE = 1000;
+  const isEnabled = options?.enabled !== false;
+
+  const track = (params: TrackEventParams) => {
+    if (
+      !isEnabled ||
+      analyticsSharedState.requestsQueue.length >= MAX_QUEUE_SIZE
+    ) {
+      return;
+    }
+    const intrinsicData = getEventIntrinsicData();
+    analyticsSharedState.requestsQueue.push({
+      ...params,
+      ...intrinsicData,
+    });
+  };
+
+  const flush = async (eventsData: TrackEventData[]) => {
+    const apiEvents = eventsData.map(transformEventDataToApiRequestData);
+    await axiosClient.request({
+      method: "POST",
+      url: `/apps/${appId}/analytics/track/batch`,
+      data: { events: apiEvents },
+    } as AnalyticsApiBatchRequest);
+  };
+
+  // start analytics processor only if it's the first instance and analytics is enabled //
+  if (
+    getSharedInstanceRefCount(ANALYTICS_SHARED_STATE_NAME) <= 1 &&
+    isEnabled
+  ) {
+    startAnalyticsProcessor(flush, options?.trackService);
+  }
+
+  return {
+    track,
+  };
+};
+
+async function startAnalyticsProcessor(
+  handleTrack: (trackRequest: TrackEventData[]) => Promise<void>,
+  options?: {
+    throttleTime: number;
+    batchSize: number;
+  }
+) {
+  const { throttleTime = 1000, batchSize = 30 } = options ?? {};
+  while (true) {
+    await new Promise((resolve) => setTimeout(resolve, throttleTime));
+    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);
+      }
+    }
+  }
+}
+
+function getEventIntrinsicData(): TrackEventIntrinsicData {
+  return {
+    timestamp: new Date().toISOString(),
+    pageUrl: typeof window !== "undefined" ? window.location.href : null,
+  };
+}
+
+function transformEventDataToApiRequestData(
+  eventData: TrackEventData
+): AnalyticsApiRequestData {
+  return {
+    event_name: eventData.eventName,
+    properties: eventData.properties,
+    timestamp: eventData.timestamp,
+    page_url: eventData.pageUrl,
+  };
+}

src/modules/analytics.types.ts

@@ -0,0 +1,41 @@
+export type TrackEventProperties = {
+  [key: string]: string | number | boolean | null | undefined;
+};
+
+export type TrackEventParams = {
+  eventName: string;
+  properties?: TrackEventProperties;
+};
+
+export type TrackEventIntrinsicData = {
+  timestamp: string;
+  pageUrl?: string | null;
+};
+
+export type TrackEventData = {
+  properties?: TrackEventProperties;
+  eventName: string;
+} & TrackEventIntrinsicData;
+
+export type AnalyticsApiRequestData = {
+  event_name: string;
+  properties?: TrackEventProperties;
+  timestamp?: string;
+  page_url?: string | null;
+};
+
+export type AnalyticsApiBatchRequest = {
+  method: "POST";
+  url: `/apps/${string}/analytics/track/batch`;
+  data: {
+    events: AnalyticsApiRequestData[];
+  };
+};
+
+export type AnalyticsModuleOptions = {
+  enabled?: boolean;
+  trackService?: {
+    throttleTime: number;
+    batchSize: number;
+  };
+};

src/modules/types.ts

@@ -1,3 +1,4 @@
 export * from "./app.types.js";
 export * from "./agents.types.js";
-export * from "./connectors.types.js";
+export * from "./connectors.types.js";
+export * from "./analytics.types.js";

src/utils/singleton.ts

@@ -0,0 +1,24 @@
+
+
+
+// Singleton (shared between sdk instances)//
+export function getSharedInstance<T>(name: string, factory: () => T): T {
+  const windowObj: Window & {
+    base44?: { [key: string]: { instance: T; _refCount: number } };
+  } = typeof window !== "undefined" ? (window as any) : { base44: {} };
+  if (!windowObj.base44) {
+    windowObj.base44 = {};
+  }
+  if (!windowObj.base44[name]) {
+    windowObj.base44[name] = { instance: factory(), _refCount: 1 };
+  }
+  return windowObj.base44[name].instance;
+}
+
+export function getSharedInstanceRefCount<T>(name: string): number {
+  const windowObj: Window & {
+    base44?: { [key: string]: { instance: T; _refCount: number } };
+  } = typeof window !== "undefined" ? (window as any) : { base44: {} };
+
+  return windowObj.base44?.[name]?._refCount ?? 0;
+}