Live Service

The Kinvey Live Service enables an event-driven way to receive data live on your device.

Normally, when an entity has been updated in a Kinvey collection, a user would have to perform a Find operation to retrieve the latest data. Using the Kinvey Live Service, updates from the Kinvey backend can be instead pushed down to the device.

Enabling Live Service

Kinvey Live Service must be enabled on a per-app basis before it can be used. Take the following steps to enable it.

1. Open the Kinvey Console and click your app.

   The app settings screen opens.

2. In the sidebar, click the Live Service tab.

   

3. On the Live Service settings page, toggle the switch to On to enable the service for your app. This allows all environments within this app to use Live Service.

   

If, at any point, you want to disable Live Service for your app, navigate back to the Live Service settings page and toggle the switch to Off.

Registering for Live Service

After you enable Live Service, you can start using it in you app code. After you have a user logged in to your app, call the following code to request Live Service:

guard let user = Kinvey.sharedClient.activeUser else {
    return
}
user.registerForRealtime() {
    switch $0 {
    case .success:
        print("register for realtime succeed")
    case .failure(let error):
        // handle registration errors
        print(error)
    }
}

Similarly, to stop using Live Service, unregister the user as shown below.

guard let user = Kinvey.sharedClient.activeUser else {
    return
}
user.unregisterForRealtime() {
    switch $0 {
    case .success:
        print("unregister for realtime succeed")
    case .failure(let error):
        // handle unregistration errors
        print(error)
    }
}

Subscribing to a Collection

An app can subscribe to one or more Kinvey collections. Subscribing to a collection allows the app to receive a live feed of all entities that are created or updated in the collection.

On the DataStore corresponding to a collection, call subscribe and provide a handler. The handler exposes four actions that are triggered when messages or errors arrive from the Live Service.

• subscription: notifies when the subscription is ready and waiting for incoming messages
• onNext receives entities added or updated in this collection
• onStatus receives informational messages regarding Live Service
• onError receives any errors that occur during communication with Live Service

A message about a create or an update represents the created or updated entity in it's entirety. The message does not come with additional information differentiating the type.

Status updates arrive on the onStatus method as a RealtimeStatus enumeration. This enumeration indicates informational events such as connecting to or disconnecting from Live Service.

Whereas the onStatus callback gets called with informational updates, the onError method gets invoked when an exception has occurred with the Kinvey Live Service. These errors include events such as not being able to subscribe to Live Service or permission errors when attempting to use Live Service.

let dataStore = try DataStore<Book>.collection()

dataStore.subscribe(subscription: {
    // handle subscription, waiting for incoming messages
}, onNext: { result in
    // handle new real-time messages
}, onStatus: { status in
    // handle subscription status changes
}, onError: { error in
    // handle errors
})

To stop receiving live updates from a collection, simply unsubscribe.

dataStore.unsubscribe() {
    switch $0 {
    case .success:
        print("unsubscribe succeed")
    case .failure(let error):
        // handle errors
        print(error)
    }
}

Current Limitations

Kinvey Live Service is subject to the following limitations:

• Limitations:
  • Message size—Entities that are larger than 32 KB are not sent through the Kinvey Live Service.
  • Business Logic—Data changes originating from Business Logic do not trigger any of the collection subscription events.
• Features not yet implemented:
  • Collection Subscription—Notifications about deleted entities.
  • Offline and Caching—Data received from Live Service is not cached neither persisted for offline use in Local Storage.