Sending a Push Notification

When a topic is set, we are ready to send a message to the topic. The message sent to the topic will be pushed to the topic subscribers.

Sending a push message to an application-scope topic

Only an application developer can send a push message to an application scope topic on the developer portal.

See Sending a Push to User Notification to learn how the application developer can push messages.

Sending a push message by leveraging the SDK

Sending a message

Only the application administrator can send a push message to an application-scope topic. See the following sample code to see how to do this:

  • // Authenticate as the app administrator.
// Check the ClientID and ClientSecret in the Kii Cloud developer portal.
Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    // Instantiate a topic.
    var topicName = "SendingAlert";
    var topic = adminContext.topicWithName(topicName);

    // Create push message data.
    var contents = {
      message : "hello push!"
    };

    // Create a push message.
    var message = new KiiPushMessageBuilder(contents).build();

    // Send the push message.
    return topic.sendMessage(message);
  }
).then(
  function(params) {
    var theTopic = params[0];
    var theMessage = params[1];
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.

    // Get the topic for the failed sendMessage() method.
    var theTopic = error.target;
    var errorString = error.message;
  }
);
  • // Authenticate as the app administrator.
// Check the ClientID and ClientSecret in the Kii Cloud developer portal.
Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    // Instantiate a topic.
    var topicName = "SendingAlert22";
    var topic = adminContext.topicWithName(topicName);

    // Create push message data.
    var contents = {
      message : "hello push!"
    };

    // Create a push message.
    var message = new KiiPushMessageBuilder(contents).build();

    // Send the push message.
    topic.sendMessage(message, {
      success: function(theTopic, theMessage) {
        // Do something.
      },
      failure: function(errorString) {
        // Handle the error.
      }
    });
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

For a group-scope topic, any group member can send a push message to it.

The following is the sample code.

  • // Instantiate a group.
var group = KiiGroup.groupWithURI(groupURI);

// Refresh the group.
group.refresh().then(
  function(theGroup) {
    // Instantiate a topic in the group scope.
    var topicName = "GroupTopic";
    var topic = group.topicWithName(topicName);

    // Create push message data.
    var contents = {
      "field1": 1,
      "field2": "str",
      "field3": 1.12,
      "field4": false
    };

    // Create a push message.
    var message = new KiiPushMessageBuilder(contents).build();

    // Send the push message.
    return topic.sendMessage(message);
  }
).then(
  function(params) {
    var theTopic = params[0];
    var theMessage = params[1];
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.

    // Get the group for the failed refresh() method.
    var theGroup = error.target;
    // Get the topic for the failed sendMessage() method.
    var theTopic = error.target;
    // Get the error message.
    var errorString = error.message;
  }
);
  • // Instantiate a group.
var group = KiiGroup.groupWithURI(groupURI);

// Refresh the group.
group.refresh({
  success: function(theGroup) {
    // Instantiate a topic in the group scope.
    var topicName = "GroupTopic";
    var topic = group.topicWithName(topicName);

    // Create push message data.
    var contents = {
      "field1": 1,
      "field2": "str",
      "field3": 1.12,
      "field4": false
    };

    // Create a push message.
    var message = new KiiPushMessageBuilder(contents).build();

    // Send the push message.
    topic.sendMessage(message, {
      success: function(theTopic, theMessage) {
        // Do something.
      },
      failure: function(errorString) {
        // Handle the error.
      }
    });
  },
  failure: function(theGroup, errorString) {
    // Handle the error.
  }
});

For a user-scope topic, only the user who owns the topic can send a push message to it.

The following is the sample code.

  • // Instantiate a topic in the user scope.
var topicName = "MyTODO";
var user = KiiUser.getCurrentUser();
var topic = user.topicWithName(topicName);

// Create push message data.
var contents = {
  "Item": "Do something",
  "Done": 0
};

// Create a push message.
var message = new KiiPushMessageBuilder(contents).build();

// Send the push message.
topic.sendMessage(message).then(
  function(params) {
    var theTopic = params[0];
    var theMessage = params[1];
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theTopic = error.target;
    var errorString = error.message;
  }
);
  • // Instantiate a topic in the user scope.
var topicName = "MyTODO";
var user = KiiUser.getCurrentUser();
var topic = user.topicWithName(topicName);

// Create push message data.
var contents = {
  "Item": "Do something",
  "Done": 0
};

// Create a push message.
var message = new KiiPushMessageBuilder(contents).build();

// Send the push message.
topic.sendMessage(message, {
  success: function(theTopic, theMessage) {
    // Do something.
  },
  failure: function(errorString) {
    // Handle the error.
  }
});

For the 3 examples, here is a brief description of what is happening in the sample code:

  • Creates a push message by calling the KiiPushMessageBuilder#build method passing the key-value pairs to be included in the message.
  • Sends the message by calling the sendMessage method.

The refresh() method is executed in the sample code for the group scope. You can omit this method if you use the group just for sending a push message.

Setting fields specific to each push notification network

Sometimes you want to include field values specific to each push notification network in your push messages.

The following sample code shows how to do this.

  • // Assume that the target topic has been instantiated.

// Create push message data.
var messageContents = {
  "key1": "value1"
};

// Create a push message builder.
var pushMessageBuilder = new KiiPushMessageBuilder(messageContents);

// Create FCM-specific data.
pushMessageBuilder.gcmCollapseKey("key")
  .gcmData({key1: "value1", key2: "value2"})
  .gcmDelayWhileIdle(true)
  .gcmRestrictedPackageName("packageName")
  .gcmTimeToLive(10);

// Create APNs-specific data.
// Make the notification silent.
var alertObject = {
  body: "alert message"
};
pushMessageBuilder.apnsAlert(alertObject)
  .apnsContentAvailable(1)
  .apnsData({key1: "value1", key2: 123});

// Send an APNs message with rich content.
// pushMessageBuilder.apnsAlert(alertObject)
//  .apnsBadge(3)
//  .apnsCategory("myCategory")
//  .apnsMutableContent(1)
//  .apnsSound("sound.mp3");

// Create MQTT-specific data.
pushMessageBuilder.mqttData({key1: "value1", key2: "value2"});

// Create a push message.
var pushMessage = pushMessageBuilder.build();

// Send the push message.
topic.sendMessage(pushMessage).then(
  function(params) {
    var theTopic = params[0];
    var theMessage = params[1];
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var theTopic = error.target;
    var errorString = error.message;
  }
);
  • // Assume that the target topic has been instantiated.

// Create push message data.
var messageContents = {
  "key1": "value1"
};

// Create a push message builder.
var pushMessageBuilder = new KiiPushMessageBuilder(messageContents);

// Create FCM-specific data.
pushMessageBuilder.gcmCollapseKey("key")
  .gcmData({key1: "value1", key2: "value2"})
  .gcmDelayWhileIdle(true)
  .gcmRestrictedPackageName("packageName")
  .gcmTimeToLive(10);

// Create APNs-specific data.
// Make the notification silent.
var alertObject = {
  body: "alert message"
};
pushMessageBuilder.apnsAlert(alertObject)
  .apnsContentAvailable(1)
  .apnsData({key1: "value1", key2: 123});

// Send an APNs message with rich content.
// pushMessageBuilder.apnsAlert(alertObject)
//  .apnsBadge(3)
//  .apnsCategory("myCategory")
//  .apnsMutableContent(1)
//  .apnsSound("sound.mp3");

// Create MQTT-specific data.
pushMessageBuilder.mqttData({key1: "value1", key2: "value2"});

// Create a push message.
var pushMessage = pushMessageBuilder.build();

// Send the push message.
topic.sendMessage(pushMessage, {
  success: function(theTopic, theMessage) {
    // Do something.
  },
  failure: function(errorString) {
    // Handle the error.
  }
});

If you are going to use the silent notification feature for iOS devices, use the apnsContentAvailable method to enable it as shown in the previous sample code. If you want to send notifications with rich content such as images to the user's iOS devices, refer to the lines that are commented out in the sample code to set the related fields.

By default, the push message will be sent to all the push notification networks. You can control message delivery by setting a flag like in the following example:

// Deliver a push message to Android devices using FCM only.
var message = KiiPushMessageBuilder.buildWith(data)
        .enableApns(false)
        .enableMqtt(false)
        .build();

// Deliver a push message to iOS devices only.
var message = KiiPushMessageBuilder.buildWith(data)
        .enableGcm(false)
        .enableMqtt(false)
        .build();

// Deliver a push message using MQTT only.
var message = KiiPushMessageBuilder.buildWith(data)
        .enableGcm(false)
        .enableApns(false)
        .build();