Subscribing to a Bucket

A user who is interested in changes to a certain bucket can receive a push notification when a change occurs in the bucket by subscribing to the bucket.

Here is a sample curl command for subscribing a user to a bucket in the application scope.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users/{TARGET_USER_ID}" \
  -d ""

Here is a sample curl command for subscribing a user to a bucket in a group scope.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users/{TARGET_USER_ID}" \
  -d ""

Here is a sample curl command for subscribing a user to a bucket in a user scope.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users/{TARGET_USER_ID}" \
  -d ""

For all the cases, make sure to replace {APP_ID} with your application's AppID and {TARGET_USER_ID} with the target user's ID. Also, {ACCESS_TOKEN} must be the target user's token or the app admin token.

If you subscribe the current user (the owner of ACCESS_TOKEN), you can omit TARGET_USER_ID, like in the following example:

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/buckets/{BUCKET_ID}/filters/all/push/subscriptions/users" \
  -d ""

Kii Cloud returns one of these responses:

• A 204 response if the subscription is successful.
• A 404 response with the error code FILTER_NOT_FOUND if the specified bucket does not exist.
• A 404 response with the error code PUSH_SUBSCRIPTION_ALREADY_EXISTS if the user is already subscribed to the bucket.

Subscribing to a bucket with many KiiObjects

A "Push to App" notification will be launched every time there is an update event in the target bucket. Subscribing to a bucket with many Objects, therefore, might cause some issues.

For example, let us assume that a user having three devices is subscribing to a bucket. This bucket has 100 Objects inside. If all of them are updated, it will trigger 100 push notifications per device or 300 total push notifications for this user.

One way to cope with such a situation (massive amount of push notifications triggered) is to use the Push to User Notification instead of the "Push to App" notifications. By sending a push request to a topic after the object updates are done, you can just send one "push to user" message per device. A shortcoming of this method is that there will be a time gap between the object updates and the push notification delivery, and this gap might cause some notifications to be dropped (See Transactions for the related discussion).