Installing the SDK to Cordova

You can install the Kii Cloud SDK for JavaScript onto mobile apps running in Apache Cordova.

There are several ways to leverage the Kii Cloud SDK in Cordova. In this document, we will present procedures of directly adding the SDK file in the Cordova's config file.

As a preparation, create a Cordova project and make a simple mobile app (e.g., "Hello Kii" app) ready.

Adding the Kii Cloud SDK

Add the Kii Cloud SDK in your projects as follows:

Download the Kii Cloud SDK Zip file.

First, download the library. Login to the developer portal (https://developer.kii.com) and click the SDK link in the "Download" page to start downloading the library.
Uncompress the ZIP file for the Kii Cloud SDK.

Two files, KiiSDK.min.js and KiiSDK.js will be extracted when you uncompress the SDK file. Select one of them and copy it to a directory such as /app/www/js in the Cordova project.

The two files have the same functionality while KiiSDK.min.js doesn't contain unnecessary characters such as spaces in the source code. Use small KiiSDK.min.js for app release and readable KiiSDK.js for app development.
Load the Kii Cloud SDK in the HEAD tag.

Set to load the SDK JS file when the mobile app launches. Change the directory of the SDK suitably. Please replace the Kii SDK directory as needed.
```
<head>
    <script type="text/javascript" src="js/KiiSDK.min.js"></script>
  ...
</head>
```
Execute the initialization method of the Kii Cloud SDK.

Execute the initialization method when the mobile app launches. You can, for example, execute the method when the deviceready event occurs or from www/js/index.js.
```
document.addEventListener('deviceready', function () {
   // Initialize the Kii Cloud SDK. Call this method before any other Kii SDK API calls.
   Kii.initializeWithSite("___APPID___", "___APPKEY___", KiiSite.JP);

   // Initialize other components.
   ...
});
```
Insert your application's AppID in the placeholder ___APPID___. You can put an arbitrary value in the placeholder ___APPKEY___.

You can safely embed the AppID in your application as long as you apply the correct access control. See Security for more information.

Integrating the push notification

If you are using Cordova, you can use phonegap-plugin-push for leveraging the push notification feature over FCM or APNs.

Setting up the push notification

You need the following settings to leverage the push notification feature with phonegap-plugin-push.

See web resources and the README file available on the above link for the detailed explanation on how to install the Cordova.

If you are using the FCM, configure the push notification settings on the Firebase console and get the Server Key and sender ID. If you are using the APNs, go to the Apple Developer Web site, configure the push notification and build settings, and get the certificate.
Set the sender ID or the APNs certificate into the Cordova project and Xcode project.
Set the FCM Server key or the APNs certificate on the Kii Cloud developer portal.

See the push notification instruction for the native application (Using FCM and FCM Push Notification Tutorial for FCM, Using APNs and iOS Push Notification Tutorial for APNs) to learn how to set up the Kii Cloud.

Installing a device

For using the Kii Cloud push notification, you need to implement a process for installing a device token to Kii Cloud. See How Push Notification Works in Kii Cloud SDK for Android for the overview of the device token installation process.

You install a device token in the phonegap-plugin-push's registration event. Get the device token from data.registrationId when the registration event occurs, like in the snippet below.

The method of the KiiPushInstallation class to be used for the registration is installGcm() for the FCM and installApns() for the APNs. All other processes are the same for both platforms.

Note that the user to receive the push notification has to be logged in when this API is executed.

FCM

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installGcm(deviceToken, 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;
    }
  );
}

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installGcm(deviceToken, 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;
    }
  });
}

APNs

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installApns(deviceToken, 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;
    }
  );
}

push.on('registration', function(data) {
  var deviceToken = data.registrationId;

  // 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().installApns(deviceToken, 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;
    }
  });
}

Specify your environment (i.e. development or production) with the development.

When the device installation is finished, the logged-in user will be bound to the specified device token and registered in Kii Cloud. The device installation will update the user who is bound to the device token to the current user. If the device token was bound to another user, the binding is canceled by the installation; push notifications sent to the old user will no longer be delivered to the device.

Uninstalling a device

You can unbind a device registered on Kii Cloud with the device uninstallation procedure. Once the device is uninstalled, the device will no longer receive any push notification.

// Specify the device type by "ANDROID" or "IOS".
var deviceType = "ANDROID";

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

// Specify the device type by "ANDROID" or "IOS".
var deviceType = "ANDROID";

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

The method of the uninstallation procedure is the same for the FCM and APNs. The second argument specifies the target platform. Set the string "ANDROID" for FCM and "IOS" for APNs.

In the first argument of the installationRegistrationID, Set the value that you have obtained from the response.installationID when you install the device with the installGcm() or installApns().