# Swift (https://sockudo.io/docs/clients/swift)
> Use SockudoSwift on iOS, macOS, tvOS, watchOS, and visionOS.
`SockudoSwift` is the official realtime client for Apple platforms. It opens a
WebSocket to Sockudo, subscribes to channels, and delivers events to your
callbacks. It supports public, private, presence, and encrypted channels, user
sign-in, client events, and the Protocol V2 feature set: connection recovery,
rewind, tag filters, delta compression, mutable messages, and proxy-backed
history helpers.
Supported deployment targets are iOS 13+, macOS 10.15+, tvOS 13+, watchOS
6+, and visionOS 1+. The package uses Swift 6.2 concurrency and isolates the
client, channels, and callbacks on `@SockudoActor`.
`SockudoSwift` starts in Pusher-compatible Protocol V1 mode (`protocol=7`). Set
`protocolVersion: 2` explicitly for new Sockudo applications that need
continuity metadata, recovery, filters, deltas, or any other V2 feature.
## Install
Install through Swift Package Manager from the SockudoSwift mirror. SwiftPM resolves this from
the `v3.0.0` Git tag and the mirror repository's root `Package.swift` manifest.
1. Add the package dependency to `Package.swift`:
```swift title="Package.swift"
.package(url: "https://github.com/sockudo/sockudo-swift", from: "3.0.0")
```
2. Depend on the `SockudoSwift` product from your target:
```swift title="Package.swift"
.target(
name: "YourApp",
dependencies: [
.product(name: "SockudoSwift", package: "sockudo-swift"),
]
)
```
3. In an Xcode project, add the same URL through **File > Add Package Dependencies** and select
the `SockudoSwift` library.
For local development against the monorepo, point SwiftPM at the package
directory instead:
```swift title="Package.swift"
.package(path: "../sockudo/client-sdks/sockudo-swift")
```
The package depends on `swift-sodium` for encrypted channels and vendors
xdelta3 for delta decoding; both resolve automatically.
## Connect
A `SockudoClient` owns one WebSocket connection for your app. Over that
connection you subscribe to **channels**: named streams such as
`public-updates` that your backend publishes events to. The client holds only
the public app key; the app secret stays on your server.
```swift title="Realtime.swift"
@SockudoActor
func startRealtime() throws -> SockudoClient {
let client = try SockudoClient(
"app-key",
options: .init(
cluster: "local",
protocolVersion: 2,
forceTLS: false,
enabledTransports: [.ws],
wsHost: "127.0.0.1",
wsPort: 6001,
wssPort: 6001,
connectionRecovery: true
)
)
let channel = client.subscribe("public-updates")
channel.bind("price-updated") { data, _ in
print(data ?? "")
}
client.connect()
return client
}
```
The function is annotated `@SockudoActor` because every client and channel
method is isolated to that actor. From other contexts, call it with `await`.
For production, point `wsHost` at the public ingress or load balancer
hostname, set `forceTLS: true`, and remove `enabledTransports: [.ws]` so the
client uses the secure transport.
`SockudoClient.Options` uses a memberwise-style initializer, so Swift requires
labelled arguments in the order they are declared. `protocolVersion` comes
directly after `cluster`, and `connectionRecovery` comes after the auth, history,
and delta options. The table below lists options in declaration order.
### Connection options
| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `cluster` | `String` | required | Cluster name. Must be non-empty. |
| `protocolVersion` | `Int` | `7` | `7` is Protocol V1 (Pusher-compatible); `2` enables Protocol V2. |
| `activityTimeout` | `TimeInterval` | `120` | Idle seconds before the client checks liveness. |
| `forceTLS` | `Bool?` | `nil` | Force `wss://`. Use `true` in production. |
| `enabledTransports` | `[Transport]?` | `nil` | Restrict to `.ws` and/or `.wss`. |
| `wsHost` | `String?` | `nil` | Sockudo hostname. |
| `wsPort` | `Int` | `80` | Port for `ws://`. |
| `wssPort` | `Int` | `443` | Port for `wss://`. |
| `wsPath` | `String` | `""` | Path prefix for the WebSocket URL. |
| `pongTimeout` | `TimeInterval` | `30` | Seconds to wait for a pong. |
| `unavailableTimeout` | `TimeInterval` | `10` | Seconds before a stalled connection is reported `unavailable`. |
| `channelAuthorization` | `ChannelAuthorizationOptions` | endpoint `/sockudo/auth` | Private, presence, and encrypted channel auth. |
| `userAuthentication` | `UserAuthenticationOptions` | endpoint `/sockudo/user-auth` | User sign-in auth. |
| `presenceHistory` | `PresenceHistoryOptions?` | `nil` | Backend proxy for presence history and snapshots. |
| `versionedMessages` | `VersionedMessagesOptions?` | `nil` | Backend proxy for channel history and mutable-message helpers. |
| `capabilityToken` | `CapabilityTokenOptions?` | `nil` | Protocol V2 capability-token auth. |
| `deltaCompression` | `DeltaOptions?` | `nil` | Connection-level delta negotiation. |
| `messageDeduplication` | `Bool` | `true` | Drop repeated `message_id` values. |
| `messageDeduplicationCapacity` | `Int` | `1000` | Size of the deduplication window. |
| `connectionRecovery` | `Bool` | `false` | Track positions and resume after reconnect (V2). |
| `echoMessages` | `Bool` | `true` | Receive your own published messages. |
| `wireFormat` | `SockudoWireFormat` | `.json` | `.json`, `.messagepack`, or `.protobuf` (V2). |
| `appendMode` | `SockudoAppendMode` | `.delta` | `.delta` or `.full` delivery of message appends. |
| `appendRollupWindow` | `Int?` | `nil` | Append rollup window in milliseconds: `0`, `20`, `40`, `100`, or `500`. |
| `maxReconnectAttempts` | `Int?` | `6` | Reconnect attempts before giving up; `nil` is unlimited. |
| `maxReconnectGapInSeconds` | `Double` | `120` | Upper bound on reconnect delay. |
| `reconnectJitter` | `Double` | `0` | Fraction (0 to 1) of each reconnect delay to randomize. |
## Subscribe and bind events
`subscribe(_:options:)` returns a `Channel` immediately; the subscription
completes asynchronously once the socket is connected (and, for protected
channels, once your auth endpoint responds). `bind` attaches a callback for one
event name and returns an `EventBindingToken`.
```swift title="PriceFeed.swift"
@SockudoActor
final class PriceFeed {
private let client: SockudoClient
private var channel: Channel?
private var token: EventBindingToken?
init(client: SockudoClient) {
self.client = client
}
func start() {
let channel = client.subscribe("public-updates")
channel.bind("sockudo:subscription_succeeded") { _, _ in
print("public-updates is live")
}
token = channel.bind("price-updated") { data, _ in
print("price:", data ?? "")
}
self.channel = channel
}
func stop() {
if let token {
channel?.unbind(eventName: "price-updated", token: token)
}
client.unsubscribe("public-updates")
}
}
```
System events use the protocol prefix: `sockudo:` on Protocol V2 and `pusher:`
on Protocol V1 (for example `pusher:subscription_succeeded`). Use
`bindGlobal` to observe every event name on a channel or client, and
`unbindAll()` only when the owner is being torn down.
### Callbacks run on SockudoActor
Event callbacks execute on the dedicated Sockudo actor, not the main thread,
and in binding order. Hop to `MainActor` for UIKit or SwiftUI state:
```swift
channel.bind("price-updated") { data, _ in
Task { @MainActor in
viewModel.latestPrice = String(describing: data)
}
}
```
From code outside `@SockudoActor`, access client methods with `await`:
```swift
func startRealtime() async {
await client.connect()
}
func stopRealtime() async {
await client.unsubscribe("public-updates")
await client.disconnect()
}
```
### Client events
Private and presence channels can send `client-` prefixed events directly to
other subscribers. `trigger(event:data:)` throws `SockudoError.badEventName`
for any other name:
```swift
_ = try channel.trigger(event: "client-typing", data: ["user": "alice"])
```
Client events triggered while the channel is not yet subscribed are buffered,
up to 50 per channel (oldest dropped on overflow), and replayed after the
subscription succeeds. Unsubscribing clears that buffer.
## Private and presence channels
Anyone with your public app key can open a socket, so Sockudo cannot decide by
itself who may join `private-*`, `presence-*`, or `private-encrypted-*`
channels. Instead, the client sends its `socket_id` and the requested channel
name to **your** backend, which checks the user's session and returns a
signature made with the app secret. Sockudo verifies that signature before
completing the subscription.
```mermaid
sequenceDiagram
participant App as iOS app
participant API as Your backend
participant S as Sockudo
App->>S: connect with public app key
S-->>App: socket_id
App->>API: POST /sockudo/auth (socket_id, channel_name)
API-->>App: signed auth response
App->>S: subscribe with auth
S-->>App: subscription_succeeded
```
```swift title="Realtime.swift"
let client = try SockudoClient(
"app-key",
options: .init(
cluster: "local",
forceTLS: false,
wsHost: "127.0.0.1",
wsPort: 6001,
channelAuthorization: .init(
endpoint: "https://api.example.com/sockudo/auth",
headersProvider: { ["Authorization": "Bearer \(SessionStore.token)"] }
)
)
)
```
`ChannelAuthorizationOptions` accepts `endpoint` (default `/sockudo/auth`),
static `headers` and `params`, `headersProvider` and `paramsProvider` closures
evaluated per request, and a `customHandler` when you need to perform the
request yourself. `userAuthentication` has the same shape (default endpoint
`/sockudo/user-auth`) and is used by `client.signIn()` for user-targeted events
and watchlists.
The backend must authenticate the current user and authorize the exact
`channel_name` before signing. Presence identity must come from the server-side
session, not a value supplied by the app. Never ship the app secret in the
app bundle.
### Presence
Subscribe as `PresenceChannel` to access members and V2 in-place presence
updates:
```swift title="Lobby.swift"
let presence = client.subscribe("presence-agent:session-123") as! PresenceChannel
presence.bind("sockudo:subscription_succeeded") { _, _ in
print("members:", presence.members.count, "me:", presence.members.myID ?? "")
}
presence.bind("sockudo:member_added") { member, _ in
print("joined:", member as Any)
}
presence.bind("sockudo:member_removed") { member, _ in
print("left:", member as Any)
}
presence.bind("sockudo:presence_update") { member, _ in
print("updated:", member as Any)
}
_ = try presence.update(data: ["status": "thinking"])
```
Wait for the subscription-success event before treating the initial membership
set as authoritative. `presence.members` exposes `count`, `myID`, `me`,
`member(id:)`, and `forEach`. `update(data:)` changes your member data without a
leave/rejoin cycle and throws `SockudoError.unsupportedFeature` on Protocol V1.
### Capability tokens
Protocol V2 also supports scoped capability tokens instead of per-channel
signatures:
```swift title="Realtime.swift"
let client = try SockudoClient(
"app-key",
options: .init(
cluster: "local",
protocolVersion: 2,
forceTLS: true,
wsHost: "realtime.example.com",
capabilityToken: .init(asyncProvider: {
try await tokenService.fetchSockudoToken()
})
)
)
```
The initial token is sent as the WebSocket `token` query parameter. JWTs with
expiry metadata refresh proactively at 80% of their lifetime, and providers are
called before reconnects. On `sockudo:token_expired`, only expiry code `40142`
refreshes in place through `sockudo:auth`; revocation code `40160` and static
tokens are not resent. Configuring token auth outside Protocol V2 throws
`SockudoError.invalidOptions`.
## Protocol V2 features
The features below require `protocolVersion: 2`. See
[Protocol V2](/docs/clients/protocol-v2) for the wire-level contract.
### Recovery and rewind
With `connectionRecovery: true`, the client records a `RecoveryPosition` per
channel and asks Sockudo to resume from it after a reconnect. `rewind` replays
recent history when a subscription starts.
```swift title="Market.swift"
let channel = client.subscribe(
"market:BTC",
options: .init(rewind: .seconds(30))
)
channel.bind("trade") { _, _ in
print(client.recoveryPosition(for: "market:BTC") as Any)
}
channel.bind("sockudo:rewind_complete") { data, _ in
print(data as Any)
}
client.bind("sockudo:resume_success") { data, _ in
print(data as Any)
}
client.bind("sockudo:resume_failed") { data, _ in
print("rebuild state:", data as Any)
}
```
`SubscriptionRewind` is `.count(n)` or `.seconds(n)`. `recoveryPositions()`
and `setRecoveryPositions(_:)` let you persist positions across app launches.
On `sockudo:resume_failed` the client drops the stored position and
resubscribes; your app must discard derived state and reload an authoritative
snapshot.
### Channel history and late join
`channel.attachSerial` holds the history head captured when the subscription
attached. Load history up to that serial for a gap-free late join. Channel
history is served through the `versionedMessages` backend proxy:
```swift
print(channel.attachSerial as Any)
channel.channelHistory(.init(limit: 50, untilAttach: true)) { result in
print(result)
}
```
### Filters and deltas
Tag filters, event-name filters, and JMESPath expressions are evaluated on the
server, so non-matching messages never reach the device. Delta compression
sends only the difference against the previous message.
```swift title="Market.swift"
let channel = client.subscribe(
"price:btc",
options: .init(
filter: Filter.eq("market", "spot"),
delta: .init(enabled: true, algorithm: .xdelta3),
events: ["price.updated"],
expression: .source("data.price >= `100`")
)
)
```
`Filter` provides `eq`, `neq`, `in`, `nin`, `exists`, `notExists`,
`startsWith`, `endsWith`, `contains`, `gt`, `gte`, `lt`, `lte`, `and`, `or`,
and `not`. Delta algorithms are `.fossil` and `.xdelta3`. See
[Filters and delta compression](/docs/clients/filters-delta).
### Mutable messages
Protocol V2 mutable messages arrive as update, delete, and append actions for
an existing `message_serial`. Apply them in serial order:
- an update replaces local content with the full event payload
- a delete is the latest visible version and may carry `nil` data
- an append concatenates onto the current local string state
If an append arrives before you have a string base, fetch the latest visible
message first and seed local state before applying more appends.
Configure `versionedMessages.endpoint` to use proxy-backed write and read
helpers without exposing Sockudo app secrets in the app. The proxy accepts
JSON `{ channel, messageSerial?, action, payload }` and calls Sockudo's signed
REST API server-side. The Swift SDK does not send WebSocket mutation frames.
```swift title="Chat.swift"
let client = try SockudoClient(
"app-key",
options: .init(
cluster: "local",
protocolVersion: 2,
forceTLS: false,
wsHost: "127.0.0.1",
wsPort: 6001,
versionedMessages: .init(
endpoint: "https://api.example.com/sockudo/versioned"
)
)
)
let channel = client.subscribe("chat:room-1")
client.connect()
channel.createMessage(
.init(name: "chat.message", data: ["text": "hello"], messageID: "msg-1")
) { result in
guard case .success(let ack) = result else { return }
Task { @SockudoActor in
channel.appendMessage(
ack.messageSerial,
request: .init(data: " world", opID: "append-1")
) { result in
print(result)
}
}
}
```
Each helper returns a `VersionedMessageAck` with `messageSerial`,
`versionSerial`, `historySerial`, `deliverySerial`, and `status`.
`updateMessage`, `deleteMessage`, `getMessage`, and `getMessageVersions` follow
the same pattern. Proxy requests time out after 10 seconds.
### Presence history
Presence history and snapshots are also proxy-backed, because a mobile client
must not sign Sockudo REST requests:
```swift title="Lobby.swift"
let client = try SockudoClient(
"app-key",
options: .init(
cluster: "local",
forceTLS: false,
wsHost: "127.0.0.1",
wsPort: 6001,
presenceHistory: .init(
endpoint: "https://api.example.com/sockudo/presence-history"
)
)
)
let channel = client.subscribe("presence-lobby") as! PresenceChannel
channel.history(.init(direction: "newest_first", limit: 50)) { result in
print(result)
}
channel.snapshot(.init(atSerial: 4)) { result in
print(result)
}
```
The proxy accepts `{channel, params, action}`. Authorize the caller and channel
on every request, bound page sizes, and forward opaque cursors unchanged. See
[Presence history](/docs/clients/presence-history).
### Binary wire formats
Set `wireFormat: .messagepack` or `.protobuf` to negotiate a binary encoding.
Both preserve `Data` message payloads as native binary. The MessagePack
representation uses the additive `["binary", ]` tagged value; existing
string and JSON variants are unchanged.
### Encrypted channels
`private-encrypted-*` channels decrypt automatically when the protected-channel
auth response contains a derived `shared_secret`:
```swift
let encrypted = client.subscribe("private-encrypted-documents")
encrypted.bind("doc-updated") { payload, _ in
print(payload as Any)
}
```
Keep the encryption master key on the backend. Continue to use TLS and normal
channel authorization.
## Connection lifecycle and reconnection
The client moves through the `ConnectionState` values `initialized`,
`connecting`, `connected`, `reconnecting`, `disconnected`, `unavailable`, and
`failed`. Every transition emits `state_change` with `previous` and `current`
keys, followed by an event named after the new state:
```swift
client.bind("state_change") { change, _ in
print("connection:", change as Any)
}
client.bind("reconnecting") { _, _ in
print("reconnecting")
}
```
A connected socket can still have a pending or rejected channel. Gate
channel-dependent UI on the channel's `subscription_succeeded` event, not on
the global `connected` state.
Unexpected disconnects reconnect with quadratic backoff: `attempt²` seconds
(0s, 1s, 4s, 9s, 16s, ...) capped by `maxReconnectGapInSeconds` (default 120),
for up to `maxReconnectAttempts` (default 6, `nil` for unlimited). The attempt
counter resets after a successful connection and on explicit `connect()` or
`disconnect()` calls.
```swift title="Realtime.swift"
let client = try SockudoClient(
"app-key",
options: .init(
cluster: "local",
maxReconnectAttempts: 10,
maxReconnectGapInSeconds: 60,
reconnectJitter: 0.5
)
)
```
Jitter is off by default. Set `reconnectJitter` (0 to 1) to randomize each
delay by that fraction so clients dropped by one event do not retry in
lockstep. Close codes `4200`–`4299` and the TLS-upgrade code `4000` reconnect
immediately; codes `4001`–`4099` are refused and are not retried.
Apply an app-specific reconnect limit for backgrounded mobile processes, and
call `disconnect()` on explicit sign-out rather than letting the retry budget
run out.
## Error handling
- **Construction:** `SockudoClient.init` throws `SockudoError.invalidAppKey`
for an empty key and `SockudoError.invalidOptions` for an empty cluster,
token auth without Protocol V2, or an unsupported `appendRollupWindow`.
- **Connection:** bind `"error"` on the client. Payloads include
`SockudoError` values such as `connectionUnavailable` as well as server
error events.
- **Subscription:** a failed auth request emits `sockudo:subscription_error`
(`pusher:subscription_error` on V1) on the channel with `type` and `error`
keys. Treat it as a permission problem, not a reason to reconnect.
- **Recovery:** on `sockudo:resume_failed`, reload authoritative application
state.
- **Helpers:** history, versioned-message, and push helpers deliver
`Result` values; a missing proxy endpoint fails with
`SockudoError.unsupportedFeature`.
```swift
client.bind("error") { error, _ in
print("Sockudo error:", error as Any)
}
channel.bind("sockudo:subscription_error") { error, _ in
print("subscription failed:", error as Any)
}
```
See [Errors](/docs/reference/errors) for server error and close codes.
## Platform notes
### Threading model
Message decoding, deduplication, and delta reconstruction run on a background
`MessageProcessor` actor before events reach `@SockudoActor` for routing and
callback delivery. Neither stage blocks the main thread. Synchronous reads of
client state such as `connectionState` and `socketID` require `await` from
outside `@SockudoActor`.
### Heartbeats
On Protocol V2 the client uses `URLSessionWebSocketTask.sendPing` for native
liveness checks. Lightweight `sockudo:ping` / `sockudo:pong` fallback messages
remain reserved for compatibility and diagnostics and do not carry
`message_id`, `serial`, or `stream_id`.
### Push notifications
Use APNs to obtain a device token, then send it to your backend. Your backend
registers the device with Sockudo and keeps APNs credentials server-side.
```swift title="AppDelegate.swift"
func application(
_ application: UIApplication,
didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
let token = deviceToken.map { String(format: "%02x", $0) }.joined()
Task {
await registerDeviceWithBackend(
deviceId: UIDevice.current.identifierForVendor?.uuidString ?? token,
platform: "apns",
providerToken: token
)
}
}
```
`SockudoPushRegistration` wraps device registration, channel subscription, and
publish calls against **your** authenticated proxy. `publish` and
`publishBatch` always send `sync = false` and expect `202 Accepted` with a
`publish_id`; list helpers use `limit` and `cursor`.
```swift title="Push.swift"
let push = SockudoPushRegistration(
options: .init(
endpoint: "https://api.example.com/sockudo/push",
headers: ["Authorization": "Bearer session-token"]
)
)
push.publish(
[
"recipients": [["type": "channel", "channel": "orders"]],
"payload": ["title": "Order updated", "body": "Ready for pickup"],
]
) { result in
if case .success(let payload) = result {
print(payload["publish_id"] as Any)
}
}
```
### Live Activities
ActivityKit can rotate Live Activity tokens. Observe the token sequence for
the full lifetime of the activity and upload every replacement:
```swift title="LiveActivity.swift"
let tokenTask = SockudoLiveActivityTokens.observePushTokens(for: activity) {
activityID, token in
await backend.replaceLiveActivityToken(activityID: activityID, token: token)
}
push.publishLiveActivity(
activityToken: currentToken,
payload: .init(
event: .update,
contentState: ["etaMinutes": 2],
priority: .conservePower
)
) { result in
print(result)
}
```
`observePushTokens` requires iOS 16.1; `observePushToStartTokens` requires
iOS 17.2. For iOS 18 shared-content audiences, use
`createLiveActivityBroadcastChannel` and `publishLiveActivityBroadcast`.
Broadcast channel management belongs on the trusted backend. See
[Apple Live Activities](/docs/server/apple-live-activities).
Do not embed APNs private keys, Sockudo app secrets, or push-admin credentials
in the app. Every push helper must point at your authenticated backend.
### Production checklist
- Use one long-lived client for the app session and disconnect it on explicit
sign-out.
- Select Protocol V2 deliberately; do not assume the default changed during a
Pusher migration.
- Move UI mutations from `@SockudoActor` to `MainActor`.
- Apply an app-specific reconnect limit for backgrounded mobile processes.
- Treat failed recovery as a signal to reload authoritative application state.
- Keep auth, history, versioned-message, and push proxy credentials on the
backend.
- Unbind view-owned callbacks to prevent retained views and duplicate updates.
- Test offline/online transitions, token expiry, app suspension, and a rolling
Sockudo restart.
## Next steps
- [Protocol V2](/docs/clients/protocol-v2): Recovery, rewind, history, and native event semantics.
- [Filters and delta compression](/docs/clients/filters-delta): Cut delivered traffic with server-side filters and deltas.
- [Authentication](/docs/getting-started/authentication): Build the backend auth endpoint for private and presence channels.
- [Push notifications](/docs/server/push-notifications): Register devices and publish through your backend.