📡 Flutter Reverb WebSocket Client #

A Dart/Flutter WebSocket client for Laravel Reverb, enabling seamless real-time communication with WebSockets.

🚀 Features #

✔️ Easy WebSocket Connection with Laravel Reverb
✔️ Authentication Support (JWT, API Keys)
✔️ Public & Private Channel Subscriptions
✔️ Real-time Event Handling
✔️ Lightweight & Easy to Use

📦 Installation #

Add simple_flutter_reverb to your pubspec.yaml:

dependencies:
    simple_flutter_reverb: ^0.0.2

and run:

flutter pub get

or install it from the command line:

flutter pub add simple_flutter_reverb

🎯 Usage #

1️⃣ Initialize the WebSocket Client #

import 'package:simple_flutter_reverb/simple_flutter_reverb.dart';

final options = SimpleFlutterReverbOptions(
  scheme: "ws", 
  host: "your-server.com",
  port: "6001",
  appKey: "your-app-key", // Reverb app key
  authUrl: "https://your-backend.com/broadcasting/auth", // optional, needed for private channels
  authToken: "your-auth-token", // optional
  privatePrefix: "private-", // default: "private-"
  usePrivateChannelPrefix: true, // default: true
);

final reverb = FlutterReverb(options: options);

2️⃣ Listen for Messages #

// Public channel
reverb.listen((message) {
  print("Received: ${message.event}, Data: ${message.data}");
}, "public-channel", isPrivate: false);

// Private channel
reverb.listen((message) {
print("Received: ${message.event}, Data: ${message.data}");
}, "public-channel", isPrivate: true);

3️⃣ Close Connection #

reverb.close();

🧪 Testing #

Unit tests are included and use mockito to simulate WebSocket interactions: TODO

flutter test

🛠 Configuration #

SimpleFlutterReverbOptions example #

class SimpleFlutterReverbOptions {
  final String scheme;
  final String host;
  final String port;
  final String appKey;
  final dynamic authToken;
  final String? authUrl;
  final String privatePrefix;
  final bool usePrefix;

  SimpleFlutterReverbOptions({
    required this.scheme,
    required this.host,
    required this.port,
    required this.appKey,
    this.authToken,
    this.authUrl,
    this.privatePrefix = 'private-',
    this.usePrefix = true,
  });
}

Usage Example #

import 'package:activeage_mobile/core/secure_storage/secure_storage.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:flutter_reverb/simple_flutter_reverb.dart';
import 'package:flutter_reverb/simple_flutter_reverb_options.dart';

import '../service_locator.dart';

/// WebSocketService manages communication with the Reverb WebSocket service.
class WebSocketService {
  // SecureStorageService instance to retrieve access tokens for authentication
  final SecureStorageService _secureStorageService = sl<SecureStorageService>();

  // FlutterReverb instance for managing WebSocket connections
  late final SimpleFlutterReverb _flutterReverb;

  /// Constructor to initialize the WebSocketService
  /// Sets up the FlutterReverb with the required configuration
  WebSocketService() {
    // Creating an options object for Reverb WebSocket connection
    final SimpleFlutterReverbOptions _options = FlutterReverbOptions(
      // Reading environment variables from .env file for Reverb configuration
      scheme: dotenv.env['REVERB_SCHEME']!,
      host: dotenv.env['REVERB_HOST']!,
      port: dotenv.env['REVERB_PORT']!,
      appKey: dotenv.env['REVERB_APP_KEY']!,
      authUrl: dotenv.env['REVERB_AUTH_URL']!, // URL for authentication (private channels) (Documentation: https://laravel.com/docs/11.x/broadcasting#authorizing-channels)
      privatePrefix: 'private-', // Prefix for private channels (Laravel default prefix is 'private-')
      // Retrieving the access token from secure storage for authentication
      authToken: _secureStorageService.getAccessToken(),
    );

    // Initializing FlutterReverb with the provided options
    _flutterReverb = FlutterReverb(options: _options);
  }

  /// Listens to a public channel and calls the onData callback with the received data.
  /// 
  /// [onData] - A callback function that will be invoked with the data from the channel.
  /// [channel] - The name of the public channel to listen to.
  void listenPublicChannel(void Function(dynamic) onData, String channel) {
    // Subscribing to the public channel
    _flutterReverb.listen(onData, channel);
  }

  /// Listens to a private channel and calls the onData callback with the received data.
  /// 
  /// [onData] - A callback function that will be invoked with the data from the channel.
  /// [channel] - The name of the private channel to listen to.
  void listenPrivateChannel(void Function(dynamic) onData, String channel) {
    // Subscribing to the private channel by passing `isPrivate: true`
    _flutterReverb.listen(onData, channel, isPrivate: true);
  }

}

/// Uncommented legacy code for reference (if needed later):
/// This section of code is an alternative approach using WebSocketChannel for managing WebSocket communication.
/// It subscribes to both public and private channels, handles authentication, and includes error handling for WebSocket connections.

🤝 Contributing #

1. Fork the repo & clone it
2. Create a new branch
3. Commit your changes
4. Push and open a Pull Request

📄 License #

This package is open-source and licensed under the MIT License.

📬 Support #

Found a bug? Have a feature request?
Open an issue or contribute to the project! 🚀