Running the SDK on Node.js

You can use the Kii Cloud SDK for JavaScript with Node.js.

Before you start, make sure that Node.js is properly installed on your development environment. The execution environment also requires Node.js.

The information in this topic does not apply if you use the Kii Cloud SDK for JavaScript with Server Extention. Implement the SDK in the same way as you incorporate the SDK into the browser.

Usage Patterns of Node.js

Kii Cloud assumes the following two usage patterns of Node.js, which can be used in various ways. In either pattern, the implementation method of it is the same.

  • To generate JavaScript files for browsers

    This pattern uses Node.js as a build environment for JavaScript files to run in browsers.

    Node.js has a mechanism to resolve namespace conflicts among libraries. You can integrate various libraries and modules into your app without confusion by using require and exports.

    You can generate JavaScript files which are executable in browsers by building created source files with webpack or Browserify.

  • To run JavaScript code

    This pattern uses Node.js as an execution environment for JavaScript code.

    Especially, when you develop an IoT solution and implement the thing program with JavaScript, install Node.js as the execution engine for JavaScript on the thing. See Implementing Things with JavaScript SDK to learn how to use Node.js on the thing.

See web resources for general technical information about how to generate JavaScript files for browsers with Node.js and how to execute JavaScript code on Node.js. Those techniques are not part of the Kii Cloud technology.

Installing the SDK Package

Follow the below steps to set up the project.

  1. Set up the project on Node.js.

    Create a directory for the project on Node.js and generate package.json by npm init in advance. Besides, incorporate frameworks to use for developing the web app and confirm that you can run a "Hello World!" app in the project.

    Kii recommends checking if your sample app works at this point before adding the Kii Cloud SDK.

  2. Add the library to the project.

    Add the library of the Kii Cloud SDK.

    $ npm install kii-cloud-sdk --save
    

    The above npm command adds the below line to the "dependencies" section of package.json.

    "dependencies": {
      ...
      "kii-cloud-sdk": "^XX.XX.XX",
      ...
    }
    

    XX.XX.XX will be replaced with the latest version. You can also check the latest version on the SDK page on the npm site. See XX.XX.XX is the latest of ... at the upper right of the page.

    The line for the version number has a caret ^ in front of the version number like "^XX.XX.XX" so that subsequent executions of npm install or npm update automatically update the SDK. You can fix the SDK version to avoid unexpected updates by removing the caret.

The installation process will create the kii-cloud-sdk directory in the node_modules directory in your project directory. In the kii-cloud-sdk directory, you should find the xmlhttprequest directory for the dependent library.

Loading and Initializing the SDK Module

At the top of your app script, add the following lines to load and initialize the kii-cloud-sdk module.

var kii = require('kii-cloud-sdk').create();
kii.Kii.initializeWithSite("___APPID___", "___APPKEY___", kii.KiiSite.US);

Insert your application's AppID in the placeholder ___APPID___. You can put an arbitrary value in the placeholder ___APPKEY___. Also, pass the Server Location (kii.KiiSite.US, kii.KiiSite.JP, kii.KiiSite.CN3, kii.KiiSite.SG, or kii.KiiSite.EU) that you've specified on the developer portal (defines the location of the Kii Cloud server).

If Webpack Throws Build Errors

Webpack might throw build errors when you attempt to generate JavaScript files for the browser after adding Kii Cloud SDK for JavaScript to your project with the require function.

If you get the errors Cannot resolve module 'child_process' and Cannot resolve module 'fs' with XMLHttpRequest.js, add the three lines starting with externals below to webpack.config.js.

module.exports = [
  {
    ......
    externals:[{
      xmlhttprequest: '{XMLHttpRequest:XMLHttpRequest}'
    }],
    ......
  }
]

Available Features

You can use most of the JavaScript SDK features with the following restrictions:

  • Upload and download of object bodies are not supported when JavaScript code is executed on the Node.js environment. On the other hand, those actions are supported when a JavaScript file built in Node.js is executed in the browser.

  • Each module has its own scope in Node.js, so you need to be careful when referring the names of the classes and constants. For example, we are loading the SDK module with var kii = require('kii-cloud-sdk').create(); in the previous sample code. This means that we need to add kii. when referring the methods and constants provided by the SDK (e.g., kii.Kii.initializeWithSite and kii.KiiSite.US).