Developing Downloadable Web Apps

A downloadable web app is a 3rd party web app that can be installed on the webOS target device.

Downloadable vs. Built-In

In webOS OSE, apps and services are divided into two categories: downloadable and built-in.

  • Downloadable apps/services are installed by appinstalld service. This service automatically generates several configurations for the apps/services. (such as trust level)
  • Built-in apps/services are built and installed by developers. Developers can customize configurations to suit their needs.

This tutorial shows a step-by-step guide for creating a downloadable web app from scratch.

Prerequisites

Before you begin, you must install the Command-Line Interface (CLI).

The CLI enables you to create, install, and launch apps or services using in a command-line environment.

Note
If you already installed Node.js & CLI and registed your target device, you can skip this section.
  1. Install Node.js (Recommended version: v16.20.2).

  2. Install the CLI.

    sudo npm install -g @webos-tools/cli
    
  3. Change the profile.

    ares-config --profile ose
    
  4. After installing the CLI, you must register your target device. Enter the ares-setup-device command to start an interactive mode:

    Note
    In the interactive mode, pressing the Enter key means to use the default value.
    document@document:~$ ares-setup-device
    name                deviceinfo                connection  profile
    ------------------  ------------------------  ----------  -------
    emulator (default)  developer@127.0.0.1:6622  ssh         ose
    
    
    ** You can modify the device info in the above list, or add new device.
    ? Select add                             # Select 'add'.
    ? Enter Device Name: webos               # The nickname of your target device. Use the short name.
    ? Enter Device IP address: 127.0.0.1     # The IP address of your target device
    ? Enter Device Port: 22                  # Just press the Enter key. Do not change this value.
    ? Enter ssh user: root                   # Just press the Enter key. Do not change this value.
    ? Enter description: new device          # Descriptions about your target device
    ? Select authentication password         # Select 'password'
    ? Enter password: [hidden]               # Leave it blank (Press the Enter key).
    ? Set default ? No                       # Enter 'y' if you want to set this device as the default device.
    ? Save ? Yes                             # Enter 'Yes'.
    
    name                deviceinfo                connection  profile
    ------------------  ------------------------  ----------  -------
    webos                root@127.0.0.1:22        ssh         ose
    emulator (default)  developer@127.0.0.1:6622  ssh         ose
    

Step 01. Creating a Dummy App

Let’s get started by creating a dummy app from templates. CLI provides various templates for webOS apps and services.

Enter the following command:

# Comannd format
# ares-generate -t <TEMPLATE TYPE> <YOUR APP NAME>
ares-generate -t webapp sampleApp

If the command succeeds, the following directory will be generated under the current directory:

sampleApp/
|---- appinfo.json
|---- icon.png
|---- index.html

Descriptions for each file are as follows:

FileDescription
appinfo.jsonMetadata for the web app. For more details, see appinfo.json.
icon.pngAn image for the app icon displayed on the app bar
index.htmlThe main page of the web app

Step 02. Packaging the App

To install the app, you have to package the app first.

Enter the following command:

# Command format
# ares-package <APP DIRECTORY>
ares-package sampleApp

If the command succeeds, an .ipk file will be generated under the current directory.

# Generated .ipk file
com.domain.app_1.0.0_all.ipk

Step 03. Installing the App

It’s time to install your package to the target device.

Enter the following command:

# Command format
# ares-install --device <TARGET DEVICE> <PACKAGED APP>
ares-install --device webos com.domain.app_1.0.0_all.ipk

Step 04. Launching the App

To launch the installed app, enter the following command:

# Command format
# ares-launch --device <TARGET_DEVICE> <APP ID>
ares-launch --device webos com.domain.app

If the command succeeds, the following string will be displayed:

Debugging the App

Using Chrome

You can use the Chrome DevTools to debug and monitor the runtime status of web apps. It allows you to control JavaScript execution, inspect the web pages’ CSS and HTML code, and monitor resource usage. Old versions of Chrome might not support the DevTools.

To debug your app, enter the following command:

# Command format
# ares-inspect --device <TARGET DEVICE> --app <APP ID> --open
 
ares-inspect --device webos --app com.domain.app --open
[Info] Set target device : testdevice
# This URL is for the DevTools page
Application Debugging - http://localhost:40709/devtools/inspector.html?ws=localhost:40709/devtools/page/1E2113E4B12042E37916985F86B5B378

If the command succeeds, the DevTools page will be launched.

Web Inspector screenshot

Note
Web 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.

Using ares-server

ares-server runs a web server based on files in the specified directory.

Originally, web browsers’ security policies restrict access to local files during debugging sessions. ares-server bypasses these policies so the user can access the local files.

Enter the following command:

# Command format
# ares-server <APP DIRECTORY> [--open]
# --open is optional.
# This option opens the debugging window directly on the default browser.
 
ares-server ./sampleApp --open
 
Local server running on http://localhost:43527 # Check the URL address

Appendix. Code Explanation

This section briefly explains the sample codes used in this tutorial.

appinfo.json

appinfo.json stores the app’s metadata.

{
    "id": "com.domain.app",    # ID of the app. This ID will be used as a unique identifier for the app.
    "version": "1.0.0",
    "vendor": "My Company",
    "type": "web",             # Type of the app
    "main": "index.html",      # The HTML file that contains the contents of your app
    "title": "new app",        # This string will be displayed on the app bar
    "icon": "icon.png",        # A path to an image for your app icon
    "requiredPermissions": ["time.query", "activity.operation"]   # ACG values for the app
}

index.html

index.html is an HTML file that contains the content of your web app.

You can use another file name, but if you do so, you’ll also need to update the main in appinfo.json.

The template codes will print “Hello, Web Application!!” on the screen. (The dummy app also has code for JavaScript services, but they won’t be used in this tutorial.)

Contents