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).
- Android API 16 and above
- iOS 9.0 and above
- Installation
- Configuration
- API Overview
- The Pusher Constructor
- Pusher Options Config
- Reconnecting
- Disconnecting
- Subscribing To Channels
- Binding To Events
- Triggering Client Events
- Accessing The Connection Socket ID
- Resolve Common Issues
Add to your pubspec.yaml
dependencies:
pusher_client: ^2.0.0Set the minimum deployment target in the Podfile to 9.0. Go to ios/Podfile, then uncomment this line:
# platform :ios, '8.0'
Change it to:
platform :ios, '9.0'
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>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>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'
}
}Then in android/app/proguard-rules.pro:
-keep class com.github.chinloyal.pusher_client.** { *; }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();
More information in reference format can be found below.
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());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);To disable logging and auto connect do this:
PusherClient pusher = PusherClient(
YOUR_APP_KEY,
options,
enableLogging: false,
autoConnect: false,
);If auto connect is disabled then you can manually connect using connect() on the pusher instance.
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. |
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.
pusher.disconnect();After disconnection the PusherClient instance will release any internally allocated resources (threads and network connections)
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.
The default method for subscribing to a channel involves invoking the subscribe method of your client object:
Channel channel = pusher.subscribe("my-channel");This returns a Channel object, which events can be bound to.
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");Subscribing to private channels involves the client being authenticated. See The Pusher Constructor section for the authenticated channel example for more information.
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 are channels whose names are prefixed by 'presence-'. Presence channels also need to be authenticated.
Channel presenceChannel = pusher.subscribe("presence-another-channel");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);
});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) |
You can unbind from an event by doing:
channel.unbind("order-status-updated");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"});
});For full details see the client events documentation.
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();For more information on how and why there is a socket Id see the documentation on authenticating users and excluding recipients.
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.
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>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>
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent