SocketX Client for Flutter

Introduction

This Flutter plugin provides the Eclypses SocketX Client for iOS and Android. It enables secure, real-time WebSocket communication between your Flutter app and SocketX servers with automatic MTE encryption. You must have access to a SocketX server instance. More Info

Purpose of SocketX:

• Secure WebSocket communication with MTE encryption
• Real-time bidirectional messaging
• Room-based communication patterns
• Binary and text protocol support

Comprehensive Documentation

This guide provides a quick-start for experienced developers. For detailed examples, troubleshooting, and in-depth explanations, see the complete README on GitHub.

Prerequisites

• Flutter SDK (stable channel)
• iOS 14.0+ / Android SDK 26+
• Xcode 14.0+ (for iOS Swift Package Manager support)
• Access to a SocketX server instance

Installation

Add to your pubspec.yaml:

dependencies:
  socketx_client:
    git:
      url: https://github.com/Eclypses/socketx-client-flutter.git

Run flutter pub get.

iOS Setup (Swift Package Manager)

The plugin uses Swift Package Manager (SPM) to manage the iOS SocketX dependency. The dependency is automatically resolved from the plugin's Package.swift file.

Ensure your iOS deployment target is set to 14.0 or higher:

1. Open ios/Runner.xcworkspace in Xcode
2. Select the Runner project → Runner target → General tab
3. Set "Minimum Deployments" to iOS 14.0 or higher

No additional manual configuration is required for SPM.

Android Setup

Ensure minSdk is set to 26 or higher in android/app/build.gradle.kts.

Setup

Import and initialize the plugin:

import 'package:socketx_client/socketx_client.dart';

class YourClass {
  final _socketX = SocketXClient();

  void init() {
    // Set up event listeners
    _socketX.onConnected.listen((_) {
      print('Connected to SocketX server');
    });

    _socketX.onMessage.listen((message) {
      print('Received: $message');
      // Handle text messages
    });

    _socketX.onBinaryMessage.listen((data) {
      print('Received ${data.length} bytes');
      // Handle binary data
    });

    _socketX.onError.listen((error) {
      print('Error: ${error.message}');
      // Handle errors
    });
  }
}

Usage

Connect to WebSocket

try {
  await _socketX.connect(
    url: 'wss://your-socketx-server.com/room',
    headers: {'Authorization': 'Bearer token'},
  );
  // Connection established - onConnected stream will fire
} catch (e) {
  print('Connection failed: $e');
}

Send Text Message

_socketX.send(text: 'Hello, SocketX!');

Send Binary Data

final binaryData = Uint8List.fromList([0x01, 0x02, 0x03, 0xFF]);
_socketX.send(binary: binaryData);

Handle Multiple Rooms

class MultiRoomChat {
  final _lobbyClient = SocketXClient();
  final _gameClient = SocketXClient();

  Future<void> connect() async {
    await _lobbyClient.connect(url: 'wss://server.com/lobby');
    await _gameClient.connect(url: 'wss://server.com/game');
  }

  void sendToLobby(String msg) => _lobbyClient.send(text: msg);
  void sendToGame(String msg) => _gameClient.send(text: msg);
}

Auto-Reconnection

int _reconnectAttempts = 0;
const _maxRetries = 5;

void setupAutoReconnect() {
  _socketX.onError.listen((error) {
    if (error.type == 'connection' && _reconnectAttempts < _maxRetries) {
      final delay = Duration(seconds: pow(2, _reconnectAttempts).toInt());
      Future.delayed(delay, () {
        _reconnectAttempts++;
        _socketX.connect(url: 'wss://server.com');
      });
    }
  });

  _socketX.onConnected.listen((_) {
    _reconnectAttempts = 0; // Reset on successful connection
  });
}

Disconnect

await _socketX.disconnect();

API Reference

See the complete README documentation for full API details. Key classes:

• SocketXClient: Main entry point for WebSocket connections
  • connect(url, headers): Establish WebSocket connection
  • disconnect(): Close connection gracefully
  • send({text, binary}): Send messages
  • onConnected: Stream for connection events
  • onMessage: Stream for text messages
  • onBinaryMessage: Stream for binary data
  • onError: Stream for error handling
• SocketXError: Error wrapper with type and message

Support

Email: info@eclypses.com
Web: www.eclypses.com

Additional Resources

• GitHub Repository – Source code and comprehensive examples
• Complete README – Detailed documentation with troubleshooting
• Release Notes – Latest updates and changes

---

All trademarks of Eclypses Inc. may not be used without Eclypses Inc.'s prior written consent.