App Metadata

The webOS TV Platform uses app metadata to identify an app and acquire other information required to install and run the app. So, before packaging your app, you must write metadata of the app in a file called appinfo.json. The appinfo.json file is located in your app's root directory and contains a single JSON object.

Here are a few tips that might help you with JSON syntax.

Do not include any comments (/* or //) .
Use double quotes, not single quotes, around properties.

appinfo.json Reference

Example

{
    "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",
    "closeOnRotation": false
    "disableBackHistoryAPI": false,
    "handlesRelaunch": false,
    "splashBackground": "AppName_Splash.png",
    "splashColor": "#111111",
    "splashFitModeOnPortrait": "width",
    "requiredMemory": 20,
    "supportPortraitMode": true,
    "supportTouchMode": "virtual",
    "transparent": false,
    "virtualTouch": {
        "verticalThreshold": 20,
        "horizontalThreshold": 50,
        "positionEventOnPress": true,
        "shortTouchThreshold": 30
    },
}

Property descriptions

Property	Required	Type	Description
icon	Required	string	Small app icon of your app, 80x80 pixels and in PNG format. The file path must be relative to the appinfo.json file. The small icon file is required for app submission and used for app testing only. In LG Content Store, the icon file of 400x400 pixels that you upload separately at LG Seller Lounge is used, instead of this property, after being auto-resized.
id	Required	string	App ID, i.e., "com.newco.app.myapp". Every app MUST have a unique ID, formed according to the reverse DNS naming conventions. The Launcher uses this ID to identify your app and displays it with the title. The app ID cannot be changed once the app is published. Must create an ID only with lowercase letters (a-z), digits (0-9), minus signs, and periods. It must start with an alphanumeric character and be at least two characters long. Must not start with the following reserved 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	Large app icon of your app, 130x130 pixels and in PNG format. The file path must be relative to the appinfo.json file. The large icon file is required for app submission and used for app testing only. In LG Content Store, the icon file of 400x400 pixels that you upload separately at LG Seller Lounge is used, instead of this property, after being auto-resized.
main	Required	string	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.
title	Required	string	App title to be shown on 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	App type. Only "web" is allowed.
vendor	Required	string	App owner to be used in the launcher and deviceinfo dialogs.
version	Required	string	App version number, comprised of three non-negative integers separated by period. The default value is "1.0.0" DO NOT contain leading zeroes. Example: "2.1.0" (not "002.1.0") The major, minor, and revision numbers are all mandatory; if any is missing, the app may not be installed. Example: "2.1.0" (not "2.1") Each number can have up to nine digits. In other words, the maximum version possible 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". Once you upload a certain version of your app on the LG Content Store, you cannot upload the same version again. To upload the app, you must increase the version number.
appDescription	Optional	string	Brief information about your app. Think of this as a short tagline for the app. It cannot exceed 60 characters.
bgColor	Optional	string	Background color of your app to be displayed on the Launcher. It is used if the bgImage is not provided or unavailable. You can specify the color in a hex value or with an HTML color name. Example: "bgColor":"#5e70a2, "bgColor":"#ffffff" This property is available only in webOS TV v1.x and v2.x. In later versions, it is ignored.
bgImage	Optional	string	Background image of your app to be displayed when activated on 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 available only in webOS TV v1.x and v2.x. In later versions, it is ignored.
closeOnRotation	Optional	boolean	Whether to close your app when the screen is rotated vertically. This property is applied to the StanbyME model only. false (default) – Your app runs regardless of whether the screen is rotated. true - Your app will be closed with a notice when the screen is rotated vertically.
disableBackHistoryAPI	Optional	boolean	Whether your app receives the back button event when the back button is pressed on Magic Remote. For more information about this property, see Back Button. false (default) - Your app does not receive the back button event. Instead, the webOS TV Platform manages the history using standard HTML history API such as history.pushState(), history.back(), and popState event. true - Your app receives the back button event. You should implement how to process the back button event in your app.
handlesRelaunch	Optional	boolean	Whether your app handles the webOSRelaunch event. When your app is re-launched, a webOSRelaunch event occurs, and the webOS TV Platform passes the webOSRelaunch event to your app. Then, depending on the value of this handlesRelaunch property, your app either handles the event on its own or not. false (default) - Your app does not handle the webOSRelaunch event. The webOS TV Platform automatically displays your app in the full-screen mode. true - Your app handles the webOSRelaunch event in the background for a while and then, comes to the foreground by calling the PalmSystem.activate() method. See App Lifecycle for more details.
iconColor	Optional	string	Background color for your app tile. The app tile is displayed on the Home screen, Launcher, and Recents. The default value is "white".
requiredMemory	Optional	number	Minimum amount of memory in megabytes required to run your app. This does not need to be the same as the maximum memory usage consumed by your app.
resolution	Optional	string	App resolution for graphics display of your app. webOS TV does not support UHD resolution for web apps. Supported resolutions are: "1920x1080" (default) - FHD resolution "1280x720" - HD resolution To get the app resolution for graphics display, use window.innerWidth and window.innerHeight properties.
splashBackground	Optional	string	Background image to be displayed while your app is being loaded. 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.
splashColor	Optional	string	Background color (RGB) of the splash image. The default value is “gray”. This property is applied to the StanbyME model only. You can set the color by specifying a hexadecimal (hex) value or an HTML color name. For example, the following values are acceptable: "#000000" and "black".
splashFitModeOnPortrait	Optional	string	Fit mode for the splash image in portrait mode. It works only if your app supports portrait mode. This property is applied to the StanbyME model only. “none” (default) - The splash image is displayed in its original size. “width” - The splash image is resized to fit the width of the screen.
supportPortraitMode	Optional	boolean	Whether the app supports portrait mode. This property is applied to the StanbyME model only. false (default) - Your app does not support portrait mode. true – Your app supports portrait mode. The splash image is displayed with the background color set by the splashColor property.
supportTouchMode	Optional	string	Mode of handling touch events. This property is applied to the StanbyME model only. “none” (default) – Your app does not support touch input. If a touch event occurs, nothing is sent to your app. “full” - Your app supports touch input. You can implement event handlers for touch inputs using the standard web API. “virtual” - If a touch event occurs, the webOS TV Platform sends it to your app as a keyboard or mouse event.
transparent	Optional	boolean	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.
virtualTouch	Optional	object	This object is for an app whose value of supportTouchMode is “virtual”, defining the details for how to convert touch inputs into a keyboard or mouse events. This property is applied to the StanbyME model only. For more information, including the default settings, see virtualTouch object.

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.

The properties listed below in the appinfo.json file are required for submission of your app to the LG Content Store (LG Store). Make sure these properties are properly specified.

id
title
type
main
largeIcon

Object Description

virtualTouch Object

Property	Required	Type	Description
verticalThreshold	Optional	number	The threshold (10-100 px) that triggers an event for touch and drag in the vertical direction. If a user touches the screen and moves over the threshold value, it is considered a drag operation, and a key event occurs. This is, if you set the threshold value small, a key event in the vertical direction (up, down) occurs even with a short swipe. Therefore, the smaller you set the threshold, the more key events occur when a user swipes the screen at the same length. The default value is 40. When smaller than 10, it is set to 10. When bigger than 100, it is set to 100.
horizontalThreshold	Optional	number	The threshold (10-100 px) that triggers an event for touch and drag in the horizontal direction. If a user touches the screen and moves over the threshold value, it is considered a drag operation, and a key event occurs. This is, if you set the threshold value small, a key event in the horizontal direction (left, right) occurs even with a short swipe. Therefore, the smaller you set the threshold, the more key events occur when a user swipes the screen at the same length. The default value is 40. When smaller than 10, it is set to 10. When bigger than 100, it is set to 100.
positionEventOnPress	Optional	boolean	Whether to send a touch press (shorter than 200ms) event as a mouse position event. false (default) – A touch press event is not sent to your app, but a touch release event is sent to your app as a key or mouse event. true - A touch press event is sent to your app as a mouse position event, and a touch release event is sent to your app as a key or mouse event.
shortTouchThreshold	Optional	number	The click threshold (10-50 px) to be recognized as short touch (like a click). It is considered a click if a dragging distance is less than the shortTouchThreshold value. Swiping more than the shortTouchThreshold value will not send a click event to your app. The default value is 10. When smaller than 10, it is set to 10. When bigger than 50, it is set to 50.

Localizing app metadata

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 and correct the values and structure, make sure that the app ID and version in each localized appinfo.json file are the same as those in the top-level appinfo.json file. Any app that fails validation cannot be packaged or uploaded.

Depending on the locale settings, the matching app information is displayed on the launcher and the Home screen.

To add app information in a specific locale, you need to first create a locale folder under the resources folder and then write an appinfo.json file under the correct location 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, your app can display its title and description in different languages. All other properties are kept the same as the top-level appinfo.json file.

{
    "title": "Translated app title"
    "appDescription": "Translated app description",
}

In the appinfo.json file for localization, you should 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 top-level appinfo.json file is loaded into the system memory of webOS TV first, and then other appinfo.json files are overridden depending on the locale setting.