README.md
1# Device usage statistics<a name="EN-US_TOPIC_0000001115588558"></a>
2
3- [Introduction](#section11660541593)
4- [Directory Structure](#section161941989596)
5- [Instruction](#section1312121216216)
6 - [Available APIs](#section1551164914237)
7 - [Usage Guidelines](#section129654513264)
8
9- [Repositories Involved](#section1371113476307)
10
11## Introduction<a name="section11660541593"></a>
12
13The **device usage statistics** includes app usage, notification usage, system usage and other usage statistics. For example, application usage statistics is used to save
14and query application usage details, event log data and application grouping.The application records (usage history statistics and usage event records) cached by
15the component will be periodically refreshed to the database for persistent storage.
16
17## Directory Structure<a name="section161941989596"></a>
18
19```
20/foundation/resourceschedule/device_usage_statistics
21├── BUILD.gn # Module compilation script
22├── LICENSE # Open source protocol
23├── adapter # Adaptation directory
24├── bundle.json # Component decoupling and compiling script
25├── frameworks # Framework layer directory
26├── interfaces
27│ ├── innerkits # Internal interface directory
28│ └── kits # External interface directory
29├── services # Service layer directory
30└── test # Testing case directory
31```
32
33## Instruction<a name="section1312121216216"></a>
34
35### Available APIs<a name="section1551164914237"></a>
36
37Device usage statistics interfaces include app usage, notification usage, system usage and other interfaces.
38Taking app usage interface as an example, the main exposed interfaces are as follows.
39
40<a name="table775715438253"></a>
41<table><thead align="left"><tr id="row12757154342519"><th class="cellrowborder" valign="top" width="60%" id="mcps1.1.3.1.1"><p id="p1075794372512"><a name="p1075794372512"></a><a name="p1075794372512"></a>API name</p>
42</th>
43<th class="cellrowborder" valign="top" width="56.81%" id="mcps1.1.3.1.2"><p id="p375844342518"><a name="p375844342518"></a><a name="p375844342518"></a>API description</p>
44</th>
45</tr>
46</thead>
47<tbody><tr id="row1975804332517"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p5758174313255"><a name="p5758174313255"></a><a name="p5758174313255"></a>queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void</p>
48</td>
49<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p14758743192519"><a name="p14758743192519"></a><a name="p14758743192519"></a>Queries the event collection of all applications through time interval.</p>
50</td>
51</tr>
52<tr id="row2758943102514"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p107581438250"><a name="p107581438250"></a><a name="p107581438250"></a>queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback<BundleActiveInfoResponse>): void</p>
53</td>
54<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p8758743202512"><a name="p8758743202512"></a><a name="p8758743202512"></a>Uses the start and end time to query the application usage time statistics.</p>
55</td>
56</tr>
57<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void</p>
58</td>
59<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>Queries the event collection of the current application through the time interval.</p>
60<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStateInfo>>): void</p>
61</td>
62<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>Queries application usage duration statistics by time interval.</p>
63<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void</p>
64</td>
65<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>Queries (returns) the priority group used by the current caller application.</p>
66<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void</p>
67</td>
68<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>Judges whether the application of the specified bundle name is currently idle.</p>
69</td>
70</tr>
71</tbody>
72</table>
73
74### Usage Guidelines<a name="section129654513264"></a>
75
76There are many interfaces for device usage statistics. Take app usage interface as an example to introduce the interface logic.
77
78- **device usage statistics saving time**:
79>1. refreshing is triggered every 30 minutes;
80>2. refreshing is triggered when system time changes;
81>3. refreshing is triggered from the next day;
82- **app querying interface**:
83>1. Query the event collection of all applications according to the start and end time;
84>2. Query the usage duration of the application according to the start and end time;
85>3. Query the event collection of the current application according to the start and end time;
86>4. Query the usage duration of the application according to the type of interval (day, week, month, year) and the start and end time;
87>5. Query the priority group of the caller application;
88>6. Judge whether the specified application is currently idle;
89
90## Repositories Involved<a name="section1371113476307"></a>
91
92resource schedule subsystem
93
94**device\_usage\_statistics**
95
96resource_schedule_service
97
98appexecfwk_standard
99
100native_appdatamgr
README_zh.md
1# 设备使用信息统计<a name="ZH-CN_TOPIC_0000001115588558"></a>
2- [简介](#section11660541593)
3- [目录](#section161941989596)
4- [说明](#section1312121216216)
5 - [接口说明](#section1551164914237)
6 - [使用说明](#section129654513264)
7
8- [相关仓](#section1371113476307)
9
10## 简介<a name="section11660541593"></a>
11
12设备使用信息统计，包括app usage/notification usage/system usage等使用统计。例如应用使用信息统计，用于保存和查询应用使用详情（app usage）、事件日志数据（event log）、应用分组（bundle group）情况。
13部件缓存的应用记录（使用历史统计和使用事件记录）会在事件上报后30分钟内刷新到数据库持久化保存。
14
15## 目录<a name="section161941989596"></a>
16
17```
18/foundation/resourceschedule/device_usage_statistics
19├── BUILD.gn # 模块编译脚本
20├── LICENSE # 开源协议
21├── adapter # 适配目录
22├── bundle.json # 部件化解耦及编译脚本
23├── frameworks # 框架层目录
24├── interfaces
25│ ├── innerkits # 对内接口目录
26│ └── kits # 对外接口目录
27├── services # 服务层目录
28└── test # 测试用例目录
29```
30
31## 说明<a name="section1312121216216"></a>
32
33### 接口说明<a name="section1551164914237"></a>
34
35设备使用信息统计接口，包括app usage/notification usage/system usage等接口，以app usage接口为例，对外提供主要接口如下。
36
37<a name="table775715438253"></a>
38<table><thead align="left"><tr id="row12757154342519"><th class="cellrowborder" valign="top" width="73%" id="mcps1.1.3.1.1"><p id="p1075794372512"><a name="p1075794372512"></a><a name="p1075794372512"></a>接口名</p>
39</th>
40<th class="cellrowborder" valign="top" width="56.81%" id="mcps1.1.3.1.2"><p id="p375844342518"><a name="p375844342518"></a><a name="p375844342518"></a>接口描述</p>
41</th>
42</tr>
43</thead>
44<tbody><tr id="row1975804332517"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p5758174313255"><a name="p5758174313255"></a><a name="p5758174313255"></a>queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void</p>
45</td>
46<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p14758743192519"><a name="p14758743192519"></a><a name="p14758743192519"></a>通过指定起始和结束时间查询所有应用的事件集合。</p>
47</td>
48</tr>
49<tr id="row2758943102514"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p107581438250"><a name="p107581438250"></a><a name="p107581438250"></a>queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback<BundleActiveInfoResponse>): void</p>
50</td>
51<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p8758743202512"><a name="p8758743202512"></a><a name="p8758743202512"></a>通过指定起始和结束时间查询应用使用时长统计信息。</p>
52</td>
53</tr>
54<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void</p>
55</td>
56<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>通过指定起始和结束时间查询当前应用的事件集合。</p>
57<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStateInfo>>): void</p>
58</td>
59<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>通过指定时间段间隔（天、周、月、年）查询应用使用时长统计信息。</p>
60<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void</p>
61</td>
62<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>查询（返回）当前调用者应用的使用优先级群组。</p>
63<tr id="row09311240175710"><td class="cellrowborder" valign="top" width="43.19%" headers="mcps1.1.3.1.1 "><p id="p159328405571"><a name="p159328405571"></a><a name="p159328405571"></a>isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void</p>
64</td>
65<td class="cellrowborder" valign="top" width="56.81%" headers="mcps1.1.3.1.2 "><p id="p493294018574"><a name="p493294018574"></a><a name="p493294018574"></a>判断指定Bundle Name的应用当前是否是空闲状态。</p>
66</td>
67</tr>
68</tbody>
69</table>
70
71### 使用说明<a name="section129654513264"></a>
72
73设备使用信息统计接口众多，以应用使用详情（app usage）接口为例，介绍接口逻辑。
74
75- **应用使用统计信息落盘时机**：
76>1. 每隔30分钟触发一次刷新；
77>2. 系统时间变更触发一次刷新；
78>3. 下一天开始触发一次刷新；
79- **应用查询接口**：
80>1. 根据起止时间查询所有应用的事件集合；
81>2. 根据起止时间查询应用的使用时长；
82>3. 根据起止时间查询当前应用的事件集合；
83>4. 根据interval（日、周、月、年）类型和起止时间查询应用的使用时长；
84>5. 查询调用者应用的优先级群组；
85>6. 判断指定应用当前是否是空闲状态；
86
87## 相关仓<a name="section1371113476307"></a>
88
89全局资源调度子系统
90
91**device\_usage\_statistics**
92
93resource_schedule_service
94
95appexecfwk_standard
96
97native_appdatamgr