Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Andr21Da16/Quikko/llms.txt

Use this file to discover all available pages before exploring further.

Quikko’s WebSocket hub broadcasts every click event to connected clients in real time. The Next.js dashboard opens a persistent WebSocket connection on load and updates charts and counters the instant a redirect fires — no polling interval, no page refresh. The same connection carries events for all of a user’s URLs simultaneously, making the dashboard feel live regardless of how many links you’re tracking.

​
How It Works

When a visitor follows a short link, the redirect handler resolves the destination and immediately fires an async recording call. The analytics service writes the event to InfluxDB and calls PublishClickEvent on the hub. The hub fans the event out to two rooms: user:{ownerID} (the URL owner’s personal room) and url:{shortCode} (the per-URL room). Any client subscribed to either room receives the message within milliseconds. 
Visitor clicks short link
        │
        ▼
  Redirect handler  ──(302)──▶  Visitor browser
        │
        └─ async RecordClick
                  │
                  ├──▶  InfluxDB  (persistent storage)
                  │
                  └──▶  WebSocket hub  ──▶  user:{ownerID} room
                                       └──▶  url:{shortCode} room

​
Connecting

ws://localhost:8080/ws?token=<accessToken>
The JWT access token travels as the token query parameter. This is intentional — browser WebSocket APIs do not allow custom headers during the HTTP upgrade handshake, so Authorization: Bearer cannot be used here. The token is validated before the upgrade completes; an invalid or expired token receives a standard 401 HTTP response and the connection is never upgraded.
Treat the token query parameter the same as the Authorization header — it carries your full access credential. Only connect over wss:// in production to prevent the token from being exposed in transit.

​
Automatic User Room Subscription

Immediately after a successful upgrade, the server subscribes the client to user:{userID} — derived automatically from the JWT claims. This means you start receiving live click events for all your short URLs with zero additional messages. No subscribe call is needed for the general dashboard view.

​
Optional Per-URL Subscription

For URL detail views, you can subscribe to a specific URL’s channel to receive a focused stream: 
{ "type": "subscribe", "payload": { "shortCode": "xYz12A" } }
The server validates that the shortCode belongs to the authenticated user before adding the client to the url:{shortCode} room. If the URL is not yours (or does not exist), the server sends back an error message and leaves the connection open — the connection is never dropped over a failed subscription. To stop receiving events for a URL: 
{ "type": "unsubscribe", "payload": { "shortCode": "xYz12A" } }

​
Message Types

TypeDirectionPurpose
subscribeclient → serverSubscribe to a per-URL channel
unsubscribeclient → serverUnsubscribe from a per-URL channel
click_eventserver → clientA redirect just fired on one of your URLs
errorserver → clientProtocol error (e.g. subscribing to another user’s URL)
All messages share the same envelope: 
{ "type": "<type>", "payload": { ... } }

​
The click_event Payload

Every time a redirect fires for a URL you are subscribed to, the server pushes: 
{
  "type": "click_event",
  "payload": {
    "shortCode": "xYz12A",
    "country": "US",
    "deviceType": "desktop",
    "browser": "Chrome",
    "timestamp": "2024-01-15T12:34:56Z"
  }
}
FieldDescription
shortCodeThe short code that was clicked
countryISO 3166-1 alpha-2 country code of the visitor
deviceTypedesktop, mobile, or tablet
browserBrowser family (Chrome, Firefox, Safari, Edge, …)
timestampUTC time of the redirect

​
Non-Blocking Broadcast

The hub’s Broadcast method uses a non-blocking select/default when writing to each client’s send channel. If a client’s buffer is full — for example, because it has stalled or is processing slowly — that specific message is dropped for that client only. All other clients in the room receive the event normally. The hub never blocks waiting on a slow consumer.
In practice, dropped messages only occur when a client’s network or JavaScript thread is severely backed up. The InfluxDB record of every click is always complete — the WebSocket stream is a live view, not the source of truth for analytics.

​
Full Protocol Reference

For the complete protocol specification including authentication error codes, unsubscribe behavior, and connection lifecycle details, see the WebSocket Protocol reference.
The Next.js dashboard manages the WebSocket connection through a Zustand realtime store. The useRealtimeClicks hook subscribes to the store and automatically triggers chart re-renders whenever a click_event arrives, keeping all counters in sync without any manual polling or state juggling.

Build docs developers (and LLMs) love

Get started for freeTalk to us