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:

Promise.resolve(Kinvey.User.getActiveUser())
    .then(function (activeUser) {
        if (activeUser) {
            return activeUser.registerForLiveService();
        }
    })
    .then(() => {
        // success
    })
    .catch(err => {
        // handle error
    });

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

Promise.resolve(Kinvey.User.getActiveUser())
    .then(function (activeUser) {
        if (activeUser) {
            return activeUser.unregisterForLiveService();
        }
    })
    .then(() => {
        // success
    })
    .catch(err => {
        // handle 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 the subscribe() method. This delegate exposes three events that are triggered when messages or errors arrive from the Live Service:

• onMessage 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 KinveyRealtimeStatus object. These objects indicate 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.

const books = Kinvey.DataStore.collection('Books', Kinvey.DataStoreType.Network);

books.subscribe({
  onMessage: (m) => {
    // handle incoming updates of entities in this collection
  },
  onStatus: (s) => {
    // handle status events, which pertain to this collection
  },
  onError: (e) => {
    // handle error events, which pertain to this collection
  }
})
  .then(() => /* success */)
  .catch(e => /* handle error */);

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

const books = Kinvey.DataStore.collection('Books', Kinvey.DataStoreType.Network);
books.unsubscribe();

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.