Push to App Notification
The Push to App notification feature lets your mobile app know that there was a change (event) on a KiiObject in a bucket. By leveraging this notification feature, your mobile app can quickly fetch the changes that occur on the server-side.
This topic explains the functionality of the Push to App notification. For the implementation, see the following topics:
- Subscribing to a Bucket
- Checking the Subscription Status of a Bucket
- Unsubscribing from a Bucket
- Receiving a Push Notification
Events
The events that can be notified by this push notification include:
- A new KiiObject is created in a bucket.
- An existing KiiObject in a bucket is updated.
- An existing KiiObject in a bucket is deleted.
- The object body of a KiiObject in a bucket is updated.
- The object body of a KiiObject in a bucket is deleted.
- The ACL of an existing KiiObject in a bucket is modified.
How Push to App notification works
The basic steps to use the Push to App notification feature is as below.
- A user subscribes to a bucket so as to start monitoring the bucket for changes.
- A change (event) occurs on a KiiObject in the bucket.
- The subscriber receives a push notification on a device.
Subscription triggers monitoring of changes in a bucket. Such changes are sent to devices as push notifications once a bucket is subscribed to.
By subscribing to a bucket, the device virtually starts to monitor the bucket. When an event occurs on an Object inside this bucket, this will be notified to the device as a push message.
If multiple users are subscribing to a bucket, a push message triggered by this bucket event 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, an update in an object in the bucket 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 bucket.
Step 2 includes changes caused by clients on any platform that the push notification feature is not enabled for.
Bucket scopes and subscription
You need to subscribe to all buckets that you want to monitor. In the following example, the KiiUser is subscribing to three buckets, a bucket from each scope (application, group, and user).
You can subscribe to a thing scope bucket too.
A user can subscribe to as many buckets as he wants as long as he has the access privilege to them. He will get a push notification when an event occurs on any one of these buckets. In the above example, the push notifications are sent to the user's devices because an update has occurred on one of the buckets that he is subscribing.
The payload of the push notification contains the information on the bucket and object that triggered the event so as to let you get the details of what has happened on the server.
Behavior of a "Push To App" notification
This feature lets Kii Cloud automatically send push notifications when events occur. The below items explain how "Push To App" notification works.
Once you subscribe to a bucket, any events that occur on the bucket will trigger the push notifications. You cannot filter by the types of events.
The push notification is sent per one event. If multiple objects in the target bucket are updated in series, you will get multiple push notifications almost at the same time.
The push notification will be sent to all installed devices. You cannot select the target push notification network.
Customizing a push message
The data in the payload in the Push to App message is predefined by Kii Cloud and cannot be customized. For iOS, you cannot customize messages displayed in Notification Center. The messages will be sent to all the push notification networks.
Here are a couple of alternatives you can take if you need to customize the messages.
Use the Push to User notification in your mobile app. First, create and subscribe to a topic. Then, implement your mobile app so that it will send a push message to the topic whenever the target bucket is updated. The messages sent to the topic is customizable.
Use a combination of the Push to User notification and the trigger-based hook. First, create and subscribe to a topic. Then, set a trigger on the target bucket to launch server code that will send a push message to the topic when the bucket is updated. See Sending a Push Notification to learn how you can write such server code.