Realtime clients

Realtime client SDKs connect to Sockudo over WebSocket, subscribe to channels, receive events, authorize protected channels through your backend, and expose Protocol V2 features.

Install client SDKs from the package names below. The old per-SDK repositories should be treated as archived/legacy mirrors.

Official clients

Use Protocol V1 when migrating existing Pusher clients. Use Protocol V2 for recovery, rewind, delta compression, tag filters, mutable messages, annotations, and native Sockudo metadata.

The realtime and HTTP SDKs have different trust boundaries. Realtime clients hold only the public app key and maintain WebSocket subscriptions. Server SDKs hold the app secret, publish over HTTP, authorize protected subscriptions, and validate webhooks. For Python and .NET in particular, make sure you choose the package whose role matches your process.

Client responsibilities

Client SDKs should:

• connect with public app key only
• call your backend for private, presence, encrypted, push, and history proxy operations
• keep app secrets out of the client bundle
• bind events and update UI state
• store recovery positions when V2 recovery is enabled
• register devices for push through trusted backend endpoints

They should never contain the app secret, provider credentials, an encryption master key, or an unrestricted capability token.

Server responsibilities

Server SDKs should:

• publish events over the HTTP API
• sign channel and user authentication responses
• proxy presence history and versioned message reads for clients
• validate webhooks
• manage push registration, credentials, channel push subscriptions, and publish workflows

Common V2 setup

const client = new Sockudo("app-key", {
  wsHost: "realtime.example.com",
  forceTLS: true,
  protocolVersion: 2,
  connectionRecovery: true,
});

Use this sequence in every client:

1. Construct one long-lived client with your public key and public WebSocket endpoint.
2. Bind connection diagnostics and event handlers.
3. Subscribe to channels, using a backend auth endpoint for protected names.
4. Connect and let the SDK resubscribe after transient failures.
5. If recovery fails, replace derived state from an authoritative snapshot.
6. Unbind or unsubscribe when a screen or worker no longer needs a channel.
7. Disconnect during application shutdown.

Choosing features

Connection and state model

A successful WebSocket connection does not mean every channel is subscribed. Wait for each channel's subscription-success event before treating its state as live. During reconnect, keep the last rendered state but mark it stale. After a successful resume, continue from the recovered serial; after a failed resume, discard derived state and fetch a fresh snapshot.

Event handlers should be idempotent. Network reconnects, application retries, and upstream publishing workflows can all repeat logical work even when the client deduplicates messages by message_id.

Protected-channel auth flow

client -> your backend: socket_id + requested channel
your backend: authenticate session and authorize that exact channel
your backend -> client: short-lived signed auth response
client -> Sockudo: subscribe with auth response

Do not implement an auth endpoint that signs every requested channel. Validate tenant ownership, resource access, and presence identity before signing. For encrypted channels, return only the derived channel shared secret—not the encryption master key.

Production checklist

• Terminate TLS at Sockudo or a load balancer and use wss://.
• Keep a single client per app or process unless isolation is intentional.
• Observe connected, unavailable, failed, and reconnecting states.
• Set auth and proxy request timeouts; handle 401, 403, and 429 separately from transport failures.
• Bound rewind and history page sizes.
• Test a rolling restart, network interruption, auth expiry, and resume failure.
• Unsubscribe and unbind handlers when views or jobs end.

Push from clients

Mobile and browser clients can collect provider tokens, but they should not call Sockudo push admin APIs directly. Send provider tokens to your backend, bind them to the authenticated user, and let the backend call Sockudo.

await fetch("/api/push/devices", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    device_id: "browser-device-1",
    platform: "webpush",
    provider_token: subscription,
  }),
});

Next steps