Lightstreamer Swift Client SDK

Lightstreamer Swift Client SDK enables any Swift application to communicate bidirectionally with a Lightstreamer Server. The API allows to subscribe to real-time data pushed by the server 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 mobile push notifications (MPN). While real-time subscriptions deliver their updates via the client connection, MPN subscriptions deliver their updates via push notifications, even when the application is offline. They are handled by a special module of the Server, the MPN Module, that keeps them active at all times and continues pushing with no need for a client connection.

This SDK is also meant to replace and evolve all the Client SDKs targeted to the Apple platforms (i.e. iOS, macOS, tvOS, and watchOS Client SDKs).

Requirements

Installation

The package exports two different library flavors: LightstreamerClient (Full) and LightstreamerClientCompact (Compact).

The compact library has no third-party dependencies. However, it doesn’t support decoding subscription fields in JSON Patch format. If a Lightstreamer server sends an update containing JSON Patch–encoded fields, the library will close the active session and notify the client through the ClientDelegate.client(_:didReceiveServerError:withMessage:) method. Additionally, the compact library doesn’t support the ItemUpdate methods valueAsJSONPatchIfAvailable(withFieldName:) and valueAsJSONPatchIfAvailable(withFieldPos:).

The full library has none of these limitations, but it relies on external libraries.

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. With SPM, simply add the Lightstreamer Swift Client SDK to the dependencies array in your Package.swift.

dependencies: [
    .package(url: "https://github.com/Lightstreamer/Lightstreamer-lib-client-swift.git", from: "6.2.1")
]

Both Compact and Full libraries are available via Swift Package Manager.

Normally you’ll want to depend on the LightstreamerClient library (Full):

targets: [
    .target(
        name: "MyTarget",
        dependencies: [ .product(name: "LightstreamerClient", package: "Lightstreamer-lib-client-swift") ])
]

But if you don’t want any dependencies on external libraries, you can depend on the LightstreamerClientCompact library:

targets: [
    .target(
        name: "MyTarget",
        dependencies: [ .product(name: "LightstreamerClientCompact", package: "Lightstreamer-lib-client-swift") ])
]

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. To integrate LightstreamerClient into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'LightstreamerClient'

CocoaPods hosts only the Full (LightstreamerClient) library.

Manually

If you prefer not to use any of the above dependency managers, you can integrate the Lightstreamer Swift Client SDK manually:

• Open Terminal and clone the SDK repository:

  git clone https://github.com/Lightstreamer/Lightstreamer-lib-client-swift.git
  

• In Xcode, choose File > Add Package Dependencies

  • Click Add Local, navigate to the folder where you cloned the SDK, and click Add Package.
    
  • On the next screen, select either LightstreamerClient or LightstreamerClientCompact.

• In the Project Navigator, select your app’s project, then tap your app target under Targets in the sidebar.

• Switch to the General tab.

• Under Frameworks, Libraries, and Embedded Content, verify that LightstreamerClient or LightstreamerClientCompact is listed.

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:

let client = LightstreamerClient(serverAddress: "https://push.lightstreamer.com/", adapterSet: "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):

let items = [ "item1", "item2", "item3" ]
let fields = [ "stock_name", "last_price" ]
let sub = Subscription(subscriptionMode: .MERGE, items: items, fields: fields)
sub.dataAdapter = "QUOTE_ADAPTER"
sub.requestedSnapshot = .yes
client.subscribe(sub)

Before sending the subscription to the server, usually at least one SubscriptionDelegate 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:

class SubscriptionDelegateImpl: SubscriptionDelegate {
    func subscription(_ subscription: Subscription, didUpdateItem itemUpdate: ItemUpdate) {
        print("\(itemUpdate.value(withFieldName: "stock_name")): \(itemUpdate.value(withFieldName: "last_price"))")
    }
    // other methods...
}

sub.addDelegate(SubscriptionDelegateImpl())

Mobile Push Notifications Quickstart

Mobile Push Notifications (MPN) are based on Apple Push Notification Service technology.

Before you can use MPN services, you need to

• register your app with APNs (read carefully the documentation about Setting Up a Remote Notification Server);
• configure the Lightstreamer MPN module (read carefully the section 5 Mobile and Web Push Notifications in the General Concepts guide).

After you have an APNs account, you can create a MPN device, which represents a specific app running on a specific mobile device.

The following snippet shows a sample implementation of the iOS app delegate methods needed to register for remote notifications and receive the corresponding token.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
   // Override point for customization after application launch.       
   UIApplication.shared.registerForRemoteNotifications()
   return true
}

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
   let tokenAsString = deviceToken.map { String(format: "%02x", $0) }.joined()
   let mpnDevice = MPNDevice(deviceToken: tokenAsString)
}

func application(_ application: UIApplication,
            didFailToRegisterForRemoteNotificationsWithError 
                error: Error) {
   // Try again later.
}

To receive notifications, you need to subscribe to a MPN subscription: it contains subscription details and the listener needed to monitor its status. Real-time data is routed via native push notifications.

let builder = MPNBuilder()
builder.body("Stock ${stock_name} is now ${last_price}")
builder.sound("Default")
builder.badge(with: "AUTO")
builder.customData([
    "stock_name" : "${stock_name}",
    "last_price" : "${last_price}"])
let format = builder.build()

let items = [ "item1", "item2", "item3" ]
let fields = [ "stock_name", "last_price" ]
let sub = MPNSubscription(subscriptionMode: .MERGE, items: items, fields: fields)
sub.notificationFormat = format
sub.triggerExpression = "Double.parseDouble($[2])>45.0"
client.subscribeMPN(sub, coalescing: true)

The notification format lets you specify how to format the notification message. It can contain a special syntax that lets you compose the message with the content of the subscription updates (see §5.4.1 of the General Concepts guide ).

The optional trigger expression lets you specify when to send the notification message: it is a boolean expression, in Java language, that when evaluates to true triggers the sending of the notification (see §5.4.2 of the General Concepts guide). If not specified, a notification is sent each time the Data Adapter produces an update.

Logging

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

let loggerProvider = ConsoleLoggerProvider(level: .debug)
LightstreamerClient.setLoggerProvider(loggerProvider)

Compatibility

Compatible with Lightstreamer Server since version 7.4.0.

Documentation

• Live demos

• API Reference

• Lightstreamer General Concepts

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