Detailed Explanation of HarmonyOS App.json5 Configuration

I. Analysis of Configuration File Examples

First, let's get acquainted with the app.json5 configuration file of a HarmonyOS application through a complete example:

{
  "app": {
    "bundleName": "com.application.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:layered_image",
    "label": "$string:app_name",
    "description": "$string:description_application",
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "apiReleaseType": "Release",
    "debug": false,
    "car": {
      "minAPIVersion": 8
    },
    "targetBundleName": "com.application.test",
    "targetPriority": 50,
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ],
    "maxChildProcess": 5,
    "multiAppMode": {
      "multiAppModeType": "multiInstance",
      "maxCount": 5
    },
    "hwasanEnabled": false,
    "ubsanEnabled": false,
    "cloudFileSyncEnabled": false,
    "configuration": "$profile:configuration",
    "assetAccessGroups": [
      "com.ohos.photos",
      "com.ohos.screenshot",
      "com.ohos.note"
    ],
    "startMode": "mainTask"
  }
}

This example demonstrates the basic structure and main configuration items of the app.json5 file. Below, we will elaborate on the meaning and usage of each configuration item.

II. Detailed Explanation of app.json5 Configuration File Tags

The app.json5 configuration file contains multiple tags, each with specific meanings and purposes. The following is a detailed explanation of each tag:

1. app Tag (Global Application Configuration)

The app tag is the core part of the configuration file, containing global configuration information for the application.

1.1 bundleName (Application Bundle Name)

• Meaning: Identifies the unique identifier of the application
• Naming Rules:
  • Must be a string separated by dots (.), with at least three segments
  • Each segment allows only English letters, numbers, and underscores (_)
  • The first segment starts with an English letter, and non-first segments start with a number or English letter
  • Each segment ends with a number or English letter
  • Consecutive dots (..) are not allowed
  • The minimum length is 7 bytes, and the maximum length is 128 bytes
  • It is recommended to use a reverse domain name format (e.g., "com.example.demo")
• Data Type: String
• Is it Optional: No

1.2 bundleType (Application Bundle Type)

• Meaning: Identifies the Bundle type of the application
• Values:
  • app: The current Bundle is an application
  • atomicService: The current Bundle is an atomic service
  • shared: The current Bundle is a shared library application (reserved field)
  • appPlugin: The current Bundle is a plugin package for an application (supported in API version 19+)
• Data Type: String
• Is it Optional: Yes, with a default value of app

1.3 debug (Debug Indicator)

• Meaning: Indicates whether the application can be debugged
• Values:
  • true: Debuggable (development phase)
  • false: Not debuggable (release phase)
• Data Type: Boolean
• Is it Optional: Yes, with a default value of false

1.4 icon (Application Icon)

• Meaning: Identifies the resource index of the application icon
• Data Type: String
• Is it Optional: No

1.5 label (Application Name)

• Meaning: Identifies the name of the application (string resource index)
• Restriction: The string length does not exceed 63 bytes
• Data Type: String
• Is it Optional: No

1.6 description (Application Description)

• Meaning: Identifies the description information of the application (string resource index)
• Restriction: The length does not exceed 255 bytes
• Data Type: String
• Is it Optional: Yes, with a default empty value

1.7 vendor (Developer)

• Meaning: Identifies the description of the application developer
• Restriction: The length does not exceed 255 bytes
• Data Type: String
• Is it Optional: Yes, with a default empty value

1.8 versionCode (Version Number)

• Meaning: Identifies the version number of the application
• Restriction: A positive integer less than 2^31
• Data Type: Numeric
• Is it Optional: No

1.9 versionName (Version Name)

• Meaning: The application version number displayed to users
• Format: A string with a length of no more than 127 bytes, composed only of numbers and dots
• Recommended Format: Four-segment format A.B.C.D
• Data Type: String
• Is it Optional: No

1.10 minAPIVersion (Minimum API Version)

• Meaning: The minimum API version of the SDK required for the application to run
• Range: 0 to 2147483647
• Data Type: Numeric
• Is it Optional: No

1.11 targetAPIVersion (Target API Version)

• Meaning: The target API version required for the application to run
• Range: 0 to 2147483647
• Data Type: Numeric
• Is it Optional: No

1.12 apiReleaseType (API Version Type)

• Meaning: The type of the target API version required for the application to run
• Values:
  • CanaryN: A restricted release version
  • BetaN: A publicly released Beta version
  • Release: A publicly released official version
• Data Type: String
• Is it Optional: No (automatically generated by the SDK Stage)

1.13 car (Special Configuration for In-Vehicle Devices)

• Meaning: Identifies special configurations for car devices
• Configurable Attributes: minAPIVersion, etc.
• Data Type: Object
• Is it Optional: Yes, using the public area configuration by default

1.14 targetBundleName (Target Application Package Name)

• Meaning: Identifies the target application specified by the current package
• Rules: Consistent with the bundleName tag
• Data Type: String
• Is it Optional: Yes, with a default empty value

1.15 targetPriority (Target Priority)

• Meaning: Identifies the priority of the current application
• Range: 1 to 100
• Data Type: Numeric
• Is it Optional: Yes, with a default value of 1

1.16 appEnvironments (Application Environment Variables)

• Meaning: Identifies the application environment variables configured for the current module
• Data Type: Object array
• Is it Optional: Yes, with a default empty value

1.17 maxChildProcess (Maximum Number of Child Processes)

• Meaning: Identifies the maximum number of child processes that the current application can create
• Range: 0 to 512 (0 means no limit)
• Data Type: Numeric
• Is it Optional: Yes, using the system default configuration

1.18 multiAppMode (Multi-Instance Mode)

• Meaning: Identifies the multi-instance mode configured for the current application
• Scope of Application: Valid only for the entry or feature modules of applications with bundleType as app
• Data Type: Object
• Is it Optional: Yes, with a default empty value

1.19 hwasanEnabled (HWAsan Detection)

• Meaning: Indicates whether HWAsan detection is enabled for the application
• Values:
  • true: Enable HWAsan detection
  • false: Do not enable HWAsan detection
• Data Type: Boolean
• Is it Optional: Yes, with a default value of false

1.20 ubsanEnabled (UBsan Detection)

• Meaning: Indicates whether UBsan detection is enabled for the application
• Values:
  • true: Enable UBsan detection
  • false: Do not enable UBsan detection
• Data Type: Boolean
• Is it Optional: Yes, with a default value of false

1.21 cloudFileSyncEnabled (Cloud-Edge File Synchronization)

• Meaning: Indicates whether the current application enables the cloud-edge file synchronization capability
• Values:
  • true: Enable
  • false: Do not enable
• Data Type: Boolean
• Is it Optional: Yes, with a default value of false

1.22 configuration (Font Size Configuration)

• Meaning: Identifies the capability of the current application's font size to follow system configuration
• Data Type: Profile file resource (string)
• Is it Optional: Yes, with a default of not following the system

1.23 assetAccessGroups (Resource Access Groups)

• Meaning: Configure the Group ID of the application
• Data Type: String array
• Is it Optional: Yes, with a default empty value

1.24 startMode (Launch Mode)

• Meaning: Configure the launch mode of the application
• Values:
  • mainTask: Main task mode (open the main UIAbility)
  • recentTask: Recent task mode (open the recently used UIAbility)
• Scope of Application: Valid only when the launchType is single-instance mode, and only supports phone and tablet devices
• Data Type: String
• Is it Optional: Yes, with a default value of mainTask

2. icon Tag (Application Icon Configuration)

The icon tag identifies the application icon and the index to the layered icon configuration file.

Layered Icon Configuration Method:

1. Place the foreground and background resources of the icon in the AppScope/resources/base/media directory.
2. Create a layered icon configuration file layered_image.json in the media directory to reference the foreground and background resources.

Example of Layered Icon Configuration File:

{
  "layered-image": {
    "background": "$media:background",
    "foreground": "$media:foreground"
  }
}

Example of icon Tag:

{
  "app": {
    "icon": "$media:layered_image"
  }
}

3. appEnvironments Tag (Application Environment Variables)

Identifies the environment variables configured for the application, used to set custom environment variables without modifying the implementation logic of third-party libraries.

Table 2: Description of appEnvironments Tag:

Attribute Name	Meaning	Data Type	Is it Optional
name	Environment variable name	String	Yes
value	Environment variable value	String	Yes

Example of appEnvironments Tag:

{
  "app": {
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ]
  }
}

4. multiAppMode Tag (Application Multi-Instance Mode)

Configuration for the application multi-instance mode, supporting two modes: multi-instance mode and application clone mode.

Table 3: Description of multiAppMode Tag:

Attribute Name	Meaning	Data Type	Is it Optional
multiAppModeType	Multi-instance mode type	String	No
maxCount	Maximum number of multi-instances	Numeric	No

Example of multiAppMode Tag:

{
  "app": {
    "multiAppMode": {
      "multiAppModeType": "appClone",
      "maxCount": 5
    }
  }
}

5. configuration Tag (Font Size Configuration)

Identifies the configuration file for the current application's font size to follow system changes.

Table 4: Description of configuration Tag:

Attribute Name	Meaning	Data Type	Is it Optional
fontSizeScale	Whether the font size follows the system	String	Yes, default is nonFollowSystem
fontSizeMaxScale	Maximum font size ratio	String	Yes, default is 3.2

Example of configuration Tag:

{
  "app": {
    "configuration": "$profile:configuration"
  }
}

Corresponding example of configuration.json file:

{
  "fontSizeScale": "followSystem",
  "fontSizeMaxScale": "3.2"
}

III. Configuration File Usage Recommendations

1. Naming Conventions: Strictly follow the naming rules of bundleName, and it is recommended to use a reverse domain name format, such as "com.company.appname".

2. Version Management:

   • versionCode should be incremented each time a new version is released.
   • versionName is recommended to use the "A.B.C.D" four-segment format for easy version management.

3. Multi-Device Adaptation:

   • Ensure application compatibility through minAPIVersion and targetAPIVersion.
   • Special configurations can be made for specific devices (such as tablets).

4. Multi-Instance Mode:

   • Select an appropriate multiAppModeType according to application requirements.
   • Pay attention to the maxCount restrictions of different modes.

5. Font Size Adaptation:

   • It is recommended to enable configuration configuration to allow the application to adjust with the system font size.
   • Reasonably set fontSizeMaxScale to avoid excessive font sizes affecting the layout.

6. Environment Variables:

   • Configure the required environment variables for the application through appEnvironments.
   • Avoid hardcoding environment-related parameters in the code.

IV. Summary

app.json5 is the core configuration file of a HarmonyOS application, containing important information such as global application configuration, icon settings, environment variables, and multi-instance modes. Reasonable configuration of this file is crucial for application development, release, and operation. Developers should carefully read the official documentation, follow configuration specifications, and ensure the correctness and completeness of application configuration.