The Kaa notification subsystem enables delivery of messages from the Kaa server to endpoints. The structure of the data that is carried by notifications is defined by the notification schema, which is configured on the Kaa server and built into Kaa endpoints. Please review the Kaa notifications design reference for more details.

This guide will familiarize you with the basic concepts of Kaa notifications and programming of the Kaa notification subsystem. It is assumed that you have already set up either a Kaa Sandbox or a full-blown Kaa cluster and that you have created at least one tenant and one application in Kaa. We also recommend that you review collecting endpoint profiles guide and using endpoint groups before you proceed with this guide.

Configuring Kaa

This section provides guidance on how to configure notifications in Kaa.

Notification schema

The default notification schema installed for Kaa applications is empty. You can configure your own notification schema using the Admin UI or REST API. For the purpose of this guide, we will use a simple notification schema shown in the following code block.

{  
    "type":"record",
    "name":"Notification",
    "namespace":"org.kaaproject.kaa.schema.sample.notification",
    "fields":[  
        {  
            "name":"message",
            "type":"string"
        }
    ]
}

Notification topics

Notifications in Kaa are organized into topics. Each topic may be associated with one or more endpoint groups. To subscribe to a specific notification, endpoints must belong to one or more endpoint groups that are associated with the corresponding notification topic.

Topics can be mandatory or optional. Mandatory topic notifications are delivered in an enforced manner. Optional topics require subscription. It is responsibility of the client code to add notification listeners and subscribe to optional topics.

You can manage notification topics via Admin UI or REST API.

Once created, a notification topic does not impact any endpoints. To deliver notifications to some endpoint, at first you need to assign the topic to an endpoint group containing this endpoint via Admin UI or REST API.

Assuming that you have created custom endpoint groups from the Using endpoint groups guide, it would be logical to create and assign the following topics:

 

 

Endpoint Group Name
Topic idAllAndroid Froyo endpointsAndroid endpointsiOS 8 endpoints3.0 RC1 QA group endpoints
Android notificationsfalsetruetruefalsefalse
iOS 8 notificationsfalsefalsefalsetruefalse
All devices notificationstruefalsefalsefalsefalse

Sending notifications

To send a notification, you can issue the REST API request or use Admin UI.

Coding

This section provides code samples which illustrate practical usage of notifications in Kaa.

Get available topics

To get a list of available topics, do the following:

import org.kaaproject.kaa.client.KaaClient;
import org.kaaproject.kaa.client.KaaDesktop;
import org.kaaproject.kaa.client.notification.NotificationManager;
import org.kaaproject.kaa.common.endpoint.gen.Topic;
...
try {
    KaaDesktop kaa = new KaaDesktop();
    KaaClient kaaClient = kaa.getClient();

    NotificationManager notificationManager = kaaClient.getNotificationManager();
    List<Topic> topics = notificationManager.getTopics();

    for (Topic topic : topics) {
        System.out.printf("Id: %s, name: %s, type: %s"
                , topic.getId(), topic.getName(), topic.getSubscriptionType());
    }
} catch (Exception e) {
    // Handle exception
}
#include <kaa/Kaa.hpp>
#include <kaa/logging/LoggingUtils.hpp>
#include <kaa/notification/INotificationManager.hpp>
...
using namespace kaa;
...
Kaa::init();
IKaaClient& kaaClient = Kaa::getKaaClient();
...
INotificationManager& notificationManager = kaaClient.getNotificationManager();
const auto& topics = notificationManager.getTopics();
for (const auto topic : topics) {
    std::cout << "Id: " << topic.id << ", name: " << topic.name
      << ", type: " << LoggingUtils::TopicSubscriptionTypeToString(
              topic.subscriptionType) << std::endl;
}

Subscribe to updates on available topics

To receive updates for the available topics list, add at least one listener as shown in the following code block (the number of listeners is not limited):

import org.kaaproject.kaa.client.KaaClient;
import org.kaaproject.kaa.client.KaaDesktop;
import org.kaaproject.kaa.client.notification.NotificationManager;
import org.kaaproject.kaa.client.notification.NotificationTopicListListener;
import org.kaaproject.kaa.common.endpoint.gen.Topic;
...
// Add listener
notificationManager.addTopicListListener(new NotificationTopicListListener() {
    @Override
    public void onListUpdated(List<Topic> topics) {
        for (Topic topic : topics) {
            System.out.printf("Id: %s, name: %s, type: %s",
            topic.getId(), topic.getName(), topic.getSubscriptionType());
    }
}});
...
// Remove listener
notificationManager.removeTopicListListener(someOtherTopicUpdateListener);
#include <kaa/Kaa.hpp>
#include <kaa/logging/LoggingUtils.hpp>
#include <kaa/notification/INotificationManager.hpp>
#include <kaa/notification/INotificationTopicListListener.hpp>
...
using namespace kaa;
...
class BasicTopicUpdateListener : public INotificationTopicListListener {
public:
    // Will be called on each update of the topic list
    virtual void onListUpdated(const Topics& newList) {
        for (const auto topic : newList) {
            std::cout << "Id: " << topic.id << ", name: " << topic.name
              << ", type: " << LoggingUtils::TopicSubscriptionTypeToString(
              topic.subscriptionType) << std::endl;
        }
    }
};
...
// Create and add listener to receive updates for available topics
INotificationTopicListListenerPtr topicUpdateListener(new BasicTopicUpdateListener);
notificationManager.addTopicListListener(topicUpdateListener);
...
// Remove listener
notificationManager.removeTopicListListener(topicUpdateListener);

When subscription changes simultaneously for several topics, the following approach is recommended for performance reasons:

import org.kaaproject.kaa.client.notification.NotificationManager;
...
// Do subscription changes with parameter forceSync set to false
notificationManager.subscribeToTopics(Arrays.asList("iOS 8 notifications", "another_optional_topic_id"), false);
notificationManager.unsubscribeFromTopic("boring_optional_topic_id", false);
...
// Add notification listener(s) (optional)
...
// Commit changes
notificationManager.sync();
#include <kaa/notification/INotificationManager.hpp>
...
// Do subscription changes with parameter forceSync set to false
notificationManager.subscribeOnTopics({"iOS 8 notifications", "another_optional_topic_id"}, false);
notificationManager.unsubscribeFromTopic("boring_optional_topic_id", false);
...
// Add notification listener(s) (optional)
...
// Commit changes
notificationManager.sync();

Default notification listener

There are two types of topic notification listeners: the default and topic specific. To receive notifications, add at least one default listener (the number of default listeners is not limited) as shown in the following code block. As a result, the listener will receive notifications from all topics (mandatory topics, as well as optional topics having been subscribed to). 

import org.kaaproject.kaa.client.KaaClient;
import org.kaaproject.kaa.client.KaaDesktop;
import org.kaaproject.kaa.client.notification.AbstractNotificationListener;
import org.kaaproject.kaa.client.notification.NotificationManager;
import org.kaaproject.kaa.schema.sample.notification.Notification;
...
public class BasicNotificationListener extends AbstractNotificationListener<Notification> {
    @Override
    public void onNotification(String topicId, Notification notification) {
        System.out.println("Received a notification: " + notification.toString());
    }
    @Override
    protected Class<Notification> getNotificationClass() {
         return Notification.class;
     }
}
...
BasicNotificationListener listener = new BasicNotificationListener();
// Add listener
notificationManager.addNotificationListener(listener);
...
// Remove listener
notificationManager.removeNotificationListener(listener);
#include <kaa/Kaa.hpp>
#include <kaa/notification/INotificationManager.hpp>
#include <kaa/notification/AbstractNotificationListener.hpp>
#include <kaa/gen/NotificationGen.hpp> // auto-generated header
...
using namespace kaa;
...
class BasicNotificationListener : public AbstractNotificationListener<Notification> {
    virtual void onNotification(const std::string& id, const Notification& notification) {
        std::cout << "Received a notification: " << notification.message << std::endl;
    }
};
...
INotificationListenerPtr globalNotificationListener(new BasicNotificationListener);
// Add listener
notificationManager.addNotificationListener(globalNotificationListener);
...
// Remove listener
notificationManager.removeNotificationListener(globalNotificationListener);

Topic specific notification listener

To receive notifications on some specific topic (either mandatory or optional), you can use topic specific listeners (the number of listeners per topic is not limited) instead of the default listener. To create a topic specific listener, do the following: 

import org.kaaproject.kaa.client.KaaClient;
import org.kaaproject.kaa.client.KaaDesktop;
import org.kaaproject.kaa.client.notification.AbstractNotificationListener;
import org.kaaproject.kaa.client.notification.NotificationManager;
import org.kaaproject.kaa.schema.sample.notification.Notification;
...
BasicNotificationListener specificListener = new BasicNotificationListener();
// Add listener
notificationManager.addNotificationListener("All devices notifications", listener);
...
// Remove listener
notificationManager.removeNotificationListener("All devices notifications", listener);
#include <kaa/Kaa.hpp>
#include <kaa/notification/INotificationManager.hpp>
#include <kaa/notification/AbstractNotificationListener.hpp>
#include <kaa/gen/NotificationGen.hpp> // auto-generated header
...
using namespace kaa;
...
class TopicSpecificNotificationListener : public AbstractNotificationListener<Notification> {
    virtual void onNotification(const std::string& id, const Notification& notification) {
        std::cout << "Weather forecast: " << notification.message << std::endl;
    }
};
...
// Create topic specific listener
INotificationListenerPtr topicSpecificListener(new TopicSpecificNotificationListener);
...
// Add listener
notificationManager.addNotificationListener("All devices notifications", topicSpecificListener);
...
// Remove listener
notificationManager.removeNotificationListener("All devices notifications", topicSpecificListener);

Subscribe to optional topics

To receive notifications on some optional topic, at first subscribe to that topic as shown in the following code block:

import org.kaaproject.kaa.client.KaaClient;
import org.kaaproject.kaa.client.KaaDesktop;
import org.kaaproject.kaa.client.notification.AbstractNotificationListener;
import org.kaaproject.kaa.client.notification.NotificationManager;
...
// Add notification listener(s) (optional)
...
// Subscribe
notificationManager.subscribeToTopic("Android notifications", true);
...
// Unsubscribe. All added listeners will be removed automatically
notificationManager.unsubscribeFromTopic("Android notifications", true);
#include <kaa/Kaa.hpp>
#include <kaa/notification/INotificationManager.hpp>
#include <kaa/notification/AbstractNotificationListener.hpp>
#include <kaa/gen/NotificationGen.hpp> // auto-generated header
...
using namespace kaa;
...
// Add notification listener(s) (optional)
...
// Subscribe
notificationManager.subscribeToTopic("Android notifications", true);
 
// Unsubscribe
notificationManager.unsubscribeFromTopic("Android notifications", true);

You can work with a list of optional topics in a similar way as with a list of available topics.

import org.kaaproject.kaa.client.notification.NotificationManager;
...
// Add notification listener(s) (optional)
...
// Subscribe
notificationManager.subscribeToTopics(Arrays.asList("iOS 8 notifications", "another_optional_topic_id"), true);
...
// Unsubscribe
notificationManager.unsubscribeFromTopics(Arrays.asList("iOS 8 notifications", "another_optional_topic_id"), true);
#include <kaa/notification/INotificationManager.hpp>
...
// Add notification listener(s) (optional)
...
// Subscribe
notificationManager.subscribeToTopics({"iOS 8 notifications", "another_optional_topic_id"}, true);
 
// Unsubscribe
notificationManager.unsubscribeFromTopics({"iOS 8 notifications", "another_optional_topic_id"}, true);

Copyright © 2014, CyberVision, Inc.