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 the sample code for subscribing to a bucket.

  • // If the bucket is new, save it on Kii Cloud by saving a KiiObject in the bucket and then
    // subscribe to the bucket. You cannot subscribe to a bucket if it does not exist on Kii Cloud.
    
    // Instantiate an existing bucket.
    var user = KiiUser.getCurrentUser();
    var bucket = user.bucketWithName("_target_bucket_");
    
    // Create a KiiObject in the bucket.
    var obj = bucket.createObject();
    
    // Save the KiiObject.
    obj.save({
      success: function(theObject) {
        // Subscribe to the bucket.
        user.pushSubscription().subscribe(bucket, {
          success: function(thePushSubscription, theBucket) {
            // Do something.
          },
          failure: function(errorString) {
            // Handle the error.
          }
        });
      },
      failure: function(theObject, errorString) {
        // Handle the error.
      }
    });
  • // If the bucket is new, save it on Kii Cloud by saving a KiiObject in the bucket and then
    // subscribe to the bucket. You cannot subscribe to a bucket if it does not exist on Kii Cloud.
    
    // Instantiate an existing bucket.
    var user = KiiUser.getCurrentUser();
    var bucket = user.bucketWithName("_target_bucket_");
    
    // Create a KiiObject in the bucket.
    var obj = bucket.createObject();
    
    // Save the KiiObject.
    obj.save().then(
      function(theObject) {
        // Subscribe to the bucket.
        return user.pushSubscription().subscribe(bucket);
      }
    ).then(
      function(params) {
        var thePushSubscription = params[0];
        var theBucket = params[1];
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
    
        // Get the KiiObject for the failed save() method.
        var theObject = error.target;
        // Get the subscription for the failed subscribe() method.
        var thePushSubscription = error.target;
        // Get the error message.
        var errorString = error.message;
      }
    );

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).