js-apis-privacyManager.md

# 隐私管理

该模块主要提供权限使用记录等隐私管理接口。

> **说明：**
> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> 本模块接口为系统接口，三方应用不支持调用。

## 导入模块

```js
import privacyManager from '@ohos.privacyManager';
```


## privacyManager.addPermissionUsedRecord

addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number): Promise<number>

受应用权限保护的应用在被其他服务、应用调用时，可以使用该接口增加一条权限使用记录。使用Promise异步回调。
权限使用记录包括：调用方的应用身份标识、使用的应用权限名称，和其访问本应用成功、失败的次数。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
| tokenID   |  number   | 是   | 调用方的应用身份标识。              |
| permissionName | string | 是   | 应用权限名称。 |
| successCount | number | 是   | 访问成功的次数。 |
| failCount | number | 是   | 访问失败的次数。 |

**返回值：**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
| Promise<number> | Promise对象。返回`0`表示成功增加记录，返回`-1`表示失败。 |

**示例：**

```js
var tokenID = appInfo.accessTokenId; // 可以通过getApplicationInfo获取accessTokenId
privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0).then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
```

## privacyManager.addPermissionUsedRecord

addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number, callback: AsyncCallback<number>): void

受应用权限保护的应用在被其他服务、应用调用时，可以使用该接口增加一条权限使用记录。使用callback异步回调。
权限使用记录包括：调用方的应用身份标识、使用的应用权限名称，和其访问本应用成功、失败的次数。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
| tokenID   |  number   | 是   | 调用方的应用身份标识。              |
| permissionName | string | 是   | 应用权限名称。 |
| successCount | number | 是   | 访问成功的次数。 |
| failCount | number | 是   | 访问失败的次数。 |
| callback | AsyncCallback<number> | 是   | 回调函数。返回`0`表示成功增加记录，返回`-1`表示失败。 |

**示例：**

```js
var tokenID = appInfo.accessTokenId; // 可以通过getApplicationInfo获取accessTokenId
privacyManager.privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0, (err, data) => {
    console.log(`callback: data->${JSON.stringify(data)}`);
});
```

## privacyManager.getPermissionUsedRecords

getPermissionUsedRecords(request: PermissionUsedRequest): Promise<PermissionUsedResponse>

获取历史权限使用记录。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
| request   |  [PermissionUsedRequest](#permissionusedrequest)   | 是   | 查询权限使用记录的请求。              |

**返回值：**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
| Promise<[PermissionUsedResponse](#permissionusedresponse)> | Promise对象。返回权限使用记录。|

**示例：**

```js
let request = {
    "tokenId": 1,
    "isRemote": 1,
    "deviceId": "device",
    "bundleName": "bundle",
    "permissionNames": 1,
    "beginTime": 0,
    "endTime": 1,
    "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};
privacyManager.getPermissionUsedRecords(request).then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
```

## privacyManager.getPermissionUsedRecords

getPermissionUsedRecords(request: PermissionUsedRequest, callback: AsyncCallback&lt;PermissionUsedResponse&gt;): void

获取历史权限使用记录。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
| request | [PermissionUsedRequest](#permissionusedrequest) | 是 | 查询权限使用记录的请求。 |
| callback | AsyncCallback<[PermissionUsedResponse](#permissionusedresponse)> | 是 | 回调函数。返回权限使用记录。 |

**示例：**

```js
let request = {
    "tokenId": 1,
    "isRemote": 1,
    "deviceId": "device",
    "bundleName": "bundle",
    "permissionNames": 1,
    "beginTime": 0,
    "endTime": 1,
    "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};
privacyManager.getPermissionUsedRecords(request, (err, data) => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
```

## privacyManager.startUsingPermission<sup>9+</sup>

startUsingPermission(tokenID: number, permissionName: string): Promise&lt;number&gt;

应用开始使用某项权限，可监听应用在前后台使用权限，并将使用权限的记录落盘，由系统服务调用。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名          | 类型   | 必填 | 说明                                  |
| -------------- | ------ | ---- | ------------------------------------ |
| tokenID        | number | 是   | 调用方的应用身份标识，获取方法参照示例。 |
| permissionName | string | 是   | 需要使用的权限名。                     |

**返回值：**

| 类型          | 说明                                    |
| ------------- | --------------------------------------- |
| Promise&lt;number&gt; | Promise对象。返回开始使用权限的结果。|

**示例：**

```js
import bundle from '@ohos.bundle';
import privacyManager from '@ohos.privacyManager';

let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function

let tokenID = appInfo.accessTokenId;
let permissionName = "ohos.permission.CAMERA";
privacyManager.startUsingPermission(tokenID, permissionName).then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
}).catch(err => {
    console.log(`Error: err->${JSON.stringify(err)}`);
});
```

## privacyManager.startUsingPermission<sup>9+</sup>

startUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback&lt;number&gt;): void

应用开始使用某项权限，可监听应用在前后台使用权限，并将使用权限的记录落盘，由系统服务调用。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名          | 类型                  | 必填 | 说明                                  |
| -------------- | --------------------- | ---- | ------------------------------------ |
| tokenID        | number                | 是   | 调用方的应用身份标识，获取方法参照示例。 |
| permissionName | string                | 是   | 需要使用的权限名。                     |
| callback       | AsyncCallback&lt;number&gt; | 是   | 异步回调，返回开始使用权限的结果。 |

**示例：**

```js
import bundle from '@ohos.bundle';
import privacyManager from '@ohos.privacyManager';

let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function

let tokenID = appInfo.accessTokenId;
let permissionName = "ohos.permission.CAMERA";
privacyManager.startUsingPermission(tokenID, permissionName, (err, data)=> {
    if (err) {
        console.log(`Error: err->${JSON.stringify(err)}`);
    } else {
        console.log(`promise: data->${JSON.stringify(data)}`);
    }
});
```

## privacyManager.stopUsingPermission<sup>9+</sup>

stopUsingPermission(tokenID: number, permissionName: string): Promise&lt;number&gt;

应用停止使用某项权限，与Start对应，由系统服务调用。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名          | 类型   | 必填 | 说明                                  |
| -------------- | ------ | ---- | ------------------------------------ |
| tokenID        | number | 是   | 调用方的应用身份标识，获取方法参照示例。 |
| permissionName | string | 是   | 需要使用的权限名。                     |

**返回值：**

| 类型          | 说明                                    |
| ------------- | --------------------------------------- |
| Promise&lt;number&gt; | Promise对象。返回停止使用权限的结果。|

**示例：**

```js
import bundle from '@ohos.bundle';
import privacyManager from '@ohos.privacyManager';

let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function

let tokenID = appInfo.accessTokenId;
let permissionName = "ohos.permission.CAMERA";
privacyManager.stopUsingPermission(tokenID, permissionName).then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
}).catch(err => {
    console.log(`Error: err->${JSON.stringify(err)}`);
});
```

## privacyManager.stopUsingPermission<sup>9+</sup>

stopUsingPermission(tokenID: number, permissionName: string, callback: AsyncCallback&lt;number&gt;): void

应用停止使用某项权限，与Start对应，由系统服务调用。

**需要权限：** ohos.permission.PERMISSION_USED_STATS，仅系统应用可用。

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名          | 类型                  | 必填 | 说明                                  |
| -------------- | --------------------- | ---- | ------------------------------------ |
| tokenID        | number                | 是   | 调用方的应用身份标识，获取方法参照示例。 |
| permissionName | string                | 是   | 需要使用的权限名。                      |
| callback       | AsyncCallback&lt;number&gt; | 是   | 异步回调，返回停止使用权限的结果。 |

**示例：**

```js
import bundle from '@ohos.bundle';
import privacyManager from '@ohos.privacyManager';

let bundleName = "com.ohos.permissionmanager"; // change to your bundle name
let appInfo = await bundle.getApplicationInfo(bundleName, 16); // need async type function

let tokenID = appInfo.accessTokenId;
let permissionName = "ohos.permission.CAMERA";
privacyManager.privacyManager.stopUsingPermission(tokenID, permissionName, (err, data)=> {
    if (err) {
        console.log(`Error: err->${JSON.stringify(err)}`);
    } else {
        console.log(`promise: data->${JSON.stringify(data)}`);
    }
});
```

## privacyManager.on<sup>9+</sup>

on(type: 'activeStateChange', permissionNameList: Array&lt;string&gt;, callback: Callback&lt;ActiveChangeResponse&gt;): void

订阅指定权限列表的权限使用状态变更事件，使用callback回调异步返回结果。

此接口为系统接口。

**需要权限：** ohos.permission.PERMISSION_USED_STATS

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名             | 类型                   | 必填 | 说明                                                          |
| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
| type               | string                | 是   | 订阅事件类型，固定为'activeStateChange'，权限使用状态变更事件。   |
| permissionNameList | Array&lt;string&gt;   | 否   | 订阅的权限名列表，为空时表示订阅所有的权限使用状态变化。           |
| callback | Callback&lt;[ActiveChangeResponse](#activechangeresponse9)&gt; | 是 | 订阅指定权限使用状态变更事件的回调。 |

**示例：**

```js
import privacyManager from '@ohos.privacyManager';

function OnPermissionUseStateChanged(data){
    console.debug("receive permission state change, data:" + JSON.stringify(data));
}
let type: 'activeStateChange' = 'activeStateChange';
let permissionNameList: Array&lt;string&gt; = [];
try{
    privacyManager.on(type, permissionNameList, OnPermissionUseStateChanged);
}
catch(err){
    console.error("on err:" + JSON.stringify(err));
}
```

## privacyManager.off<sup>9+</sup>

off(type: 'activeStateChange', permissionNameList: Array&lt;string&gt;, callback?: Callback&lt;ActiveChangeResponse&gt;): void;

取消订阅指定权限列表的权限使用状态变更事件，使用callback回调异步返回结果。

此接口为系统接口。

**需要权限：** ohos.permission.PERMISSION_USED_STATS

**系统能力：** SystemCapability.Security.AccessToken

**参数：**

| 参数名             | 类型                   | 必填 | 说明                                                          |
| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
| type               | string                | 是   | 订阅事件类型，固定为'activeStateChange'，权限使用状态变更事件。   |
| permissionNameList | Array&lt;string&gt;   | 否   | 订阅的权限名列表，为空时表示订阅所有的权限状态变化，必须与on的输入一致。 |
| callback | Callback&lt;[ActiveChangeResponse](#activechangeresponse9)&gt; | 否 | 取消订阅指定tokenId与指定权限名状态变更事件的回调。|

**示例：**

```js
import privacyManager from '@ohos.privacyManager';

let type: 'activeStateChange' = 'activeStateChange';
let permissionNameList: Array&lt;string&gt; = [];
try{
    privacyManager.off(type, permissionNameList);
}
catch(err){
    console.error("off err:" + JSON.stringify(err));
}
```

## PermissionUsageFlag

使用记录的查询方式的枚举。

**系统能力：** SystemCapability.Security.AccessToken

| 名称                    | 值 | 描述                   |
| ----------------------- | ------ | ---------------------- |
| FLAG_PERMISSION_USAGE_SUMMARY             | 0    | 表示查询总览数据。 |
| FLAG_PERMISSION_USAGE_DETAIL         | 1    | 表示查询详细数据。         |

## PermissionUsedRequest

表示使用记录的查询请求。

**系统能力：**  以下各项对应的系统能力均为SystemCapability.Security.AccessToken

| 名称       | 类型             | 必填   | 说明                                       |
| -------- | -------------- | ---- | ---------------------------------------- |
| tokenId  | number         | 否    | 目标应用的身份标识。                                 |
| isRemote | boolean         | 否    | 默认值false。 |
| deviceId  | string         | 否    | 目标应用所在设备的ID。                                 |
| bundleName | string         | 否    | 目标应用的包名。 |
| permissionNames  | Array&lt;string&gt;         | 否    | 需要查询的权限集合。                                 |
| beginTime | number         | 否    | 查询的起始时间，单位：ms，默认值0，不设定起始时间。 |
| endTime | number         | 否    | 查询的终止时间，单位：ms，默认值0，不设定终止时间。 |
| flag | [PermissionUsageFlag](#permissionusageflag)         | 是    | 查询方式，默认值FLAG_PERMISSION_USAGE_SUMMARY。 |

## PermissionUsedResponse

表示所有应用的访问记录。

**系统能力：**  以下各项对应的系统能力均为SystemCapability.Security.AccessToken

| 名称       | 类型             | 必填   | 说明                                       |
| -------- | -------------- | ---- | ---------------------------------------- |
| beginTime | number         | 否    | 查询记录的起始时间，单位：ms。 |
| endTime | number         | 否    | 查询记录的终止时间，单位：ms。 |
| bundleRecords  | Array&lt;[BundleUsedRecord](#bundleusedrecord)&gt;         | 否    | 应用的权限使用记录集合。                                 |

## BundleUsedRecord

某个应用的访问记录。

**系统能力：**  以下各项对应的系统能力均为SystemCapability.Security.AccessToken

| 名称       | 类型             | 必填   | 说明                                       |
| -------- | -------------- | ---- | ---------------------------------------- |
| tokenId  | number         | 否    | 目标应用的身份标识。                                 |
| isRemote | boolean         | 否    | 默认值false。 |
| deviceId  | string         | 否    | 目标应用所在设备的ID。                                 |
| bundleName | string         | 否    | 目标应用的包名。 |
| permissionRecords  | Array&lt;[PermissionUsedRecord](#permissionusedrecord)&gt;         | 否    | 每个应用的权限使用记录集合。                                 |

## PermissionUsedRecord

某个权限的访问记录。

**系统能力：**  以下各项对应的系统能力均为SystemCapability.Security.AccessToken

| 名称       | 类型             | 必填   | 说明                                       |
| -------- | -------------- | ---- | ---------------------------------------- |
| permissionName  | string         | 否    | 权限名。                                 |
| accessCount | number         | 否    | 该权限访问总次数。 |
| rejectCount | number         | 否    | 该权限拒绝总次数。 |
| lastAccessTime | number         | 否    | 最后一次访问时间，单位：ms。 |
| lastRejectTime | number         | 否    | 最后一次拒绝时间，单位：ms。 |
| lastAccessDuration | number         | 否    | 最后一次访问时长，单位：ms。 |
| accessRecords  | Array&lt;[UsedRecordDetail](#usedrecorddetail)&gt;         | 否    | 访问记录集合，当flag为FLAG_PERMISSION_USAGE_SUMMARY时生效，默认查询10条。                                 |
| rejectRecords  | Array&lt;[UsedRecordDetail](#usedrecorddetail)&gt;         | 否    | 拒绝记录集合，当flag为FLAG_PERMISSION_USAGE_SUMMARY时生效，默认查询10条。                                 |

## UsedRecordDetail

单次访问记录详情。

**系统能力：**  以下各项对应的系统能力均为SystemCapability.Security.AccessToken

| 名称       | 类型             | 必填   | 说明                                       |
| -------- | -------------- | ---- | ---------------------------------------- |
| status  | number         | 否    | 访问状态。                                 |
| timestamp | number         | 否    | 访问时的时间戳，单位：ms。 |
| accessDuration  | number         | 否    | 访问时长，单位：ms。                                 |

## PermissionActiveStatus<sup>9+</sup>

表示权限使用状态类型的枚举。

**系统能力：** 以下各项对应的系统能力均为SystemCapability.Security.AccessToken

| 名称                      | 默认值 | 描述              |
| ------------------------- | ------ | ---------------- |
| PERM_INACTIVE             | 0      | 表示未使用权限。   |
| PERM_ACTIVE_IN_FOREGROUND | 1      | 表示前台使用权限。 |
| PERM_ACTIVE_IN_BACKGROUND | 2      | 表示后台使用权限。 |

## ActiveChangeResponse<sup>9+</sup>

 **系统能力:** 以下各项对应的系统能力均为SystemCapability.Security.AccessToken

| 名称           | 类型                    | 可读 | 可写 | 说明                   |
| -------------- | ---------------------- | ---- | ---- | --------------------- |
| tokenId        | number                 | 是   | 否   | 调用方的应用身份标识    |
| permissionName | string                 | 是   | 否   | 使用状态发生变化的权限名 |
| deviceId       | string                 | 是   | 否   | 设备号                 |
| activeStatus   | [PermissionActiveStatus](#permissionactivestatus9) | 是   | 否   | 权限使用状态类型        |