github.com/jpatel531/pusher-websocket-swift

Pusher Websocket library for Swift | owner=@hamchapman



Documentation

PusherSwift (pusher-websocket-swift)

Build Status Cocoapods Compatible Platform Carthage Compatible Twitter GitHub license

Table of Contents

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects and is our recommended method of installing PusherSwift and its dependencies.

If you don't already have the Cocoapods gem installed, run the following command:

$ gem install cocoapods

To integrate PusherSwift into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

pod 'PusherSwift'

Then, run the following command:

$ pod install

Carthage

Carthage is a decentralized dependency manager that automates the process of adding frameworks to your Cocoa application.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate PusherSwift into your Xcode project using Carthage, specify it in your Cartfile:

github "pusher/pusher-websocket-swift"

Configuration

There are a number of configuration parameters which can be set for the Pusher client. They are:

  • authEndpoint (String) - the URL that the library will make an authentication request to if attempting to subscribe to a private or presence channel and you have not provided a secret
  • secret (String) - your app's secret so that authentication requests do not need to be made to your authentication endpoint and instead subscriptions can be authenticated directly inside the library (this is mainly desgined to be used for development)
  • userDataFetcher (() -> PusherUserData) - if you are subscribing to an authenticated channel and wish to provide a function to return user data
  • attemptToReturnJSONObject (Bool) - whether or not you'd like the library to try and parse your data as JSON (or not, and just return a string)
  • encrypted (Bool) - whether or not you'd like to use encypted transport or not
  • authRequestCustomizer (NSMutableURLRequest -> NSMutableURLRequest) - if you are subscribing to an authenticated channel and wish to provide a function to customize the authorization request
  • autoReconnect (Bool) - set whether or not you'd like the library to try and autoReconnect upon disconnection
  • host (String) - set a custom value for the host you'd like to connect to
  • port (Int) - set a custom value for the port that you'd lilke to connect to
  • cluster (String) - specify the cluster that you'd like to connect to, e.g. eu

All of these configuration options can be set when instantiating the Pusher object, for example:

let pusher = Pusher(
  key: "APP_KEY",
  options: [
    "authEndpoint": "http://localhost:9292/pusher/",
    "encrypted": true
  ]
)

Authenticated channel example:

let request = {(urlRequest:NSMutableURLRequest) -> NSMutableURLRequest in
    urlRequest.setValue("token", forHTTPHeaderField: "Authorization")
    return urlRequest
}

let pusher = Pusher( 
  key: "APP_KEY",
  options: [
    "authEndpoint": "http://localhost:9292/pusher/",
    "authRequestCustomizer": request,
    "encrypted": true
  ]
)

Where "Authorization" and "token" are the field and value your server is expecting in the headers of the request.

Connection

A Websocket connection is established by providing your API key to the constructor function:

let pusher = Pusher(key: "APP_KEY")
pusher.connect()

This returns a client object which can then be used to subscribe to channels and then calling connect() triggers the connection process to start.

Connection state changes

There is a connection state change delegate that you can implement if you want to get updated when the connection state changes.

You use it like this:

class ViewController: UIViewController, ConnectionStateChangeDelegate {

    override func viewDidLoad() {
        super.viewDidLoad()
        let pusher = Pusher(key: "APP_KEY")
        pusher.connection.stateChangeDelegate = self
        pusher.connect()
        // ...
    }

    func connectionChange(old: ConnectionState, new: ConnectionState) {
        print("old: \(old) -> new: \(new)")
    }
}

Subscribing

Public channels

The default method for subscribing to a channel involves invoking the subscribe method of your client object:

let myChannel = pusher.subscribe('my-channel')

This returns PusherChannel object, which events can be bound to.

Private channels

Private channels are created in exactly the same way as public channels, except that they reside in the 'private-' namespace. This means prefixing the channel name:

let myPrivateChannel = pusher.subscribe('private-my-channel')

Presence channels

Presence channels are created in exactly the same way as private channels, except that they reside in the 'presence-' namespace.

let myPresenceChannel = pusher.subscribe('presence-my-channel')

Note that both private and presence channels require the user to be authenticated in order to subscribe to the channel. This authentication can either happen inside the library, if you configured your Pusher object with your app's secret, or an authentication request is made to an authentication endpoint that you provide, again when instantiaing your Pusher object.

Note that we recommend that you use an authentication endpoint over including your app's secret in your app in the vast majority of use cases. If you are completely certain that there's no risk to you including your app's secret in your app, for example if your app is just for internal use at your company, then it can make things easier than setting up an authentication endpoint.

Binding to events

Events can be bound to at 2 levels; globally and per channel. When binding to an event you can choose to save the return value, which is a unique identifier for the event handler that gets created. The only reason to save this is if you're going to want to unbind from the event at a later point in time. There is an example of this below.

Global events

You can attach behaviour to these events regardless of the channel the event is broadcast to. The following is an example of an app that binds to new comments from any channel:

let pusher = Pusher(key: "MY_KEY")
pusher.subscribe("my-channel")

pusher.bind("new-comment", callback: { (data: AnyObject?) -> Void in
    if let data = data as? Dictionary<String, AnyObject> {
        if let commenter = data["commenter"] as? String, message = data["message"] as? String {
            print("\(commenter) wrote \(message)")
        }
    }
})

Per-channel events

These are bound to a specific channel, and mean that you can reuse event names in different parts of your client application. The following might be an example of a stock tracking app where several channels are opened for different companies:

let pusher = Pusher(key: "MY_KEY")
let myChannel = pusher.subscribe("my-channel")

myChannel.bind("new-price", callback: { (data: AnyObject?) -> Void in
    if let data = data as? Dictionary<String, AnyObject> {
        if let price = data["price"] as? String, company = data["company"] as? String {
            print("\(company) is now priced at \(price)")
        }
    }
})

Unbind event handlers

You can remove previously-bound handlers from an object by using the unbind function. For example,

let pusher = Pusher(key: "MY_KEY")
let myChannel = pusher.subscribe("my-channel")

let eventHandlerId = myChannel.bind("new-price", callback: { (data: AnyObject?) -> Void in
  ...
})

myChannel.unbind(eventName: "new-price", callbackId: eventHandlerId)

You can unbind from events at both the global and per channel level. For both objects you also have the option of calling unbindAll, which, as you can guess, will unbind all eventHandlers on the object.

Testing

There are a set of tests for the library that can be run using the standard methods (Command-U in Xcode). The tests also get run on Travis-CI.

Communication

  • If you have found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, submit a pull request (preferrably with some tests :) ).

Maintainers

PusherSwift is owned and maintained by Pusher. It was originally created by Hamilton Chapman

License

PusherSwift is released under the MIT license. See LICENSE for details.