📡 PusherClient

A lightweight Flutter package that brings Pusher Channels real-time functionality to Flutter apps, inspired by the official pusher-js library.

🚀 Features

  • ✅ Connect to Pusher via WebSocket
  • 📢 Subscribe to public, private, and presence channels
  • 📬 Bind to custom and system events
  • 🔀 Bind to multiple events on the same channel
  • 🎯 Bind to all events using null event name
  • ❌ Unbind events to remove specific or all callbacks
  • 🔐 Support for authenticated channels
  • 🔄 Auto-handles pusher:connection_established, subscription_succeeded, etc.
  • 🔄 Trigger client events on private channels (e.g., client-typing)
  • 🧑‍🤝‍🧑 Presence channels with user tracking
  • 🚪 Proper cleanup with close() method for channels

📦 Installation

dependencies:
pusher_client:
  git:
    url: https://github.com/yourusername/pusher_client.git

🛠️ Getting Started

1. Import and initialize

import 'package:pusher_client/pusher_client_ego.dart';

final pusher = PusherClient(
key: 'YOUR_PUSHER_KEY',
cluster: 'YOUR_CLUSTER',
authEndpoint: 'https://yourserver.com/pusher/auth', // Optional
headers: {
'Authorization': 'Bearer YOUR_TOKEN', // Optional
},
);

await pusher.connect();

2. Subscribe to a channel and bind to events

final channel = pusher.subscribe('public-chat');

// Bind to specific event
channel.bind(
  eventName: 'new-message',
  success: (event) {
    print('📩 Message: ${event.data}');
  },
  error: (error) {
    print('❌ Error: $error');
  },
);

// Bind to multiple events
channel.bind(
  eventName: 'user-joined',
  success: (event) => print('👋 User joined'),
);

channel.bind(
  eventName: 'user-left',
  success: (event) => print('👋 User left'),
);

// Bind to ALL events (eventName: null)
channel.bind(
  eventName: null,
  success: (event) => print('Any event: ${event['event']}'),
);

3. Unbind events

// Store callback reference if you need to remove it later
void myCallback(event) => print('Message: ${event.data}');

channel.bind(eventName: 'new-message', success: myCallback);

// Remove specific callback
channel.unbind(eventName: 'new-message', callback: myCallback);

// Remove ALL callbacks for an event
channel.unbind(eventName: 'new-message');

// Remove ALL callbacks for all events
channel.unbind(eventName: null);

4. Trigger a client event (private channels only)

final privateChannel = pusher.subscribe('private-room');

privateChannel.trigger('client-typing', {'user': 'Alice', 'isTyping': true});

5. Close a channel

// Properly unsubscribe and cleanup
channel.close();

🔐 Auth for Private & Presence Channels

Your backend must return a JSON object like this:

For Private Channels:

{
  "auth": "your_app_key:signature"
}

For Presence Channels:

{
  "auth": "your_app_key:signature",
  "channel_data": "{\"user_id\": \"123\", \"user_info\": {\"name\": \"Alice\"}}"
}

Use Pusher's official server SDKs to generate these responses:

🧪 Example main.dart

void main() async {
final pusher = PusherClient(
key: 'APP_KEY',
cluster: 'APP_CLUSTER',
authEndpoint: 'https://your-auth-endpoint',
);

await pusher.connect();

final channel = pusher.subscribe('public-chat');

channel.bind(
  eventName: 'new-message',
  success: (event) => print('Received: ${event.data}'),
);

// Listen to all events
channel.bind(
  eventName: null,
  success: (event) => print('Event: ${event['event']}'),
);

await Future.delayed(Duration(days: 365)); // Keep alive

// Cleanup
channel.close();
await pusher.disconnect();
}

📚 API Reference

PusherClient

Method Description
connect() Establishes the WebSocket connection
subscribe(channel) Subscribes to a channel and returns PusherChannel
disconnect() Closes connection and clears all channels

PusherChannel

Method Description
bind({eventName, success, error}) Binds callback to event (null = all events)
unbind({eventName, callback}) Removes specific or all callbacks
trigger(event, data) Sends client event (private channels only)
close() Unsubscribes and cleans up the channel

⚠️ Limitations

  • This is a simplified version and doesn't include encryption or full presence features like member lists yet.
  • Ensure your auth server signs correctly for private/presence channels.

📃 License

MIT © Omar Aly

🙌 Acknowledgments

Inspired by the official pusher-js and pusher-http libraries.

Libraries

pusher_client_ego