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:
Configuration file that describes how the service is constructed and operates. See services.json for details.
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 app ID is com.domain.app
Then, service name must be com.domain.app.service
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 +"!" });
});
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.
Packaging and installing processes are the same for all types of apps.
If the JS service uses methods of external services, you must add the group information of the external methods to the requiredPermissions field in appinfo.json of the 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 app.
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.
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.