Enabling the Kii Push Notification Feature (MQTT)

This topic describes how to integrate the feature of MQTT push notification to a web app. If you are to integrate the push notification to a Cordova app, see Installing the SDK to Cordova.

See MQTT Protocol for the overview of MQTT.

Setting up

The following four steps are needed to leverage the MQTT push notification.

Select a library
Install a user or a thing
Get an MQTT endpoint
Establish an MQTT connection
Uninstall a user or a thing

Select a library

Obtain an external library which supports MQTT to use it in JavaScript. See the list of libraries published by MQTT.org for available libraries.

Kii has tested MQTT.js with Kii Cloud. Kii has also verified that Paho works with Kii Cloud.

Install a user or a thing

To send push messages to a web app, install (register) a user or a thing which receives push messages. User/thing installation associates the Kii Cloud user or thing with an MQTT connection on Kii Cloud.

Here is an example of installing a user for push notification.

// Configure the push notification in production mode.
var development = false;

// Set up an MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().installMqtt(development).then(
  function(response) {
    var installationID = response.installationID;
    var installationRegistrationID = response.installationRegistrationID;
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var thePushInstallation = error.target;
    var errorString = error.message;
  }
);

// Configure the push notification in production mode.
var development = false;

// Set up an MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().installMqtt(development, {
  success: function(response) {
    var installationID = response.installationID;
    var installationRegistrationID = response.installationRegistrationID;
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
    var thePushInstallation = error.target;
    var errorString = error.message;
  }
});

The argument development specifies the environment of the push notification (i.e. development or production). In the above example, we are specifying the production environment by setting the argument to false.

The KiiUser needs to be logged in when executing the installMqtt() method. The user needs to be logged in because the destination of the push notification is a user who is subscribing to the bucket or topic in Kii Cloud.

Install a thing with the pushInstallation() method described in Implementing Things with JavaScript SDK.

Get an MQTT endpoint

Next, you need to get an MQTT endpoint from Kii Cloud. By getting the MQTT endpoint, you will be able to get all the information needed to establish an MQTT connection (i.e. connect to an MQTT broker and subscribe an MQTT topic).

Here is an example of getting an MQTT endpoint.

var installationID = "[INSTALLATION_ID]";

// Get the MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().getMqttEndpoint(installationID).then(
  function(response) {
    var username = response.username;
    var password = response.password;
    var mqttTopic = response.mqttTopic;
    var xMqttTtl = response["X-MQTT-TTL"];
    var portTCP = response.portTCP;
    var portSSL = response.portSSL;
    var portWS = response.portWS;
    var portWSS = response.portWSS;
    // Do something.
  }
).catch(
  function(error){
    // Handle the error.
  }
);

var installationID = "[INSTALLATION_ID]";

// Get the MQTT endpoint for the logged-in user to Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().getMqttEndpoint(installationID, {
  success: function(response) {
    var host = response.host;
    var username = response.username;
    var password = response.password;
    var mqttTopic = response.mqttTopic;
    var xMqttTtl = response["X-MQTT-TTL"];
    var portTCP = response.portTCP;
    var portSSL = response.portSSL;
    var portWS = response.portWS;
    var portWSS = response.portWSS;
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
  }
});

In installationID, specify the installation ID that was returned by the installMqtt() method.

The preparation of the MQTT endpoint starts when you install a user or a thing. If the MQTT endpoint is not ready at the time the getMqttEndpoint() method is executed, the method will retry at most three times with one-second interval.

Establish an MQTT connection

You have all the information needed to establish an MQTT connection (i.e. connect to an MQTT broker and subscribe an MQTT topic) after you get the MQTT endpoint.

Use the following information to subscribe MQTT topics.

Information	Value to Set
Hostname	`host` property's value in the retrieved MQTT endpoint
Port number	`portTCP` (for TCP) or `portSSL` (for SSL/TLS) property's value in the retrieved MQTT endpoint
WebSocket port number	`portWS` (for TCP) or `portWSS` (for SSL/TLS) property's value in the retrieved MQTT endpoint
Keep alive timer for the CONNECT request	Depend on your application (See Keep alive timer)
Client identifier for the CONNECT request	`mqttTopic` property's value in the retrieved MQTT endpoint
Username for the CONNECT request	`username` property's value in the retrieved MQTT endpoint
Password for the CONNECT request	`password` property's value in the retrieved MQTT endpoint
Topic name for the SUBSCRIBE request	`mqttTopic` property's value in the retrieved MQTT endpoint

Establish an MQTT connection by calling an API from the MQTT library with the above information. See JavaScript (Web) Push Notification Tutorial for a sample implementation with MQTT.js and Paho.

In general, use a connection over WebSocket with the port number stored in the portWSS property to connect from a web app in the browser. Use a connection over the TCP socket with the port number stored in the portTCP property to connect from a thing.

Note that Kii Cloud only supports one MQTT connection per user. If multiple instances of a web app are launched at the same time, only one connection can be established.

Some MQTT libraries repeatedly disconnect and reconnect a connection when multiple instances of a web app are launched at the same time. Implement logic to check the reconnection frequency and throw a connection error in the web app as required.

Keep alive timer

MQTT defines a keep alive protocol to check if the connection is retained or disconnected.

The connection will be disconnected if the client does not send any message for the duration of 1.5 * Keep alive timer set on the CONNECT request. If the client is not going to send any message within this duration, it needs to send the PINGREQ request.

The methods to implement the process to send the PINGREQ request varies depending on the libraries. Some libraries automatically send it internally, and other require the user program to handle it. See the documentation of your MQTT library to learn how to implement the process.

Uninstall a user or thing

In order to disable the push notification for a user or a thing, implement the uninstallation processing. You can use the installation ID or the installation registration ID to specify the target user or thing.

First, see the sample code below for uninstalling a user with the installation ID.

var installationID = "[INSTALLATION_ID]";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstallByInstallationID(installationID).then(
  function(response) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var errorString = error.message;
  }
);

var installationID = "[INSTALLATION_ID]";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstallByInstallationID(installationID, {
  success: function(response) {
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
    var errorString = error.message;
  }
});

In installationID, specify the installation ID that was returned by the installMqtt() method.

Next, see the sample code below for uninstalling a user with the installation registration ID.

var installationRegistrationID = "[INSTALLATION_REGISTRATION_ID]";
var deviceType = "MQTT";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstall(installationRegistrationID, deviceType).then(
  function(response) {
    // Do something.
  }
).catch(
  function(error) {
    // Handle the error.
    var errorString = error.message;
  }
);

var installationRegistrationID = "[INSTALLATION_REGISTRATION_ID]";
var deviceType = "MQTT";

// Delete the MQTT endpoint for the logged-in user from Kii Cloud.
KiiUser.getCurrentUser().pushInstallation().uninstall(installationRegistrationID, deviceType, {
  success: function(response) {
    // Do something.
  },
  failure: function(error) {
    // Handle the error.
    var errorString = error.message;
  }
});

In installationRegistrationID, specify the installation registration ID that was returned by the installMqtt() method. Also, in deviceType, specify MQTT as the type of push notification to be disabled.

The push notification is disabled after the uninstallation processing completes successfully.

Uninstall a thing with the pushInstallation() method described in Implementing Things with JavaScript SDK.