Usage Guide

Using SwiftPhoenixClient

SwiftPhoenixClient is built to mirror the Javascript Client as closely as possible. If you've used that client, then this should be familiar.

Creating a Socket

First, you need to create the socket that will join channels, receive events, and send messages

let socket = Socket(url: "ws://localhost:4000/socket/websocket", params: ["token": "Bearer 123", "user": "Full Name"])
socket.connect()

This will create a Socket that is pointed to "ws://localhost:4000/socket/websocket" with query parameters token and user appended to the URL. params is optional and can be left out if desired.

You can hook into the Socket as well.

socket.onOpen = { print("Socket Opened") }
socket.onClose = { print("Socket Closed") }
socket.onError = { error in print("Socket Error: ", error.localizedDescription) }

When you're done, be sure to disconnect

socket.disconnect()

Channels and Events

Once your socket is created, you can join channel topics which listen for specific events and allow for sending data do a topic. Whenever sending data, you can use the .receive() hook to get the status of the outbound push message.

let socket = Socket(url: "ws://localhost:4000/socket/websocket")
let channel = socket.channel("room:123", params: ["token": "Room Token"])
channel.on("new_msg") { payload in print("Got message", payload) }

channel.push("new_msg", payload: ["body": "This is a message"])
    .receive("ok") { payload in print("Sent message", payload) }
    .receive("error") { payload in print("Send failed", payload) }
    .receive("timeout") { payload in print("Networking issue...", payload) }

channel.join()
    .receive("ok") { payload in print("Channel Joined", payload) }
    .receive("error") { payload in print("Failed to join", payload) }
    .receive("timeout") { payload in print("Networking issue...", payload) }

There are also three hooks you can add to a Channel, onClose, onError, and onMessage.

/// Called when errors occur on the channel
channel.onError = { (payload) in print("Error: ", payload) }

/// Called when the channel is closed
channel.onClose = { (payload) in print("Channel Closed") }

/// Called before the `.on(event:, callback:)` hook is called for all events. Allows you to
/// hook in an manipulate or spy on the incoming payload before it is sent out to it's
/// bound handler. You must return the payload, modified or unmodified
channel.onMessage = { (event, payload, ref) -> Payload in 
    payload["modified"] = true
    return payload 
}

Sending Messages

You can send message through the socket with any topic. Then you can receive events as the message sends

socket
    .push(topic: "rooms:lobby", 
          event: "new:msg", 
          payload: ["user": "Full Name", "body": "test message"])
    .receive("ok", handler: { (payload) in print("Message Sent") })
    .receive("error", handler: { (payload) in print("Message Failed") })
    .always {
        // This will fire on any event
    }

Ideally though, you should be sending messages through their respective channel

channel
    .push("new:msg", payload: ["body": "message body"])
    .receive("ok", handler: { (payload) in print("Message Sent") })