diff --git a/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md b/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md index f757a8c..2e1460c 100644 --- a/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md +++ b/documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md @@ -19,12 +19,19 @@ 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. 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 + > 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 +50,8 @@ wss://dev-api.oneskyit.com/v3/ws/group/{group_id}/client/{client_id}?api_key=