The Tizen Web application configuration file is composed of XML elements, including the <widget> element as its root and other elements. These elements represent application information, such as configuration elements and Tizen extending configuration elements for mobile and wearable applications.
This configuration information is used when you install or run the Tizen Web application on the Tizen platform. The Tizen Web application project must have the config.xml file in the project root directory.
The configuration file can be easily edited with the Web application configuration editor (form editor), or you can modify the XML structure directly using the configuration source editor. With the form editor, you can set the project configuration (manifest), even if you have no experience with developing a Tizen Web application project. If you are fluent with the configuration file XML structure, you can create the configuration file directly through the configuration source editor.
Note
The config.xml must conform to both the XML file format and the W3C specification requirements. Editing the file XML structure with the configuration source editor is intended for advanced users only.
Editing the config.xml File
There are 2 different ways to edit the config.xml file:
Use the Source tab:
Double-click the config.xml file in the Project Explorer view.
Select the Source tab.
Figure: Source tab
Use the form tabs:
Double-click the config.xml file in the Project Explorer view.
Select one of the form tabs (Overview, Features, Privileges, Localization, Policy, Preferences, Tizen).
Figure: Form tabs
Configuration Element Hierarchy
The Tizen Web application configuration file consists of XML elements organized in a hierarchy. The following tree structure shows the relationship between the elements of the config.xml file.
Note
The extension elements are denoted as though the xmlns:tizen="http://tizen.org/ns/widgets" namespace declaration is in effect.
The maximum length of the attribute and the element (except <tizen:metadata>, W3C preference element) can be limited to 2048 bytes. In this case, leftover bytes are ignored.
Tizen Account
<tizen:account/> element
Used to register account provider information.
Occurrences:
0 or more
Expected children:
icon
Mandatory. Since the icons are used on the device under Settings > Accounts, place them in a shared directory.
Attributes:
Account: File path of the account provider icon. The icon size is 72 x 72 pixels.
AccountSmall: File path of the account provider small icon. The icon size is 45 x 45 pixels.
display-name
Mandatory; display name of the account provider
capability
Optional; capability of the account provider. Capabilities are defined in the http://<VENDOR_INFORMATION>/accounts/capability/<NAME> IRI format.
Used to indicate that the Web application can handle a specific operation with the specified MIME type and URI. For more information, see Application Information and Controls.
Occurrences:
0 or more
Expected children:
src
Attributes:
name
Mandatory; page handling the requests
reload
Optional; sets whether the page is reloaded when it is already loaded (available values: enable (default), disable)
Since: 2.4
Note
The reload attribute is supported since Tizen 2.4. If the required_version in the application's config.xml file is set to a version older than Tizen 2.4, and the reload attribute is used, the application installation fails.
operation
Mandatory; string that defines the action to be performed
uri and mime
Optional; additional parameters used for resolving application control requests
privilege
Optional; additional parameter used for getting required API access privileges for application control requests
Mandatory; Tizen application ID, which is a combination of the Tizen package ID and project name. The application ID is unique among applications on the device.
The project name is a set of characters (0~9, a~z, A~Z) randomly generated by Tizen Studio. The minimum value is 1 byte and the maximum value is 52 bytes.
package
Mandatory; Tizen package ID generated by Tizen Studio, consisting of 10 characters (0~9, a~z, A~Z). The package ID is unique in Tizen Store.
required_version
Mandatory; Tizen API version required for running the Web application
launch_mode
Optional; sets which launch mode is supported (available values: single (default), group, caller)
single: launched as a main application
group: launched as a sub application
caller: caller application defines the launch mode with the app_control_set_launch_mode() method
Since: 2.4
Note
The launch_mode attribute is supported since Tizen 2.4. If the required_version in the application's config.xml file is set to a version older than Tizen 2.4, and the launch_mode attribute is used, the application installation fails.
Used to point to a document which is hosted on an external server and acts as the Web application start page. The Tizen WRT allows the start page to be hosted on an external server.
If the start page is contained in the widget package, it is defined with the <content> W3C element. If both <content> and <tizen:content/> elements are defined, the <tizen:content/> element is used.
Occurrences:
0 or more
If more than 1 <tizen:content/> element is specified, the first instance of the element is used.
Attributes:
src
Mandatory; URI of the external start page
Example:
<tizen:content src="https://www.tizen.org/"/>
Tizen Content Security Policy
<tizen:content-security-policy/> element
Used to define an additional content security policy for a packaged or hosted application.
Used to define hardware and software components for a Tizen application. This attribute is only used in Tizen Store for filtering purposes. It is ignored by the Web Runtime installation procedure.
Note
Even though the <feature/> element is defined in the Widget Packaging and XML Configuration guidelines, an extended version is used in Tizen.
Used to define metadata information shared with other Web applications. The defined metadata can be accessed (read-only) through the Tizen Application API.
Occurrences:
0 or more
Attributes:
key
Mandatory; unique key string.
The maximum length can be limited to 80 bytes. In this case, leftover bytes are ignored.
value
Optional; string.
The maximum length can be limited to 8192 bytes. In this case, leftover bytes are ignored.
If the system auto rotation setting is on, the Web application viewport orientation is changed accordingly by default.
context-menu
Optional; context menu is displayed when the user clicks, for example, an image, text, or link (available values: enable (default), disable)
background-support
Optional; application execution continues when it is moved to the background (available values: enable (execution continues in the background), disable (default; application is suspended))
Note
Since Tizen 2.4, the system manages background processes more tightly. Even if the background-support attribute is set to enable, a Web application process can be suspended in the background. To guarantee that the application runs in the background, add at least one background category for the application with the <tizen:background-category> element. Only the background categories declared in the system can be used.
encryption
Optional; Web application resources (HTML, JavaScript, and CSS files) are stored encrypted (available values: enable, disable (default))
install-location
Optional; application installation location (available values: auto (default), internal-only, prefer-external)
auto: the system defines the installation location
internal-only: the application is installed in the device's internal storage
prefer-external: the application is installed in the external storage (if available)
hwkey-event
Optional; a hardware key event is sent to the Web application when the user presses the hardware key (available values: enable (default), disable)
If this option is enabled, the tizenhwkey custom event is sent to the Web application. The tizenhwkey event object has a keyName attribute (available values: menu and back).
Example:
<!--Viewport orientation is locked to "landscape"-->
<tizen:setting screen-orientation="landscape"/>
<!--Context menu is not displayed-->
<tizen:setting context-menu="disable"/>
<!--Web application execution is not suspended-->
<!--when the application is sent to the background-->
<tizen:setting background-support="enable"/>
<!--Web applications resources are stored encrypted by the WRT-->
<tizen:setting encryption="enable"/>
<!--Installation location is set to "internal-only"-->
<tizen:setting install-location="internal-only"/>
<!--Hardware key event is sent to the Web application when the hardware key is pressed-->
<tizen:setting hwkey-event="enable"/>
Tizen Trust-anchor
<tizen:trust-anchor/> element
Used to assign your own SSL root certificates for the application's HTTPS communication.
Occurrences:
0 or 1
Attributes:
use-system-certs
Mandatory; indicates whether system certificates are used (available values: true, false)
Example:
<tizen:trust-anchor use-system-certs="false"/>
Extending Configuration Elements in Wearable Applications
The extension elements are denoted as though the xmlns:tizen="http://tizen.org/ns/widgets" namespace declaration is in effect.
The maximum length of the attribute and the element (except tizen:metadata, W3C preference element) can be limited to 2048 bytes. In that case, leftover bytes are ignored.
Tizen Account
<tizen:account/> element
Used to register account provider information.
Occurrences:
0 or more
Expected children:
display-name
Mandatory; display name of the account provider
capability
Optional; capability of the account provider. Capabilities are defined in the http://<VENDOR_INFORMATION>/accounts/capability/<NAME> IRI format.
Used to indicate that the Web application can handle a specific operation with the specified MIME type and URI. For more information, see Application Information and Controls.
Occurrences:
0 or more
Expected children:
src
Attributes:
name
Mandatory; page handling the requests
reload
Optional; sets whether the page is reloaded when it is already loaded (available values: enable (default), disable)
Since: 2.4
Note
The reload attribute is supported since Tizen 2.4. If the required_version in the application's config.xml file is set to a version older than Tizen 2.4, and the reload attribute is used, the application installation fails.
operation
Mandatory; string that defines the action to be performed
uri and mime
Optional; additional parameters used for resolving application control requests
privilege
Optional; additional parameter used for getting required API access privileges for application control requests
Mandatory; unique ID of the Web widget in the <TIZEN_APPLICATION_ID>.<STRING> format, where <STRING> consists of 1 or more characters (0~9, a~z, A~Z)
primary
Mandatory; defines a primary Web widget among the Web widgets in a Web application (available values: true, false)
max-instance
Optional; limits the number of widget instances concurrently executable for a Web application. When omitted or its value is 0, unlimited number of widget instances are supported. The expected value is integer.
Mandatory; local file path, relative to the source Web application directory of the widget starting page
<tizen:widget-size/> element
Used to define the size of the Web widget.
Occurrences:
1
Attributes:
preview
Mandatory; image file path, relative to the source Web application directory of the box content displayed in the widget viewer
<tizen:widget-metadata/> element
Used to define a (key, value) pair that can be read by a Web widget through the WidgetService API. Its main use is to allow you to define a constant to be read by a Web widget.
Occurrences:
1 or more
Attributes:
key
Mandatory; string.
value
Mandatory; string.
Tizen App-defined Privilege
<tizen:appdefined-privilege/> element
Used to get the required access privileges provided by a provider package.
Occurrences:
0 or more
Attributes:
name
Mandatory; name of the app-defined privilege
license
Optional; name of the license file used to verify the privilege
Used to uniquely identify a Tizen wearable application.
Occurrences:
1
Attributes:
id
Mandatory; Tizen application ID, which is a combination of the Tizen Wearable package ID and project name. The application ID is unique among applications on the device.
The project name is a set of characters (0~9, a~z, A~Z) randomly generated by Tizen Studio. The minimum value is 1 byte and the maximum value is 52 bytes.
package
Mandatory; Tizen wearable package ID generated by Tizen Studio, consisting of 10 characters (0~9, a~z, A~Z). The package ID is unique in the Samsung Apps.
required_version
Mandatory; Tizen API version required for running the Web application
ambient_support
Optional; sets whether the Web application supports the ambient mode (available values: enable, disable (default))
If this option is enabled, the application can be shown in the ambient mode.
Since: 2.3.1
Note
The ambient_support option is only used for watch applications, and ignored in all non-watch applications.
The ambient_support attribute is supported since Tizen 2.3.1. If the required_version in the application's config.xml file is set to a version older than Tizen 2.3.1, and the ambient_support attribute is used, the application installation fails.
launch_mode
Optional; sets which launch mode is supported (available values: single (default), group, caller)
single: launched as a main application
group: launched as a sub application
caller: caller application defines the launch mode with the app_control_set_launch_mode() method
Since: 2.4
Note
The launch_mode attribute is supported since Tizen 2.4. If the required_version in the application's config.xml file is set to a version older than Tizen 2.4, and the launch_mode attribute is used, the application installation fails.
Used to define the hardware and software components for a Tizen wearable Web application. This attribute is only used in the Samsung Apps for filtering purposes. It is ignored by the Web Runtime installation procedure.
Note
Even though the <feature/> element is defined in the Widget Packaging and XML Configuration guidelines, an extended version is used in Tizen.
Used to define the properties of an IME (Input Method Editor) type application, which is used when you want to create your own keyboard module for the Tizen platform.
Note <tizen:category name="http://tizen.org/category/ime"/> must be defined to activate <tizen:ime>.
Occurrences:
0 or 1
Expected children:
uuid
Mandatory; universally unique, a unique identifier that distinguishes an IME from each other, displayed in the form of a standard UUID (8-4-4-4-12 for a total of 36 characters)
languages
Mandatory; list of input languages that the current IME supports
Note <tizen:language/> elements are provided as the child elements of this element.
Used to define metadata information shared with other Web applications. The defined metadata can be accessed (read-only) through the Tizen Application API.
Occurrences:
0 or more
Attributes:
key
Mandatory; unique key string.
The maximum length can be limited to 80 bytes. In that case, leftover bytes are ignored.
value
Optional; string.
The maximum length can be limited to 8192 bytes. In that case, leftover bytes are ignored.
Mandatory; Tizen service ID, which is a combination of the Tizen wearable package ID and service name.
The service ID is a set of characters (0~9, a~z, A~Z) and unique among service applications on the device. The minimum value is 1 byte and the maximum value is 52 bytes.
on-boot
Optional; sets whether the service application is launched automatically on device boot (available values: true, false (default))
Note
This attribute is not supported on Tizen wearable devices. Since Tizen 2.4, this attribute is not supported on all Tizen devices.
auto-restart
Optional; sets whether the service application is relaunched automatically when it is terminated (available values: true, false (default))
Note
This attribute is not supported on Tizen wearable devices. Since Tizen 2.4, this attribute is not supported on all Tizen devices.
Used to define the start page of the Web service application.
Occurrences:
1
Attributes:
src
Mandatory; start JavaScript file path of the Web service application. The path is relative to the source Web application directory.
<tizen:name/> element
Used to define the name of the Web service application.
Occurrences:
1 or more
Attributes:
xml:lang
Optional; specifies the language of the service name (for available values, see the IANA Language Subtag)
<tizen:icon/> element
Used to define the icon for the Web service application.
Occurrences:
0 or 1
Attributes:
src
Mandatory; file path of the Web service application icon. The path is relative to the source Web application directory.
<tizen:description/> element
Used to define the description for the Web service application.
Occurrences:
0 or 1
<tizen:metadata/> element
Used to define metadata information shared with other Web applications. The defined metadata can be accessed (read-only) through the Tizen Application API.
Occurrences:
0 or more
Attributes:
key
Mandatory; unique key string
value
Optional; string
<tizen:category/> element
Used to define the categories that the service application belongs to.
Occurrences:
0 or more
Attributes:
name
Mandatory; string
Tizen Settings
<tizen:setting/> element
Used to define additional application settings.
Occurrences:
0 or more
Attributes:
background-support
Optional; application execution continues when it is moved to the background (available values: enable (execution continues in the background), disable (default; application is suspended))
Note
Since Tizen 2.4, the system manages background processes more tightly. Even if the background-support attribute is set to enable, a Web application process can be suspended in the background. To guarantee that the application runs in the background, add at least one background category for the application with the <tizen:background-category> element. Only the background categories declared in the system can be used.
context-menu
Optional; sets whether the context menu is shown (available values: enable (default), disable)
If this option is enabled, the context menu is visible to the user.
encryption
Optional; sets whether Web application resources are encrypted (available values: enable, disable (default))
If this option is enabled, the application resources (HTML, JS and CSS files) are encrypted.
screen-orientation
Optional; sets whether it locks the orientation of the Web application (available values: portrait (default), landscape, auto-rotation)
portrait or landscape: orientation is locked to portrait or landscape respectively
auto-rotation: follows the device orientation setting
install-location
Optional; application installation location (available values: auto (default), internal-only, prefer-external)
auto: the system defines the installation location
internal-only: the application is installed in the device's internal storage
prefer-external: the application is installed in the external storage (if available)
hwkey-event
Optional; a hardware key event is sent to the Web application when the user presses the hardware key (available values: enable (default), disable)
If this option is enabled, the tizenhwkey custom event is sent to the Web application. The tizenhwkey event object has a keyName attribute (available value: back).