From 93d99051d6a6e97548f4ff0f4ee41ade799dadb9 Mon Sep 17 00:00:00 2001 From: wyuanchao Date: Mon, 28 Feb 2022 19:11:39 +0800 Subject: [PATCH 1/3] device usage statistics docs Signed-off-by: wyuanchao --- .../device-usage-statistics/Readme-CN.md | 5 + .../device-usage-statistics-dev-guide.md | 218 ++++++++ .../device-usage-statistics-overview.md | 24 + .../apis/js-apis-deviceUsageStatistics.md | 471 ++++++++++++++++++ 4 files changed, 718 insertions(+) create mode 100644 zh-cn/application-dev/device-usage-statistics/Readme-CN.md create mode 100644 zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md create mode 100644 zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md create mode 100644 zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md diff --git a/zh-cn/application-dev/device-usage-statistics/Readme-CN.md b/zh-cn/application-dev/device-usage-statistics/Readme-CN.md new file mode 100644 index 00000000000..e0c382796b7 --- /dev/null +++ b/zh-cn/application-dev/device-usage-statistics/Readme-CN.md @@ -0,0 +1,5 @@ +# 设备使用信息统计 + +- 后台任务 + - [设备使用信息统计概述](device-usage-statistics-overview.md) + - [设备使用信息统计开发指导](device-usage-statistics-dev-guide.md) \ No newline at end of file diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md new file mode 100644 index 00000000000..04644f8f91e --- /dev/null +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md @@ -0,0 +1,218 @@ +## 设备使用信息统计 + +### 权限 + +ohos.permission.BUNDLE_ACTIVE_INFO + +**表1** 设备使用信息统计主要接口 + +| 接口名 | 描述 | +| -------- | -------- | +| function queryBundleActiveStates(begin:number, end:number, callback:AsyncCallback<Array<BundleActiveState>>):void | 通过指定起始和结束时间查询所有应用的事件集合 | +| function queryBundleStateInfos(begin:number, end:number, callback:AsyncCallback<BundleStateInfoResponse>):void | 通过指定起始和结束时间查询应用使用时长统计信息 | +| function queryCurrentBundleActiveStates(begin:number, end:number, callback:AsyncCallback<Array<BundleActiveState>>):void | 通过指定起始和结束时间查询当前应用的事件集合 | +| function queryBundleStateInfoByInterval(byInterval:intervalType, begin:number, end:number, callback:AsyncCallback<Array<BundleStateInfo>>):void | 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息 | +| function queryAppUsagePriorityGroup(callback:AsyncCallback<number>):void | 查询（返回）当前调用者应用的使用优先级群组 | +| function isIdleState(bundleName:string, callback:AsyncCallback<boolean>):void | 判断指定Bundle Name的应用当前是否是空闲状态 | + +## 开发步骤 + +1. 在config.json文件中配置长时任务权限 + + ```json + "module": { + "package": "com.example.deviceUsageStatistics", + ..., + "reqPermissions": [ + { + "name": "ohos.permission.BUNDLE_ACTIVE_INFO" + } + ] + } + ``` + +2. 通过指定起始和结束时间查询所有应用的事件集合 + + ```js + import stats from '@ohos.usagestatskit' + + // 异步方法promise方式 + stats.queryBundleActiveStates(0, 20000000000000).then( res => { + console.log('queryBundleActiveStates promise succeeded, data number: ' + res.length); + for (let i = 0; i < res.length; i++) { + console.log("queryBundleActiveStates, promise bundleName = " + res[i].bundleName) + console.log("queryBundleActiveStates, promise stateType = " + res[i].stateType) + console.log("queryBundleActiveStates, promise stateOccurredTime = " + res[i].stateOccurredTime) + } + }).catch( err => { + console.log('queryBundleActiveStates promise failed, because: ' + err.data); + }); + + // 异步方法callback方式 + setTimeout(()=>{ + stats.queryBundleActiveStates(0, 20000000000000, (err, res) => { + console.log('queryBundleActiveStates callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for (let i = 0; i < res.length; i++) { + console.log("queryBundleActiveStates, callback bundleName = " + res[i].bundleName) + console.log("queryBundleActiveStates, callback stateType = " + res[i].stateType) + console.log("queryBundleActiveStates, callback stateOccurredTime = " + res[i].stateOccurredTime) + } + } else { + console.log('queryBundleActiveStates callback failed, because: ' + err.data); + } + }) + }, 500); + ``` + +3. 通过指定起始和结束时间查询应用使用时长统计信息 + + ```js + import stats from '@ohos.usagestatskit' + + // 异步方法promise方式 + stats.queryBundleStateInfos(0, 20000000000000).then( res => { + console.log('queryBundleStateInfos promise succeeded, data number: ' + res.length); + for(let key in res){ + console.log("queryBundleStateInfos promise key = " + key) + console.log("queryBundleStateInfos promise bundleName = " + res[key].bundleName) + console.log("queryBundleStateInfos promise abilityPrevAccessTime = " + res[key].abilityPrevAccessTime) + console.log("queryBundleStateInfos promise abilityInFgTotalTime = " + res[key].abilityInFgTotalTime) + } + }).catch( err => { + console.log('queryBundleStateInfos promise failed, because: ' + err.data); + }); + + // 异步方法callback方式 + setTimeout(()=>{ + stats.queryBundleStateInfos(0, 20000000000000,(err, res) => { + console.log('queryBundleStateInfos callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for(let key in res){ + console.log("queryBundleStateInfos callback key = " + key) + console.log("queryBundleStateInfos callback bundleName = " + res[key].bundleName) + console.log("queryBundleStateInfos callback abilityPrevAccessTime = " + res[key].abilityPrevAccessTime) + console.log("queryBundleStateInfos callback abilityInFgTotalTime = " + res[key].abilityInFgTotalTime) + } + } else { + console.log('queryBundleStateInfos callback failed, because: ' + err.data); + } + }) + }, 500); + ``` + +4. 通过指定起始和结束时间查询当前应用的事件集合 + + ```js + import stats from '@ohos.usagestatskit' + + // 异步方法promise方式 + stats.queryCurrentBundleActiveStates(0, 20000000000000).then( res => { + console.log('queryCurrentBundleActiveStates promise succeeded, data number: ' + res.length); + for (let i = 0; i < res.length; i++) { + console.log("queryCurrentBundleActiveStates, promise bundleName = " + res[i].bundleName) + console.log("queryCurrentBundleActiveStates, promise stateType = " + res[i].stateType) + console.log("queryCurrentBundleActiveStates, promise stateOccurredTime = " + res[i].stateOccurredTime) + } + }).catch( err => { + console.log('queryCurrentBundleActiveStates promise failed, because: ' + err.data); + }); + + // 异步方法callback方式 + setTimeout(()=>{ + stats.queryCurrentBundleActiveStates(0, 20000000000000,(err, res) => { + console.log('queryCurrentBundleActiveStates callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for (let i = 0; i < res.length; i++) { + console.log("queryCurrentBundleActiveStates, callback bundleName = " + res[i].bundleName) + console.log("queryCurrentBundleActiveStates, callback stateType = " + res[i].stateType) + console.log("queryCurrentBundleActiveStates, callback stateOccurredTime = " + res[i].stateOccurredTime) + } + } else { + console.log('queryCurrentBundleActiveStates callback failed, because: ' + err.data); + } + }) + }, 500); + ``` + +5. 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息 + + ```js + import stats from '@ohos.usagestatskit' + + // 异步方法promise方式 + stats.queryBundleStateInfoByInterval(0, 0, 20000000000000).then( res => { + console.log('queryBundleStateInfoByInterval promise succeeded, data number: ' + res.length); + for (let i = 0; i < res.length; i++) { + console.log("queryBundleStateInfoByInterval, promise bundleName = " + res[i].bundleName) + console.log("queryBundleStateInfoByInterval, promise abilityPrevAccessTime = " + res[i].abilityPrevAccessTime) + console.log("queryBundleStateInfoByInterval, promise abilityInFgTotalTime = " + res[i].abilityInFgTotalTime) + } + }).catch( err => { + console.log('queryBundleStateInfoByiInterval promise failed, because: ' + err.data); + }); + + // 异步方法callback方式 + setTimeout(()=>{ + stats.queryBundleStateInfoByInterval(0, 0, 20000000000000,(err, res) => { + console.log('queryBundleStateInfoByInterval callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for (let i = 0; i < res.length; i++) { + console.log("queryBundleStateInfoByInterval, callback bundleName = " + res[i].bundleName) + console.log("queryBundleStateInfoByInterval, callback abilityPrevAccessTime = " + res[i].abilityPrevAccessTime) + console.log("queryBundleStateInfoByInterval, callback abilityInFgTotalTime = " + res[i].abilityInFgTotalTime) + } + } else { + console.log('queryBundleStateInfoByInterval callback failed, because: ' + err.data); + } + }) + }, 500); + ``` + +6. 查询（返回）当前调用者应用的使用优先级群组 + + ```js + import stats from '@ohos.usagestatskit' + + // 异步方法promise方式 + stats.queryAppUsagePriorityGroup().then( res => { + console.log('queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('queryAppUsagePriorityGroup promise failed, because: ' + err.data); + }); + + // 异步方法callback方式 + setTimeout(()=>{ + stats.queryAppUsagePriorityGroup((err, res) => { + if(err.data === 0) { + console.log('queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); + } else { + console.log('queryAppUsagePriorityGroup callback failed, because: ' + err.data); + } + }) + }, 500); + ``` + +7. 判断指定Bundle Name的应用当前是否是空闲状态 + + ```js + import stats from '@ohos.usagestatskit' + + // 异步方法promise方式 + stats.isIdleState("com.ohos.camera").then( res => { + console.log('isIdleState promise succeeded. result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('isIdleState promise failed, because: ' + err.data); + }); + + // 异步方法callback方式 + setTimeout(()=>{ + stats.isIdleState("com.ohos.camera", (err, res) => { + if(err.data === 0) { + console.log('isIdleState callback succeeded. result: ' + JSON.stringify(res)); + } else { + console.log('isIdleState callback failed, because: ' + err.data); + } + }) + }, 500); + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md new file mode 100644 index 00000000000..0b2d4142dbb --- /dev/null +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md @@ -0,0 +1,24 @@ +# 设备使用信息统计概述 + +设备使用信息统计，包括app usage/notification usage/system usage等使用统计。例如应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（bundle group）情况。部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。 + +## 设备使用信息统计功能说明 + +设备使用信息统计接口众多，以应用使用详情（app usage）接口为例，介绍接口逻辑。 + +- **应用使用统计信息落盘时机**： +>1. 每隔30分钟触发一次刷新； +>2. 系统时间变更触发一次刷新； +>3. 下一天开始触发一次刷新； + +- **应用查询接口**： +>1. 根据起止时间查询所有应用的事件集合； +>2. 根据起止时间查询应用的使用时长； +>3. 根据起止时间查询当前应用的事件集合； +>4. 根据interval（日、周、月、年）类型和起止时间查询应用的使用时长； +>5. 查询调用者应用的优先级群组； +>6. 判断指定应用当前是否是空闲状态； + +### 设备使用信息统计使用权限 +- 设备使用信息统计接口只对系统应用开放，三方应用不可调用。 +- 系统应用调用设备使用信息统计接口前，必须申请ohos.permission.BUNDLE_ACTIVE_INFO权限。 \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md new file mode 100644 index 00000000000..b9dfa135743 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md @@ -0,0 +1,471 @@ +# 设备使用信息统计 + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +## 导入模块 + +``` +import stats from '@ohos.usagestatskit' +``` + +## usagestatskit.isIdleState +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +- **接口**： +isIdleState(bundleName: string, callback: AsyncCallback): void + +- **说明**： +判断指定bundleName的应用当前是否是空闲状态，使用Callback形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | bundleName | string | 是 | 应用的bundleName。| + | callback | AsyncCallback | 是 | 指定的callback回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | + + +- **示例**： + + ``` + stats.isIdleState("com.ohos.camera", (err, res) => { + if(err.data === 0) { + console.log('isIdleState callback succeeded, result: ' + JSON.stringify(res)); + } else { + console.log('isIdleState callback failed, because: ' + err.data); + } + }); + ``` + +## usagestatskit.isIdleState +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +- **接口**： +isIdleState(bundleName: string): Promise; + +- **说明**： +判断指定bundleName的应用当前是否是空闲状态，使用Promise形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | bundleName | string | 是 | 应用的bundleName。| + +- **返回值**： + + | 类型 | 说明 | + | -------- | -------- | + | Promise | 指定的Promise回调方法。如果指定的bundleName有效，则返回指定bundleName的应用当前是否是空闲状态；否则返回null。 | + +- **示例**： + + ``` + stats.isIdleState("com.ohos.camera").then( res => { + console.log('isIdleState callback succeeded, result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('isIdleState callback failed, because: ' + err.data); + }); + ``` + +## usagestatskit.queryAppUsagePriorityGroup +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +- **接口**： +queryAppUsagePriorityGroup(callback: AsyncCallback): void + +- **说明**： +查询（返回）当前调用者应用的使用优先级群组，使用Callback形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback | 是 | 指定的callback回调方法。返回当前调用者应用的使用优先级群组。| + +- **示例**： + + ``` + stats.queryAppUsagePriorityGroup((err, res) => { + if(err.data === 0) { + console.log('queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); + } else { + console.log('queryAppUsagePriorityGroup callback failed. because: ' + err.data); + } + }); + ``` + +## usagestatskit.queryAppUsagePriorityGroup +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.AppGroup + +- **接口**： +queryAppUsagePriorityGroup(): Promise + +- **说明**： +查询（返回）当前调用者应用的使用优先级群组，使用Promise形式返回。 + +- **返回值**： + + | 类型 | 说明 | + | -------- | -------- | + | Promise | 指定的Promise回调方法。查询（返回）当前调用者应用的使用优先级群组。| + +- **示例**： + + ``` + stats.queryAppUsagePriorityGroup().then( res => { + console.log('queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res)); + }).catch( err => { + console.log('queryAppUsagePriorityGroup promise failed. because: ' + err.data); + }); + ``` + +## usagestatskit.queryBundleStateInfos +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback): void + +- **说明**： +通过指定起始和结束时间查询应用使用时长统计信息，使用Callback形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + | callback | AsyncCallback | 是 | 指定的callback回调方法。返回指定起始和结束时间内应用使用时长统计信息。| + +- **示例**： + + ``` + stats.queryBundleStateInfos(0, 20000000000000, (err, res) => { + console.log('queryBundleStateInfos callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for(let key in res){ + console.log("queryBundleStateInfos callback key = " + key) + console.log("queryBundleStateInfos callback bundleName = " + res[key].bundleName) + console.log("queryBundleStateInfos callback abilityPrevAccessTime = " + res[key].abilityPrevAccessTime) + console.log("queryBundleStateInfos callback abilityInFgTotalTime = " + res[key].abilityInFgTotalTime) + } + } else { + console.log('queryBundleStateInfos callback failed, because: ' + err.data); + } + }); + ``` + +## usagestatskit.queryBundleStateInfos +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryBundleStateInfos(begin: number, end: number): Promise + +- **说明**： +通过指定起始和结束时间查询应用使用时长统计信息，使用Promise形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + +- **返回值**： + + | 类型 | 说明 | + | -------- | -------- | + | Promise | 指定的Promise回调方法。返回指定起始和结束时间内应用使用时长统计信息。| + +- **示例**： + + ``` + stats.queryBundleStateInfos(0, 20000000000000).then( res => { + console.log('queryBundleStateInfos promise succeeded, data number: ' + res.length); + for(let key in res){ + console.log("queryBundleStateInfos promise key = " + key) + console.log("queryBundleStateInfos promise bundleName = " + res[key].bundleName) + console.log("queryBundleStateInfos promise abilityPrevAccessTime = " + res[key].abilityPrevAccessTime) + console.log("queryBundleStateInfos promise abilityInFgTotalTime = " + res[key].abilityInFgTotalTime) + } + }).catch( err => { + console.log('queryBundleStateInfos promise failed, because: ' + err.data); + }); + ``` + +## usagestatskit.queryBundleStateInfoByInterval +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback>): void + +- **说明**： +通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Callback形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | byInterval | IntervalType | 是 | 查询类型。| + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + | callback | AsyncCallback> | 是 | 指定的callback回调方法。返回指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。| + +- **示例**： + + ``` + stats.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => { + console.log('queryBundleStateInfoByInterval callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for (let i = 0; i < res.length; i++) { + console.log("queryBundleStateInfoByInterval, callback bundleName = " + res[i].bundleName) + console.log("queryBundleStateInfoByInterval, callback abilityPrevAccessTime = " + res[i].abilityPrevAccessTime) + console.log("queryBundleStateInfoByInterval, callback abilityInFgTotalTime = " + res[i].abilityInFgTotalTime) + } + } else { + console.log('queryBundleStateInfoByInterval callback failed, because: ' + err.data); + } + }); + ``` + +## usagestatskit.queryBundleStateInfoByInterval +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise> + +- **说明**： +通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Promise形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | byInterval | IntervalType | 是 | 查询类型。| + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + +- **返回值**： + + | 类型 | 说明 | + | -------- | -------- | + | Promise> | 指定的Promise回调方法。返回指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。| + +- **示例**： + + ``` + stats.queryBundleStateInfoByInterval(0, 0, 20000000000000).then( res => { + console.log('queryBundleStateInfoByInterval promise succeeded, data number: ' + res.length); + for (let i = 0; i < res.length; i++) { + console.log("queryBundleStateInfoByInterval, promise bundleName = " + res[i].bundleName) + console.log("queryBundleStateInfoByInterval, promise abilityPrevAccessTime = " + res[i].abilityPrevAccessTime) + console.log("queryBundleStateInfoByInterval, promise abilityInFgTotalTime = " + res[i].abilityInFgTotalTime) + } + }).catch( err => { + console.log('queryBundleStateInfoByiInterval promise failed, because: ' + err.data); + }); + ``` + +## usagestatskit.queryBundleActiveStates +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback>): void + +- **说明**： +通过指定起始和结束时间查询所有应用的事件集合，使用Callback形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + | callback | AsyncCallback> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询所有应用的事件集合。| + +- **示例**： + + ``` + stats.queryBundleActiveStates(0, 20000000000000, (err, res) => { + console.log('queryBundleActiveStates callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for (let i = 0; i < res.length; i++) { + console.log("queryBundleActiveStates, callback bundleName = " + res[i].bundleName) + console.log("queryBundleActiveStates, callback stateType = " + res[i].stateType) + console.log("queryBundleActiveStates, callback stateOccurredTime = " + res[i].stateOccurredTime) + } + } else { + console.log('queryBundleActiveStates callback failed, because: ' + err.data); + } + }); + ``` + +## usagestatskit.queryBundleActiveStates +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryBundleActiveStates(begin: number, end: number): Promise> + +- **说明**： +通过指定起始和结束时间查询所有应用的事件集合，使用Promise形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + +- **返回值**： + + | 类型 | 说明 | + | -------- | -------- | + | Promise> | 指定的Promise回调方法。返回指定起始和结束时间查询所有应用的事件集合。| + +- **示例**： + + ``` + stats.queryBundleActiveStates(0, 20000000000000).then( res => { + console.log('queryBundleActiveStates promise succeeded, data number: ' + res.length); + for (let i = 0; i < res.length; i++) { + console.log("queryBundleActiveStates, promise bundleName = " + res[i].bundleName) + console.log("queryBundleActiveStates, promise stateType = " + res[i].stateType) + console.log("queryBundleActiveStates, promise stateOccurredTime = " + res[i].stateOccurredTime) + } + }).catch( err => { + console.log('queryBundleActiveStates promise failed, because: ' + err.data); + }); + ``` + +## usagestatskit.queryCurrentBundleActiveStates +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback>): void + +- **说明**： +通过指定起始和结束时间查询当前应用的事件集合，使用Callback形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + | callback | AsyncCallback> | 是 | 指定的callback回调方法。返回指定起始和结束时间查询当前应用的事件集合。| + +- **示例**： + + ``` + stats.queryCurrentBundleActiveStates(0, 20000000000000,(err, res) => { + console.log('queryCurrentBundleActiveStates callback succeeded, data number: ' + res.length); + if(err.data == 0) { + for (let i = 0; i < res.length; i++) { + console.log("queryCurrentBundleActiveStates, callback bundleName = " + res[i].bundleName) + console.log("queryCurrentBundleActiveStates, callback stateType = " + res[i].stateType) + console.log("queryCurrentBundleActiveStates, callback stateOccurredTime = " + res[i].stateOccurredTime) + } + } else { + console.log('queryCurrentBundleActiveStates callback failed, because: ' + err.data); + } + }); + ``` + +## usagestatskit.queryCurrentBundleActiveStates +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +- **接口**： +queryCurrentBundleActiveStates(begin: number, end: number): Promise> + +- **说明**： +通过指定起始和结束时间查询当前应用的事件集合，使用Promise形式返回。 + +- **参数**： + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | begin | number | 是 | 起始时间。| + | end | number | 是 | 结束时间。| + +- **返回值**： + + | 类型 | 说明 | + | -------- | -------- | + | Promise> | 指定的Promise回调方法。返回指定起始和结束时间查询当前应用的事件集合。| + +- **示例**： + + ``` + stats.queryCurrentBundleActiveStates(0, 20000000000000).then( res => { + console.log('queryCurrentBundleActiveStates promise succeeded, data number: ' + res.length); + for (let i = 0; i < res.length; i++) { + console.log("queryCurrentBundleActiveStates, promise bundleName = " + res[i].bundleName) + console.log("queryCurrentBundleActiveStates, promise stateType = " + res[i].stateType) + console.log("queryCurrentBundleActiveStates, promise stateOccurredTime = " + res[i].stateOccurredTime) + } + }).catch( err => { + console.log('queryCurrentBundleActiveStates promise failed, because: ' + err.data); + }); + ``` + +## usagestatskit.BundleStateInfo +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +提供应用使用时长的具体信息。 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | bundleName | string | 是 | 应用包名。| + | abilityPrevAccessTime | number | 是 | 应用最后一次使用的时间。| + | abilityInFgTotalTime | number | 是 | 应用在前台使用的总时间。| + +## usagestatskit.BundleActiveState +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +提供应用事件的具体信息。 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | bundleName | string | 是 | 应用包名。| + | stateType | number | 是 | 应用事件类型。| + | stateOccurredTime | number | 是 | 应用事件发生的时间戳。| + +## usagestatskit.BundleActiveInfoResponse +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +提供应用使用时长的具体信息。 + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | [key: string]: BundleStateInfo | BundleStateInfo | 是 | 不同应用的使用时长统计信息。| + +## usagestatskit.IntervalType +- **系统能力**： +SystemCapability.ResourceSchedule.UsageStatistics.App + +触发工作的网络类型。 + + |名称 |默认值 |说明| + | -------- | -------- | -------- | + | BY_OPTIMIZED | 0 | 表示系统自己判断最合适的查询类型（天、周、月、年）去查询指定时间段间隔的应用使用时长信息。| + | BY_DAILY | 1 | 表示系统按照天去查询指定时间段间隔的应用使用时长信息。| + | BY_WEEKLY | 2 | 表示系统按照周去查询指定时间段间隔的应用使用时长信息。| + | BY_MONTHLY | 3 | 表示系统按照月去查询指定时间段间隔的应用使用时长信息。| + | BY_ANNUALLY | 4 | 表示系统按照年去查询指定时间段间隔的应用使用时长信息。| \ No newline at end of file -- Gitee From cc934fe0cb1f0386792d2d0a0fd5942e31dbc1e6 Mon Sep 17 00:00:00 2001 From: wyuanchao Date: Mon, 28 Feb 2022 20:47:05 +0800 Subject: [PATCH 2/3] device usage statistics docs Signed-off-by: wyuanchao --- .../device-usage-statistics-dev-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md index 04644f8f91e..b485214c0f9 100644 --- a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md @@ -17,7 +17,7 @@ ohos.permission.BUNDLE_ACTIVE_INFO ## 开发步骤 -1. 在config.json文件中配置长时任务权限 +1. 在config.json文件中配置设备使用信息统计权限 ```json "module": { -- Gitee From 81376443d190b3a60284d05f7df233c7c9871bd4 Mon Sep 17 00:00:00 2001 From: wyuanchao Date: Tue, 1 Mar 2022 14:56:00 +0800 Subject: [PATCH 3/3] device-usage-statistics Signed-off-by: wyuanchao --- .../device-usage-statistics-dev-guide.md | 37 +++++++----- .../device-usage-statistics-overview.md | 4 +- .../apis/js-apis-deviceUsageStatistics.md | 60 ++++++++----------- 3 files changed, 48 insertions(+), 53 deletions(-) diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md index b485214c0f9..3afd163afdf 100644 --- a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-dev-guide.md @@ -1,23 +1,30 @@ ## 设备使用信息统计 -### 权限 +## 场景介绍 -ohos.permission.BUNDLE_ACTIVE_INFO +设备使用信息统计，包括app usage/notification usage/system usage等使用统计。例如应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（bundle group）情况。 +部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。 + +## 接口说明 +注册相关接口包导入： +```js +import stats from '@ohos.usagestatskit'; +``` **表1** 设备使用信息统计主要接口 | 接口名 | 描述 | | -------- | -------- | -| function queryBundleActiveStates(begin:number, end:number, callback:AsyncCallback<Array<BundleActiveState>>):void | 通过指定起始和结束时间查询所有应用的事件集合 | -| function queryBundleStateInfos(begin:number, end:number, callback:AsyncCallback<BundleStateInfoResponse>):void | 通过指定起始和结束时间查询应用使用时长统计信息 | -| function queryCurrentBundleActiveStates(begin:number, end:number, callback:AsyncCallback<Array<BundleActiveState>>):void | 通过指定起始和结束时间查询当前应用的事件集合 | -| function queryBundleStateInfoByInterval(byInterval:intervalType, begin:number, end:number, callback:AsyncCallback<Array<BundleStateInfo>>):void | 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息 | -| function queryAppUsagePriorityGroup(callback:AsyncCallback<number>):void | 查询（返回）当前调用者应用的使用优先级群组 | -| function isIdleState(bundleName:string, callback:AsyncCallback<boolean>):void | 判断指定Bundle Name的应用当前是否是空闲状态 | +| function queryBundleActiveStates(begin:number, end:number, callback:AsyncCallback<Array<BundleActiveState>>):void | 通过指定起始和结束时间查询所有应用的事件集合。 | +| function queryBundleStateInfos(begin:number, end:number, callback:AsyncCallback<BundleStateInfoResponse>):void | 通过指定起始和结束时间查询应用使用时长统计信息。 | +| function queryCurrentBundleActiveStates(begin:number, end:number, callback:AsyncCallback<Array<BundleActiveState>>):void | 通过指定起始和结束时间查询当前应用的事件集合。 | +| function queryBundleStateInfoByInterval(byInterval:intervalType, begin:number, end:number, callback:AsyncCallback<Array<BundleStateInfo>>):void | 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 | +| function queryAppUsagePriorityGroup(callback:AsyncCallback<number>):void | 查询（返回）当前调用者应用的使用优先级群组。 | +| function isIdleState(bundleName:string, callback:AsyncCallback<boolean>):void | 判断指定Bundle Name的应用当前是否是空闲状态。 | ## 开发步骤 -1. 在config.json文件中配置设备使用信息统计权限 +1. 在config.json文件中配置设备使用信息统计权限。 ```json "module": { @@ -31,7 +38,7 @@ ohos.permission.BUNDLE_ACTIVE_INFO } ``` -2. 通过指定起始和结束时间查询所有应用的事件集合 +2. 通过指定起始和结束时间查询所有应用的事件集合。 ```js import stats from '@ohos.usagestatskit' @@ -65,7 +72,7 @@ ohos.permission.BUNDLE_ACTIVE_INFO }, 500); ``` -3. 通过指定起始和结束时间查询应用使用时长统计信息 +3. 通过指定起始和结束时间查询应用使用时长统计信息。 ```js import stats from '@ohos.usagestatskit' @@ -101,7 +108,7 @@ ohos.permission.BUNDLE_ACTIVE_INFO }, 500); ``` -4. 通过指定起始和结束时间查询当前应用的事件集合 +4. 通过指定起始和结束时间查询当前应用的事件集合。 ```js import stats from '@ohos.usagestatskit' @@ -135,7 +142,7 @@ ohos.permission.BUNDLE_ACTIVE_INFO }, 500); ``` -5. 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息 +5. 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。 ```js import stats from '@ohos.usagestatskit' @@ -169,7 +176,7 @@ ohos.permission.BUNDLE_ACTIVE_INFO }, 500); ``` -6. 查询（返回）当前调用者应用的使用优先级群组 +6. 查询（返回）当前调用者应用的使用优先级群组。 ```js import stats from '@ohos.usagestatskit' @@ -193,7 +200,7 @@ ohos.permission.BUNDLE_ACTIVE_INFO }, 500); ``` -7. 判断指定Bundle Name的应用当前是否是空闲状态 +7. 判断指定Bundle Name的应用当前是否是空闲状态。 ```js import stats from '@ohos.usagestatskit' diff --git a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md index 0b2d4142dbb..2044ec8683c 100644 --- a/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md +++ b/zh-cn/application-dev/device-usage-statistics/device-usage-statistics-overview.md @@ -1,10 +1,10 @@ # 设备使用信息统计概述 -设备使用信息统计，包括app usage/notification usage/system usage等使用统计。例如应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（bundle group）情况。部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。 +设备使用信息统计，包括app usage/notification usage/system usage等使用统计，目前只支持app usage使用统计。应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（bundle group）情况。部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。 ## 设备使用信息统计功能说明 -设备使用信息统计接口众多，以应用使用详情（app usage）接口为例，介绍接口逻辑。 +设备使用信息统计接口众多，目前只支持app usage使用统计，接下来介绍下应用使用详情（app usage）的接口逻辑。 - **应用使用统计信息落盘时机**： >1. 每隔30分钟触发一次刷新； diff --git a/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md index b9dfa135743..0ff74ddd401 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md +++ b/zh-cn/application-dev/reference/apis/js-apis-deviceUsageStatistics.md @@ -11,12 +11,11 @@ import stats from '@ohos.usagestatskit' ``` ## usagestatskit.isIdleState +isIdleState(bundleName: string, callback: AsyncCallback): void + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.AppGroup -- **接口**： -isIdleState(bundleName: string, callback: AsyncCallback): void - - **说明**： 判断指定bundleName的应用当前是否是空闲状态，使用Callback形式返回。 @@ -41,12 +40,11 @@ isIdleState(bundleName: string, callback: AsyncCallback): void ``` ## usagestatskit.isIdleState +isIdleState(bundleName: string): Promise; + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.AppGroup -- **接口**： -isIdleState(bundleName: string): Promise; - - **说明**： 判断指定bundleName的应用当前是否是空闲状态，使用Promise形式返回。 @@ -73,12 +71,11 @@ isIdleState(bundleName: string): Promise; ``` ## usagestatskit.queryAppUsagePriorityGroup +queryAppUsagePriorityGroup(callback: AsyncCallback): void + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.AppGroup -- **接口**： -queryAppUsagePriorityGroup(callback: AsyncCallback): void - - **说明**： 查询（返回）当前调用者应用的使用优先级群组，使用Callback形式返回。 @@ -101,12 +98,11 @@ queryAppUsagePriorityGroup(callback: AsyncCallback): void ``` ## usagestatskit.queryAppUsagePriorityGroup +queryAppUsagePriorityGroup(): Promise + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.AppGroup -- **接口**： -queryAppUsagePriorityGroup(): Promise - - **说明**： 查询（返回）当前调用者应用的使用优先级群组，使用Promise形式返回。 @@ -127,12 +123,11 @@ queryAppUsagePriorityGroup(): Promise ``` ## usagestatskit.queryBundleStateInfos +queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback): void + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback): void - - **说明**： 通过指定起始和结束时间查询应用使用时长统计信息，使用Callback形式返回。 @@ -163,12 +158,11 @@ queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryBundleStateInfos(begin: number, end: number): Promise - - **说明**： 通过指定起始和结束时间查询应用使用时长统计信息，使用Promise形式返回。 @@ -202,12 +196,11 @@ queryBundleStateInfos(begin: number, end: number): Promise>): void + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback>): void - - **说明**： 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Callback形式返回。 @@ -238,12 +231,11 @@ queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: num ``` ## usagestatskit.queryBundleStateInfoByInterval +queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise> + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise> - - **说明**： 通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息，使用Promise形式返回。 @@ -277,12 +269,11 @@ queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: num ``` ## usagestatskit.queryBundleActiveStates +queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback>): void + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback>): void - - **说明**： 通过指定起始和结束时间查询所有应用的事件集合，使用Callback形式返回。 @@ -312,12 +303,11 @@ queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback> + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryBundleActiveStates(begin: number, end: number): Promise> - - **说明**： 通过指定起始和结束时间查询所有应用的事件集合，使用Promise形式返回。 @@ -350,12 +340,11 @@ queryBundleActiveStates(begin: number, end: number): Promise>): void + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback>): void - - **说明**： 通过指定起始和结束时间查询当前应用的事件集合，使用Callback形式返回。 @@ -385,12 +374,11 @@ queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallba ``` ## usagestatskit.queryCurrentBundleActiveStates +queryCurrentBundleActiveStates(begin: number, end: number): Promise> + - **系统能力**： SystemCapability.ResourceSchedule.UsageStatistics.App -- **接口**： -queryCurrentBundleActiveStates(begin: number, end: number): Promise> - - **说明**： 通过指定起始和结束时间查询当前应用的事件集合，使用Promise形式返回。 -- Gitee