App Metadata

You must write metadata of your app in a file called appinfo.json before packing the app. webOS TV use metadata to identify your app, its icon, and other information that are needed to launch and run the app. The appinfo.json file is located in your app's root directory and contains a single JSON object.

Here are little tips that might help you with JSON syntax:

  • Do not include any comments (/* or //) in JSON files.

  • Use double quotes around the properties--no single quotes.

LG Content Store Requirements

You must specify the following appinfo.json properties when submitting your app to the LG Content Store (LG Store).

  • id

  • title

  • type

  • main

  • largeIcon

See appinfo.json reference section for details of these required properties.

Localizing App Metadata

If you want to localize your app into more than one language, you need to write additional appinfo.json files per each language. Because the app ID and version in the top-level appinfo.json are used to validate for correcting value and structure, make sure that the app ID and version in each localized appinfo.json are the same as those in the top-level appinfo.json. Any app that fails the validation cannot be packaged or uploaded.

According to the locale setting value, the app metadata localization shows the matching app information at the launcher and the home screen.

To provide app information in a specific locale, you need to create locale folders under the resources folder, then appinfo.json files for each locale under correct locations as shown below:

Directory structure and appinfo.json files for localizing app metadata

The locale consists of Language, Script, and Country/Region information. (e.g., ko-KR, mn-Cy-MN)

With additional appinfo.json files, you can provide your app title and description in various languages. All other properties are kept the same as the default appinfo.json file in the root of the project.

{
    "title": "Translated app title"
    "appDescription": "Translated app description",
}
  • In the appinfo.json file for localization, you should only fill appDescription and title properties.

  • If you use non-Latin letters (non-ASCII) in the appinfo.json file, you should save the file in UTF-8 without BOM format.

When the locale value is changed after adding an appinfo.json file corresponding to the locale information, the appinfo.json file in the app root directory is loaded into the system memory of webOS TV first. Then the other appinfo.json files are overridden depending on the locale setting.

appinfo.json Reference

Schema

{
	"id": "com.myco.app.appname",
	"title": "AppName",
	"main": "index.html",
	"icon": "AppName_80x80.png",
	"largeIcon": "AppName_130x130.png",
	"type": "web",
	"vendor": "My Company",
	"version": "1.0.0",
	"appDescription": "This is an app tagline",
	"resolution": "1920x1080",
	"bgColor": "red",
	"iconColor": "red",
	"bgImage": "AppName_Preview.png",
	"splashBackground": "AppName_Splash.png"
	"transparent": false, 
	"handlesRelaunch": false,
        "disableBackHistoryAPI": false,
	"requiredMemory": 20
}

Property Descriptions

Property

Required

Type

Description

icon

Required

string

The small app icon displayed for your app, 80x80 pixels, in PNG format.

The file path must be relative to the appinfo.json file.

The small icon file specified in this property is required for app submission and used for app testing only. In LG Content Store, the icon file of 400x400 pixels, you upload separately at LG Seller Lounge, is used instead of this property after auto-resizing.

id

Required

string

The app ID, i.e., "com.newco.app.myapp".

Every app MUST have a unique ID, formed from reverse DNS naming conventions. The launcher uses the ID to uniquely identify your app and displays it with the title. The app ID is set once and cannot be changed after publishing the app.

  • Must create the ID only with lowercase letters (a-z), digits (0-9), minus signs, and periods. It must be at least two characters long and must start with an alphanumeric character.

  • Cannot start with the following reverse domain names:
    com.palm, com.webos, com.lge, com.palmdts

  • Start the ID with a reverse domain of the company/institution. (Recommended)

  • Finish the ID with the subdomain app.app-name. (Recommended)

largeIcon

Required

string

The large app icon displayed for your app, 130x130 pixels and should be in PNG format.

The file path must be relative to the appinfo.json file.

The large icon file specified in this property is required for app submission and used for app testing only. In LG Content Store, the icon file of 400x400 pixels, you upload separately at LG Seller Lounge, is used instead of this property after auto-resizing.

main

Required

string

The launch point for your app.

The file path must be relative to the appinfo.json file and needs to point to an HTML file. The default is index.html.

splashBackground

Required

string

The background image path to be shown while your app is loading.

The path must be relative to the appinfo.json file. The file must be in PNG format, and the resolution should be 1920 x 1080.

title

Required

string

The app title that is shown in the Launcher and the app window.

You can use the HTML <title> element in your app for the subtitle. The app version or vendor name is recommended for the subtitle.

type

Required

string

The app type. Only "web" is allowed.

vendor

Required

string

The app owner that is used in the launcher and deviceinfo dialogs.

version

Required

string

The app version number, comprised of three non-negative integers in the format. The default value is "1.0.0"

  • DO NOT contain leading zeroes.

    ..
    e.g. "2.1.0" (not "2.1")
  • The major, minor, and revision numbers are all mandatory; otherwise, the app may not be installed. Each number can have up to nine digits. For example, the maximum version is "999999999.999999999.999999999".

  • The major, minor, and revision numbers are discrete. For example, "1.5.3" is a lower version than "1.15.3".

  • After uploading your app on the LG Content Store, you cannot upload the same version of your app again. To update and re-upload an app, you must increase the version number.

appDescription

Optional

string

The brief information about your app.

Think of this as a short tagline for the app. It cannot exceed 60 characters.

bgColor

Optional

string

The color of the app background in the Launcher.

It is displayed when the bgImage is not provided or unable to display. You can specify the color as a hex value or as an HTML color name.

  • Example: "bgColor":"#5e70a2, "bgColor":"#ffffff"

This property is only available in webOS TV v1.x and v2.x. This property is ignored from webOS TV v3.0 or later.

bgImage

Optional

string

The background image displayed for your app when activated in the Launcher.

The image must be in PNG format, and the image size must be 1920 x 1080 pixels. The file path must be relative to the appinfo.json file.

  • Example: "image/myappbgimage.png"

This property is only available in webOS TV v1.x and v2.x. This property is ignored in webOS TV v3.0 or later.

disableBackHistoryAPI

Optional

boolean

Set whether your app needs to receive the back key event when the back button of the remote control unit is pressed. For more information about this property, see Back Button.

  • false (default) - Your app does not need to receive the back key event. Instead, the webOS TV platform manages history using standard HTML history API such as history.pushState(), history.back(), and popState event.

  • true - Your app needs to receive the back key event. You should implement the method of how to process the back key event in your app.

handlesRelaunch

Optional

boolean

Determines how your web app handles the webOSRelaunch event.

The webOSRelaunch event occurs whenever your web app is re-launched irrespective of handlesRelaunch property value. webOS TV platform will pass the webOSRelaunch event to your app. This value determines whether the app can take background action or not.

If your app sets handlesRelaunch to:

  • false (default) - Your app does not handle the webOSRelaunch event. webOS TV platform will automatically display your app in the full-screen mode.

  • true - Your app needs to handle the webOSRelaunch event in the background for a while. Then, your app comes to the foreground by calling the PalmSystem.activate() method. See App Lifecycle for more details.

iconColor

Optional

string

The background color for your app tile.

The app tile is displayed in the Home, the Launcher, and the Recent screen. The default value is white.

requiredMemory

Optional

number

The maximum usage of memory, in megabytes, while your app is launching. This is not the same as the maximum memory usage while your app is running.

resolution

Optional

string

The screen resolution of your app.

webOS TV does not support UHD resolution for web apps. webOS TV supports the following resolutions:

  • "1920x1080": FHD resolution (default)

  • "1280x720": HD resolution

transparent

Optional

boolean

The app background that overlays the system background.

This property configures the transparency of the app's background. If you do not set the background color or background image, the system background (black color) is displayed.

  • false (default) - The transparency rate of the app background is decreased and the system background is shown as a little grey color.

  • true - The system background is displayed clearly.

enyoVersion, onDeviceSource, and onDeviceSource sub-properties are no longer supported for the following reasons.

  • These properties are not supported by webOS TV 4.0 or later.

  • For Enyo 2.6, these properties are not needed to implement apps. They are used only for Enyo v2.3 and v2.5.

Navigation