Scott.Idem/OSIT-AE-App-Svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated documentation.

Browse Source
This commit is contained in:
Scott Idem
2026-03-11 19:06:37 -04:00
parent 0da5894529
commit dfad2831d6
2 changed files with 15 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
documentation/GUIDE__AE_API_V3_for_Frontend_websockets.md
View File

@@ -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.

2
tests/README.md
View File

@@ -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"