PieSocket Realtime Flutter Client

PieSocket SDK for Flutter written in Dart.

Installation

Add PieSocket into your project.

flutter pub add piesocket_channels

Usage

Import the library

import 'package:piesocket_channels/channels.dart';

Stand-alone Usage

Create a Channel instance as shown below.

Chanel channel = Channel.connect("wss://example.com", true)

channel.listen("system:message", (PieSocketEvent event) {
    log("WebSocket message arrived!");
    print(event.toString());
});

PieSocket's managed WebSocket server

Use following code to create a Channel with PieSocket's managed WebSocket servers.

Get your API key and Cluster ID here: Get API Key

PieSocketOptions options = PieSocketOptions();
options.setClusterId("demo");
options.setApiKey("VCXCEuvhGcBDP7XhiJJUDvR1e1D3eiVjgZ9VRiaV");

PieSocket piesocket = PieSocket(options);
Channel channel = piesocket.join("chat-room");

v4 — multi-channel over one connection

Set version: "4" to share a single WebSocket across every join() call. join() still returns a Channel synchronously, same as v3 — the multiplexing happens in the background:

PieSocketOptions options = PieSocketOptions();
options.setClusterId("demo");
options.setApiKey("VCXCEuvhGcBDP7XhiJJUDvR1e1D3eiVjgZ9VRiaV");
options.setVersion("4");

PieSocket piesocket = PieSocket(options);
Channel chat = piesocket.join("chat-room");     // opens the socket
Channel alerts = piesocket.join("alerts");      // rides the same socket

chat.listen("message", (event) { /* ... */ });
alerts.publishEvent("ping", data: {"at": DateTime.now().toIso8601String()});

Notes for v4:

• join() stays synchronous even for a multiplexed channel — the system::subscribe control frame is sent in the background. Listen for system:connected (primary channel) the same way you would under v3. A secondary channel's subscribe failing (e.g. system::subscribe_error) is not delivered to the channel's own listeners — it's only logged — matching how the JS SDK handles this same case.
• Presence is delta-based. The full roster arrives once; after that Channel's member list is kept in sync from join/leave deltas. Call channel.refreshMembers() to re-sync from the server on demand.
• All v4 system events are double-colon (system::member_joined, system::binary, etc.), unlike v3's single-colon system: events.
• Binary needs no opt-in. Any binary frame arrives as a system::binary event whose data is a base64 string — decode it with base64Decode. To send, call channel.sendBinary(bytes) — a raw binary frame the server re-wraps as system::binary for every other client (JS peers included). Primary channel only; a secondary channel's sendBinary throws.
• publishEvent(event, {data, meta}) sends a structured payload (a Map, List, or primitive) directly, without needing to pre-jsonEncode it into a PieSocketEvent first — use this instead of publish(PieSocketEvent) for anything beyond a plain string, to avoid double-encoding it on the wire.
• notifySelf is connection-wide, not per-channel — if the first join() call is the one that opens the shared socket, every other channel multiplexed onto it also gets that socket's notifySelf setting.
• Unsubscribing the connect-time channel promotes another joined channel to keep the connection alive; a few in-flight frames may be missed during the swap.
• Guarded channels (private- prefix, or forceAuth: true) resolve their JWT from authEndpoint the same as v3, without join() waiting on the fetch — a join() for another room that races in while that fetch is still in flight attaches once it resolves, rather than opening a second shared connection.

PieRTC — WebRTC video/audio rooms (v4 only)

PieRTC is programmable WebRTC over v4 — the Flutter counterpart to piesocket-js's PieRTC. There's no v3 equivalent in this SDK. It depends on flutter_webrtc (already a dependency of this package) — your app still needs to add that package's own camera/microphone permission entries to its AndroidManifest.xml/ Info.plist; this package has no platform folders of its own to put them in.

options.setVersion("4");
PieSocket piesocket = PieSocket(options);

Channel room = piesocket.join(
  "video-room",
  video: true,
  onLocalVideo: (stream, pieRTC) { /* attach to a renderer */ },
  onParticipantJoined: (uuid, stream) { /* attach remote stream */ },
  onParticipantLeft: (uuid) { /* remove remote stream */ },
);

• Pass video: true, audio: true, or pieRTC: true to join() to mark a room as PieRTC — room.pieRTC is attached once the room's connection resolves (may be after join() already returned, same as everything else under v4).
• Signalling uses its own rtc:: namespace (rtc::offer, rtc::answer, rtc::candidate, etc.) — a plain PieSocket relay, no server-side special-casing, so a Flutter and a JS/web client can share the same room.
• room.pieRTC.shareScreen() renegotiates a screen track onto every peer (alongside the camera); stopScreenShare() removes it. Both fire onScreenSharingStopped (with this client's own uuid) and publish rtc::stopped_screen; the SDK also stops if the user ends the share from the OS UI. Zero-config on web, desktop, macOS and iOS (iOS uses in-app ReplayKit capture). Android additionally needs the app to run a foreground service of type mediaProjection while sharing — the simplest way is the flutter_background package (FlutterBackground.enableBackgroundExecution() before shareScreen()), which ships the <service> its manifest needs.

PieSocket is scalable WebSocket API service with following features:

• Authentication
• Private Channels
• Presence Channels
• Publish messages with REST API
• Auto-scalability
• Webhooks
• Analytics
• Authentication
• Upto 60% cost savings

We highly recommend using PieSocket over self hosted WebSocket servers for production applications.

Events

system:connected is the event fired when WebSocket connection is ready, get a full list system messages here: PieSocket System Messages

Documentation

For usage examples and more information, refer to: Official SDK docs