app.json5 Configuration File

An application-level configuration file provides the global configuration of an application and configuration of a specific device type for the compilation tool, OS, and AppGallery. Each project must contain an app.json5 configuration file, which is stored in the project name/AppScope/app.json5 directory.

NOTE

Using the sample code in the actual project may cause a compilation failure. You need to configure the code as required. For example, if the resource file referenced by the $ symbol does not exist in the project, you need to manually add the resource file or replace it with the actual one.

In the configuration file, fields can be repeated. The last field is used.

Configuration File Example

The following example describes the structure and content of the app.json5 configuration file.

{
  "app": {
    "bundleName": "com.application.myapplication",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:layered_image",
    "alternateIcons": [
      {
        "name": "summer_theme",
        "icon": "$media:layered-image"
      },
      {
        "name": "winter_theme",
        "icon": "$media:background"
      }
    ],
    "label": "$string:app_name",
    "description": "$string:description_application",
    "minAPIVersion": 9,
    "targetAPIVersion": 9,
    "debug": false,
    "car": {
      "minAPIVersion": 8
    },
    "appEnvironments": [
      {
        "name":"name1",
        "value": "value1"
      }
    ],
    "maxChildProcess": 5,
    "multiAppMode": {
      "multiAppModeType": "appClone",
      "maxCount": 5
    },
    "hwasanEnabled": false,
    "ubsanEnabled": false,
    "cloudFileSyncEnabled": false,
    "cloudStructuredDataSyncEnabled": false,
    "configuration": "$profile:configuration",
    "assetAccessGroups": [
      "com.ohos.photos",
      "com.ohos.screenshot",
      "com.ohos.note"
    ],
    "startMode": "mainTask",
    "buildVersion": "1.0.0",
    "allowListenBundleChangedEvent": [
      "5628971256935874952"
    ]
  }
}

Tags in the Configuration File

As shown above, the app.json5 file contains several tags.

Table 1 Tags in the app.json5 file

appEnvironments

The 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.

Table 2 appEnvironments

Example of the appEnvironments structure:

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

multiAppMode

The multiAppMode tag represents the multi-app mode of the application.

Table 3 multiAppMode

Example of the multiAppMode structure:

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

configuration

This tag corresponds to a profile resource, which is used to configure whether the font size of an application changes with the system.

Example of the configuration structure:

{
  "app": {
    // ...
    "configuration": "$profile:configuration",
    // ...
  }
}

Define 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.

Table 4 configuration

Example of the configuration structure:

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

alternateIcons

This tag is used to configure the list of alternate application icons and supports dynamically switching application icons at runtime. You can preconfigure multiple alternate icons, and the application can dynamically switch icons based on scenarios such as user preferences, holiday themes, and branding campaigns.

This tag is supported starting from API version 26.0.0.

Table 5 alternateIcons

Example:

{
  "app": {
    // ...
    "alternateIcons": [
      {
        "name": "summer_theme",
        "icon": "$media:layered-image"
      },
      {
        "name": "winter_theme",
        "icon": "$media:background"
      }
    ],
    // ...
  }
}