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:

client.getActiveUser().registerLiveService(new KinveyClientCallback<Void>() {
   @Override
   public void onSuccess(Void o) {
       // handle success
   }

   @Override
   public void onFailure(Throwable throwable) {
       // handle failure
   }
});

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

client.getActiveUser().unregisterLiveService(new KinveyClientCallback<Void>() {
       @Override
       public void onSuccess(Void o) {
           // handle success
       }

       @Override
       public void onFailure(Throwable throwable) {
           // handle failure
       }
   });

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.

• 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 KinveyLiveServiceStatus 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.

DataStore<Book> store = DataStore.collection(
            "books",
            Book.class,
            StoreType.NETWORK,
            client);

KinveyDataStoreLiveServiceCallback<Book> liveServiceCallback = new  KinveyDataStoreLiveServiceCallback<Book>() {
    @Override
    public void onNext(Book next) {
        // handle new live service messages
    }

    @Override
    public void onError(Exception e) {
       // handle errors
    }

    @Override
    public void onStatus(KinveyLiveServiceStatus status) {
       // handle subscription status changes
    }
});



store.subscribe(liveServcieCallback, new KinveyClientCallback<Boolean>() {
   @Override
   public void onSuccess(Boolean aBoolean) {
       // handle success
   }

   @Override
   public void onFailure(Throwable throwable) {
       // handle faliure
   }
});

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

store.unsubscribe(new KinveyClientCallback<Void>() {
       @Override
       public void onSuccess(Void aVoid) {
           // handle success
       }

       @Override
       public void onFailure(Throwable throwable) {
           // handle faliure
       }
   });

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.