Last updated: August 2, 2024 | Originally published: October 19, 2022
We recently introduced the Lightstreamer Flutter plugin to respond to the increasing requests dictated by the incredible success that the Flutter framework for creating multi-platform applications has been encountering for some years now.
You can find the plugin in the official package repository for Dart and Flutter apps: https://pub.dev/packages/lightstreamer_flutter_client
What is Flutter?
Flutter is an open-source framework created by Google for building modern, natively compiled, multi-platform applications from a single codebase.
Flutter is powered by Dart, a strongly-typed, object-oriented programming language, optimized for fast apps running on any platform, also created by Google. It has C-style syntax and borrowed concepts from several other languages like Java, C# and JavaScript.
The Lightstreamer Flutter plugin
The Lightstreamer Flutter plugin allows you to add real-time data streaming to your Flutter applications in a very simple way and with little implementation effort.
If you are new to Lightstreamer, it’s a battle-tested solution for delivering real-time to mobile, web, and desktop applications. Its optimized transmission algorithms ensure that data reach the clients with low latency even in the worst network conditions.
The Flutter plugin is a wrapper around our fully-featured Android Client SDK and Swift Client SDK, and works like a bridge linking your application’s Dart code with the native code of the Lightstreamer client libraries for Android and iOS platforms.
Internally, the plugin works by passing messages between the Dart application and the host platform code using platform channels: one MethodChannel and three BasicMessageChannel.
The MethodChannel is used to request actions to the Lightstreamer libraries as per instructions received from the client application, such as opening and closing the connection with the Lightstreamer server and subscribing to and unsubscribing from specific items.
The com.lightstreamer.lightstreamer_flutter_client.status BasicMessageChannel is used to send real-time updates to the client application about the status of the connection with the Lightstreamer server.
The com.lightstreamer.lightstreamer_flutter_client.realtime BasicMessageChannel is used to send real-time updates about the Items the client application is subscribed to.
The com.lightstreamer.lightstreamer_flutter_client.messages BasicMessageChannel is used to send feedback on the status of send message operations requested by the client application.
To go deeper with Flutter platform channels please refer to https://docs.flutter.dev/development/platform-integration/platform-channels.
The plugin is fully open source, and you can follow the project on GitHub.
How it works, a practical example
The plugin contains a practical example showing how to implement bi-directional real-time data transmission with Lightstreamer in a Flutter application.
First of all, you need to import the plugin in the Dart code of your project; the plugin name is lightstreamer_flutter_client. After adding it to your pubspec.yaml file and running flutter packages get, you will be able to import it in your source code files as shown below.
import 'package:lightstreamer_flutter_client/lightstreamer_flutter_client.dart';
To connect to a Lightstreamer Server, a LightstreamerClient object has to be created, configured, and instructed to connect to a specified endpoint. The platform-specific implementation will take care of this when it receives a ‘connect’ command on the MethodChannel. A minimal version of the Dart code that through the ‘connect’ command connects to our public Lightstreamer Demo Server (available at https://push.lightstreamer.com) will look like this:
Future<void> _startRealTime() async {
String currentStatus;
try {
Map<String, String> params = {
"user": "prova1",
"password": "qwerty!",
"forcedTransport": "WS",
"firstRetryMaxDelay": "1500",
"retryDelay": "3850",
"idleTimeout": "5000",
"reconnectTimeout": "7500",
"stalledTimeout": "pioajasol",
"sessionRecoveryTimeout": "12500",
"keepaliveInterval": "5000",
"pollingInterval": "5700",
"reverseHeartbeatInterval": "8890",
"maxBandwidth": "10.1",
"httpExtraHeaders": "{x-lightstreamer: prova1, x-test: abcdef}",
"httpExtraHeadersOnSessionCreationOnly": "true",
// "proxy": "{HTTP,localhost,19540,1,1}"
};
currentStatus = await LightstreamerFlutterClient.connect(
"https://push.lightstreamer.com/", "DEMO", params) ??
'Unknown client session status';
} on PlatformException catch (e) {
currentStatus =
"Problems in starting a session with Lightstreamer: '${e.message}' .";
}
setState(() {
_status = currentStatus;
});
}
The params map contains examples of extra connection properties that will be used to configure the policy settings used to connect to the Lightstreamer Server. Basically, these parameters refer to those in ConnectionOptions and ConnectionDetails classes of the Lightstreamer client libraries.
Once connected to a Lightstreamer server, your app probably wants to receive some real-time updates.
The client needs to subscribe to specific items handled by a Data Adapter deployed on the server side. This can be accomplished by instantiating an object of type Subscription. For more details about Subscription in Lightstreamer see section 3.2 of the Lightstreamer General Concepts documentation. A sample of Dart code that subscribes to three fields (last_price, time, stock_name) of some items of the classic Stock-List example is:
Future<void> _subscribe() async {
String? subId = "";
try {
Map<String, String> params = {
"dataAdapter": "QUOTE_ADAPTER",
"requestedMaxFrequency": "7",
"requestedSnapshot": "yes",
};
subId = await LightstreamerFlutterClient.subscribe(
"MERGE",
mySubController.text.split(","),
"last_price,time,stock_name".split(","),
params);
static_sub_id = subId as String;
LightstreamerFlutterClient.setSubscriptionListener(subId, _values);
} on PlatformException catch (e) {
// ...
}
}
The item names should be provided through the “mySubController” input text of the UI.
The code below shows an example of the implementation of the callback to consume any real-time updates from your subscriptions:
void _values(String item, String fieldName, String fieldValue) {
setState(() {
_lastUpdate =
item + "," + fieldName + "," + fieldValue + "\n" + _lastUpdate;
highlightcolorLast = Colors.yellow;
});
}
Now, your app receives real-time updates from the server but may also want to send back some messages to the Lightstreamer server, to be routed to the back end or maybe to feed a chat conversation with the other connected users. The code below is an example of how to send messages from the client to the Lightstreamer server; in this case, the message to be sent is from an input text of the UI:
Future<void> _sendMessage() async {
try {
await LightstreamerFlutterClient.sendMessageExt(
myController.text, "Sequence1", 5000, _clientmessages, true);
} on PlatformException catch (e) {
// ...
}
}
This is an example of the implementation of the callback to receive feedback on the sendmessage status:
void _clientmessages(String msg) {
setState(() {
_status = msg;
});
}
How to go further
- The plugin is available as a package on pub.dev; just take a look at the project home: pub.dev/packages/lightstreamer_flutter_client.
- To add a package to your Flutter project, see Adding a package dependency to an app.
- Check out this demo for a more complete example than the one embedded in the plugin project of integration between Lightstreamer and Flutter App Development Toolkit.
- For help getting started with Flutter, view Flutter’s online documentation, which offers tutorials, samples, guidance on mobile development, and full API reference.
- For help getting started with Lightstreamer, view Lightstreamer’s online documentation.
- In particular, since there is no specific Lightstreamer API documentation for Dart, you can refer to the Android API Client reference or to the Swift API Client reference.