1# Device Usage Statistics 2 3This module provides APIs for collecting statistics on device usage. 4 5System applications can call these APIs to implement the following features: 6 7- Query the usage duration in different time segments, events (foreground, background, start and end of continuous tasks), and the number of notifications, on a per application basis. 8- Query statistics about system events (sleep, wakeup, unlock, and screen lock). 9- Query the bundle group information of applications, including the invoking application itself. 10- Query the idle status of applications, including the invoking application itself. 11- Set the bundle group for other applications. 12- Register and deregister the callback for application group changes. 13 14Third-party applications can call these APIs to implement the following features: 15 16- Query the idle status of the invoking application itself. 17- Query the bundle group information of the invoking application itself. 18- Query the events of the invoking application itself. 19 20> **NOTE** 21> 22> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 23 24 25## Modules to Import 26 27``` 28import bundleState from '@ohos.bundleState' 29``` 30 31## bundleState.isIdleState 32 33isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void 34 35Checks whether the application specified by **bundleName** is in the idle state. This API uses an asynchronous callback to return the result. A third-party application can only check the idle status of itself. 36 37**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 38 39**Parameters** 40 41| Name | Type | Mandatory | Description | 42| ---------- | ---------------------------- | ---- | ---------------------------------------- | 43| bundleName | string | Yes | Bundle name of an application. | 44| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the value of <b class="+ topic/ph hi-d/b " id="b597417553714">bundleName</b> is valid, <b class="+ topic/ph hi-d/b " id="b1897411555719">null</b> will be returned.| 45 46**Example** 47 48 ``` 49 bundleState.isIdleState("com.ohos.camera", (err, res) => { 50 if (err) { 51 console.log('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); 52 } else { 53 console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); 54 } 55 }); 56 ``` 57 58## bundleState.isIdleState 59 60isIdleState(bundleName: string): Promise<boolean> 61 62Checks whether the application specified by **bundleName** is in the idle state. This API uses a promise to return the result. A third-party application can only check the idle status of itself. 63 64**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 65 66**Parameters** 67 68| Name | Type | Mandatory | Description | 69| ---------- | ------ | ---- | -------------- | 70| bundleName | string | Yes | Bundle name of an application.| 71 72**Return value** 73 74| Type | Description | 75| ---------------------- | ---------------------------------------- | 76| Promise<boolean> | Promise used to return the result. If the value of **bundleName** is valid, **null** will be returned.| 77 78**Example** 79 80 ``` 81 bundleState.isIdleState("com.ohos.camera").then(res => { 82 console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); 83 }).catch(err => { 84 console.log('BUNDLE_ACTIVE isIdleState promise failed, because: ' + err.code); 85 }); 86 ``` 87 88## bundleState.queryAppUsagePriorityGroup 89 90queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void 91 92Queries the priority group of this application. This API usesan asynchronous callback to return the result. 93 94**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 95 96**Parameters** 97 98| Name | Type | Mandatory | Description | 99| ---------- | ------ | ---- | -------------- | 100 101| callback | AsyncCallback<number> | Yes | Callback used to return the result.| 102 103**Example** 104 105 ``` 106 bundleState.queryAppUsagePriorityGroup((err, res) => { 107 if (err) { 108 console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback failed. because: ' + err.code); 109 } else { 110 console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup callback succeeded. result: ' + JSON.stringify(res)); 111 } 112 }); 113 ``` 114 115## bundleState.queryAppUsagePriorityGroup 116 117queryAppUsagePriorityGroup(): Promise<number> 118 119Queries the priority group of this application. This API uses a promise to return the result. 120 121**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 122 123**Return value** 124 125| Type | Description | 126| --------------- | --------------------------- | 127| Promise<number> | Promise used to return the result.| 128 129**Example** 130 131 ``` 132 bundleState.queryAppUsagePriorityGroup().then(res => { 133 console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise succeeded. result: ' + JSON.stringify(res)); 134 }).catch(err => { 135 console.log('BUNDLE_ACTIVE queryAppUsagePriorityGroup promise failed. because: ' + err.code); 136 }); 137 ``` 138## bundleState.queryBundleStateInfos 139 140queryBundleStateInfos(begin: number, end: number, callback: AsyncCallback<BundleActiveInfoResponse>): void 141 142Queries the application usage duration statistics based on the specified start time and end time. This API uses an asynchronous callback to return the result. 143 144**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 145 146**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 147 148**System API**: This is a system API and cannot be called by third-party applications. 149 150**Parameters** 151 152| Name | Type | Mandatory | Description | 153| -------- | ---------------------------------------- | ---- | --------------------------------------- | 154| begin | number | Yes | Start time. | 155| end | number | Yes | End time. | 156| callback | AsyncCallback<[BundleActiveInfoResponse](#bundleactiveinforesponse)> | Yes | Callback used to return the result.| 157 158**Example** 159 160 ``` 161 bundleState.queryBundleStateInfos(0, 20000000000000, (err, res) => { 162 if (err) { 163 console.log('BUNDLE_ACTIVE queryBundleStateInfos callback failed, because: ' + err.code); 164 } else { 165 console.log('BUNDLE_ACTIVE queryBundleStateInfos callback success.'); 166 let i = 1; 167 for (let key in res) { 168 console.log('BUNDLE_ACTIVE queryBundleStateInfos callback number : ' + i); 169 console.log('BUNDLE_ACTIVE queryBundleStateInfos callback result ' + JSON.stringify(res[key])); 170 i++; 171 } 172 } 173 }); 174 ``` 175 176## bundleState.queryBundleStateInfos 177 178queryBundleStateInfos(begin: number, end: number): Promise<BundleActiveInfoResponse> 179 180Queries the application usage duration statistics based on the specified start time and end time. This API uses a promise to return the result. 181 182**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 183 184**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 185 186**System API**: This is a system API and cannot be called by third-party applications. 187 188**Parameters** 189 190| Name | Type | Mandatory | Description | 191| ----- | ------ | ---- | ----- | 192| begin | number | Yes | Start time.| 193| end | number | Yes | End time.| 194 195**Return value** 196 197| Type | Description | 198| ---------------------------------------- | -------------------------------------- | 199| Promise<[BundleActiveInfoResponse](#bundleactiveinforesponse)> | Promise used to return the result.| 200 201**Example** 202 203 ``` 204 bundleState.queryBundleStateInfos(0, 20000000000000).then(res => { 205 console.log('BUNDLE_ACTIVE queryBundleStateInfos promise success.'); 206 let i = 1; 207 for (let key in res) { 208 console.log('BUNDLE_ACTIVE queryBundleStateInfos promise number : ' + i); 209 console.log('BUNDLE_ACTIVE queryBundleStateInfos promise result ' + JSON.stringify(res[key])); 210 i++; 211 } 212 }).catch(err => { 213 console.log('BUNDLE_ACTIVE queryBundleStateInfos promise failed, because: ' + err.code); 214 }); 215 ``` 216 217## bundleState.queryBundleStateInfoByInterval 218 219queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStateInfo>>): void 220 221Queries the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually). This API uses an asynchronous callback to return the result. 222 223**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 224 225**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 226 227**System API**: This is a system API and cannot be called by third-party applications. 228 229**Parameters** 230 231| Name | Type | Mandatory | Description | 232| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 233| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried. | 234| begin | number | Yes | Start time. | 235| end | number | Yes | End time. | 236| callback | AsyncCallback<Array<[BundleStateInfo](#bundlestateinfo)>> | Yes | Callback used to return the result.| 237 238**Example** 239 240 ``` 241 bundleState.queryBundleStateInfoByInterval(0, 0, 20000000000000, (err, res) => { 242 if (err) { 243 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback failed, because: ' + err.code); 244 } else { 245 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback success.'); 246 for (let i = 0; i < res.length; i++) { 247 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback number : ' + (i + 1)); 248 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval callback result ' + JSON.stringify(res[i])); 249 } 250 } 251 }); 252 ``` 253 254## bundleState.queryBundleStateInfoByInterval 255 256queryBundleStateInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise<Array<BundleStateInfo>> 257 258Queries the application usage duration statistics in the specified time frame at the specified interval (daily, weekly, monthly, or annually). This API uses a promise to return the result. 259 260**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 261 262**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 263 264**System API**: This is a system API and cannot be called by third-party applications. 265 266**Parameters** 267 268| Name | Type | Mandatory | Description | 269| ---------- | ----------------------------- | ---- | ----- | 270| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried.| 271| begin | number | Yes | Start time.| 272| end | number | Yes | End time.| 273 274**Return value** 275 276| Type | Description | 277| ---------------------------------------- | ---------------------------------------- | 278| Promise<Array<[BundleStateInfo](#bundlestateinfo)>> | Promise used to return the result.| 279 280**Example** 281 282 ``` 283 bundleState.queryBundleStateInfoByInterval(0, 0, 20000000000000).then(res => { 284 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise success.'); 285 for (let i = 0; i < res.length; i++) { 286 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise number : ' + (i + 1)); 287 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise result ' + JSON.stringify(res[i])); 288 } 289 }).catch(err => { 290 console.log('BUNDLE_ACTIVE queryBundleStateInfoByInterval promise failed, because: ' + err.code); 291 }); 292 ``` 293 294## bundleState.queryBundleActiveStates 295 296queryBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void 297 298Queries events of all applications based on the specified start time and end time. This API uses an asynchronous callback to return the result. 299 300**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 301 302**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 303 304**System API**: This is a system API and cannot be called by third-party applications. 305 306**Parameters** 307 308| Name | Type | Mandatory | Description | 309| -------- | ---------------------------------------- | ---- | --------------------------------------- | 310| begin | number | Yes | Start time. | 311| end | number | Yes | End time. | 312| callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | Yes | Callback used to return the result.| 313 314**Example** 315 316 ``` 317 bundleState.queryBundleActiveStates(0, 20000000000000, (err, res) => { 318 if (err) { 319 console.log('BUNDLE_ACTIVE queryBundleActiveStates callback failed, because: ' + err.code); 320 } else { 321 console.log('BUNDLE_ACTIVE queryBundleActiveStates callback success.'); 322 for (let i = 0; i < res.length; i++) { 323 console.log('BUNDLE_ACTIVE queryBundleActiveStates callback number : ' + (i + 1)); 324 console.log('BUNDLE_ACTIVE queryBundleActiveStates callback result ' + JSON.stringify(res[i])); 325 } 326 } 327 }); 328 ``` 329 330## bundleState.queryBundleActiveStates 331 332queryBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>> 333 334Queries events of all applications based on the specified start time and end time. This API uses a promise to return the result. 335 336**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 337 338**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 339 340**System API**: This is a system API and cannot be called by third-party applications. 341 342**Parameters** 343 344| Name | Type | Mandatory | Description | 345| ----- | ------ | ---- | ----- | 346| begin | number | Yes | Start time.| 347| end | number | Yes | End time.| 348 349**Return value** 350 351| Type | Description | 352| ---------------------------------------- | -------------------------------------- | 353| Promise<Array<[BundleActiveState](#bundleactivestate)>> | Promise used to return the result.| 354 355**Example** 356 357 ``` 358 bundleState.queryBundleActiveStates(0, 20000000000000).then(res => { 359 console.log('BUNDLE_ACTIVE queryBundleActiveStates promise success.'); 360 for (let i = 0; i < res.length; i++) { 361 console.log('BUNDLE_ACTIVE queryBundleActiveStates promise number : ' + (i + 1)); 362 console.log('BUNDLE_ACTIVE queryBundleActiveStates promise result ' + JSON.stringify(res[i])); 363 } 364 }).catch(err => { 365 console.log('BUNDLE_ACTIVE queryBundleActiveStates promise failed, because: ' + err.code); 366 }); 367 ``` 368 369## bundleState.queryCurrentBundleActiveStates 370 371queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void 372 373Queries events of this application based on the specified start time and end time. This API uses an asynchronous callback to return the result. 374 375**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 376 377**Parameters** 378 379| Name | Type | Mandatory | Description | 380| -------- | ---------------------------------------- | ---- | --------------------------------------- | 381| begin | number | Yes | Start time. | 382| end | number | Yes | End time. | 383| callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | Yes | Callback used to return the result.| 384 385**Example** 386 387 ``` 388 bundleState.queryCurrentBundleActiveStates(0, 20000000000000, (err, res) => { 389 if (err) { 390 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code); 391 } else { 392 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback success.'); 393 for (let i = 0; i < res.length; i++) { 394 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback number : ' + (i + 1)); 395 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback result ' + JSON.stringify(res[i])); 396 } 397 } 398 }); 399 ``` 400 401## bundleState.queryCurrentBundleActiveStates 402 403queryCurrentBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>> 404 405Queries events of this application based on the specified start time and end time. This API uses a promise to return the result. 406 407**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 408 409**Parameters** 410 411| Name | Type | Mandatory | Description | 412| ----- | ------ | ---- | ----- | 413| begin | number | Yes | Start time.| 414| end | number | Yes | End time.| 415 416**Return value** 417 418| Type | Description | 419| ---------------------------------------- | -------------------------------------- | 420| Promise<Array<[BundleActiveState](#bundleactivestate)>> | Promise used to return the result.| 421 422**Example** 423 424 ``` 425 bundleState.queryCurrentBundleActiveStates(0, 20000000000000).then(res => { 426 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise success.'); 427 for (let i = 0; i < res.length; i++) { 428 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise number : ' + (i + 1)); 429 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise result ' + JSON.stringify(res[i])); 430 } 431 }).catch(err => { 432 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise failed, because: ' + err.code); 433 }); 434 ``` 435 436## BundleStateInfo 437 438Provides the usage duration information of applications. 439 440### Attributes 441 442**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 443 444| Name | Type | Mandatory | Description | 445| ------------------------ | ------ | ---- | ---------------------------------------- | 446| bundleName | string | Yes | Bundle name of an application. | 447| abilityPrevAccessTime | number | Yes | Last time when the application was used. | 448| abilityInFgTotalTime | number | Yes | Total time that the application runs in the foreground. | 449| id | number | No | User ID.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 450| abilityPrevSeenTime | number | No | Last time when the application was visible in the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 451| abilitySeenTotalTime | number | No | Total time that the application is visible in the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 452| fgAbilityAccessTotalTime | number | No | Total time that the application accesses the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 453| fgAbilityPrevAccessTime | number | No | Last time when the application accessed the foreground.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 454| infosBeginTime | number | No | Time logged in the first application usage record in the **BundleActiveInfo** object.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 455| infosEndTime | number | No | Time logged in the last application usage record in the **BundleActiveInfo** object.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 456 457### merge 458 459merge(toMerge: BundleStateInfo): void 460 461Merges the application usage information that has the same bundle name. 462 463**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 464 465**Parameters** 466 467| Name | Type | Mandatory | Description | 468| ------- | ----------------------------------- | ---- | -------------- | 469| toMerge | [BundleStateInfo](#bundlestateinfo) | Yes | Application usage information to merge.| 470 471## BundleActiveState 472 473Provides information about an application event. 474 475**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 476 477| Name | Type | Mandatory | Description | 478| --------------------- | ------ | ---- | ---------------------------------------- | 479| bundleName | string | Yes | Bundle name of an application. | 480| stateType | number | Yes | Application event type. | 481| stateOccurredTime | number | Yes | Timestamp when the application event occurs. | 482| appUsagePriorityGroup | number | No | Usage priority group of the application.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 483| indexOfLink | string | No | Shortcut ID.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 484| nameOfClass | string | No | Class name.<br>This API is defined but not implemented in OpenHarmony 3.1 Release. It will be available for use in OpenHarmony 3.1 MR.| 485 486## BundleActiveInfoResponse 487 488Provides the usage duration information of applications. 489 490**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 491 492| Name | Type | Mandatory | Description | 493| ------------------------------ | ---------------------------------------- | ---- | -------------- | 494| [key: string]: BundleStateInfo | [key: string]: [BundleStateInfo](#bundlestateinfo) | Yes | Usage duration information by application.| 495 496 497## IntervalType 498 499Enumerates the interval types for querying the application usage duration. 500 501**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 502 503| Name | Default Value | Description | 504| ------------ | ---- | ---------------------------------------- | 505| BY_OPTIMIZED | 0 | The system obtains the application usage duration statistics in the specified time frame at the interval the system deems appropriate.| 506| BY_DAILY | 1 | The system obtains the application usage duration statistics in the specified time frame on a daily basis. | 507| BY_WEEKLY | 2 | The system obtains the application usage duration statistics in the specified time frame on a weekly basis. | 508| BY_MONTHLY | 3 | The system obtains the application usage duration statistics in the specified time frame on a monthly basis. | 509| BY_ANNUALLY | 4 | The system obtains the application usage duration statistics in the specified time frame on an annual basis. | 510