How Push Notification Works

This topic explains the relation between Kii Cloud and push notification networks such as FCM.

The content of this topic applies to FCM and APNs. For implementation using MQTT, see MQTT Protocol.

Push notification components

Any of the push notification networks requires the following three components:

  • FCM or APNs server

    The server of the service provider such as Google and Apple for push notification.

  • Devices such as smartphones

    Devices being used by end users.

  • Application server

    Kii Cloud that functions as the application server for push notification.

The push notification networks identify each device by device token. A device token is not a device IMEI but an ID to identify a certain mobile app on a certain device. It is issued by calling libraries of FCM or APNs. The servers of FCM and APNs manage a list of pairs of a device token and an actual device.

When a push notification is sent, the application server calls the server of the target push notification network and passes the push message and the device token of the destination device. The target push notification network sends the message to the device specified by the device token.

A push notification message is a JSON string as shown in the diagram below. The JSON string includes control fields specific to the push notification network in addition to the message for the recipient user.

Push notification in Kii Cloud

The Kii Cloud APIs do not send push notifications to devices but users.

The three types of push notifications of Kii Cloud are sent to users in the following ways:

  • A Push to App notification is sent to a user's devices when a bucket subscribed to by the user is updated.
  • A Push to User notification is sent to a user's devices when a message is sent to a topic subscribed to by the user.
  • A Direct Push notification is sent to a user's devices when the administrator sends a message to the user.

One request for a push notification to a user generates a notification to each of the user's all devices if necessary initialization has been done on each device.

Kii Cloud manages a list of pairs of a user and a device token so that it can send push notifications to users. If a recipient user has multiple devices, Kii Cloud sends multiple requests to the push notification networks.

You cannot use the push notification feature without defining users. If you need to avoid explicit logins, consider implementations using pseudo users and so on.

Request flow

See below for the entire flow that starts with the initialization of the push notification feature and ends with a user's reception of a push notification. Some of them are hidden if the Kii Cloud SDK is used.

  1. A device sends a request to the FCM or APNs server to register the device.

  2. The FCM or APNs server registers the device and issues a device token.

  3. The device calls the push initialization API of the Kii Cloud SDK when a user logs in. The API sends the device token and the user ID to Kii Cloud. These are stored in Kii Cloud as a pair.

  4. An event occurs on Kii Cloud. Using the stored pair of the user ID and device token, Kii Cloud identifies the recipient user's device to send a push notification.

  5. Kii Cloud requests the FCM or APNs server to send a push notification to the target device token.

  6. The FCM or APNs server sends a push message to the device. The device processes the received push message.

Step :num3: where a device token is registered to Kii Cloud is called device installation. The installation needs to be performed when the mobile app is initialized and when the push notification network notifies that the device token has been changed.

Installing a device

A process where a device token is registered to Kii Cloud (:num3: in Request flow above) is called device installation.

When a device is installed, the logged-in user is associated with the device token and also registered to Kii Cloud.

Device installation is related to a process to receive push notifications. Check how to initialize the push notification feature on the platform of your mobile app (Android, iOS, or JavaScript that will receive push notifications triggered by the subscriptions and push messages set with the REST API.

When the user does not need to receive push notifications anymore, uninstall the device so that Kii Cloud discards the association of the device token and the user. Execute this process also when the push notification network informs Kii Cloud that the device token is not valid any longer.

Relation between a device and a user

Kii Cloud uses device tokens issued by the push notification network for identifying the destination of push messages.

On the basis of this mechanism, the push notification feature works as below:

  • A user can install multiple devices and gets multiple device tokens. If the user concurrently logs in to a smartphone and a tablet, both devices receive push notifications.

  • If multiple users log in to the same mobile app on the installed device, only the last user who installs the device receives push notifications. When a new user installs a device, the pair of the old user and the device token is overwritten with the pair of the new user and the device token on Kii Cloud.

  • If the pseudo user feature is used, a different pseudo user is assigned to each device. A mobile app that implements the pseudo user feature does not allow a single user to receive push notifications on multiple devices.

A device token is deleted from Kii Cloud when any of the following actions are taken:

  • The mobile app calls the API to uninstall the device from Kii Cloud.

  • A different user installs the device and the previous user paired with the device token is overwritten on Kii Cloud.

  • Kii Cloud detects that the device token is not valid any longer (Therefore, it is appropriate to install the device each time the mobile app starts).