From dfad2831d689b077021d4a0d5ab57fa9da3ab063 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Wed, 11 Mar 2026 19:06:37 -0400
Subject: [PATCH] Updated documentation.

---
 .../GUIDE__AE_API_V3_for_Frontend_websockets.md | 17 +++++++++++++----
 tests/README.md                                 |  2 ++
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md b/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
index f757a8cb..17a1f9e2 100644
--- a/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
+++ b/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
@@ -19,12 +19,16 @@ This guide explains how to implement real-time communication using the **Aether
 ## 2. Connection Strategy
 
 ### A. Endpoint URL
-The V3 WebSocket path requires both a `group_id` and a `client_id` (using **Vision ID** random strings).
+The V3 WebSocket path requires both a `group_id` and a `client_id`. Both are treated as **opaque unique strings** by the backend — no specific format is enforced.
 
 ```text
 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. 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.
 
 ### B. Authentication
@@ -43,8 +47,13 @@ wss://dev-api.oneskyit.com/v3/ws/group/{group_id}/client/{client_id}?api_key=<ke
 
 ### C. Connection Example (TypeScript)
 ```ts
-const group_id = "group_abc123"; // Random Vision ID
-const client_id = "device_xyz789"; // Random Vision ID
+// 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 api_key = import.meta.env.VITE_API_KEY;
 const jwt = getSessionToken(); // your JWT helper
 
@@ -188,5 +197,5 @@ If you are upgrading from the legacy V2 WebSocket (`/ws/group/...`):
 
 1.  **Change the URL**: Prepend `/v3/` to your WebSocket path.
 2.  **Wrap your JSON**: In V2, you might have sent `{"msg": "hi"}`. In V3, this must be `{"msg_type": "msg", "target": "group", "msg": "hi"}`.
-3.  **Use Vision IDs**: Ensure all IDs passed in the path and `to_id` fields are the random string IDs (`id_random`), not database integers.
+3.  **Use unique string IDs**: Both `group_id` and `client_id` in the path are opaque strings — any unique value works (timestamp, UUID, Vision ID random string). Just don't use raw database integer IDs. For `to_id` in direct messages, use whatever `client_id` that target client registered with.
 4.  **Listen for `msg_type`**: Update your frontend handlers to switch logic based on the `msg_type` field instead of proprietary keys.
diff --git a/tests/README.md b/tests/README.md
index b1b8d20e..f9e2c79f 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -249,6 +249,8 @@ These are IDs for records that we can use for testing. Please do not delete them
 ### Events Modules
 * Aether test/demo Event: 'pjrcghqwert' (1) "Demo One Sky IT Conference"
 * Aether test/demo Event Session: 'DOW3h7v6H42' (703) "How To Do Things"
+* Aether test/demo Event Session (Digital Posters): "K8cxUIEWyQk" "The Beginning of Digital Posters!"
+* Aether test/demo Event Session (Digital Posters): "1Un1xI1Rgk8" "Poster Session 99: All about posters!"
 * Aether test/demo Event Presentation: '7U2eXSjR6H4' (1670) "Build a House"
 * Aether test/demo Event Presenter: 'gT-hxnifb-0' (2202) "Bob The Builder"
 * Aether test/demo Event File: 'OOsHXtng5mr' (2985) "1 Quick Test for macOS.mp4"