Inherits from NSObject
Conforms to PTPusherConnectionDelegate
PTPusherEventBindings
Declared in PTPusher.h
PTPusher.m

Overview

A PTPusher object provides a high level API for communicating with the Pusher service.

A single instance of PTPusher can be used to connect to the service, subscribe to channels and send events.

To create an instance of PTPusher, you will need your Pusher API key. This can be obtained from your account dashboard.

PTPusher’s delegate methods allow an object to receive important events in the client and connection’s lifecycle, such as connection, disconnection, reconnection and channel subscribe/unsubscribe events.

Whilst PTPusher exposes it’s connection object as a readonly property, there is no need to manage or create this connection yourself. The connection can be queried for it’s current connection state and socket ID if needed.

PTPusher aims to mirror the Pusher Javascript client API as much as possible although whilst the Javascript API uses event binding for any system events, such as channel subscription libPusher uses standard Cocoa and Objective-C patterns such as delegation and notification where it makes sense to do so.

PTPusher will attempt to try and remain connected whenever possible. If the connection disconnects, then depending on the error code returned, it will either try to reconnect immediately, reconnect after a configured delay or not reconnect at all. See the project README for more information on this.

Note: due to various problems people have had connecting to Pusher without SSL over a 3G connection, it is highly recommend that you use SSL. For this reason, SSL is enabled by default.

The Pusher protocol version, used to determined which features are supported.

Tasks

Properties

Creating new instances

Managing the connection

Subscribing to channels

Publishing events

Deprecated methods

Properties

authorizationURL

The authorization URL for private subscriptions.

@property (nonatomic, strong) NSURL *authorizationURL

Discussion

The authorization URL for private subscriptions.

All private channels (including presence channels) require authorization in order to subscribe.

Authorization happens on your own server. When subscribing to a private or presence channel, an authorization POST request will be sent to the URL specified by this property.

Attempting to subscribe to a private or presence channel without setting this property will result in an assertion error.

For more information on channel authorization, see the Pusher documentation website.

Declared In

PTPusher.h

connection

The connection object for this client.

@property (nonatomic, strong, readonly) PTPusherConnection *connection

Discussion

The connection object for this client.

Each instance uses a single connection only. Most clients will likely only ever need a single PTPusher object and therefore a single connection.

The connection is exposed to provide access to it’s socketID and connection state. Clients should not attempt to manage this connection directly.

Declared In

PTPusher.h

delegate

The object that acts as the delegate for the receiving instance.

@property (nonatomic, weak) id<PTPusherDelegate> delegate

Discussion

The object that acts as the delegate for the receiving instance.

The delegate must implement the PTPusherDelegate protocol. The delegate is not retained.

Declared In

PTPusher.h

reconnectDelay

Specifies the delay between reconnection attempts. Defaults to 5 seconds.

@property (nonatomic, assign) NSTimeInterval reconnectDelay

Discussion

Specifies the delay between reconnection attempts. Defaults to 5 seconds.

Declared In

PTPusher.h

Class Methods

pusherWithKey:connectAutomatically:

Initialises a new PTPusher instance with a connection configured with the given key. (Deprecated: Use pusherWithKey:delegate:encrypted: or pusherWithKey:delegate:)

+ (id)pusherWithKey:(NSString *)key connectAutomatically:(BOOL)connectAutomatically

Parameters

key

Your application’s API key. It can be found in the API Access section of your application within the Pusher user dashboard.

connect

Automatically If YES, the connection will be connected on initialisation.

Discussion

Initialises a new PTPusher instance with a connection configured with the given key.

If you intend to set a delegate for this instance, you are recommended to set connectAutomatically to NO, set the delegate then manually call connect.

Declared In

PTPusher.h

pusherWithKey:connectAutomatically:encrypted:

Initialises a new PTPusher instance with a connection configured with the given key. (Deprecated: Use pusherWithKey:delegate:encrypted: or pusherWithKey:delegate:)

+ (id)pusherWithKey:(NSString *)key connectAutomatically:(BOOL)connectAutomatically encrypted:(BOOL)isEncrypted

Parameters

key

Your application’s API key. It can be found in the API Access section of your application within the Pusher user dashboard.

connectAutomatically

If YES, the connection will be connected on initialisation.

isEncrypted

If yes, a secure connection over SSL will be established.

Discussion

Initialises a new PTPusher instance with a connection configured with the given key.

If you intend to set a delegate for this instance, you are recommended to set connectAutomatically to NO, set the delegate then manually call connect.

Declared In

PTPusher.h

pusherWithKey:delegate:

Returns a new PTPusher instance with an connection configured with the given key.

+ (id)pusherWithKey:(NSString *)key delegate:(id<PTPusherDelegate>)delegate

Parameters

key

Your application’s API key. It can be found in the API Access section of your application within the Pusher user dashboard.

delegate

The delegate for this instance

Discussion

Returns a new PTPusher instance with an connection configured with the given key.

Instances created using this method will be encrypted by default. This requires SSL access on your account, which is generally recommended for mobile connections.

Declared In

PTPusher.h

pusherWithKey:delegate:encrypted:

Returns a new PTPusher instance with a connection configured with the given key.

+ (id)pusherWithKey:(NSString *)key delegate:(id<PTPusherDelegate>)delegate encrypted:(BOOL)isEncrypted

Parameters

key

Your application’s API key. It can be found in the API Access section of your application within the Pusher user dashboard.

delegate

The delegate for this instance

isEncrypted

If yes, a secure connection over SSL will be established.

Discussion

Returns a new PTPusher instance with a connection configured with the given key.

Declared In

PTPusher.h

Instance Methods

channelNamed:

Returns a previously subscribed channel with the given name.

- (PTPusherChannel *)channelNamed:(NSString *)name

Parameters

name

The name of the channel required.

Discussion

Returns a previously subscribed channel with the given name.

If the channel specified has not been subscribed to previously, or has been explicilty unsubscribed from, this will return nil.

This method will return channels that have become implicitly unsubscribed from if the client has disconnected.

Declared In

PTPusher.h

connect

Establishes a connection to the Pusher server.

- (void)connect

Discussion

Establishes a connection to the Pusher server.

If already connected, this method does nothing.

Declared In

PTPusher.h

disconnect

Disconnects from the Pusher server.

- (void)disconnect

Discussion

Disconnects from the Pusher server.

If already disconnected, this method does nothing.

Declared In

PTPusher.h

initWithConnection:

Initialises a new instance. This is the designated initialiser.

- (id)initWithConnection:(PTPusherConnection *)connection

Parameters

connection

An initialised connection for this instance.

Discussion

Initialises a new instance. This is the designated initialiser.

Clients should typically use one of the factory methods provided, which will configure the connection object for you using the standard Pusher host and port.

If you need to connect to Pusher using an alternative endpoint URL, e.g. for testing purposes, then you can initialise an instance of PTPusherConnection with an appropriate URL and pass it into this method.

Declared In

PTPusher.h

initWithConnection:connectAutomatically:

See initWithConnection: (Deprecated: See initWithConnection:)

- (id)initWithConnection:(PTPusherConnection *)connection connectAutomatically:(BOOL)connectAutomatically

Declared In

PTPusher.h

sendEventNamed:data:channel:

Sends an event directly over the connection’s socket.

- (void)sendEventNamed:(NSString *)name data:(id)data channel:(NSString *)channelName

Discussion

Sends an event directly over the connection’s socket.

Whilst Pusher provides a REST API for publishing events, it also supports the sending of events directly from clients over the client’s existing connection.

Client events have the following restrictions:

  • The user must be subscribed to the channel that the event is being triggered on.

  • Client events can only be triggered on private and presence channels because they require authentication.

  • Client events must be prefixed by client-. Events with any other prefix will be rejected by the Pusher server, as will events sent to channels to which the client is not subscribed.

This method does nothing to enforce the first two restrictions. It is instead recommended that you use the PTPusherChannel event triggering API rather than calling this method directly.

Warning: Note: This Pusher feature is currently in beta and requires enabling on your account.

Declared In

PTPusher.h

subscribeToChannelNamed:

Subscribes to the named channel.

- (PTPusherChannel *)subscribeToChannelNamed:(NSString *)name

Parameters

name

The name of the channel to subscribe to.

Return Value

The channel object.

Discussion

Subscribes to the named channel.

This method can be used to subscribe to any type of channel, including private and presence channels by including the appropriate channel name prefix.

Note: this method returns the channel object immediately, but it might not yet be subscribed - subscription is asynchronous. You do not have to wait for a channel to become subscribed before setting up event bindings. If you care about when the channel is subscribed, you can use key-value observing on it’s isSubscribed property or implement the appropriate PTPusherDelegate method.

It is valid to call this (or any of the other subscribe methods) while the client is not connected. All channels default to unsubscribed and any subcribed channels will become implicitly unsubscribed if the client disconnects. When the client connects, all channels will be re-subscribed to automatically.

When you subscribe to a channel, PTPusher keeps a strong reference to that channel and maintains that reference until the channel is explicitly unsubscribed (by calling [PTPusherChannel unsubscribe].

If you maintain your own strong reference to the returned channel object, you should be aware that once unsubscribed, the object will no longer be of any use. For this reason you should be wary of passing around strong references to channels that you may unsubscribe from.

For more information on channel lifetime, see the README.

Declared In

PTPusher.h

subscribeToPresenceChannelNamed:

Subscribes to the named presence channel.

- (PTPusherPresenceChannel *)subscribeToPresenceChannelNamed:(NSString *)name

Parameters

name

The name of the channel (without the presence prefix) to subscribe to.

Discussion

Subscribes to the named presence channel.

The “presence-” prefix should be excluded from the name; it will be added automatically.

Declared In

PTPusher.h

subscribeToPresenceChannelNamed:delegate:

Subscribes to the named presence channel.

- (PTPusherPresenceChannel *)subscribeToPresenceChannelNamed:(NSString *)name delegate:(id<PTPusherPresenceChannelDelegate>)presenceDelegate

Parameters

name

The name of the channel (without the presence prefix) to subscribe to.

presenceDelegate

The presence delegate for this channel.

Discussion

Subscribes to the named presence channel.

The “presence-” prefix should be excluded from the name; it will be added automatically.

Whilst the presence delegate can be set on the channel after it is returned, to ensure events are not missed, it is advised that you call this method and specify a delegate. The delegate will be assigned before subscription happens.

Declared In

PTPusher.h

subscribeToPrivateChannelNamed:

Subscribes to the named private channel.

- (PTPusherPrivateChannel *)subscribeToPrivateChannelNamed:(NSString *)name

Parameters

name

The name of the channel (without the private prefix) to subscribe to.

Discussion

Subscribes to the named private channel.

The “private-” prefix should be excluded from the name; it will be added automatically.

Declared In

PTPusher.h

unsubscribeFromChannel:

Unsubscribes from the specified channel.

- (void)unsubscribeFromChannel:(PTPusherChannel *)channel

Parameters

channel

The channel to unsubscribe from.

Discussion

Unsubscribes from the specified channel.

This method is deprecated. You should use [PTPusherChannel unsubscribe] instead.

When you explicitly unsubscribe from a channel, it will never be re-subscribed to and PTPusher will remove any of it’s references to the channel. If you maintain no strong references to the channel of your own, the channel object will be deallocated.

If you do maintain a strong reference to a channel object, you should discard it after calling unsubscribe.

Declared In

PTPusher.h