Push to User Notification

The Push to User notification feature provides a means to push messages using a publisher-subscriber model. This feature will let you and your app users quickly send messages to other users while providing a way to scope to which the messages are sent

This topic explains the functionality of the Push to User notification. For the implementation, see the following topics:

Base URI

The base URI for accesing the topic is as follows:

Appication Scope: https://api-jp.kii.com/api/apps/<APP_ID>/topics/<TOPIC_NAME>
Gropu Scope: https://api-jp.kii.com/api/apps/<APP_ID>/groups/<GROUP_ID>/topics/<TOPIC_NAME>
User Scope: https://api-jp.kii.com/api/apps/<APP_ID>/users/<USER_ID>/topics/<TOPIC_NAME>

How Push to User notification works

Kii Push to User notifications work as follows:

A user or the administrator creates a new topic.
Other users subscribe to this topic.
A user or the administrator sends a push message to the topic.
A push notification is sent to all the subscribers.

You can also use this feature to send a push message to yourself (e.g. achieving multiple device sync).

The topic acts as a channel for sending push messages. Users who have an interest in a certain topic can get the messages sent to the topic by subscribing to it.

If multiple users are subscribing to a topic, a push message sent to this topic will be delivered to all of them. If a user owns multiple devices, the push message will be sent to all devices. In the above example, sending a push message to the topic triggers two push messages sent to the users' devices. The push message, of course, is not delivered to a device of a user who is not subscribing to the topic.

Topics and scopes

A topic can have one of the following scopes.

Application Scope: The topic belongs to an application (application developer).
Group Scope: The topic belongs to a specific user group.
User scope: The topic belongs to a specific user.

The topic scope is very similar to the bucket scope explained in Scopes and Access Privileges in the Getting Started. As illustrated in the next figure, buckets and topics can co-exist in the same scope instance.

You can subscribe to a thing scope topic too.

How to create topics and send messages depend on the scope of the topic:

For an application scope topic, you will use the REST API to create the topic. Sending a message to the topic is done via the developer portal. These actions require the app admin privilege.
For a group or user scope, you will use the Kii Cloud SDK to create the topic and to send a message to the topic.

Push to User flow

Here is an example of subscribing to a group-scope topic and sending a push notification to the topic. There are two groups with some topics. Three users are going to leverage the Push to User notification feature.

Creating topics

You can create a topic in an application, group or user scope. You can put any name to the topic. The topic is referred with this name in your code.

In the example, we are creating group scope topics. As you can see, you can create different topics per group.
Subscribing topics

By subscribing to a topic, you bind the current user with the topic. The user must be logging in when he subscribes a topic.

As shown in the example, a user can subscribe to multiple topics at the same time.

A user needs to have the subscription privilege on the topic to subscribe to. See Topic Access Control for more details.
Sending push messages

To send a push message, you send a request to the target topic via the client SDK API or developer portal.

Upon sending the message, you can select the target push notification network and the target environment (development or production). You can also set some information in the push payload.

A user needs to have the message sending privilege on the topic to request the push. See Topic Access Control for more details.
Receiving push messages

Push messages will be sent to all devices owned by topic subscribers via the push notification network.

The push notification is handled per topic instance. In this example, the push messages are sent only to the topic instance "Received" in the group "Sales Div." and it does not affect the topic instance "Received" in the group "Tennis Club".

Push to User sample scenarios

Typical scenario for each scope

Let us explore three typical scenarios that are achievable with each topic scope.

Application scope

One good scenario for using the application scope topic is to create a channel for broadcasting messages to all application users.

The basic steps would be as follows:

Create an app-scope topic as an app admin.
Have the application subscribed to this topic when it's launched for the first time.
We're all set! When you want to send a broadcast message you can do it in the developer portal: just select the topic and send the message to the topic.

Group scope

A group scope topic is convenient for creating a channel for group messaging. Your application can dynamically create such channels so as to let your users enjoy group messaging.

The basic steps would be as follows:

An app user creates a user group and invites some friends to the group (See Managing Groups for more information).
The app user creates a new topic that belongs to this group.
The user asks the group members to subscribe to this topic.
Done! Any group member can now push a message to the group by sending a message to the topic.

User scope

A user scope topic is usable to push private messages to all devices. For example, you might want to allow a user to push TODO items from one device. These items will be pushed to all devices belonging to the user so that the TODO list can be checked on any of them.

The basic steps would be as follows:

An application user creates a user-scope topic.
The application user then subscribes to this topic on all owned devices.
The application user installs all devices to receive the push notification.
Done! When the user pushes a message to this topic, it will be pushed to all subscribed devices.

Using topics

User segmentation in push notification

By leveraging topics, you can send push notifications to the specific user segment. For example, you can create topics that represent the user's gender. You can then send push messages to the appropriate topic so as to selectively deliver the messages to the designated users (e.g., sending sales information only to female users).

In practice, this is an application of the application scope scenario mentioned in the previous section. You will first create topics for each user segment. Then, you will implement your mobile app so that it will subscribe to the appropriate topic(s) upon its initialization. Once you've done these, you can send push messages to the target user segment by sending them to the corresponding topic.

In this method, the number of topics you need to create is the number of user segments. Suppose that you want to define the user segments based on their ages (below 20s, 20s, 30s, 40s, 50s, and over 60s). You will need to create one topic for each segment. When you want to send push messages to all users over 50, you will be sending the messages to two topics, one for 50s and another for over 60s.

Should you need to define more fine-grained segments with multiple criteria, youneed to define more topics, like "20s (male)", "20s (female)", and so on, then specify multiple topics with the And operator to send push messages.

Changing a topic's ACL

The default permissions assigned to a topic are determined by its scope. See Topic Access Control to learn more.

Sometimes we want to customize the users who can subscribe and/or send push messages to a topic. You can change topic permissions from your mobile app.

Here are some examples:

Permitting read-only access to all authenticated users for a group-scope topic

Suppose you have a group-scope topic for group messaging. Now you want to invite any authenticated users (i.e. application users who are not the group members) to the topic as read-only members.

This can be done by letting the topic creator add an ACL entry that represents "allowing any authenticated users to subscribe to the topic".
Permitting full access to a certain user for a group-scope topic

Following the previous example, let us now suppose that you want to invite a user (Alice) to the group-scope topic as an administrator. Here we want her to have full access to the topic (i.e. allowing her to subscribe and send push messages to the topic) like the group members.

This can be done by letting the topic creator add ACL entries that represent "allowing Alice to subscribe to the topic" and "allowing Alice to send push messages to the topic".
Sharing a user-scope topic among a group

Suppose we have a user-scope topic for managing a private TODO list. Now the owner of this scope wants to share the TODO list with their family members. The owner already has created a group (MyFamily) for his family members, so we want to permit read-only access to this group.

This can be done by letting the scope creator add an ACL entry that represents "allowing the group MyFamily to subscribe to the topic".