To request permissions for your application, declare all the permissions one by one in the project configuration file. and may cause the application release application to be rejected.
and may cause the application release application to be rejected.
-
The reason for requesting permissions must be clearly stated so that users know what scenarios or functions the permissions will be used for.
If the actual usage scenario/function, permission usage reason, and actual called permission are not clearly notified to users, the permission application will be rejected. As a result, the application release request will be rejected.
Example: reason for requesting the camera permission.
Positive example: The camera is used for video calls or taking photos.
Negative example (The actual use case or function is not clearly stated.): Use the camera; Obtain the camera permission; Permission required.
Negative example (The reason for using the permission is inconsistent with the actual permission function): Recording audio for voice chat; obtaining the Bluetooth permission for file transfer between multiple devices.
-
Use a complete sentence that is concise, specific, and easy to understand to explain why the application requires the permissions. Avoid using the passive voice and end sentences with a full stop.
-
Recommended sentence pattern: Used for something/Used to do something/Used for doing something.
-
Example: reason for requesting the camera permission.
Correct usage: Used for video calls.
-
-
To ease multi-language adaptation, the recommended length of reason is fewer than 72 characters (36 Chinese characters displayed in two lines on the UI), and the maximum length is 256 characters.
-
The string cannot be a blank string. That is, the string cannot be left blank or contain only spaces.
-
If the permissions requested are used in multiple scenarios, ensure the integrity of the character string so that the user can understand all scenarios where the permission is used. If the same permission is requested in multiple HAPs, ensure the integrity and consistency of the reason field for each permission.
**Example: **
There are two HAPs in the application, both of which need to request the permission to use the camera. HAP 1 provides the video call function, and HAP 2 provides the live video function.
Correct usage: Used for video calls and live video.
Incorrect usage 1: "Used for video calls." for HAP 1, and "Used for live video" for HAP 2.
Incorrect usage 2: "Used for video calls." for both HAP 1 and HAP 2.
Declaring Permissions in the Configuration File
You must declare permissions in the requestPermissions tag of the module.json5 configuration file for the application.
| Field | Description | Data Type | Value Range |
|---|---|---|---|
| name | Name of the permission to request. | String | This field is mandatory. The value must be a permission defined in the system. For details, see Application Permissions. |
| reason | Reason for requesting the permission. | String | This field is optional. It is used for application release verification. It must be specified for a user_grant or manual_settings permission and support multilingual adaptation. It can be referenced as a string resource in $string: *** format. To configure the string resource reference, add the "name": "reason" tag to the string.json file. For details, see Resource File Examples. For details about how to set reason, see Specifications for reason. |
| usedScene | Use case of the permission. This field is used for application release verification. It has two parameters: - abilities: names of the abilities (UIAbility or ExtensionAbility) that use the permission. - when: when the permission is used. | Object | usedScene is mandatory when your application requests a user_grant or manual_settings permission and is optional in other cases. - abilities: array of UIAbility or ExtensionAbility names. - when: This parameter can only be set to a fixed value, either inuse (when in use) or always. It cannot be left empty. |
Example
Declare permissions in the requestPermissions tag of the module.json5 configuration file.
The value of "name" is for reference only. Set permissions to match your case.
{
"module": {
// ···
// 1. ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION are user_grant permissions, and reason and usedScene are mandatory.
// 2. ohos.permission.USE_BLUETOOTH is a system_grant permission, and reason and usedScene are optional.
"requestPermissions": [
{
"name": "ohos.permission.APPROXIMATELY_LOCATION",
"reason": "$string:approximately_location_permission_reason",
"usedScene": {
"abilities": [
"FormAbility"
],
"when": "inuse"
}
},
{
"name": "ohos.permission.LOCATION",
"reason": "$string:location_permission_reason",
"usedScene": {
"abilities": [
"FormAbility"
],
"when": "inuse"
}
},
{
"name": "ohos.permission.USE_BLUETOOTH"
}
]
}
} Specifications for reason
The reason field (reason for requesting the permission) is mandatory when a user_grant or manual_settings permission is requested. You must declare each required permission in the application's configuration file.
In the dialog box displayed for the user to grant the permission, the permission group is displayed. For details about permission groups, see Application Permission Groups.
[h2]Specifications and Suggestions for the reason Field
and may cause the application release application to be rejected.
-
The reason for requesting permissions must be clearly stated so that users know what scenarios or functions the permissions will be used for.
If the actual usage scenario/function, permission usage reason, and actual called permission are not clearly notified to users, the permission application will be rejected. As a result, the application release request will be rejected.
Example: reason for requesting the camera permission.
Positive example: The camera is used for video calls or taking photos.
Negative example (The actual use case or function is not clearly stated.): Use the camera; Obtain the camera permission; Permission required.
Negative example (The reason for using the permission is inconsistent with the actual permission function): Recording audio for voice chat; obtaining the Bluetooth permission for file transfer between multiple devices.
-
Use a complete sentence that is concise, specific, and easy to understand to explain why the application requires the permissions. Avoid using the passive voice and end sentences with a full stop.
-
Recommended sentence pattern: Used for something/Used to do something/Used for doing something.
-
Example: reason for requesting the camera permission.
Correct usage: Used for video calls.
-
-
To ease multi-language adaptation, the recommended length of reason is fewer than 72 characters (36 Chinese characters displayed in two lines on the UI), and the maximum length is 256 characters.
-
The string cannot be a blank string. That is, the string cannot be left blank or contain only spaces.
-
If the permissions requested are used in multiple scenarios, ensure the integrity of the character string so that the user can understand all scenarios where the permission is used. If the same permission is requested in multiple HAPs, ensure the integrity and consistency of the reason field for each permission.
**Example: **
There are two HAPs in the application, both of which need to request the permission to use the camera. HAP 1 provides the video call function, and HAP 2 provides the live video function.
Correct usage: Used for video calls and live video.
Incorrect usage 1: "Used for video calls." for HAP 1, and "Used for live video" for HAP 2.
Incorrect usage 2: "Used for video calls." for both HAP 1 and HAP 2.
[h2]Presentation of reason
The reason for requesting a permission can be presented in two modes: authorization pop-up window and permission details page of an application in Settings > Privacy > Permission manager.
-
For the permissions in the Phone, Messaging, Calendar, Contacts, and Call logs permission groups, the content and usage of each permission requested must be presented to the user.
Sentence pattern: Permissions A, used to/for ... Permission B, used to/for ...
Example: Permission A, used to obtain the call status and mobile network information. Permission B, used for secure operation and statistics charging services.
-
For the permissions in other permission groups, only the reason for the first requested permission is presented to the user. The permissions are sorted as they appear in the permission groups under Permission manager.
Example: If a permission group consists of permissions A, B, and C in sequence, and permissions C and B are requested, the reason for using permission B is presented to the user.
-
When multiple packages of an application request identical permissions with differing reasons, only one reason is displayed in the ReqPermissionDetail returned by the system. The priorities are as follows in descending order: HAP of the entry type, HAP of the feature type, and HSP in an application.