OddSockets Flutter SDK

Official Flutter/Dart SDK for OddSockets real-time messaging platform

Flutter Ready Dart/Flutter Cross-platform High Performance Stream-based

Overview & Features

The OddSockets Flutter SDK provides a powerful, easy-to-use interface for real-time messaging across all Flutter-supported platforms including iOS, Android, Web, Windows, macOS, and Linux.

Cross-platform

Works on iOS, Android, Web, Windows, macOS, and Linux with the same API.

Stream-based

Native Dart Stream integration for reactive programming with StreamBuilder.

BLoC Integration

Built-in support for flutter_bloc state management pattern.

High Performance

Optimized for low latency with efficient WebSocket connections and smart routing.

Battery Optimized

Mobile-optimized reconnection logic and background handling for better battery life.

Type Safety

Full Dart type safety with comprehensive error handling and recovery.

Installation

yaml
dependencies:
  oddsockets_flutter: ^1.0.0
bash
flutter pub add oddsockets_flutter
bash
dart pub add oddsockets_flutter

Quick Start

Basic Usage

dart
import 'package:oddsockets_flutter/oddsockets_flutter.dart';

final client = OddSocketsClient(
  OddSocketsConfig.defaultConfig('ak_live_1234567890abcdef'),
);

final channel = client.channel('my-channel');

// Subscribe to messages
await channel.subscribe((message) {
  print('Received: ${message.data}');
});

// Publish a message
await channel.publish('Hello, Flutter!');

StreamBuilder Integration

dart
class ChatWidget extends StatefulWidget {
  @override
  _ChatWidgetState createState() => _ChatWidgetState();
}

class _ChatWidgetState extends State<ChatWidget> {
  late OddSocketsClient client;
  late OddSocketsChannel channel;

  @override
  void initState() {
    super.initState();
    client = OddSocketsClient(
      OddSocketsConfig.defaultConfig('ak_live_1234567890abcdef'),
    );
    channel = client.channel('chat-room');
  }

  @override
  Widget build(BuildContext context) {
    return StreamBuilder<Message>(
      stream: channel.messageStream,
      builder: (context, snapshot) {
        if (snapshot.hasData) {
          return Text('Latest: ${snapshot.data!.data}');
        }
        return Text('Waiting for messages...');
      },
    );
  }
}

Configuration Builder

dart
final config = OddSocketsConfig.builder('ak_live_1234567890abcdef')
    .mobile() // Mobile-optimized settings
    .heartbeatInterval(Duration(seconds: 45))
    .reconnectAttempts(10)
    .build();

final client = OddSocketsClient(config);

Configuration

Client Options

dart
final client = OddSocketsClient(
  OddSocketsConfig(
    apiKey: 'your-api-key',           // Required: Your OddSockets API key
    userId: 'user-id',                // Optional: User identifier
    autoConnect: true,                // Optional: Auto-connect on creation
    reconnectAttempts: 5,             // Optional: Max reconnection attempts
    heartbeatInterval: Duration(seconds: 30), // Optional: Heartbeat interval
  ),
);

Channel Options

dart
await channel.subscribe(callback, SubscribeOptions(
  enablePresence: true,             // Enable presence tracking
  retainHistory: true,              // Retain message history
  filterExpression: 'user.premium == true', // Message filter expression
));

await channel.publish(message, PublishOptions(
  ttl: Duration(hours: 1),          // Time to live
  metadata: {'priority': 'high'},   // Additional metadata
  storeInHistory: true,             // Store in message history
));

Examples

Explore comprehensive examples demonstrating the OddSockets Flutter SDK in action:

Performance & Compatibility

OddSockets Flutter SDK delivers superior performance with broad platform compatibility:

<50ms
Latency
99.9%
Uptime
32KB
Max Message
1M+
Messages/sec

Flutter Support

  • Flutter 3.0+ (2022)
  • Dart 2.17+ (2022)
  • Null Safety
  • Sound Type System

Platform Support

  • iOS 11+ / Android 21+
  • Web (Chrome, Firefox, Safari)
  • Windows 10+ / macOS 10.14+
  • Linux (Ubuntu 18.04+)

Platform Integrations

The OddSockets Flutter SDK works seamlessly across all Flutter-supported platforms. Here are examples showing platform-specific optimizations:

Mobile (iOS/Android)

dart
class MobileChatApp extends StatefulWidget {
  @override
  _MobileChatAppState createState() => _MobileChatAppState();
}

class _MobileChatAppState extends State<MobileChatApp> with WidgetsBindingObserver {
  late OddSocketsClient client;
  late OddSocketsChannel channel;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    
    // Mobile-optimized configuration
    final config = OddSocketsConfig.builder('ak_live_1234567890abcdef')
        .mobile() // Optimizes for battery life and mobile networks
        .build();
    
    client = OddSocketsClient(config);
    channel = client.channel('mobile-chat');
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    super.didChangeAppLifecycleState(state);
    
    // Handle app lifecycle for better battery management
    switch (state) {
      case AppLifecycleState.paused:
        // Reduce heartbeat frequency when app is backgrounded
        break;
      case AppLifecycleState.resumed:
        // Restore normal operation when app is foregrounded
        break;
      default:
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Mobile Chat')),
      body: StreamBuilder<Message>(
        stream: channel.messageStream,
        builder: (context, snapshot) {
          // Your chat UI here
          return Container();
        },
      ),
    );
  }
}

Web

dart
import 'dart:html' as html;

class WebChatApp extends StatefulWidget {
  @override
  _WebChatAppState createState() => _WebChatAppState();
}

class _WebChatAppState extends State<WebChatApp> {
  late OddSocketsClient client;
  late OddSocketsChannel channel;

  @override
  void initState() {
    super.initState();
    
    // Web-optimized configuration
    final config = OddSocketsConfig.builder('ak_live_1234567890abcdef')
        .web() // Optimizes for web browsers
        .build();
    
    client = OddSocketsClient(config);
    channel = client.channel('web-chat');
    
    // Handle browser tab visibility for better performance
    html.document.addEventListener('visibilitychange', (event) {
      if (html.document.hidden ?? false) {
        // Reduce activity when tab is not visible
      } else {
        // Resume normal activity when tab becomes visible
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Web Chat')),
        body: StreamBuilder<Message>(
          stream: channel.messageStream,
          builder: (context, snapshot) {
            // Your web chat UI here
            return Container();
          },
        ),
      ),
    );
  }
}

Desktop (Windows/macOS/Linux)

dart
class DesktopChatApp extends StatefulWidget {
  @override
  _DesktopChatAppState createState() => _DesktopChatAppState();
}

class _DesktopChatAppState extends State<DesktopChatApp> {
  late OddSocketsClient client;
  late OddSocketsChannel channel;

  @override
  void initState() {
    super.initState();
    
    // Desktop-optimized configuration
    final config = OddSocketsConfig.builder('ak_live_1234567890abcdef')
        .desktop() // Optimizes for desktop environments
        .build();
    
    client = OddSocketsClient(config);
    channel = client.channel('desktop-chat');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('Desktop Chat')),
        body: Row(
          children: [
            // Sidebar for desktop layout
            Container(
              width: 250,
              child: StreamBuilder<PresenceInfo?>(
                stream: channel.presenceStream,
                builder: (context, snapshot) {
                  // User list sidebar
                  return Container();
                },
              ),
            ),
            // Main chat area
            Expanded(
              child: StreamBuilder<Message>(
                stream: channel.messageStream,
                builder: (context, snapshot) {
                  // Your desktop chat UI here
                  return Container();
                },
              ),
            ),
          ],
        ),
      ),
    );
  }
}

BLoC Integration

dart
// Events
abstract class ChatEvent {}
class ChatStarted extends ChatEvent {}
class MessageReceived extends ChatEvent {
  final Message message;
  MessageReceived(this.message);
}
class MessageSent extends ChatEvent {
  final String content;
  MessageSent(this.content);
}

// States
abstract class ChatState {}
class ChatInitial extends ChatState {}
class ChatConnected extends ChatState {
  final List<Message> messages;
  ChatConnected(this.messages);
}

// BLoC
class ChatBloc extends Bloc<ChatEvent, ChatState> {
  final OddSocketsClient _client;
  late final OddSocketsChannel _channel;
  late StreamSubscription _messageSubscription;

  ChatBloc(this._client) : super(ChatInitial()) {
    _channel = _client.channel('chat-room');
    
    on<ChatStarted>(_onChatStarted);
    on<MessageReceived>(_onMessageReceived);
    on<MessageSent>(_onMessageSent);
  }

  Future<void> _onChatStarted(ChatStarted event, Emitter<ChatState> emit) async {
    await _channel.subscribe((message) {
      add(MessageReceived(message));
    });
    
    emit(ChatConnected([]));
  }

  void _onMessageReceived(MessageReceived event, Emitter<ChatState> emit) {
    if (state is ChatConnected) {
      final currentState = state as ChatConnected;
      emit(ChatConnected([...currentState.messages, event.message]));
    }
  }

  Future<void> _onMessageSent(MessageSent event, Emitter<ChatState> emit) async {
    await _channel.publish(event.content);
  }

  @override
  Future<void> close() {
    _messageSubscription.cancel();
    _client.dispose();
    return super.close();
  }
}