1# app.json5 Configuration File 2<!--Kit: Ability Kit--> 3<!--Subsystem: BundleManager--> 4<!--Owner: @wanghang904--> 5<!--Designer: @hanfeng6--> 6<!--Tester: @kongjing2--> 7<!--Adviser: @Brilliantry_Rui--> 8 9## Configuration File Example 10 11 12This topic gives an overview of the **app.json5** configuration file. To start with, let's go through an example of what this file contains. 13 14```json 15{ 16 "app": { 17 "bundleName": "com.application.myapplication", 18 "vendor": "example", 19 "versionCode": 1000000, 20 "versionName": "1.0.0", 21 "icon": "$media:layered_image", 22 "label": "$string:app_name", 23 "description": "$string:description_application", 24 "minAPIVersion": 9, 25 "targetAPIVersion": 9, 26 "debug": false, 27 "car": { 28 "minAPIVersion": 8 29 }, 30 "targetBundleName": "com.application.test", 31 "targetPriority": 50, 32 "appEnvironments": [ 33 { 34 "name":"name1", 35 "value": "value1" 36 } 37 ], 38 "maxChildProcess": 5, 39 "multiAppMode": { 40 "multiAppModeType": "multiInstance", 41 "maxCount": 5 42 }, 43 "hwasanEnabled": false, 44 "ubsanEnabled": false, 45 "cloudFileSyncEnabled": false, 46 "cloudStructuredDataSyncEnabled": false, 47 "configuration": "$profile:configuration", 48 "assetAccessGroups": [ 49 "com.ohos.photos", 50 "com.ohos.screenshot", 51 "com.ohos.note" 52 ], 53 "startMode": "mainTask" 54 } 55} 56``` 57## Tags in the Configuration File 58 59As shown above, the **app.json5** file contains several tags. 60 61 62 **Table 1** Tags in the app.json5 file 63 64| Name| Description| Data Type| Initial Value Allowed| 65| -------- | -------- | -------- | -------- | 66| bundleName | Bundle name, which uniquely identifies an application. The value must comply with the following rules:<br>- The bundle name contains at least three segments, separated by periods (.). Each segment can contain only letters, digits, and underscores (_).<br>- The first segment starts with a letter, and other segments start with a digit or letter. Each segment ends with a digit or letter.<br>- Consecutive periods (.) are not allowed.<br>- Contains 7 to 128 bytes.<br>You are advised to use the reverse domain name notation, for example, *com.example.demo*, where the first part is the domain suffix **com**, the second part is the vendor/individual name, and the third part is the application name, which can be of multiple levels.| String| No| 67| bundleType| Bundle type. The options are as follows:<br>- **app**: The bundle is an application.<br>- **atomicService**: The bundle is an atomic service.<br>- **shared**: The bundle is a shared library. This option is reserved.<!--Del--><br>- **appService**: The bundle is a system-level shared library and can be used only by system applications.<!--DelEnd--><br>- **appPlugin**: The bundle is the plugin package of an application. This field is supported since API version 19.| String| Yes (initial value: **app**)| 68| debug | Whether the application can be debugged.<br>- **true**: Can be debugged. Used in the development phase.<br>- **false**: Cannot be debugged. Used in the release phase.| Boolean| Generated by DevEco Studio during compilation and building. Yes (initial value: **false**)| 69| icon | Application icon. The value is the index to an icon resource file. Single-layer icons and layered icons can be configured. For details about the configuration rules and examples, see [Configuring Layered Icons](layered-image.md).| String| No| 70| label | Application name. The value is the index to a string resource with a maximum of 63 bytes, supporting multiple languages. For details, see [Configuring Layered Icons](layered-image.md).| String| No| 71| description | Description of an application. The value is a string of a maximum of 255 bytes, indicating the description string or the string resource index of the description. This field can be used to display application information on, for example, the **About** page.| String| Yes (initial value: left empty)| 72| vendor | Vendor of the application. The value is a string with a maximum of 255 bytes. This field can be used to display the vendor information on, for example, the **About** page.| String| Yes (initial value: left empty)| 73| versionCode | Version number of an application. The value ranges from 0 to 2147483647. It is used only to determine whether a version is later than another version. A larger value indicates a later version.<br>Ensure that a new version of the application uses a value greater than any of its predecessors.| Number| No| 74| versionName | Version number of the application displayed to users.<br>The value contains a maximum of 127 bytes and consists of only digits and dots. The four-part format *A.B.C.D* is recommended, wherein:<br>Part 1 (*A*): major version number. A major version consists of major new features or large changes.<br>Part 2 (*B*): minor version number. A minor version consists of some new features and large bug fixes.<br>Part 3 (*C*): feature version number. A feature version consists of scheduled new features.<br>Part 4 (*D*): patch version number. A patch version consists of some bug fixes.| String| No| 75| minCompatibleVersionCode | Minimum historical version compatible with the application. It is used for collaboration across devices, data migration, and cross-device compatibility determination. This field is reserved and the value ranges from 0 to 2147483647.| Number| Yes (initial value: value of **versionCode**)| 76| minAPIVersion | Minimum SDK API version required for running an application. The value ranges from 0 to 2147483647.| Number| Yes (This tag is automatically generated during application build and cannot be manually configured. It corresponds to the **compatibleSdkVersion** tag in the [project-level build-profile.json5 file](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-hvigor-build-profile-app#section45865492619)).<!--RP1--><!--RP1End--> | 77| targetAPIVersion | Target API version required for running the application. The value ranges from 0 to 2147483647.| Number| Yes (This tag is automatically generated during application build and cannot be manually configured. It corresponds to the **targetSdkVersion** tag in the [project-level build-profile.json5 file](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-hvigor-build-profile-app#section45865492619). If the **targetSdkVersion** tag is not configured, this tag will be generated by **compileSdkVersion**.)<!--RP1--><!--RP1End--> | 78| apiReleaseType | Type of the target API version required for running the application. The value can be **"CanaryN"**, **"BetaN"**, or **"Release"**, where **N** represents a positive integer.<br>- **Canary**: indicates a restricted release.<br>- **Beta**: indicates a publicly released beta version.<br>- **Release**: indicates a publicly released official version.| String| Yes (The value is automatically set by DevEco Studio based on the stage of the SDK in use; a manually set value will be overwritten during compilation and building.)| 79| accessible | Whether an application can access the installation directory. This field takes effect only for the preset system applications but not the third-party applications.<br>- **true**: The application installation directory is accessible.<br>- **false**: The application installation directory is not accessible.| Boolean| Yes (initial value: **false**)| 80| multiProjects | Whether the application supports joint development of multiple projects.<br>- **true**: The application supports joint development of multiple projects. For details about multi-project development, see [Implementing Multi-project Builds](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-hvigor-multi-projects).<br>- **false**: The application does not support joint development of multiple projects.| Boolean| Yes (This tag is automatically generated during application build and cannot be manually configured. It corresponds to the **multiProjects** tag in the [project-level build-profile.json5 file](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-hvigor-build-profile-app)).| 81| asanEnabled | Whether to enable [Address Sanitizer (ASan)](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-asan) to detect memory corruption issues such as buffer overflows.<br>- **true**: ASan is enabled.<br>- **false**: ASan is disabled.| Boolean| Yes (initial value: **false**)| 82| tablet | Tablet-specific configuration, which includes the **minAPIVersion** attribute.<br>When running on tablets, the application applies the attribute settings under this tag and ignores the general settings in the **app.json5** file.| Object| Yes (initial value: general settings in the **app.json5** file)| 83| tv | TV-specific configuration, which includes the **minAPIVersion** attribute.<br>When running on TVs, the application applies the attribute settings under this tag and ignores the general settings in the **app.json5** file.| Object| Yes (initial value: general settings in the **app.json5** file)| 84| wearable | Wearable-specific configuration, which includes the **minAPIVersion** attribute.<br>When running on wearables, the application applies the attribute settings under this tag and ignores the general settings in the **app.json5** file.| Object| Yes (initial value: general settings in the **app.json5** file)| 85| car | Telematics–specific configuration, which includes the **minAPIVersion** attribute. <br>When running on telematics devices, the application applies the attribute settings under this tag and ignores the general settings in the **app.json5** file.| Object| Yes (initial value: general settings in the **app.json5** file)| 86| default | Default device–specific configuration, which includes the **minAPIVersion** attribute.<br>When running on default devices, the application applies the attribute settings under this tag and ignores the general settings in the **app.json5** file.| Object| Yes (initial value: general settings in the **app.json5** file)| 87|targetBundleName|Target bundle name. The value rule and range are the same as those of **bundleName**. When a value is specified, the target application becomes one with the overlay feature.|String|Yes (initial value: left empty)| 88|targetPriority|Priority of the application. The value ranges from 1 to 100. This tag can be configured only when **targetBundleName** is configured.|Number|Yes (initial value: **1**)| 89|generateBuildHash |Whether to generate hash values for all HAP and HSP files of the application by using the packaging tool.<br>If this tag is set to **true**, the packaging tool generates hash values for all HAP and HSP files of the application. The hash values (if any) are used to determine whether the application needs to be updated when the system is updated in OTA mode but the **versionCode** value of the application remains unchanged.<br>- **true**: The packaging tool generates hash values for all HAPs and HSPs of the current application.<br>- **false**: The packaging tool does not generate hash values for all HAPs and HSPs of the current application.<br>**NOTE**<br>This tag applies only to system applications.|Boolean|Yes (initial value: **false**)| 90| GWPAsanEnabled | Whether to enable [GWP-ASan](https://developer.huawei.com/consumer/en/doc/best-practices/bpta-stability-gwpasan-detection#section2735718353) for detecting memory safety violations, including use-after-free and out-of-bounds memory read/write operations.<br>- **true**: The GWP-asan detection is enabled for the application.<br>- **false**: The GWP-asan detection is disabled for the application.| Boolean| Yes (initial value: **false**)| 91| [appEnvironments](#appenvironments) | Application environment variables configured for the current application.| Object array| Yes (initial value: left empty)| 92| maxChildProcess | Maximum number of child processes that can be created by the current application. The value ranges from 0 to 512. The value **0** indicates that the number is not limited. If the application has multiple modules, use the configuration of the **entry** module.| Number| Yes (initial value: <!--RP2-->**1**<!--RP2End-->)| 93| [multiAppMode](#multiappmode)| Multi-app mode of the application. This tag takes effect only for the entry or feature module of the application whose **bundleType** is **app**. If there are multiple modules, use the configuration of the **entry** module.| Object| Yes (initial value: left empty)| 94| hwasanEnabled | Whether [Hardware-assisted Address Sanitizer (HWASan)](https://developer.huawei.com/consumer/en/doc/harmonyos-guides/ide-hwasan) is enabled for an application. HWAsan is an enhanced Asan improved by the Top-Byte-Ignore feature. Compared with Asan, HWAsan has a lower memory overhead and a larger range of detection for memory errors.<br>- **true**: HWAsan is enabled.<br>- **false**: HWAsan is disabled.<br>**NOTE**<br>This field is supported since API version 14.| Boolean| Yes (initial value: **false**)| 95| ubsanEnabled | Whether UBsan detection is enabled for an application.<br>Undefined Behavior Sanitizer (UBsan) is a tool used to detect undefined behavior in applications during runtime. It aims to help you detect potential errors and vulnerabilities in code.<br>- **true**: UBsan is enabled.<br>- **false**: UBsan is disabled.<br>**NOTE**<br>This field is supported since API version 14.| Boolean| Yes (initial value: **false**)| 96| cloudFileSyncEnabled | Whether device-cloud file synchronization is enabled for the application.<br>- **true**: The device-cloud file synchronization is enabled.<br>- **false**: The device-cloud file synchronization is disabled.| Boolean| Yes (initial value: **false**) | 97| cloudStructuredDataSyncEnabled | Whether device-cloud structured data synchronization is enabled for the application.<br>- **true**: The device-cloud structured data synchronization is enabled.<br>- **false**: The device-cloud structured data synchronization is disabled.<br>**NOTE**<br>This field is supported since API version 20.| Boolean| Yes (initial value: **false**) | 98| [configuration](#configuration)| Whether the font size of the current application follows the system.<br>This tag is a **profile** file resource that used to specify the configuration file that describes the application font size changes with the system.| String| Yes (initial value: **nonFollowSystem**)| 99| assetAccessGroups | Group ID of an application (configured by the developer), which forms group information with the Developer ID (allocated by AGC).<br>When HAP is packaged, DevEco Studio uses the developer certificate to sign the group information.<br>**NOTE**<br>This field is supported since API version 18.| String array| Yes (initial value: left empty)| 100| appPreloadPhase | The stage at which the application is preloaded. The options are as follows:<br>- **processCreated**: preload the application to the stage where process is created.<br>- **abilityStageCreated**: preload the application to the stage where [AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md) is created.<br>- **windowStageCreated**: preload the application to the stage where [WindowStage](../reference/apis-arkui/arkts-apis-window-WindowStage.md) is created.<br>**NOTE**<br>This field is supported since API version 20.<br>This field is valid only in the entry module of the application.| String| Yes (If the value is not specified, preloading is not performed.)| 101| [startMode](../application-models/application-component-configuration-stage.md#configuring-the-launch-mode)| Launch mode of the application. The options are as follows:<br>- **mainTask**: main task mode, indicating that the main UIAbility of the application is always started when the icon is tapped.<br>- **recentTask**: recent task mode, indicating that the most recently used UIAbility is started when the icon is tapped.<br>**NOTE**<br>This field is supported since API version 20.<br>This field is valid only when launchType is set to [singleton](../application-models/uiability-launch-type.md#singleton).<br>This field is supported only on phones and tablets (excluding freeform windows).| String| Yes (initial value: **mainTask**)| 102 103## appEnvironments 104 105The **appEnvironments** tag represents the application environment variables. Running applications tend to depend on some third-party libraries that use custom environment variables. To avoid modifying the implementation logic of the third-party libraries, you can customize environment variables in the project configuration file for use during runtime. 106 107**Table 2** appEnvironments 108 109| Name| Description| Data Type| Initial Value Allowed| 110| -------- | -------- | -------- | -------- | 111| name | Name of the environment variable. The value is a string with a maximum of 4096 bytes.| String | Yes (initial value: left empty)| 112| value | Value of the environment variable. The value is a string with a maximum of 4096 bytes. | String | Yes (initial value: left empty)| 113 114Example of the **appEnvironments** structure: 115 116```json 117{ 118 "app": { 119 "appEnvironments": [ 120 { 121 "name":"name1", 122 "value": "value1" 123 } 124 ] 125 } 126} 127``` 128 129## multiAppMode 130 131The **multiAppMode** tag represents the multi-app mode of the application. 132 133**Table 3** multiAppMode 134 135| Name| Description| Data Type| Initial Value Allowed| 136| -------- | -------- | -------- | -------- | 137| multiAppModeType | Multi-open mode. The options are as follows:<br>- **multiInstance**: multi-instance mode. Only 2-in-1 devices are supported. A resident process does not support this value.<br>- **appClone**: app clone mode.| String | No| 138| maxCount | Maximum number of applications that can be opened. The options are as follows:<br>- In **multiInstance** mode, the value ranges from 1 to 10.<br>- In **appClone** mode, the value ranges from 1 to 5. | Number | No| 139 140Example of the **multiAppMode** structure: 141 142```json 143{ 144 "app": { 145 "multiAppMode": { 146 "multiAppModeType": "appClone", 147 "maxCount": 5 148 } 149 } 150} 151``` 152 153## configuration 154 155This tag corresponds to a profile resource, which is used to configure whether the font size of an application changes with the system. 156 157Example of the **configuration** structure: 158 159```json 160{ 161 "app": { 162 "configuration": "$profile:configuration" 163 } 164} 165``` 166 167Define the **configuration.json** file under **AppScope/resources/base/profile** in the development view. The file name (**configuration** in this example) can be customized, but must be consistent with the file specified by the **configuration** tag. The configuration file lists the attributes that enable the application font size to change with the system. 168 169**Table 4** configuration 170 171| Name| Description| Data Type| Initial Value Allowed| 172| -------- | -------- | -------- | -------- | 173| fontSizeScale | Settings of the application font size. The options are as follows:<br>- **followSystem**: The font size follows the system.<br>- **nonFollowSystem**: The font size does not follow the system.| String| Yes (initial value: **nonFollowSystem**)| 174| fontSizeMaxScale | Maximum ratio of the application font size after the font size is set to follow the system. The options are as follows: **1**, **1.15**, **1.3**, **1.45**, **1.75**, **2**, and **3.2**. <br> For example, the value is set to **1.75** and the system font size is 10 fp, the application font size changes as follows:<br>(1) If the system font size is set to 1.5 times its original size in Settings, the application font size also changes to 15 fp, in line with the system.<br>(2) If the system font size is set to 2 times its original size in Settings, the system font size is 20 fp. However, the application font size is 17.5 fp because the maximum ratio of the application font size is set to 1.75.<br>**NOTE**<br>If **fontSizeScale** is set to **nonFollowSystem**, this attribute does not take effect. | String| Yes (initial value: **3.2**)| 175 176Example of the **configuration** structure: 177 178```json 179{ 180 "configuration": { 181 "fontSizeScale": "followSystem", 182 "fontSizeMaxScale": "3.2" 183 } 184} 185``` 186