Application Package Structure Configuration File

When developing an application in the Feature Ability (FA) model, you need to declare the package structure of the application in the config.json file. Similarly, when developing an application in the stage model, you need to declare the package structure of the application in the module.json5 and app.json files.

Configuration File Internal Structure

The configuration files each consist of two mandatory tags, namely, app and module. For details, see Table 1.

Table 1 Configuration file internal structure

Internal Structure of the app Tag

Code snippet in the app.json file:

{
	"app": {
        "bundleName": "com.application.music",
        "vendor": "application",
        "versionCode": 1,
        "versionName": "1.0",
        "minCompatibleVersionCode": 1,
        "apiCompatibleVersion": 7,
        "apiTargetVersion": 8,
        "apiReleaseType": "Release",
        "debug": false,
        "icon": "$media:app_icon",
        "label": "$string:app_name",
        "description": "$string:description_application",
        "distributedNotificationEnabled": true,
        "entityType": "game",
        "car": {
            "apiCompatibleVersion": 8
        }
    }
}

This tag is an application-level attribute that applies to all the HAP files and components in the application. For the internal structure of the tag, see Table 2.

Table 2 Internal structure of the app tag

Internal Structure of the module Tag

Code snippet in the module.json5 file:

{
    "module": {
        "name": "myHapName",
        "type": "entry|feature|har",
        "srcEntrance" : "./MyAbilityStage.js",
        "description" : "$string:description_application",
        "process": "string", 
        "mainElement": "MainAbility",
        "deviceTypes": [
            "tablet", 
            "tv", 
            "wearable",
            "car",
            "router",
        ],
        "deliveryWithInstall": true,
        "installationFree": false,
        "virtualMachine": "ark | default",
        "metadata": [
            {
                "name": "string",
                "value": "string",
                "resource": "$profile:config_file1"
            },
            {
                "name": "string",
                "value": "string",
                "resource": "$profile:config_file2"
            }
        ],
        "abilities": [
            {
                "name": "MainAbility",
                "srcEntrance" : "./login/MyMainAbility.ts",
                "description": "$string:description_main_ability",
                "icon": "$media:icon",
                "label": "HiMusic",
                "visible": true,
                "skills": [
                    {
                        "actions": [
                            "action.system.home"
                        ],
                        "entities": [
                            "entity.system.home"
                        ],
                        "uris": [ ]
                    }
                ],
                "backgroundModes": [
                    "dataTransfer",
                    "audioPlayback",
                    "audioRecording",
                    "location",
                    "bluetoothInteraction",
                    "multiDeviceConnection",
                    "wifiInteraction",
                    "voip",
                    "taskKeeping"
                ],
            }
        ],
        "requestPermissions": [
            {
                "name": "ohos.abilitydemo.permission.PROVIDER",
                "reason": "$string:reason",
                "usedScene": {
                    "abilities": [
                        "FormAbility"
                    ],
                    "when": "inuse"
                }
            }
        ]
    }
}

This tag stores the HAP configuration, which only applies to the current HAP file.

Table 3 Internal structure of the module tag

Table 4 System-defined deviceTypes values

Example of the deviceTypes attribute structure:

{
	"module": {
		"name": "myHapName",
        "type": "har",
        "deviceTypes" : [
            "wearable"
        ]
	}
}

Example of the pages attribute structure:

{
    "module": {
       "name": "myHapName",
        "type": "har",
        "deviceTypes" : [
            "wearable"
        ],
        "pages": "$profile:pages_config"
    }
}

Example of the pages_config configuration file:

{
    "src": [
        "pages/index/index",
        "pages/second/second",
        "pages/third/third",
        "pages/four/four"
    ]
}

Internal Structure of the metadata Attribute

The metadata attribute provides the configuration about the module, ability, and extensionAbility. The value is of the array type. The configuration is valid only for the current module, ability, or extensionAbility.

Table 5 Internal structure of the metadata attribute

Example of the metadata attribute structure:

{ 
    "module": {
        "metadata": [
            {
                "name": "string",
                "value": "string",
                "resource": "$profile:config_file"
            },
            {
                "name": "string",
                "value": "string",
                "resource": "$profile:config_file"
            }
        ]
    }
}

Internal Structure of the abilities Attribute

The abilities attribute describes the ability configuration information. The value is of the array type.

Table 6 Internal structure of the abilities attribute

Example of the abilities attribute structure:

{
    "abilities": [{
        "name": "MainAbility",
        "srcEntrance": "./ets/login/MyLoginAbility.ts",
        "launchType":"standard"
        "description": "$string:description_main_ability",
        "icon": "$media:icon",
        "label": "Login",
        "permissions": [],
        "metadata": [],
        "visible": true,
        "continuable": true,
        "skills": [{
            "actions": ["action.system.home"],
            "entities": ["entity.system.home"],
            "uris": []
        }],
        "backgroundModes": [
            "dataTransfer",
            "audioPlayback",
            "audioRecording",
            "location",
            "bluetoothInteraction",
            "multiDeviceConnection",
            "wifiInteraction",
            "voip",
            "taskKeeping"
        ],
    }],
}

Internal Structure of the skills Attribute

This attribute identifies a want feature that can be received by the ability or extension.

Table 7 Internal structure of the skills attribute

Table 8 Internal structure of the uris attribute

Example of the skills attribute structure:

{
    "abilities": [
        {
            "skills": [
                {
                    "actions": [
                        "action.system.home"
                    ],
                    "entities": [
                        "entity.system.home"
                    ],
                    "uris": [
                        {
                            "scheme":"uri2",
                            "host":"host2",
                            "port":"port2",
                            "pathStartWith":"path2",
                            "pathRegex":"/query/.*",
                            "path":"path",
                            "type": "text/*"
                        },
                    ]
                }
            ],
        }
    ],
    "extensionAbilities": [
        {
            "skills": [
                {
                    "actions": [
                    ],
                    "entities": [
                    ],
                    "uris": [
                        {
                            "scheme":"uri2",
                            "host":"host2",
                            "port":"port2",
                            "pathStartWith":"path2",
                            "pathRegex":"/query/.*",
                            "path":"path",
                            "type": "text/*"
                        },
                    ]
                }
            ],
        }
    ],
}

Internal Structure of the extensionAbility Attribute

The extensionAbility attribute describes the configuration information of the current Extension ability.

Table 9 Internal structure of the extensionAbility attribute

Example of the extensionAbility attribute structure:

{
    "extensionAbilities": [
        {
            "name": "FormName",
            "srcEntrance": "./form/MyForm.ts",
            "icon": "$media:icon",
            "label" : "$string:extension_name",
            "description": "$string:form_description",
            "type": "form", 
            "permissions": ["ohos.abilitydemo.permission.PROVIDER"],
            "readPermission": "",
            "writePermission": "",
            "visible": true,
            "uri":"scheme://authority/path/query"
            "skills": [{
                "actions": [],
                "entities": [],
                "uris": []
            }],
            "metadata": [
                {
                    "name": "ohos.extability.form",
                    "resource": "$profile:form_config", 
                }
            ],
        }
    ]
}

Internal Structure of the requestPermissions Attribute

The requestPermissions attribute indicates the permissions defined for the HAP file.

Table 10 Internal structure of the requestPermissions attribute

Example of the requestPermissions attribute structure:

{
    "name": "ohos.abilitydemo.permission.PROVIDER",
    "reason": "$string:reason",
    "usedScene": {
        "abilities": [
            "AudioAbility",
            "VideoAbility",
        ],
        "when": "inuse"
    }
}

Internal Structure of the form Attribute

The forms attribute indicates the service widget configuration. The service widget is an application brief view that can be displayed on the home screen and periodically updated. You can include the forms attribute in any of the following modes:

1. Set type to form in extensions.

2. Specify the form information in metadata, where:

   • name indicates the name of the service widget, for example, ohos.extability.form.
   • resource indicates where the resources of the service widget are stored.

Table 11 Internal structure of the forms attribute

Table 13 Internal structure of the window attribute

Example of the forms attribute structure:

Define the form_config.json file (this file name is customizable) in resources/base/profile of the development view.

{
    "forms": [
        {
            "name": "Form_Js",
            "description": "$string:form_description",
            "src": "./js/pages/card/index",
            "window": {
                "designWidth": 720,
                "autoDesignWidth": true
            },
            "colorMode": "auto",
            "formConfigAbility": "ability://xxxxx",
            "formVisibleNotify": false,
            "isDefault": true,
            "updateEnabled": true,
            "scheduledUpdateTime": "10:30",
            "updateDuration": 1,
            "defaultDimension": "2*2",
            "supportDimensions": [
                "2*2"
            ],
           "metadata": [
             {
                "name": "string",
                "value": "string",
                "resource": "$profile:config_file"
             }
           ] 
        }
    ]
}

Define metadata information in the extension component of the module.json5 file.

{
	"extensionAbilities": [
        {
            "name": "MyForm",
            "type": "form", 
            "metadata": [
                {
                    "name": "ohos.extability.form",
                    "resource": "$profile:form_config",
                }
            ],
        }
	]
}

Internal Structure of the shortcuts Attribute

This attribute identifies the shortcut information of an application. The value is an array. A maximum of four shortcuts can be configured. It contains four sub-attributes: shortcutId, label, icon, and wants.

Specify the shortcut information in metadata, where:

• name indicates the name of the shortcut, for example, ohos.ability.shortcut.

• resource indicates where the resources of the shortcut are stored.

Table 13 Internal structure of the shortcuts attribute

Define the shortcut_config.json file (this file name is customizable) in resources/base/profile of the development view.

{
        "shortcuts": [
            {
                "shortcutId": "id_test1",
                "label": "$string:shortcut",
                "icon": "$media:aa_icon",
                "wants": [
                    {
                       "bundleName": "com.ohos.hello"
                       "abilityName": "MainAbility"
                    }
                ]
            }
        ]
}

Define the metadata information under module in the module.json5 file as follows:

{
    "module": {
        "name": "MyAbilityStage",
        "abilities" : [
            {
                "name" : "MyAbility",
                "srcEntrance": "./abilities/MyAbility.ts",
                "skills": [{
                            "actions": ["action.system.home"],
                            "entities": ["entity.system.home"],
                            "uris": []
                }],
                "metadata": [
                    {
                        "name": "ohos.ability.shortcut",
                        "resource": "$profile:shortcuts_config", 
                    }
                ],
            }
        ]
    }
}

Internal Structure of the commonEvents Attribute

The commonEvents attribute identifies the registered static common event information. The value is an array.

Specify the commonEvent information in the metadata, where:

• name indicates the name of the common event, for example, ohos.extability.staticSubscriber.

• resource indicates where the resources of the common event are stored.

Table 14 Internal structure of the commonEvents attribute

Define the common_event_config.json file in resources/base/profile in the development view. (The file name can be defined by developers.)

{
    "commonEvents": [
            {
                "name": "abilityName",
                "permission": "string",
                "types": [
                    "string",
                    "string"
                ],
                "events": [
                    "string",
                    "string"
                ]
            }
    ]
}

Define the metadata information under extension in the module.json5 file as follows:

"extensionAbilities": [
    {
        "name": "mySubscriber",
        "srcEntrance": "./extension/my_subscriber.js",
        "type": "staticSubscriber",
        "metadata": [
            {
                "name": "ohos.extability.staticSubscriber",
                "resource": "$profile:common_event_config", 
            }
        ],
    }
]

Internal Structure of the distroFilter Attribute

Distribution rules of the application.

This attribute defines the rules for distributing HAP files based on different device specifications, so that precise matching can be performed when AppGallery distributes applications. Distribution rules cover three factors: API version, screen shape, and screen resolution. During distribution, a unique HAP is determined based on the mapping between deviceType and these three factors.

Table 16 Internal structure of the distroFilter attribute

Table 17 Internal structure of the apiVersion attribute

Table 18 Internal structure of the screenShape attribute

Table 19 Internal structure of the screenWindow attribute

Table 20 Internal structure of the screenDensity attribute

Table 21 Internal structure of the countryCode attribute

Example of the distroFilter attribute structure:

Define the distroFilter_config.json file in resources/base/profile of the development view. (The file name can be defined by developers.)

"distroFilter": [
    {
       "apiVersion": {
            "policy": "include",
            "value": [4,5]
        },
        "screenShape": {
            "policy": "include",
            "value": ["circle","rect"]
        },
        "screenWindow": {
            "policy": "include",
            "value": ["454*454","466*466"]
        }
    }
]

Define the metadata information under extensionAbilities in the module.json5 file as follows:

"extensionAbilities": [
    {
        "name": "mySubscriber",
        "srcEntrance": "./extension/my_subscriber.js",
        "type": "staticSubscriber", 
        "metadata": [
            {
                "name": "ohos.extability.staticSubscriber",
                "resource": "$profile:distroFilter_config", 
            }
        ],
    }
]