PieSocket Channels - Flutter SDK

PieSocket offers Channels Dart SDK for easy integration into cross-platform Flutter projects.

This SDK is a Dart Package and it can be used as a standalone WebSocket client in any Dart project.

Channels SDK implements auto-reconnections among other best WebSocket practices.

Getting started

Create a Flutter project and follow the steps below to add the SDK in your project.

Installation

Add PieSocket Channels into your project.

flutter pub add piesocket_channels

Usage

You are now ready to import PieSocket Channels in your application.

import 'package:piesocket_channels/channels.dart';

Initialize PieSocket

Define your API Key, Cluster ID and pass it to PieSocket class.

Get your API key and Cluster ID here: Create PieSocket account

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

PieSocket piesocket = PieSocket(options);

To see the full list of available configuration options,

See: PieSocket Configuration Options

A setter methtod is available on the PieSocketOptions class for all the options listed in the linked page.

Subscribe to a Channel

Subscribe to a Channel with PieSocket's managed WebSocket server.

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

Here chat-room is what we call a roomId. You need this ID to publish messages from your server.

See: How to chose a Room ID

Listen to an event

You can attach multiple listeners to an event by using the code below multiple times. All listeners will be called when the event is fired.

room.listen("new_message", (PieSocketEvent event) {
    print(event.toString());
});

There are system events like system:connected, system:member_joined, etc. You can listen to these events to build a beautiful realtime-connected experience.

See a list of all system events here: All system events

Remove an event listener

.listen method returns a String ID for every registered listener. You can use the same listener ID to remove listener of an event.

room.removeListener("new_message", listenerId);

Remove all event listeners

To stop listening for an event, and remove all of the listeners, use the following method.

room.removeAllListeners("new_message");

Publish Events

Use the publish method to publish an event from the client itself.

You must enable client-to-client communication setting for the Channels cluster to make this work, in new clusters it is enabled by default.

channel.listen("system:connected", (PieSocketEvent event) {
    //Channel is connected

    //Create an event
    PieSocketEvent newMessage = PieSocketEvent("new_message");
    newMessage.setData("Hello World!");

    //Publish event
    room.publish(newMessage);
});

Developers usually publish events from the backend-server.

See: How to publish events from server

Room members

You can see who is in a room, get system:member_joined to fire and track when people leave by enabling Presence features in a room.

options.setPresence(true);

List all members

To get a list containing all members of the room, use the following code

List members = room.getAllMembers();

Same is possible from your server, see the REST API section

Get current member

To get information about the current member, use following code

var member = room.getCurrentMember();

User Authentication

PieSocket lets you block un-authorized connections and identify users with the help of JWT authentication tokens.

To learn more, like how to set an User ID, what are Private Channels, etc.

See the: Authentication guide

Set Authentication Endpoint

Set an Authentication URL which generates and responds with JWT tokens. Channels SDK makes a POST request to this URL with Channel information, everytime an user tries to connect to a private room.

 options.setAuthEndpoint("https://mywebsite.com/generate-jwt")

Optional, add headers to the authEndpoint request

var headers = {"Content-type": "application/json",  "Accept": "application/json"};

options.setAuthHeaders(headers);

The URL should respond with following JSON on successful authentications.

{"auth":"*************"}

Set JWT Token

To skip the authEndpoint call, and set the JWT yourself, use following method.

options.setJwt("*****************");

Leave a Channel

To unsubscribe from a Channel and close the ongoing WebSocket connection, use following code.

All event listeners on this Channel will be removed.

piesocket.leave("chat-room")

Stand-alone Usage

You can use this SDK to connect to third party WebSocket servers. Skip, the configuration part and create a Channel instance as shown below.

{danger} You will miss out on features like Private Channels, Presence Channels, Multiple Rooms, etc. Stick to PieSocket's managed WebSockets to save upto 60% costs.

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

Help

Facing difficulties? Use the chat box on the bottom-right corner of this page to reach us.