Scaledrone Swift

Use the Scaledrone Swift client to connect to the Scaledrone realtime messaging service

This project is still a work in progress, pull requests and issues are very welcome.

Installation

CocoaPods

Check out Get Started tab on cocoapods.org.

To use Scaledrone in your project add the following 'Podfile' to your project

pod 'Scaledrone', '~> 0.5.2'

Then run:

pod install

Carthage

Check out the Carthage Quick Start instructions.

To use Scaledrone with Carthage, add the following to your Cartfile:

github "ScaleDrone/Scaledrone-Swift"

Then run:

carthage update

After that, follow the instructions on Carthage's docs.

Usage

First thing is to import the framework. See the Installation instructions on how to add the framework to your project.

import Scaledrone

Once imported, you can connect to Scaledrone.

scaledrone = Scaledrone(channelID: "your-channel-id")
scaledrone.delegate = self
scaledrone.connect()

After you are connected, there are some delegate methods that we need to implement.

scaledroneDidConnect

func scaledroneDidConnect(scaledrone: Scaledrone, error: Error?) {
    print("Connected to Scaledrone")
}

scaledroneDidReceiveError

func scaledroneDidReceiveError(scaledrone: Scaledrone, error: Error?) {
    print("Scaledrone error", error ?? "")
}

scaledroneDidDisconnect

func scaledroneDidDisconnect(scaledrone: Scaledrone, error: Error?) {
    print("Scaledrone disconnected", error ?? "")
}

Authentication

Implement the ScaledroneAuthenticateDelegate protocol and set an additional delegate

scaledrone.authenticateDelegate = self

Then use the authenticate method to authenticate using a JWT

scaledrone.authenticate(jwt: "jwt_string")

scaledroneDidAuthenticate

func scaledroneDidAuthenticate(scaledrone: Scaledrone, error: Error?) {
    print("Scaledrone authenticated", error ?? "")
}

Sending messages

scaledrone.publish(message: "Hello from Swift", room: "myroom")
// Or
room.publish(message: ["foo": "bar", "1": 2])

Subscribing to messages

Subscribe to a room and implement the ScaledroneRoomDelegate protocol, then set additional delegation

let room = scaledrone.subscribe(roomName: "myroom")
room.delegate = self

scaledroneRoomDidConnect

func scaledroneRoomDidConnect(room: ScaledroneRoom, error: Error?) {
    print("Scaledrone connected to room", room.name, error ?? "")
}

scaledroneRoomDidReceiveMessage

The member argument exists when the message was sent to an observable room using the socket API (not the REST API).

func scaledroneRoomDidReceiveMessage(room: ScaledroneRoom, message: ScaledroneMessage) {
    if message.member != nil {
        // This message was sent to an observable room
        // This message was sent through the socket API, not the REST API
        print("Received message from member:", message.memberID as Any)
    }
    
    let data = message.data
    
    if let messageData = data as? [String: Any] {
        print("Received a dictionary:", messageData)
    }
    if let messageData = data as? [Any] {
        print("Received an array:", messageData)
    }
    if let messageData = data as? String {
        print("Received a string:", messageData)
    }
}

Observable rooms

Observable rooms act like regular rooms but provide additional functionality for keeping track of connected members and linking messages to members.

Adding data to the member object

Observable rooms allow adding custom data to a connected user. The data can be added in two ways:

Passing the data object to a new instance of Scaledrone in your Swift code.

let scaledrone = Scaledrone(channelID: "<channel_id>", data: ["name": "Swift", "color": "#ff0000"])

This data can later be accessed like so:

func scaledroneObservableRoomMemberDidJoin(room: ScaledroneRoom, member: ScaledroneMember) {
    print("member joined with clientData", member.clientData)
}

Adding the data to the JSON Web Token as the data clause during authentication. This method is safer as the user has no way of changing the data on the client side.

{
  "client": "client_id_sent_from_javascript_client",
  "channel": "channel_id",
  "data": {
    "name": "Swift",
    "color": "#ff0000"
  },
  "permissions": {
    "^main-room$": {
      "publish": false,
      "subscribe": false
    }
  },
  "exp": 1408639878000
}

This data can later be accessed like so:

func scaledroneObservableRoomMemberDidJoin(room: ScaledroneRoom, member: ScaledroneMember) {
    print("member joined with authData", member.authData)
}

Receiving the observable events

Implement the ScaledroneObservableRoomDelegate protocol, then set additional delegation.

Observable room names need to be prefixed with observable-

let room = scaledrone.subscribe(roomName: "observable-room")
room.delegate = self
room.observableDelegate = self

scaledroneObservableRoomDidConnect

func scaledroneObservableRoomDidConnect(room: ScaledroneRoom, members: [ScaledroneMember]) {
    // The list will contain yourself
    print(members.map { (m: ScaledroneMember) -> String in
        return m.id
    })
}

scaledroneObservableRoomMemberDidJoin

func scaledroneObservableRoomMemberDidJoin(room: ScaledroneRoom, member: ScaledroneMember) {
    print("member joined", member, member.id)
}

scaledroneObservableRoomMemberDidLeave

func scaledroneObservableRoomMemberDidLeave(room: ScaledroneRoom, member: ScaledroneMember) {
    print("member left", member, member.id)
}

Message History

When creating a Scaledrone room you can supply the number of messages to recieve from that room's history. The messages will arrive, in reverse chronological order and one by one, in scaledroneRoomDidReceiveMessage, just like real-time messages.

In order to recieve message history messages, this feature needs to be enabled in the Scaledrone dashboard. You can learn more about Message History and its limitations in Scaledrone docs.

let room = scaledrone.subscribe(roomName: "chat-room", messageHistory: 50)

Basic Example

import UIKit

class ViewController: UIViewController, ScaledroneDelegate, ScaledroneRoomDelegate {

    let scaledrone = Scaledrone(channelID: "your-channel-id")

    override func viewDidLoad() {
        super.viewDidLoad()
        scaledrone.delegate = self
        scaledrone.connect()
    }

    func scaledroneDidConnect(scaledrone: Scaledrone, error: Error?) {
        print("Connected to Scaledrone channel", scaledrone.clientID)
        let room = scaledrone.subscribe(roomName: "notifications")
        room.delegate = self
    }

    func scaledroneDidReceiveError(scaledrone: Scaledrone, error: Error?) {
        print("Scaledrone error")
    }

    func scaledroneDidDisconnect(scaledrone: Scaledrone, error: Error?) {
        print("Scaledrone disconnected")
    }

    func scaledroneRoomDidConnect(room: ScaledroneRoom, error: Error?) {
        print("Scaledrone connected to room", room.name)
    }

    func scaledroneRoomDidReceiveMessage(room: ScaledroneRoom, message: String) {
        print("Room received message:", message)
    }
}

For a longer example see the ViewController.swift file.

Migration notes

0.5.0

Scaledrone 0.5.0 removes the use of NSError in favor of Error in the delegate methods, and adds support for Swift 5.

0.5.2:

scaledroneRoomDidReceiveMessage(room:message:member) was renamed to scaledroneRoomDidReceiveMessage(room:message:) and message is now of type ScaledroneMessage which includes the member and message IDs, the message's time as well as the data that was sent.

Todo:

Automatic reconnection

ztkevin / scaledrone-swift Goto Github PK