Developing External JS Services

External JS services are 3rd party JS services that must be installed on the webOS target device. External JS services can be created and deployed using the Command-Line Interface (CLI) tool that are provided by the webOS Open Source Edition (OSE) SDK.

External JS services must be packaged in an app (web, QML, native). Therefore, before creating a JS service, make sure you have an app to package with the external JS service. If such an app is not available, create a web app as described in Creating Web Apps.

This page describes the steps to develop an external JS service using CLI. For detailed information on the commands used in this tutorial, see CLI commands.

Creating JS Services

Developing an external JS service requires the following steps:

• Step 1: Create a JS Service
• Step 2: Implement the JS Service
• Step 3: Configure the JS Service
• Step 4: Package the JS Service
• Step 5: Install the JS Service
• Step 6: Run the JS Service

Step 1: Create a JS Service

Start by creating a JS service using the available JS service template.

To create a basic JS service, execute the following command:

$ ares-generate -t js_service sampleService

In the above command:

• js_service is the name of the template that creates a basic JS service.
• sampleService is the JS service directory which is created in the current directory.

The following shows an example directory structure of JS services packaged in an app.

sampleService/
├── helloclient.js
├── helloworld_webos_service.js
├── package.json
└── services.json

The JS service directory (sampleService) has the following files:

Step 2: Implement the JS Service

Service implementation files provide various use cases of JS service.

Before registering a service into your code, you should load the webos-service module. The webos-service module for Node.js provides an interface to the system bus, wrapped in familiar Node.js idioms.

This loads the webos-service module.

var Service = require('webos-service');

The following JavaScript example registers a service which responds to a request with a “Hello, !” message.

var service = new Service("com.domain.app.service");

service.register("hello", function(message) {
  var name = message.payload.name ? message.payload.name : "World";

    message.respond({
        returnValue: true,
        Response: "Hello, " + name + "!"
    });
});

For more details about webos-service module, see webos-service Library API Reference.

Step 3: Configure the JS Service

package.json

A package.json file configures the service metadata and points to the main service file. This file is needed for packaging (related with Node.js).

A minimal package.json looks like this:

{
    "name": "com.domain.app.service",
    "main": "helloworld_webos_service.js"
}

A brief explanation of the above file:

• name - Specify the name of the service. The service name must begin with the app ID. So, if app ID is com.domain.app, the service name must be com.domain.app.service.

• main - Specify the name of the main service JavaScript file.

There are quite a few other values one can set in the package.json file. For the complete specification of the package.json, see the npm documentation.

services.json

A services.json file defines the services that must be registered on the Luna Bus. The methods of these services can be called from other apps and services. For more information, see services.json.

A services.json file looks like this:

{
    "id": "com.domain.app.service",
    "description": "Helloworld Service",
    "services": [{
        "name": "com.domain.app.service"
    }]
}

Step 4: Package the JS Service

The JS service must be packaged along with the app.

For details on packaging the app, see Packaging the Web App.

Step 5: Install the JS Service

The JS service must be installed along with the app.

For details on installing the app, see Installing the Web App.

Step 6: Run the JS Service

If the JS service is successfully installed, you can try running the JS service on the target device.

To call the JS service, use the following command on your host machine:

$ ares-shell -r "luna-send -n 1 -f luna://com.domain.app.service/hello '{\"name\":\"webOS\"}'" -d <target device>

where <target device> is the name of the webOS Auto target device. The response will be:

{
    "returnValue": true,
    "Response": "Hello, webOS!"
}

When Hello method of com.domain.app.service is called, the service adds name, the delivered parameter, returns the text.

Since this JS service is a dynamic service, it is run when called and terminated after a certain period of inactivity (5 seconds). For more information about dynamic service, see Static and Dynamic Services.

Debugging JS Services

To debug a JS service, Node’s Inspector is used. (Not to be confused with the legacy node-inspector, which has been deprecated as of Node 7.7.0. See Legacy Debugger for details.)

By communicating with the Inspector clients on the host machine, Node’s Inspector lets you observe the values of variables and control the JavaScript execution. For more information on Node.js debugging using the Inspector, refer to the Node.js Debugging Guide.

To enable the Inspector on a webOS OSE device, use the ares-inspect command. For detailed usage of the command, see ares-inspect.

General Usage:

$ ares-inspect --device <TARGET_DEVICE> --service <SERVICE_ID>

To start debugging the JS service, open a client tool, such as Chrome DevTools and Visual Studio Code, and connect to the Inspector. For a list of tools that can connect to Node’s Inspector, see Inspector Clients.

The following shows an example screenshot of debugging with Chrome DevTools and Node’s Inspector.