chore(PLA-2218): enable socket disconnection when page visibility switches to hidden (#866)

Author: jareddellitt

.changeset/tasty-zoos-appear.md

@@ -0,0 +1,5 @@
+---
+"@knocklabs/client": patch
+---
+
+Disconnects socket after an initial delay when page visibility is hidden and removes the `auto_manage_socket_connection` and `auto_manage_socket_connection_delay` flags from `FeedClientOptions`.

packages/client/src/api.ts

@@ -3,12 +3,15 @@ import axiosRetry from "axios-retry";
 import { Socket } from "phoenix";
 
 import { exponentialBackoffFullJitter } from "./helpers";
+import { PageVisibilityManager } from "./pageVisibility";
 
 type ApiClientOptions = {
   host: string;
   apiKey: string;
   userToken: string | undefined;
   branch?: string;
+  /** Automatically disconnect the socket when the page is hidden and reconnect when visible. Defaults to `true`. */
+  disconnectOnPageHidden?: boolean;
 };
 
 export interface ApiResponse {
@@ -28,6 +31,7 @@ class ApiClient {
   private axiosClient: AxiosInstance;
 
   public socket: Socket | undefined;
+  private pageVisibility: PageVisibilityManager | undefined;
 
   constructor(options: ApiClientOptions) {
     this.host = options.host;
@@ -68,6 +72,10 @@ class ApiClient {
           });
         },
       });
+
+      if (options.disconnectOnPageHidden !== false) {
+        this.pageVisibility = new PageVisibilityManager(this.socket);
+      }
     }
 
     axiosRetry(this.axiosClient, {
@@ -101,6 +109,14 @@ class ApiClient {
     }
   }
 
+  teardown() {
+    this.pageVisibility?.teardown();
+
+    if (this.socket?.isConnected()) {
+      this.socket.disconnect();
+    }
+  }
+
   private canRetryRequest(error: AxiosError) {
     // Retry Network Errors.
     if (axiosRetry.isNetworkError(error)) {

packages/client/src/clients/feed/feed.ts

@@ -41,8 +41,6 @@ const feedClientDefaults: Pick<FeedClientOptions, "archived" | "mode"> = {
   mode: "compact",
 };
 
-const DEFAULT_DISCONNECT_DELAY = 2000;
-
 const CLIENT_REF_ID_PREFIX = "client_";
 
 class Feed {
@@ -53,10 +51,7 @@ class Feed {
   private userFeedId: string;
   private broadcaster: EventEmitter;
   private broadcastChannel!: BroadcastChannel | null;
-  private disconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private hasSubscribedToRealTimeUpdates: boolean = false;
-  private visibilityChangeHandler: () => void = () => {};
-  private visibilityChangeListenerConnected: boolean = false;
 
   // The raw store instance, used for binding in React and other environments
   public store: FeedStore;
@@ -117,13 +112,6 @@ class Feed {
 
     this.socketManager?.leave(this);
 
-    this.tearDownVisibilityListeners();
-
-    if (this.disconnectTimer) {
-      clearTimeout(this.disconnectTimer);
-      this.disconnectTimer = null;
-    }
-
     if (this.broadcastChannel) {
       this.broadcastChannel.close();
     }
@@ -553,8 +541,6 @@ class Feed {
       __loadingType: undefined,
       __fetchSource: undefined,
       __experimentalCrossBrowserUpdates: undefined,
-      auto_manage_socket_connection: undefined,
-      auto_manage_socket_connection_delay: undefined,
     };
 
     const result = await this.knock.client().makeRequest({
@@ -815,10 +801,6 @@ class Feed {
     // In server environments we might not have a socket connection
     if (!this.socketManager) return;
 
-    if (this.defaultOptions.auto_manage_socket_connection) {
-      this.setUpVisibilityListeners();
-    }
-
     // If we're initializing but they have previously opted to listen to real-time updates
     // then we will automatically reconnect on their behalf
     if (this.hasSubscribedToRealTimeUpdates && this.knock.isAuthenticated()) {
@@ -838,33 +820,6 @@ class Feed {
     }
   }
 
-  /**
-   * Listen for changes to document visibility and automatically disconnect
-   * or reconnect the socket after a delay
-   */
-  private setUpVisibilityListeners() {
-    if (
-      typeof document === "undefined" ||
-      this.visibilityChangeListenerConnected
-    ) {
-      return;
-    }
-
-    this.visibilityChangeHandler = this.handleVisibilityChange.bind(this);
-    this.visibilityChangeListenerConnected = true;
-    document.addEventListener("visibilitychange", this.visibilityChangeHandler);
-  }
-
-  private tearDownVisibilityListeners() {
-    if (typeof document === "undefined") return;
-
-    document.removeEventListener(
-      "visibilitychange",
-      this.visibilityChangeHandler,
-    );
-    this.visibilityChangeListenerConnected = false;
-  }
-
   private emitEvent(
     type:
       | MessageEngagementStatus
@@ -882,34 +837,6 @@ class Feed {
     // Internal events only need `items:`
     this.broadcastOverChannel(`items:${type}`, { items });
   }
-
-  private handleVisibilityChange() {
-    const disconnectDelay =
-      this.defaultOptions.auto_manage_socket_connection_delay ??
-      DEFAULT_DISCONNECT_DELAY;
-
-    const client = this.knock.client();
-
-    if (document.visibilityState === "hidden") {
-      // When the tab is hidden, clean up the socket connection after a delay
-      this.disconnectTimer = setTimeout(() => {
-        client.socket?.disconnect();
-        this.disconnectTimer = null;
-      }, disconnectDelay);
-    } else if (document.visibilityState === "visible") {
-      // When the tab is visible, clear the disconnect timer if active to cancel disconnecting
-      // This handles cases where the tab is only briefly hidden to avoid unnecessary disconnects
-      if (this.disconnectTimer) {
-        clearTimeout(this.disconnectTimer);
-        this.disconnectTimer = null;
-      }
-
-      // If the socket is not connected, try to reconnect
-      if (!client.socket?.isConnected()) {
-        client.socket?.connect();
-      }
-    }
-  }
 }
 
 export default Feed;

packages/client/src/clients/feed/interfaces.ts

@@ -34,11 +34,6 @@ export interface FeedClientOptions {
   trigger_data?: TriggerData;
   // Optionally enable cross browser feed updates for this feed
   __experimentalCrossBrowserUpdates?: boolean;
-  // Optionally automatically manage socket connections on changes to tab visibility (defaults to `false`)
-  auto_manage_socket_connection?: boolean;
-  // Optionally set the delay amount in milliseconds when automatically disconnecting sockets from inactive tabs (defaults to `2000`)
-  // Requires `auto_manage_socket_connection` to be `true`
-  auto_manage_socket_connection_delay?: number;
   // Optionally scope notifications to a given date range
   inserted_at_date_range?: {
     // Optionally set the start date with a string in ISO 8601 format
@@ -88,8 +83,6 @@ export type FetchFeedOptionsForRequest = Omit<
   __loadingType: undefined;
   __fetchSource: undefined;
   __experimentalCrossBrowserUpdates: undefined;
-  auto_manage_socket_connection: undefined;
-  auto_manage_socket_connection_delay: undefined;
 };
 
 export interface ContentBlockBase {

packages/client/src/interfaces.ts

@@ -9,6 +9,8 @@ export interface KnockOptions {
   host?: string;
   logLevel?: LogLevel;
   branch?: string;
+  /** Automatically disconnect the socket when the page is hidden and reconnect when visible. Defaults to `true`. */
+  disconnectOnPageHidden?: boolean;
 }
 
 export interface KnockObject<T = GenericData> {

packages/client/src/knock.ts

@@ -26,6 +26,7 @@ class Knock {
   public userToken?: string;
   public logLevel?: LogLevel;
   public readonly branch?: string;
+  private readonly disconnectOnPageHidden?: boolean;
   private tokenExpirationTimer: ReturnType<typeof setTimeout> | null = null;
   readonly feeds = new FeedClient(this);
   readonly objects = new ObjectClient(this);
@@ -42,6 +43,7 @@ class Knock {
     this.host = options.host || DEFAULT_HOST;
     this.logLevel = options.logLevel;
     this.branch = options.branch || undefined;
+    this.disconnectOnPageHidden = options.disconnectOnPageHidden;
 
     this.log("Initialized Knock instance");
 
@@ -170,9 +172,7 @@ class Knock {
     if (this.tokenExpirationTimer) {
       clearTimeout(this.tokenExpirationTimer);
     }
-    if (this.apiClient?.socket && this.apiClient.socket.isConnected()) {
-      this.apiClient.socket.disconnect();
-    }
+    this.apiClient?.teardown();
   }
 
   log(message: string, force = false) {
@@ -190,6 +190,7 @@ class Knock {
       host: this.host,
       userToken: this.userToken,
       branch: this.branch,
+      disconnectOnPageHidden: this.disconnectOnPageHidden,
     });
   }
 

packages/client/src/pageVisibility.ts

@@ -0,0 +1,70 @@
+import type { Socket } from "phoenix";
+
+const DEFAULT_DISCONNECT_DELAY_MS = 30_000;
+
+/**
+ * Disconnects the socket after a delay when the page becomes hidden,
+ * and reconnects when it becomes visible again. This avoids holding
+ * open connections for background tabs that aren't being viewed.
+ *
+ * The delay prevents unnecessary disconnects during brief tab switches.
+ * Phoenix channels automatically rejoin after reconnecting.
+ */
+export class PageVisibilityManager {
+  private disconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private wasConnected = false;
+
+  constructor(
+    private socket: Socket,
+    private disconnectDelayMs: number = DEFAULT_DISCONNECT_DELAY_MS,
+  ) {
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", this.onVisibilityChange);
+    }
+  }
+
+  private onVisibilityChange = () => {
+    if (document.hidden) {
+      this.scheduleDisconnect();
+    } else {
+      this.reconnect();
+    }
+  };
+
+  private scheduleDisconnect() {
+    this.clearTimer();
+
+    this.disconnectTimer = setTimeout(() => {
+      this.disconnectTimer = null;
+
+      if (this.socket.isConnected()) {
+        this.wasConnected = true;
+        this.socket.disconnect();
+      }
+    }, this.disconnectDelayMs);
+  }
+
+  private reconnect() {
+    this.clearTimer();
+
+    if (this.wasConnected) {
+      this.wasConnected = false;
+      this.socket.connect();
+    }
+  }
+
+  private clearTimer() {
+    if (this.disconnectTimer) {
+      clearTimeout(this.disconnectTimer);
+      this.disconnectTimer = null;
+    }
+  }
+
+  teardown() {
+    this.clearTimer();
+
+    if (typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.onVisibilityChange);
+    }
+  }
+}

packages/client/test/api.test.ts

@@ -131,6 +131,41 @@ describe("API Client", () => {
       // Restore original window value
       (global as GlobalWithWindow).window = originalWindow;
     });
+
+    test("creates PageVisibilityManager by default in browser environment", () => {
+      const originalWindow = (global as GlobalWithWindow).window;
+      (global as GlobalWithWindow).window = {} as Window;
+
+      const apiClient = new ApiClient({
+        host: "https://api.knock.app",
+        apiKey: "pk_test_12345",
+        userToken: undefined,
+      });
+
+      expect(
+        (apiClient as unknown as Record<string, unknown>)["pageVisibility"],
+      ).toBeDefined();
+
+      (global as GlobalWithWindow).window = originalWindow;
+    });
+
+    test("skips PageVisibilityManager when disconnectOnPageHidden is false", () => {
+      const originalWindow = (global as GlobalWithWindow).window;
+      (global as GlobalWithWindow).window = {} as Window;
+
+      const apiClient = new ApiClient({
+        host: "https://api.knock.app",
+        apiKey: "pk_test_12345",
+        userToken: undefined,
+        disconnectOnPageHidden: false,
+      });
+
+      expect(
+        (apiClient as unknown as Record<string, unknown>)["pageVisibility"],
+      ).toBeUndefined();
+
+      (global as GlobalWithWindow).window = originalWindow;
+    });
   });
 
   describe("Request Handling", () => {