Getting Started With the iOS, macOS, tvOS and watchOS Client Libraries

The iOS, macOS, tvOS and watchOS Client Libraries, from version 2.0 onwards, follow the Unified Client API model: a common API model used across all Lightstreamer client libraries.

Obtaining a connection and subscribing to an item is a simple and straightforward procedure:

• Create an instance of LSLightstreamerClient.
• Set connection parameters in [LSLightstreamerClient connectionDetails] and [LSLightstreamerClient connectionOptions].
• Start connecting with [LSLightstreamerClient connect] (note that this operation is now asynchronous).
• Create an LSSubscription, set subscription parameters and add an .
• Subscribe and start receiving real-time updates with [LSLightstreamerClient subscribe:].

Mobile Push Notifications

From version 4.0 onwards, iOS, macOS, tvOS and watchOS Client Libraries reintroduce support for Mobile Push Notifications: a specific kind of subscriptions, MPN subscriptions, let you route real-time updates via push notifications, so users can receive updates even when the app is offline or in background mode.

Subscribing to an item via Mobile Push Notifications is as simple as it is for real-time subscriptions:

• Create an instance of LSMPNDevice, using the device token obtained via [UIApplication registerForRemoteNotifications].
• Register the device on the Server with [LSLightstreamerClient registerForMPN:].
• Create an LSMPNSubscription and set subscription parameters, optionally using LSMPNBuilder for the notification format.
• Subscribe and start receiving push notifications with [LSLightstreamerClient subscribeMPN:coalescing:].

Platform Limitations

On watchOS the Client Library does not support the WebSocket transport.

Importing the Framework in Your Project

The client library is packaged as a framework. This both simplifies its inclusion in your project and provides better interoperability with Swift.

To add it to your project proceed as follows:

• In the “Build Phases” section of your Xcode project, add the framework package to the “Link Binary With Libraries” list.

• Import the the framework in your source code with:

  #import <Lightstreamer_iOS_Client/Lightstreamer_iOS_Client.h>

  (where “_iOS_” must be changed accordingly to your target platform).

• If you are developing with Swift, add the import statement above to your bridging header.

Creating an Instance of LSLightstreamerClient

To create an instance of LSLightstreamerClient simply allocate and initialize it.

Objective-C:

LSLightstreamerClient *client= [[LSLightstreamerClient alloc] initWithServerAddress:@"http://myserver.mydomain.com"
                                                                         adapterSet:@"MY_ADAPTER_SET"];

Swift:

let client = LSLightstreamerClient(serverAddress: "http://myserver.mydomain.com",
                                      adapterSet: "MY_ADAPTER_SET")

Connection Parameters and Starting the Connection

You can set additional connection parameters on [LSLightstreamerClient connectionDetails] and [LSLightstreamerClient connectionOptions]. Before connecting you may want to add a delegate. Done this, connect using [LSLightstreamerClient connect].

Objective-C:

client.connectionDetails.user= @"my_user";
[client.connectionDetails setPassword:@"my_password"];
client.connectionOptions.requestedMaxBandwidth= @"100";

[client addDelegate:self];

[client connect];

Swift:

client.connectionDetails.user = "my_user"
client.connectionDetails.setPassword("my_password")
client.connectionOptions.requestedMaxBandwidth = "100"

client.addDelegate(self)

client.connect()

Please note that the [LSLightstreamerClient connect] call is now asynchronous: it will not block the current thread and return immediately. You may safely use it on the main thread. Connection progress will be notified through delegate events.

Listening for Connection Events

Added delegates will receive the [LSClientDelegate client:didChangeStatus:] event each time the connection changes its status.

Objective-C:

- (void) client:(nonnull LSLightstreamerClient *)client didChangeStatus:(nonnull NSString *)status {
    if ([status hasPrefix:@"CONNECTED:"]) {
        // ...
    }
}

Swift:

func client(_ client: LSLightstreamerClient, didChangeStatus status: String) {
    if (status.hasPrefix("CONNECTED")) {
        // ...
    }
}

Once the connection is established you will receive a notification with a status beginning with “CONNECTED:”. See event documentation for more information.

Creating a Subscription

You don’t have to wait for a connection to be established to subscribe. You may safely subscribe in any moment, the subscription will be delivered to the Server as soon as a session has been created.

To create a subscription allocate and initialize an LSSubscription instance and set its properties with the desired values. Once the subscription is set up, subscribe using [LSLightstreamerClient subscribe:].

Objective-C:

LSSubscription *subscription= [[LSSubscription alloc] initWithSubscriptionMode:@"MERGE"];
subscription.items= @[@"my_item_1", @"my_item_2"];
subscription.fields= @[@"my_field_1", @"my_field_2"];
subscription.dataAdapter= @"MY_ADAPTER";
subscription.requestedSnapshot= @"yes";
[subscription addDelegate:self];

[client subscribe:subscription];

Swift:

let subscription = LSSubscription(subscriptionMode: "MERGE")
subscription.items = ["my_item_1", "my_item_2"]
subscription.fields = ["my_field_1", "my_field_2"]
subscription.dataAdapter = "MY_ADAPTER"
subscription.requestedSnapshot = "yes"
subscription.addDelegate(self)

client.subscribe(subscription)

The library keeps memory of active subscriptions and automatically resubscribes them if the connection drops.

Listening for Real-Time Update Events

Subscription delegates will receive the [LSSubscriptionDelegate subscription:didUpdateItem:] event each time an update is received.

Objective-C:

- (void) subscription:(nonnull LSSubscription *)subscription didUpdateItem:(nonnull LSItemUpdate *)itemUpdate {
    NSString *value= [itemUpdate valueWithFieldName:@"my_field_1"];
    // ...
}

Swift:

func subscription(_ subscription: LSSubscription, didUpdateItem itemUpdate: LSItemUpdate) {
    let value = itemUpdate.value(withFieldName: "my_field_1")
    // ...
}

Congratulations! Your subscription with Lightstreamer Server is now set up!

Mobile Push Notifications

The same update events may also be routed via push notifications by using an MPN subscription. Note that Lightstreamer Server needs additional configuration before MPN subscriptions can be used. See the General Concepts document for more information.

First of all, register for remote notifications using common iOS APIs, such as registerForRemoteNotifications on UIApplication. Once you have obtained the device token, create an LSMPNDevice with a string representation of the token and call [LSLightstreamerClient registerForMPN:] to register it also on the Server:

Objective-C:

NSString *token= [[[deviceToken description]
                   stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"<>"]]
                  stringByReplacingOccurrencesOfString:@" " withString:@""];

LSMPNDevice *device= [[LSMPNDevice alloc] initWithDeviceToken:token];
[client registerForMPN:device];

Swift:

let token = deviceToken.description
    .trimmingCharacters(in: CharacterSet(charactersIn: "<>"))
    .replacingOccurrences(of: " ", with: "")

let device = LSMPNDevice(deviceToken: token)
client.register(forMPN: device)

Like previous calls, registration is asynchronous: it will not block the current thread and return immediately. The client will wait until a connection is established before sending the registration.

Once registered, or even while registration is still pending, you can create an instance of LSMPNSubscription. It requires the same properties of a real-time subscription, with the addition of a notification format, expressed as a JSON structure, that describes how push notifications should be formatted.

To build the push notification format’s JSON structure, the LSMPNBuilder object provides methods to help you set each one of the notification fields.

Objective-C:

LSMPNBuilder *builder= [[LSMPNBuilder alloc] init];
[builder body:@"Update received with values: ${my_field_1}, ${my_field_2}"];
[builder sound:@"Default"];
[builder badgeWithString:@"1"];

LSMPNSubscription *mpnSubscription= [[LSMPNSubscription alloc] initWithSubscriptionMode:@"MERGE"];
mpnSubscription.items = @["my_item_1", "my_item_2"]
mpnSubscription.fields = @["my_field_1", "my_field_2"]
mpnSubscription.dataAdapter = @"MY_ADAPTER"
mpnSubscription.notificationFormat= [builder build];

[client subscribeMPN:mpnSubscription coalescing:YES];

Swift:

let builder = LSMPNBuilder()
    .body("Update received with values: ${my_field_1}, ${my_field_2}")
    .sound("Default")
    .badge(with: "1")

let mpnSubscription = LSMPNSubscription(subscriptionMode: "MERGE")
mpnSubscription.items = ["my_item_1", "my_item_2"]
mpnSubscription.fields = ["my_field_1", "my_field_2"]
mpnSubscription.dataAdapter = "MY_ADAPTER"
mpnSubscription.notificationFormat = builder.build()

client.subscribeMPN(mpnSubscription, coalescing: true)

Your MPN subscription is now set up, and the app will start receiving push notifications.

Closing the Connection

To close the connection simply call [LSLightstreamerClient disconnect].

Objective-C:

[client disconnect];

Swift:

client.disconnect()

This will stop real-time updates.

If you also activated an MPN subscription, disconnecting will not stop push notifications: they will continue to be delivered to the app until an unsubscription is performed.