Developing External JS Services

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

Creating JS Services

JS services can be created and deployed using CLI commands that are provided by webOS OSE SDK. This topic describes the steps to create an external JS service. For detailed information on the commands, see Command-Line Interface.

Once you generate the service, JS service directory should be configured as below.

JS service directory structure

JS service directory structure

  • APP_DIR: Directory of the web app.
  • SERVICE_DIR: Directory of the service. This directory will include sub-directories of the services that are included in the web app.

Developing an external JS service requires the following steps:

Step 1: Create a JS Service Project

Start by creating a project 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.
Note
When prompted to enter the service name, make sure the service name begins with the app ID. If you do not follow this naming rule, the service packaging does not work normally. So, for example:

  • If web app ID is com.domain.app
  • Then, service name must be com.domain.app.myservice

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

File

Description

helloclient.js

Sample JS service which subscribes helloworld_webos_service.js service. This sample shows how to communicate between services.

helloworld_webos_service.js

Sample JS service which provides several simple commands. These commands are specified in the services.json file.

package.json

Configuration file of NPM. For details, see https://docs.npmjs.com/getting-started/using-a-package.json.

services.json

Configuration file that defines what commands the service provides on the webOS bus.

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 (luna://com.domain.app.myservice/hello) which responds to a request with a “Hello, World!” message.

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

service.register("Hello", function(message) {
    message.respond({
        Response: "Hello, World " + message.payload.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.myservice",
    "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 web app ID. So, if web app ID is com.domain.app, the service name must be com.domain.app.myservice.

  • 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 https://docs.npmjs.com/files/package.json.

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.myservice",
    "description": "Sample helloworld service",
    "services": [{
        "name": "com.domain.app.myservice",
        "description": "Sample helloworld service"
    }]
}

Step 4: Package the JS Service

The JS service must be packaged along with the web app.

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

Note
If the JS service uses methods of external services, you must add the group information of the external methods to the requiredPermission field in appinfo.json of the web app used for packaging the JS service. See Configuring the Web App for details.

Step 5: Install the JS Service

The JS service must be installed along with the web app.

For details on packaging the web app, see Installing the Web App.

About launching the JS service
Because external JS services are installed as a dynamic service type, the service becomes active only when another application or service use the service by calling its method. If its method has been called as subscription, the service remains active without exiting. If the service is not used, it exits after 5 seconds. For more information on the 5-second timeout, see FAQ.

Debugging JS Services

You can use the Node Inspector to debug JS services by monitoring the run-time status of a JS service that is running on a target device. The Node Inspector allows you to observe the values of variables and to control JavaScript execution. For more information about Node Inspector, refer to the GitHub of Node Inspector.

To launch the Node inspector on a webOS OSE device, you must execute the ares-inspect command while the JS service is running. For detailed information on the command, see ares-inspect.

General Usage:

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

This loads the Node Inspector in your default browser as shown below:

Node Inspector screenshot

Node Inspector screenshot

Note
Node Inspector works only in Blink-based web browsers such as Chrome and Opera. If another browser (e.g., Safari or Internet Explorer) is set as your default web browser, you must re-open the inspector page in a Blink-based web browser.

Contents