Skip to content

Realtime ​

See Connecting to Realtime and Groups and Messages. Every method that throws, throws SkapiError.

connectRealtime ​

swift
func connectRealtime(_ callback: @escaping @Sendable (RealtimeEvent) -> Void) async throws

Opens the realtime connection and returns once it is open. callback runs on a background task for every event; hop to the main actor for UI work. See Events. Called again while connected, it only swaps the callback. The connection reopens on its own after a drop.

swift
try await skapi.connectRealtime { event in
    Task { @MainActor in
        messages.append(event)
    }
}

Errors ​

codemessage
INVALID_REQUESTNo access. (not signed in)
INVALID_REQUESTWebSocket closed before it opened.

closeRealtime ​

swift
func closeRealtime()

Closes the connection. The callback gets "close"; the group gets USER_DISCONNECTED and USER_LEFT. Does nothing when no connection is open. It is not async, but from outside the actor it is called with await skapi.closeRealtime().

joinRealtime ​

swift
func joinRealtime(group: String?) async throws -> JSON

Joins a group, leaving the current one. nil (or "") leaves the group.

json
{"type": "success", "message": "Joined realtime message group: \"lobby\"."}
{"type": "success", "message": "Left realtime message group."}

Errors ​

codemessage
INVALID_REQUESTNo realtime connection. Execute connectRealtime() before this method.

postRealtime ​

swift
func postRealtime(_ message: JSON, recipient: String, notification: JSON? = nil) async throws -> JSON

Sends any JSON value to a user (recipient is a user ID) or to the group you joined (recipient is its name). Returns {"type": "success", "message": "Message sent."}.

notification: ["title": String, "body": String, "config"?: ["always": Bool]], a web push for recipients in a browser. See Notifications.

Errors ​

codemessage
INVALID_REQUESTNo realtime connection. Execute connectRealtime() before this method.
INVALID_REQUESTNo recipient.
INVALID_REQUESTUser has not joined to the recipient group. Run joinRealtime(group: "<group>")
INVALID_REQUESTRealtime connection is not open. Try reconnecting with connectRealtime(). (the connection is down)
INVALID_PARAMETERMessage is <n> bytes; a realtime message can be at most 32768 bytes including its headers.
INVALID_PARAMETER"notification" should be an object with "title" and "body". / Key "title" is required. / "title" should be type: <string>. / "config.always" should be type: <boolean>.
INVALID_PARAMETERNotification size exceeds 3kb.

getRealtimeGroups ​

swift
func getRealtimeGroups(_ params: JSON? = nil, fetchOptions: FetchOptions? = nil) async throws -> JSON

Groups that have members now: {"list": [{"group", "number_of_users"}], ...}. Left out, params lists every group.

key
searchFor"group" (default) or "number_of_users"
valuea string for "group", a number for "number_of_users"
condition">", ">=", "=", "<", "<=", "!=" (or gt, gte, eq, lt, lte, ne)
rangean upper bound of the same type as value; replaces condition

fetchOptions: see Paging.

Errors ​

codemessage
INVALID_PARAMETER"<value>" is invalid in "searchFor". allowed types or values are: "group", "number_of_users".
INVALID_PARAMETER"<value>" is invalid in "condition". allowed types or values are: ...
INVALID_PARAMETER"value" must be a number. / "value" must be a string. / "range" must be a number. / "range" must be a string.

getRealtimeUsers ​

swift
func getRealtimeUsers(_ params: JSON? = nil, fetchOptions: FetchOptions? = nil) async throws -> JSON

Connections in a group: {"list": [{"user_id", "cid"}], ...}.

key
groupthe group; left out, the one you joined
user_idonly this user's connections

Errors ​

codemessage
INVALID_PARAMETERNo group has been joined. Otherwise "group" is required.
INVALID_PARAMETER"<value>" is invalid in "group". allowed type or value is: Type<string>.
INVALID_PARAMETERUser ID in "user_id" is empty. / User ID in "user_id" is invalid.

RealtimeEvent ​

swift
struct RealtimeEvent {
    let type: String
    let message: JSON
    let sender: String?
    let senderCid: String?
    let senderRid: String?
    let code: String?
    var json: JSON { get }
}
field
type"message", "private", "notice", "success", "error", "reconnect" or "close"
messagethe JSON value that was sent, or a status text
senderuser ID of the sender (message, private, notice)
senderCidconnection ID of the sender, "cid:..."
senderRidthe group it came through
codeon notices: USER_JOINED, USER_LEFT or USER_DISCONNECTED
jsonthe event as an object with the skapi-js keys: type, message, sender, sender_cid, sender_rid, code

See Events.

skapi-swift 2.4.0