Web Client 9.0.0-beta.4

Lightstreamer Web Client 9.0.0-beta.4 API Reference

Summary

Introduction

Lightstreamer Web Client SDK enables any JavaScript application running in a web browser to communicate bidirectionally with a Lightstreamer Server. The API allows to subscribe to real-time data pushed by the server, to display such data, and to send any message to the server.

The library offers automatic recovery from connection failures, automatic selection of the best available transport, and full decoupling of subscription and connection operations. It is responsible of forwarding the subscriptions to the Server and re-forwarding all the subscriptions whenever the connection is broken and then reopened.

The library also offers support for Web Push Notifications on Apple platforms via Apple Push Notification Service (APNs) and Google platforms via Firebase Cloud Messaging (FCM). With Web Push, subscriptions deliver their updates via push notifications even when the application is offline (see the Stock-List Demos with Web Push Notifications).

The library is distributed through the npm service. It supports module bundlers like Webpack, Rollup.js and Browserify; further it is compatible with an AMD loader like Require.js, and it can be accessed through global variables.

Depending on the chosen deployment architecture, on the browser in use, and on some configuration parameters, the Web Client Library will try to connect to the designated Lightstreamer Server in the best possible way. A Deployment Configuration Matrix is available online, which summarizes the client-side combinations and the instructions on which settings to use to guarantee that an optimal connection is established. See the legend on the second tab to learn about the meaning of each column.

More introductory notes are provided in the Web Client Guide document that can be found in the Github project. Look for the relevant tag.

The JavaScript library can be available depending on Edition and License Type. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Note the following documentation convention:

Function arguments qualified as <optional> can be omitted only if not followed by further arguments. In some cases, arguments that can be omitted (subject to the same restriction) may not be qualified as <optional>, but their optionality will be clear from the description.

Installing

You can install the package lightstreamer-client-web using npm

npm install lightstreamer-client-web

The package contains a variety of library formats to suit the needs of the major development flavors. It supports module bundlers like Webpack, Rollup.js and Browserify; it is compatible with an AMD loader like Require.js, and it can be accessed through global variables. For further details see the README.

Quickstart

To connect to a Lightstreamer Server, a LightstreamerClient object has to be created, configured, and instructed to connect to the Lightstreamer Server. A minimal version of the code that creates a LightstreamerClient and connects to the Lightstreamer Server on https://push.lightstreamer.com will look like this:

var client = new LightstreamerClient("https://push.lightstreamer.com/","DEMO");
client.connect();

For each subscription to be subscribed to a Lightstreamer Server a Subscription instance is needed. A simple Subscription containing three items and two fields to be subscribed in MERGE mode is easily created (see Lightstreamer General Concepts):

var sub = new Ls.Subscription("MERGE",["item1","item2","item3"],["stock_name","last_price"]);
sub.setDataAdapter("QUOTE_ADAPTER");
sub.setRequestedSnapshot("yes");
client.subscribe(sub);

Before sending the subscription to the server, usually at least one SubscriptionListener is attached to the Subscription instance in order to consume the real-time updates. The following code shows the values of the fields stock_name and last_price each time a new update is received for the subscription:

sub.addListener({
    onItemUpdate: function(obj) {
      console.log(obj.getValue("stock_name") + ": " + obj.getValue("last_price"));
    }
});

Below is the complete JavaScript code embedded in an HTML page:

<html>
<head>
    <script src="https://unpkg.com/lightstreamer-client-web/lightstreamer.min.js"></script>
    <script>
    var client = new Ls.LightstreamerClient("https://push.lightstreamer.com","DEMO");  
    client.connect();
    
    var sub = new Ls.Subscription("MERGE",["item1","item2","item3"],["stock_name","last_price"]);
    sub.setDataAdapter("QUOTE_ADAPTER");
    sub.setRequestedSnapshot("yes");
    sub.addListener({
        onItemUpdate: function(obj) {
          console.log(obj.getValue("stock_name") + ": " + obj.getValue("last_price"));
        }
    });
    client.subscribe(sub);
    </script>
</head>
<body>
</body>
</html>

Logging

To enable the internal client logger, create a LoggerProvider and set it as the default provider of LightstreamerClient.

var loggerProvider = new ConsoleLoggerProvider(ConsoleLogLevel.DEBUG);
LightstreamerClient.setLoggerProvider(loggerProvider);

Compatibility

The library requires Server 7.3.2.

Documentation

Support

For questions and support please use the Official Forum. The issue list of this page is exclusively for bug reports and feature requests.

License

Apache 2.0