From e608696ec82519be19514640d1923e043a51e1a1 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Wed, 11 Mar 2026 19:03:16 -0400
Subject: [PATCH] Docs: WS guide - client_id is UUID v4 persisted in
 localStorage, not Date.now()

---
 .../GUIDE__AE_API_V3_for_Frontend_websockets.md      | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md b/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
index 2e1460c..17a1f9e 100644
--- a/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
+++ b/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
@@ -27,10 +27,7 @@ wss://[api_domain]/v3/ws/group/{group_id}/client/{client_id}
 
 **`group_id`** — identifies the shared channel (e.g., an event ID, a room name, or a Vision ID random string). All clients using the same `group_id` receive group-targeted messages together.
 
-**`client_id`** — uniquely identifies this specific connection. Common choices:
-- `Date.now()` timestamp (e.g. `1773266158823`) — simple and collision-resistant for short-lived sessions
-- A UUID (`crypto.randomUUID()`)
-- A Vision ID random string if you need the client to be addressable by a known database identity
+**`client_id`** — uniquely identifies this specific connection. The backend accepts any unique string (UUID, timestamp, Vision ID — no format validation). The **recommended pattern** is a UUID v4 generated once and persisted in `localStorage` so the same identity is reused across page reloads and sessions on that browser.
 
 > Use `ws://` for local development and `wss://` in production (any HTTPS site). The Nginx config must include the Upgrade block — see Section 6.
 
@@ -50,8 +47,13 @@ wss://dev-api.oneskyit.com/v3/ws/group/{group_id}/client/{client_id}?api_key=<ke
 
 ### C. Connection Example (TypeScript)
 ```ts
+// client_id: generated once, persisted in localStorage for stable identity across reloads
+if (!localStorage.getItem('controller_client_id')) {
+    localStorage.setItem('controller_client_id', crypto.randomUUID());
+}
+const client_id = localStorage.getItem('controller_client_id')!; // UUID v4, e.g. "550e8400-e29b-41d4-a716-446655440000"
+
 const group_id = "event_abc123"; // Any unique string identifying the shared channel
-const client_id = String(Date.now()); // Any unique string identifying this client connection
 const api_key = import.meta.env.VITE_API_KEY;
 const jwt = getSessionToken(); // your JWT helper