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.
|
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"
|
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.
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.
This property is available only in webOS TV v1.x and v2.x. In later versions, it is ignored. |
Optional |
boolean |
Whether to close your app when the screen is rotated vertically. This property is applied to the StanbyME model only.
|
|
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.
|
|
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.
|
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:
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. |
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". |
|
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.
|
|
Optional |
boolean |
Whether the app supports portrait mode. This property is applied to the StanbyME model only.
|
|
Optional |
string |
Mode of handling touch events. This property is applied to the StanbyME model only.
|
|
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.
|
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.
|
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.
|
positionEventOnPress |
Optional |
boolean |
Whether to send a touch press (shorter than 200ms) event as a mouse position 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.
|
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:
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.