pusher_client

Description:

pusher client

Pusher Channels Flutter Client #




A Pusher Channels client plugin for Flutter targeting Android and iOS. It wraps
pusher-websocket-java v2.2.5 and pusher-websocket-swift v8.0.0.
For tutorials and more in-depth information about Pusher Channels, visit the official docs.
This client works with official pusher servers and laravel self hosted pusher websocket server (laravel-websockets).
Supported Platforms & Deployment Targets #

Android API 16 and above
iOS 9.0 and above

Table of Contents #

Installation
Configuration

For iOS
For Android


API Overview
The Pusher Constructor
Pusher Options Config
Reconnecting
Disconnecting
Subscribing To Channels

Public Channels
Private Channels
Private Encrypted Channels

Presence Channels




Binding To Events

Callback Parameters
Unbind Channel Events


Triggering Client Events
Accessing The Connection Socket ID
Resolve Common Issues

Installation #
Add to your pubspec.yaml
dependencies:
pusher_client: ^2.0.0
copied to clipboard
Configuration #
For iOS #
Set the minimum deployment target in the Podfile to 9.0. Go to ios/Podfile, then uncomment this line:
# platform :ios, '8.0'
copied to clipboard
Change it to:
platform :ios, '9.0'
copied to clipboard
You may have an issue subscribing to private channels if you're using a local pusher server like laravel-websockets, to fix this go to ios/Runner/Info.plist and add:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
copied to clipboard
If you know which domains you will connect to add:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>example.com</key>
<dict>
<key>NSExceptionAllowsInsecureHTTPLoads</key>
<true/>
<key>NSIncludesSubdomains</key>
<true/>
</dict>
</dict>
</dict>
copied to clipboard
For Android #
If you have enabled code obfuscation with R8 or proguard, you need to add the following rule in android/app/build.gradle:
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
copied to clipboard
Then in android/app/proguard-rules.pro:
-keep class com.github.chinloyal.pusher_client.** { *; }
copied to clipboard
API Overview #
Here's the API in a nutshell.
PusherOptions options = PusherOptions(
host: 'example.com',
wsPort: 6001,
encrypted: false,
auth: PusherAuth(
'http://example.com/auth',
headers: {
'Authorization': 'Bearer $token',
},
),
);

PusherClient pusher = PusherClient(
YOUR_APP_KEY,
options,
autoConnect: false
);

// connect at a later time than at instantiation.
pusher.connect();

pusher.onConnectionStateChange((state) {
print("previousState: ${state.previousState}, currentState: ${state.currentState}");
});

pusher.onConnectionError((error) {
print("error: ${error.message}");
});

// Subscribe to a private channel
Channel channel = pusher.subscribe("private-orders");

// Bind to listen for events called "order-status-updated" sent to "private-orders" channel
channel.bind("order-status-updated", (PusherEvent event) {
print(event.data);
});

// Unsubscribe from channel
pusher.unsubscribe("private-orders");

// Disconnect from pusher service
pusher.disconnect();

copied to clipboard
More information in reference format can be found below.
The Pusher Constructor #
The constructor takes an application key which you can get from the app's API Access section in the Pusher Channels dashboard, and a pusher options object.
PusherClient pusher = PusherClient(YOUR_APP_KEY, PusherOptions());
copied to clipboard
If you are going to use private, presence or encrypted channels then you will need to provide a PusherAuth to be used when authenticating subscriptions. In order to do this you need to pass in a PusherOptions object which has had an auth set.
PusherAuth auth = PusherAuth(
// for auth endpoint use full url
'http://example.com/auth',
headers: {
'Authorization': 'Bearer $token',
},
);

PusherOptions options = PusherOptions(
auth: auth
);

PusherClient pusher = PusherClient(YOUR_APP_KEY, options);
copied to clipboard
To disable logging and auto connect do this:
PusherClient pusher = PusherClient(
YOUR_APP_KEY,
options,
enableLogging: false,
autoConnect: false,
);
copied to clipboard
If auto connect is disabled then you can manually connect using connect() on the pusher instance.
Pusher Options Config #
Most of the functionality of this plugin is configured through the PusherOptions object. You configure it by setting parameters on the object before passing it to the Pusher client. Below is a table containing all of the properties you can set.



Method
Parameter
Description




encrypted
bool
Whether the connection should be made with TLS or not.


auth
PusherAuth
Sets the authorization options to be used when authenticating private, private-encrypted and presence channels.


host
String
The host to which connections will be made.


wsPort
int
The port to which unencrypted connections will be made. Automatically set correctly.


wssPort
int
The port to which encrypted connections will be made. Automatically set correctly.


cluster
String
Sets the cluster the client will connect to, thereby setting the Host and Port correctly.


activityTimeout
int
The number of milliseconds of inactivity at which a "ping" will be triggered to check the connection. The default value is 120,000.


pongTimeout
int
The number of milliseconds the client waits to receive a "pong" response from the server before disconnecting. The default value is 30,000.


maxReconnectionAttempts
int
Number of reconnection attempts that will be made when pusher.connect() is called, after which the client will give up.


maxReconnectGapInSeconds
int
The delay in two reconnection extends exponentially (1, 2, 4, .. seconds) This property sets the maximum inbetween two reconnection attempts.



Reconnecting #
The connect() method is also used to re-connect in case the connection has been lost, for example if a device loses reception. Note that the state of channel subscriptions and event bindings will be preserved while disconnected and re-negotiated with the server once a connection is re-established.
Disconnecting #
pusher.disconnect();
copied to clipboard
After disconnection the PusherClient instance will release any internally allocated resources (threads and network connections)
Subscribing To Channels #
Channels use the concept of channels as a way of subscribing to data. They are identified and subscribed to by a simple name. Events are bound to a channel and are also identified by name.
As mentioned above, channel subscriptions need only be registered once by the PusherClient instance. They are preserved across disconnection and re-established with the server on reconnect. They should NOT be re-registered. They may, however, be registered with a PusherClient instance before the first call to connect - they will be completed with the server as soon as a connection becomes available.
Public Channels #
The default method for subscribing to a channel involves invoking the subscribe method of your client object:
Channel channel = pusher.subscribe("my-channel");
copied to clipboard
This returns a Channel 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:
Channel privateChannel = pusher.subscribe("private-status-update");
copied to clipboard
Subscribing to private channels involves the client being authenticated. See The Pusher Constructor section for the authenticated channel example for more information.
Private Encrypted Channels #
Similar to Private channels, you can also subscribe to a private encrypted channel. This plugin fully supports end-to-end encryption. This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them. These channels must be prefixed with 'private-encrypted-'
Like with private channels, you must provide an authentication endpoint. That endpoint must be using a server client that supports end-to-end encryption. There is a demonstration endpoint to look at using nodejs.
Presence Channels #
Presence channels are channels whose names are prefixed by 'presence-'. Presence channels also need to be authenticated.
Channel presenceChannel = pusher.subscribe("presence-another-channel");
copied to clipboard
Binding To Events #
There are two types of events that occur on channel subscriptions.

Protocol related events such as those triggered when a subscription succeeds, for example "pusher:subscription_succeeded"
Application events that have been triggered by code within your app

Channel channel = pusher.subscribe("private-orders");

channel.bind("order-status-updated", (PusherEvent event) {
print(event.data);
});
copied to clipboard
Callback Parameters #
The callbacks you bind receive a PusherEvent:



Property
Type
Description




eventName
String
The name of the event.


channelName
String
The name of the channel that the event was triggered on. (Optional)


data
String
The data that was passed to trigger, encoded as a string. If you passed an object then that will have been serialized to a JSON string which you can parse as necessary. (Optional)


userId
String
The ID of the user who triggered the event. This is only available for client events triggered on presence channels. (Optional)



Unbind Channel Events #
You can unbind from an event by doing:
channel.unbind("order-status-updated");
copied to clipboard
Triggering Client Events #
Once a private or presence subscription has been authorized and the subscription has succeeded, it is possible to trigger events on those channels.
Events triggered by clients are called client events. Because they are being triggered from a client which may not be trusted there are a number of enforced rules when using them. Some of these rules include:

Event names must have a 'client-' prefix
Rate limits
You can only trigger an event when the subscription has succeeded

channel.bind("pusher:subscription_succeeded", (PusherEvent event) {
channel.trigger("client-istyping", {"name": "Bob"});
});
copied to clipboard
For full details see the client events documentation.
Accessing The Connection Socket ID #
Once connected you can access a unique identifier for the current client's connection. This is known as the socket Id. You can access the value once the connection has been established as follows:
String socketId = pusher.getSocketId();
copied to clipboard
For more information on how and why there is a socket Id see the documentation on authenticating users and excluding recipients.
Resolve Common Issues #
iOS doesn't log when enableLogging is set to true #
iOS logging doesn't seem to output to flutter console, however if you run the
app from Xcode you should be able to see the logs.
Subscribing to private channels with iOS #
If using a local pusher server but are unable to subscribe to a private channel
then add this to your ios/Runner/Info.plist:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
copied to clipboard
If you know which domains you will connect to add:
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>example.com</key>
<dict>
<key>NSExceptionAllowsInsecureHTTPLoads</key>
<true/>
<key>NSIncludesSubdomains</key>
<true/>
</dict>
</dict>
</dict>
copied to clipboard