Preparation

Here are a couple of steps you need to perform in order to leverage the thing push feature.

Installation

You need to install a thing to Kii Cloud so that Kii Cloud acknowledges it and start the necessary preparation for sending MQTT-based push notifications.
MQTT Connection Establishment

You need to establish an MQTT connection so as to receive push notifications.

Installation

Installing a thing

You can install a thing either with the thing's access token or with the app admin token.

Here is an example of installing a thing with the thing's access token. As shown in the example, specify the "deviceType" field as "MQTT". "The "development" field specifies if the thing is installed for the development or production environment.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.InstallationCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations" \
  -d '{
        "deviceType": "MQTT",
        "development": true
      }'

Here is an example of installing a thing with the app admin token. In this case, you need to explicitly specify the thingID of the target thing.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.InstallationCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations" \
  -d '{
        "thingID": "{THING_ID}",
        "deviceType": "MQTT",
        "development": true
      }'

In both cases, Kii Cloud will return a 201 response if the installation is successful.

201 Created

Content-Type: application/vnd.kii.InstallationCreationResponse+json
Location: /apps/<appID>/installations/{INSTALLATIN_ID}
{
  "installationID" : "{INSTALLATION_ID}",
  "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID}"
}

Getting an installation

The thing owners and the app admin can retrieve the detail of the existing installation.

Here is an example of getting an installation. As shown in the example, specify the target installation ID.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/{INSTALLATION_ID}"

Kii Cloud returns the installation detail as a 200 response.

200 OK

Content-Type: application/vnd.kii.InstallationRetrievalResponse+json
{
  "installationID" : "{INSTALLATION_ID}",
  "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID}"
  "development" : true,
  "thingID" : "{THING_ID}",
  "deviceType" : "MQTT"
}

Getting a list of installations

The thing owners and the app admin can retrieve a list of all installations made on a thing.

Here is an example of getting a list of installation. As shown in the example, specify the target thing with its thingID.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations?thingID={THING_ID}"

Kii Cloud returns the list of installation as a 200 response.

200 OK

Content-Type: application/vnd.kii.InstallationsRetrievalResponse+json
{
  "installations" : [ {
    "installationID" : "{INSTALLATION_ID_1}",
    "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID_1}",
    "development" : true,
    "thingID" : "{THING_ID_1}",
    "deviceType" : "MQTT"
  }, {
    "installationID" : "{INSTALLATION_ID_2}",
    "installationRegistrationID" : "{INSTALLATION_REGISTRATION_ID_2}",
    "development" : true,
    "thingID" : "{THING_ID_2}",
    "deviceType" : "MQTT"
  } ]
}

Deleting an installation

The thing owners and the app admin can delete an installation.

Here is an example of deleting an installation with the installation ID.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/{INSTALLATION_ID}"

You can also delete an installation with its installation registration ID. In this case, you also need to specify the deviceType (ANDROID, IOS, or MQTT) with the registration ID. Here is an example.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/MQTT:{INSTALLATION_REGISTRATION_ID}"

Kii Cloud returns a 204 response if the deletion is successful.

Establishing an MQTT connection

Once a thing is installed on Kii Cloud, it is ready to subscribe to an MQTT broker for receiving push notifications. In order to do so, the thing first needs to retrieve the information of an MQTT endpoint and establish an MQTT connection using this information.

Retrieving an MQTT endpoint

The thing owners and the app admin can retrieve an MQTT endpoint.

Here is an example.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/installations/{INSTALLATION_ID}/mqtt-endpoint"

If the MQTT endpoint is ready, Kii Cloud returns its information as a 200 response.

200 OK

Content-Type: application/vnd.kii.MQTTEndpointResponse+json
{
  "installationID" : "{INSTALLATION_ID}",
  "username" : "{USERNAME}",
  "password" : "{PASSWORD}",
  "mqttTopic" : "{MQTT_TOPIC}",
  "host" : "{BROKER_HOST}",
  "portTCP" : {PORT_TCP},
  "portSSL" : {PORT_SSL},
  "portWS" : {PORT_WS},
  "portWSS" : {PORT_WSS},
  "X-MQTT-TTL" : {MQTT_TTL}
}

The returned values are to be used for establishing an MQTT connection (i.e. subscribing to the MQTT topic). The X-MQTT-TTL specifies the time the MQTT topic is valid in seconds.

Preparing an MQTT endpoint may take some time after the thing is installed. If the MQTT endpoint is not ready at the time the thing tries to retrieve its info, Kii Cloud returns a 503 response instead.

503 Service Unavailable

Content-Type: application/vnd.kii.MQTTEndpointNotReadyException+json
Retry-After: 10
{
  "errorCode" : "MQTT_ENDPOINT_NOT_READY",
  "message" : "MQTT endpoint for  {INSTALLATION_ID} is not ready. Please try again later.",
  "installationID" : "{INSTALLATION_ID}",
  "appID" : "{APP_ID}"
}

The response contains the header field "Retry-After" that notifies the time (sec) the thing needs to wait before it reissues the request. If you get a 503 response, resend the same request after this time.

Establishing an MQTT connection

Once you retrieve an MQTT endpoint, you have all the information needed to establish an MQTT connection (i.e. connecting to an MQTT broker and subscribing to an MQTT topic).

You can use any external library for establishing an MQTT connection. There are many open source libraries for many platforms. Refer to the list of available libraries by MQTT.org.

Information for subscribing to a MQTT topic

Use the following information to subscribe to an MQTT topic.

Connection Parameter	Value
Hostname	"host" in the retrieved MQTT endpoint
Port number	"portTCP" (for TCP) or "portSSL" (for SSL/TLS) in the retrieved MQTT endpoint
Port number for WebSocket	"portWS" (for TCP) or "portWSS" (for SSL/TLS) in the retrieved MQTT endpoint
Keep alive timer for the CONNECT command	Specify this according to your app implementation (See Keep alive timer)
Client identifier for the CONNECT command	"mqttTopic" in the retrieved MQTT endpoint
Username for the CONNECT command	"username" in the retrieved MQTT endpoint
Password for the CONNECT command	"password" in the retrieved MQTT endpoint
Topic name for the SUBSCRIBE command	"mqttTopic" in the retrieved MQTT endpoint

Keep alive timer

MQTT defines an alive monitoring process with the keep alive timer to verify the connection is active.

The connection will be disconnected if the client does not send any message for the duration of 1.5 * the value of the keep alive timer set on the CONNECT command. If the client is not going to send any message within this duration, it needs to send the PINGREQ command. Refer to the documentation of the MQTT library you are using for more specific information.

When you implement an MQTT client, Kii recommends you to verify that the connection is still retained after a certain period of time without the client's sending any commands. If the connection is disconnected, the PINGREQ command might not have been sent.