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=