fix(analytics): allow clients to disable tracking (#269)

Author: oded-soffrin

src/client.ts

@@ -17,6 +17,7 @@ import { createUsersModule } from "./modules/users.js";
 import { RoomsSocket, RoomsSocketConfig } from "./utils/socket-utils.js";
 import type {
   Base44Client,
+  CreateClientAnalyticsConfig,
   CreateClientConfig,
   CreateClientOptions,
 } from "./client.types.js";
@@ -28,7 +29,12 @@ import {
 } from "./modules/actors.js";
 
 // Re-export client types
-export type { Base44Client, CreateClientConfig, CreateClientOptions };
+export type {
+  Base44Client,
+  CreateClientAnalyticsConfig,
+  CreateClientConfig,
+  CreateClientOptions,
+};
 
 /**
  * Creates a Base44 client.
@@ -71,6 +77,7 @@ export function createClient(config: CreateClientConfig): Base44Client {
   const {
     serverUrl = "https://base44.app",
     appId,
+    analytics,
     token,
     serviceToken,
     requiresAuth = false,
@@ -248,6 +255,7 @@ export function createClient(config: CreateClientConfig): Base44Client {
       serverUrl,
       appId,
       userAuthModule,
+      enabled: analytics?.enabled ?? true,
     }),
     actors: actorsModule.module,
     cleanup: () => {

src/client.types.ts

@@ -36,6 +36,22 @@ export interface CreateClientOptions {
   actorsTransport?: "auto" | "proxy" | "direct";
 }
 
+/**
+ * Configuration for the SDK's app analytics module.
+ */
+export interface CreateClientAnalyticsConfig {
+  /**
+   * Whether app analytics is enabled for this client.
+   *
+   * When disabled, automatic analytics and calls to `analytics.track()` are
+   * no-ops. The SDK does not create an analytics session identifier, start
+   * heartbeat timers, or send analytics requests.
+   *
+   * @defaultValue `true`
+   */
+  enabled: boolean;
+}
+
 /**
  * Configuration for creating a Base44 client.
  */
@@ -62,6 +78,12 @@ export interface CreateClientConfig {
    * It's the string between `/apps/` and `/editor/`.
    */
   appId: string;
+  /**
+   * Controls app analytics for this client.
+   *
+   * Omit this option to preserve the default analytics behavior.
+   */
+  analytics?: CreateClientAnalyticsConfig;
   /**
    * User authentication token. Used to authenticate as a specific user.
    *

src/index.ts

@@ -2,6 +2,7 @@ import {
   createClient,
   createClientFromRequest,
   type Base44Client,
+  type CreateClientAnalyticsConfig,
   type CreateClientConfig,
   type CreateClientOptions,
 } from "./client.js";
@@ -25,6 +26,7 @@ export {
 
 export type {
   Base44Client,
+  CreateClientAnalyticsConfig,
   CreateClientConfig,
   CreateClientOptions,
   Base44ErrorJSON,

src/modules/analytics.ts

@@ -62,13 +62,15 @@ export interface AnalyticsModuleArgs {
   serverUrl: string;
   appId: string;
   userAuthModule: InternalAuthModule;
+  enabled: boolean;
 }
 
 export const createAnalyticsModule = ({
   axiosClient,
   serverUrl,
   appId,
   userAuthModule,
+  enabled,
 }: AnalyticsModuleArgs) => {
   // prevent overflow of events //
   const { maxQueueSize, throttleTime, batchSize } = analyticsSharedState.config;
@@ -77,7 +79,7 @@ export const createAnalyticsModule = ({
   // so the per-callsite `typeof window` guards below aren't enough to keep it
   // from touching `document` (e.g. `document.referrer` on init). Node/SSR is
   // still handled by those `window` guards, so this doesn't affect it.
-  if (!analyticsSharedState.config?.enabled || isReactNative) {
+  if (!enabled || !analyticsSharedState.config?.enabled || isReactNative) {
     return {
       track: () => {},
       cleanup: () => {},

tests/unit/analytics.test.ts

@@ -69,6 +69,7 @@ describe("Analytics Module", () => {
   afterEach(() => {
     vi.clearAllMocks();
     base44.cleanup();
+    vi.unstubAllGlobals();
     sharedState = null;
   });
 
@@ -89,6 +90,38 @@ describe("Analytics Module", () => {
     });
   });
 
+  test("should have no analytics side effects when disabled in client config", () => {
+    const storage = {
+      getItem: vi.fn(() => null),
+      setItem: vi.fn(),
+    };
+    const addEventListener = vi.fn();
+    vi.stubGlobal("localStorage", storage);
+    vi.stubGlobal("document", { referrer: "", visibilityState: "visible" });
+    vi.stubGlobal("window", {
+      addEventListener,
+      removeEventListener: vi.fn(),
+      history: { replaceState: vi.fn() },
+      localStorage: storage,
+      location: { origin: "https://example.com", pathname: "/", search: "" },
+    });
+    const setIntervalSpy = vi.spyOn(globalThis, "setInterval");
+
+    const disabled = createClient({
+      serverUrl,
+      appId,
+      analytics: { enabled: false },
+    });
+    disabled.analytics.track({ eventName: "should-not-track" });
+
+    expect(sharedState?.requestsQueue).toEqual([]);
+    expect(storage.setItem).not.toHaveBeenCalled();
+    expect(setIntervalSpy).not.toHaveBeenCalled();
+    expect(addEventListener).not.toHaveBeenCalled();
+
+    disabled.cleanup();
+  });
+
   test("should clear the memoized session context on reset", () => {
     expect(sharedState?.sessionContext).toEqual({ user_id: "test-user-id" });