1# @ohos.resourceschedule.usageStatistics (Device Usage Statistics) 2 3The **usageStatistics** module provides APIs for collecting statistics on device usage. For example, you can use the APIs to query whether an application is commonly used and an application's priority group, usage duration, system events (hibernation, wakeup, unlocking, and screen locking), application events (foreground, background, and start and end of continuous tasks), and the number of notifications. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9 10## Modules to Import 11 12``` 13import usageStatistics from '@ohos.resourceschedule.usageStatistics' 14``` 15 16## usageStatistics.isIdleState 17 18isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void 19 20Checks whether an application is commonly used (with the value of **GroupType** being less than or equal to 30). This API uses an asynchronous callback to return the result. 21 22**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 23 24**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 25 26**System API**: This is a system API. 27 28**Parameters** 29 30| Name | Type | Mandatory | Description | 31| ---------- | ---------------------------- | ---- | ---------------------------------------- | 32| bundleName | string | Yes | Bundle name of the application. | 33| callback | AsyncCallback<boolean> | Yes | Callback used to return the result.<br>If the application is commonly used, **true** is returned. If the application is not commonly used or **bundleName** is invalid, **false** is returned.| 34 35**Error codes** 36 37For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 38 39| ID | Error Message | 40| ---------- | ---------------------------- | 41| 10000001 | Memory operation failed. | 42| 10000002 | Parcel operation failed. | 43| 10000003 | System service operation failed. | 44| 10000004 | IPC failed. | 45| 10000006 | Failed to get the application information. | 46 47**Example** 48```ts 49import { BusinessError } from '@ohos.base'; 50 51usageStatistics.isIdleState("com.ohos.camera", (err: BusinessError, res: boolean) => { 52 if (err) { 53 console.log('BUNDLE_ACTIVE isIdleState callback failed. code is: ' + err.code + ',message is: ' + err.message); 54 } else { 55 console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); 56 } 57}); 58``` 59 60## usageStatistics.isIdleState 61 62isIdleState(bundleName: string): Promise<boolean> 63 64Checks whether an application is commonly used (with the value of **GroupType** being less than or equal to 30). This API uses a promise to return the result. 65 66**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 67 68**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 69 70**System API**: This is a system API. 71 72**Parameters** 73 74| Name | Type | Mandatory | Description | 75| ---------- | ------ | ---- | -------------- | 76| bundleName | string | Yes | Bundle name of the application.| 77 78**Return value** 79 80| Type | Description | 81| ---------------------- | ---------------------------------------- | 82| Promise<boolean> | Promise used to return the result.<br>If the application is commonly used, **true** is returned. If the application is not commonly used or **bundleName** is invalid, **false** is returned.| 83 84**Error codes** 85 86For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 87 88| ID | Error Message | 89| ---------- | ---------------------------- | 90| 10000001 | Memory operation failed. | 91| 10000002 | Parcel operation failed. | 92| 10000003 | System service operation failed. | 93| 10000004 | IPC failed. | 94| 10000006 | Failed to get the application information. | 95 96**Example** 97 98```ts 99import { BusinessError } from '@ohos.base'; 100 101usageStatistics.isIdleState("com.ohos.camera").then((res: boolean) => { 102 console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); 103}).catch((err: BusinessError) => { 104 console.log('BUNDLE_ACTIVE isIdleState promise failed. code is: ' + err.code + ',message is: ' + err.message); 105}); 106``` 107## usageStatistics.isIdleStateSync<sup>10+<sup> 108 109isIdleStateSync(bundleName: string): boolean 110 111Checks whether an application is commonly used (with the value of **GroupType** being less than or equal to 30). This API returns the result synchronously. 112 113**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 114 115**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 116 117**System API**: This is a system API. 118 119**Parameters** 120 121| Name | Type | Mandatory | Description | 122| ---------- | ---------------------------- | ---- | ---------------------------------------- | 123| bundleName | string | Yes | Bundle name of the application. | 124 125**Return value** 126 127| Type | Description | 128| ---------------------- | ---------------------------------------- | 129| boolean | If the application is commonly used, **true** is returned. If the application is not commonly used or **bundleName** is invalid, **false** is returned.| 130 131**Error codes** 132 133For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 134 135| ID | Error Message | 136| ---------- | ---------------------------- | 137| 10000001 | Memory operation failed. | 138| 10000002 | Parcel operation failed. | 139| 10000003 | System service operation failed. | 140| 10000004 | IPC failed. | 141| 10000006 | Failed to get the application information. | 142 143**Example** 144```ts 145let isIdleState: boolean = usageStatistics.isIdleStateSync("com.ohos.camera"); 146``` 147 148## usageStatistics.queryAppGroup 149 150queryAppGroup(): Promise<number> 151 152Queries the priority group of this application. This API uses a promise to return the result. 153 154**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 155 156**System API**: This is a system API. 157 158**Return value** 159 160| Type | Description | 161| --------------- | --------------------------- | 162| Promise<number> | Promise used to return the priority group. A smaller value indicates a higher priority.| 163 164**Error codes** 165 166For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 167 168| ID | Error Message | 169| ---------- | ---------------------------- | 170| 10000001 | Memory operation failed. | 171| 10000002 | Parcel operation failed. | 172| 10000003 | System service operation failed. | 173| 10000004 | IPC failed. | 174| 10000005 | Application is not installed. | 175| 10000006 | Failed to get the application information. | 176| 10100002 | Failed to get the application group information. | 177 178**Example** 179 180```ts 181import { BusinessError } from '@ohos.base'; 182 183usageStatistics.queryAppGroup().then((res: number) => { 184 console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res)); 185}).catch((err: BusinessError) => { 186 console.log('BUNDLE_ACTIVE queryAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message); 187}); 188``` 189 190## usageStatistics.queryAppGroup 191 192queryAppGroup(callback: AsyncCallback<number>): void 193 194Queries the priority group of this application. This API uses an asynchronous callback to return the result. 195 196**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 197 198**System API**: This is a system API. 199 200**Parameters** 201 202| Name | Type | Mandatory | Description | 203| -------- | --------------------- | ---- | -------------------------- | 204| callback | AsyncCallback<number> | Yes | Callback used to return the priority group. A smaller value indicates a higher priority.| 205 206**Error codes** 207 208For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 209 210| ID | Error Message | 211| ---------- | ---------------------------- | 212| 10000001 | Memory operation failed. | 213| 10000002 | Parcel operation failed. | 214| 10000003 | System service operation failed. | 215| 10000004 | IPC failed. | 216| 10000005 | Application is not installed. | 217| 10000006 | Failed to get the application information. | 218| 10100002 | Failed to get the application group information. | 219 220**Example** 221 222```ts 223import { BusinessError } from '@ohos.base'; 224 225usageStatistics.queryAppGroup((err: BusinessError, res: number) => { 226 if(err) { 227 console.log('BUNDLE_ACTIVE queryAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message); 228 } else { 229 console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res)); 230 } 231}); 232``` 233 234## usageStatistics.queryAppGroupSync<sup>10+<sup> 235 236queryAppGroupSync(): number 237 238Queries the priority group of this application. This API returns the result synchronously. 239 240**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 241 242**System API**: This is a system API. 243 244**Return value** 245 246| Type | Description | 247| --------------- | --------------------------- | 248| number | Priority group. A smaller value indicates a higher priority.| 249 250**Error codes** 251 252For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 253 254| ID | Error Message | 255| ---------- | ---------------------------- | 256| 10000001 | Memory operation failed. | 257| 10000002 | Parcel operation failed. | 258| 10000003 | System service operation failed. | 259| 10000004 | IPC failed. | 260| 10000005 | Application is not installed. | 261| 10000006 | Failed to get the application information. | 262| 10100002 | Failed to get the application group information. | 263 264**Example** 265 266```ts 267let priorityGroup: number = usageStatistics.queryAppGroupSync(); 268``` 269 270## usageStatistics.queryAppGroup 271 272queryAppGroup(bundleName : string): Promise<number> 273 274Queries the priority group of the application specified by **bundleName**. This API uses a promise to return the result. 275 276**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 277 278**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 279 280**System API**: This is a system API. 281 282**Parameters** 283 284| Name | Type | Mandatory | Description | 285| ---------- | ------ | ---- | ---------------------------------------- | 286| bundleName | string | Yes | Bundle name of the application.| 287 288**Return value** 289 290| Type | Description | 291| --------------- | --------------------------- | 292| Promise<number> | Promise used to return the priority group. A smaller value indicates a higher priority.| 293 294**Error codes** 295 296For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 297 298| ID | Error Message | 299| ---------- | ---------------------------- | 300| 10000001 | Memory operation failed. | 301| 10000002 | Parcel operation failed. | 302| 10000003 | System service operation failed. | 303| 10000004 | IPC failed. | 304| 10000005 | Application is not installed. | 305| 10000006 | Failed to get the application information. | 306| 10100002 | Failed to get the application group information. | 307 308**Example** 309 310```javascript 311// Promise mode when bundleName is specified 312import { BusinessError } from '@ohos.base'; 313 314let bundleName: string = "com.ohos.camera"; 315usageStatistics.queryAppGroup(bundleName).then((res: number) => { 316 console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res)); 317}).catch((err: BusinessError) => { 318 console.log('BUNDLE_ACTIVE queryAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message); 319}); 320``` 321 322## usageStatistics.queryAppGroup 323 324queryAppGroup(bundleName : string, callback: AsyncCallback<number>): void 325 326Queries the priority group of the application specified by **bundleName**. This API uses an asynchronous callback to return the result. 327 328**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 329 330**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 331 332**System API**: This is a system API. 333 334**Parameters** 335 336| Name | Type | Mandatory | Description | 337| ---------- | --------------------- | ---- | ---------------------------------------- | 338| bundleName | string | Yes | Bundle name of the application.| 339| callback | AsyncCallback<number> | Yes | Callback used to return the priority group. A smaller value indicates a higher priority.| 340 341**Error codes** 342 343For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 344 345| ID | Error Message | 346| ---------- | ---------------------------- | 347| 10000001 | Memory operation failed. | 348| 10000002 | Parcel operation failed. | 349| 10000003 | System service operation failed. | 350| 10000004 | IPC failed. | 351| 10000005 | Application is not installed. | 352| 10000006 | Failed to get the application information. | 353| 10100002 | Failed to get the application group information. | 354 355**Example** 356 357```ts 358import { BusinessError } from '@ohos.base'; 359 360let bundleName: string = "com.ohos.camera"; 361usageStatistics.queryAppGroup(bundleName, (err: BusinessError, res: number) => { 362 if(err) { 363 console.log('BUNDLE_ACTIVE queryAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message); 364 } else { 365 console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res)); 366 } 367}); 368``` 369 370## usageStatistics.queryAppGroupSync<sup>10+<sup> 371 372queryAppGroupSync(bundleName: string): number 373 374Queries the priority group of the application specified by **bundleName**. This API returns the result synchronously. 375 376**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 377 378**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 379 380**System API**: This is a system API. 381 382**Parameters** 383 384| Name | Type | Mandatory | Description | 385| ---------- | ---------------------------- | ---- | ---------------------------------------- | 386| bundleName | string | Yes | Bundle name of the application. | 387 388**Return value** 389 390| Type | Description | 391| --------------- | --------------------------- | 392| number | Priority group. A smaller value indicates a higher priority.| 393 394**Error codes** 395 396For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 397 398| ID | Error Message | 399| ---------- | ---------------------------- | 400| 10000001 | Memory operation failed. | 401| 10000002 | Parcel operation failed. | 402| 10000003 | System service operation failed. | 403| 10000004 | IPC failed. | 404| 10000005 | Application is not installed. | 405| 10000006 | Failed to get the application information. | 406| 10100002 | Failed to get the application group information. | 407 408**Example** 409 410```ts 411let priorityGroup: number = usageStatistics.queryAppGroupSync("com.ohos.camera"); 412``` 413 414## usageStatistics.setAppGroup 415 416setAppGroup(bundleName: string, newGroup: GroupType): Promise<void> 417 418Sets a new group for the application specified by **bundleName**. This API uses a promise to return the result. It can be called only by the current application. 419 420**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 421 422**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 423 424**System API**: This is a system API. 425 426**Parameters** 427 428| Name | Type | Mandatory | Description | 429| ---------- | --------- | ---- | ---- | 430| bundleName | string | Yes | Bundle name of the application.| 431| newGroup | [GroupType](#grouptype) | Yes | Type of the new group. | 432 433**Return value** 434 435| Type | Description | 436| ------------- | ------------------------- | 437| Promise<void> | Promise that returns no value.| 438 439**Error codes** 440 441For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 442 443| ID | Error Message | 444| ---------- | ---------------------------- | 445| 10000001 | Memory operation failed. | 446| 10000002 | Parcel operation failed. | 447| 10000003 | System service operation failed. | 448| 10000004 | IPC failed. | 449| 10000006 | Failed to get the application information. | 450| 10100001 | Repeated operation on the application group. | 451 452**Example** 453 454```ts 455import { BusinessError } from '@ohos.base'; 456 457let bundleName: string = "com.example.deviceUsageStatistics"; 458let newGroup = usageStatistics.GroupType.DAILY_GROUP; 459 460usageStatistics.setAppGroup(bundleName, newGroup).then( () => { 461 console.log('BUNDLE_ACTIVE setAppGroup promise succeeded.'); 462}).catch((err: BusinessError) => { 463 console.log('BUNDLE_ACTIVE setAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message); 464}); 465``` 466 467## usageStatistics.setAppGroup 468 469setAppGroup(bundleName: string, newGroup: GroupType, callback: AsyncCallback<void>): void 470 471Sets a new group for the application specified by **bundleName**. This API uses an asynchronous callback to return the result. It can be called only by the current application. 472 473**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 474 475**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 476 477**System API**: This is a system API. 478 479**Parameters** 480 481| Name | Type | Mandatory | Description | 482| ---------- | ------------------- | ---- | ------------------------- | 483| bundleName | string | Yes | Bundle name of the application. | 484| newGroup | [GroupType](#grouptype) | Yes | Type of the new group. | 485| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 486 487**Error codes** 488 489For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 490 491| ID | Error Message | 492| ---------- | ---------------------------- | 493| 10000001 | Memory operation failed. | 494| 10000002 | Parcel operation failed. | 495| 10000003 | System service operation failed. | 496| 10000004 | IPC failed. | 497| 10000006 | Failed to get the application information. | 498| 10100001 | Repeated operation on the application group. | 499 500**Example** 501 502```ts 503import { BusinessError } from '@ohos.base'; 504 505let bundleName: string = "com.example.deviceUsageStatistics"; 506let newGroup = usageStatistics.GroupType.DAILY_GROUP; 507 508usageStatistics.setAppGroup(bundleName, newGroup, (err: BusinessError) => { 509 if(err) { 510 console.log('BUNDLE_ACTIVE setAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message); 511 } else { 512 console.log('BUNDLE_ACTIVE setAppGroup callback succeeded.'); 513 } 514}); 515``` 516 517## usageStatistics.queryBundleStatsInfos 518 519queryBundleStatsInfos(begin: number, end: number, callback: AsyncCallback<BundleStatsMap>): void 520 521Queries the application usage duration statistics based on the specified start time and end time, with the minimum granularity of a day. This API uses an asynchronous callback to return the result. 522 523**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 524 525**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 526 527**System API**: This is a system API. 528 529**Parameters** 530 531| Name | Type | Mandatory | Description | 532| -------- | ---------------------------------------- | ---- | --------------------------------------- | 533| begin | number | Yes | Start time, in milliseconds. | 534| end | number | Yes | End time, in milliseconds. | 535| callback | AsyncCallback<[BundleStatsMap](#bundlestatsmap)> | Yes | Callback used to return the application usage duration statistics.| 536 537**Error codes** 538 539For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 540 541| ID | Error Message | 542| ---------- | ---------------------------- | 543| 10000001 | Memory operation failed. | 544| 10000002 | Parcel operation failed. | 545| 10000003 | System service operation failed. | 546| 10000004 | IPC failed. | 547| 10000006 | Failed to get the application information. | 548| 10000007 | Failed to get the system time. | 549 550**Example** 551 552```ts 553import { BusinessError } from '@ohos.base'; 554 555usageStatistics.queryBundleStatsInfos(0, 20000000000000, (err: BusinessError, res:usageStatistics.BundleStatsMap) => { 556 if (err) { 557 console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback failed. code is: ' + err.code + ',message is: ' + err.message); 558 } else { 559 console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback success.'); 560 console.log('BUNDLE_ACTIVE queryBundleStatsInfos callback result ' + JSON.stringify(res)); 561 } 562}); 563``` 564 565## usageStatistics.queryBundleStatsInfos 566 567queryBundleStatsInfos(begin: number, end: number): Promise<BundleStatsMap> 568 569Queries the application usage duration statistics based on the specified start time and end time, with the minimum granularity of a day. This API uses a promise to return the result. 570 571**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 572 573**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 574 575**System API**: This is a system API. 576 577**Parameters** 578 579| Name | Type | Mandatory | Description | 580| ----- | ------ | ---- | ----- | 581| begin | number | Yes | Start time, in milliseconds.| 582| end | number | Yes | End time, in milliseconds.| 583 584**Return value** 585 586| Type | Description | 587| ---------------------------------------- | -------------------------------------- | 588| Promise<[BundleStatsMap](#bundlestatsmap)> | Promise used to return the application usage duration statistics.| 589 590**Error codes** 591 592For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 593 594| ID | Error Message | 595| ---------- | ---------------------------- | 596| 10000001 | Memory operation failed. | 597| 10000002 | Parcel operation failed. | 598| 10000003 | System service operation failed. | 599| 10000004 | IPC failed. | 600| 10000006 | Failed to get the application information. | 601| 10000007 | Failed to get the system time. | 602 603**Example** 604 605```ts 606import { BusinessError } from '@ohos.base'; 607 608usageStatistics.queryBundleStatsInfos(0, 20000000000000).then((res:usageStatistics.BundleStatsMap) => { 609 console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise success.'); 610 console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise result ' + JSON.stringify(res)); 611}).catch((err: BusinessError) => { 612 console.log('BUNDLE_ACTIVE queryBundleStatsInfos promise failed. code is: ' + err.code + ',message is: ' + err.message); 613}); 614``` 615 616## usageStatistics.queryBundleStatsInfoByInterval 617 618queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number, callback: AsyncCallback<Array<BundleStatsInfo>>): void 619 620Queries 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. 621 622**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 623 624**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 625 626**System API**: This is a system API. 627 628**Parameters** 629 630| Name | Type | Mandatory | Description | 631| ---------- | ---------------------------------------- | ---- | ---------------------------------------- | 632| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried. | 633| begin | number | Yes | Start time, in milliseconds. | 634| end | number | Yes | End time, in milliseconds. | 635| callback | AsyncCallback<Array<[BundleStatsInfo](#bundlestatsinfo)>> | Yes | Callback used to return the application usage duration statistics.| 636 637**Error codes** 638 639For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 640 641| ID | Error Message | 642| ---------- | ---------------------------- | 643| 10000001 | Memory operation failed. | 644| 10000002 | Parcel operation failed. | 645| 10000003 | System service operation failed. | 646| 10000004 | IPC failed. | 647| 10000006 | Failed to get the application information. | 648| 10000007 | Failed to get the system time. | 649 650**Example** 651 652```ts 653import { BusinessError } from '@ohos.base'; 654 655usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000, (err: BusinessError, res: Array<usageStatistics.BundleStatsInfo>) => { 656 if (err) { 657 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback failed. code is: ' + err.code + ',message is: ' + err.message); 658 } else { 659 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback success.'); 660 for (let i = 0; i < res.length; i++) { 661 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback number : ' + (i + 1)); 662 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval callback result ' + JSON.stringify(res[i])); 663 } 664 } 665}); 666``` 667 668## usageStatistics.queryBundleStatsInfoByInterval 669 670queryBundleStatsInfoByInterval(byInterval: IntervalType, begin: number, end: number): Promise<Array<BundleStatsInfo>> 671 672Queries 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. 673 674**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 675 676**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 677 678**System API**: This is a system API. 679 680**Parameters** 681 682| Name | Type | Mandatory | Description | 683| ---------- | ----------------------------- | ---- | ----- | 684| byInterval | [IntervalType](#intervaltype) | Yes | Type of information to be queried.| 685| begin | number | Yes | Start time, in milliseconds.| 686| end | number | Yes | End time, in milliseconds.| 687 688**Return value** 689 690| Type | Description | 691| ---------------------------------------- | ---------------------------------------- | 692| Promise<Array<[BundleStatsInfo](#bundlestatsinfo)>> | Promise used to return the application usage duration statistics.| 693 694**Error codes** 695 696For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 697 698| ID | Error Message | 699| ---------- | ---------------------------- | 700| 10000001 | Memory operation failed. | 701| 10000002 | Parcel operation failed. | 702| 10000003 | System service operation failed. | 703| 10000004 | IPC failed. | 704| 10000006 | Failed to get the application information. | 705| 10000007 | Failed to get the system time. | 706 707**Example** 708 709```ts 710import { BusinessError } from '@ohos.base'; 711 712usageStatistics.queryBundleStatsInfoByInterval(0, 0, 20000000000000).then((res: Array<usageStatistics.BundleStatsInfo>) => { 713 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise success.'); 714 for (let i = 0; i < res.length; i++) { 715 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise number : ' + (i + 1)); 716 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise result ' + JSON.stringify(res[i])); 717 } 718}).catch((err: BusinessError) => { 719 console.log('BUNDLE_ACTIVE queryBundleStatsInfoByInterval promise failed. code is: ' + err.code + ',message is: ' + err.message); 720}); 721``` 722 723## usageStatistics.queryBundleEvents 724 725queryBundleEvents(begin: number, end: number, callback: AsyncCallback<Array<BundleEvents>>): void 726 727Queries events of all applications based on the specified start time and end time. This API uses an asynchronous callback to return the result. 728 729**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 730 731**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 732 733**System API**: This is a system API. 734 735**Parameters** 736 737| Name | Type | Mandatory | Description | 738| -------- | ---------------------------------------- | ---- | --------------------------------------- | 739| begin | number | Yes | Start time, in milliseconds. | 740| end | number | Yes | End time, in milliseconds. | 741| callback | AsyncCallback<Array<[BundleEvents](#bundleevents)>> | Yes | Callback used to return the events.| 742 743**Error codes** 744 745For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 746 747| ID | Error Message | 748| ---------- | ---------------------------- | 749| 10000001 | Memory operation failed. | 750| 10000002 | Parcel operation failed. | 751| 10000003 | System service operation failed. | 752| 10000004 | IPC failed. | 753| 10000006 | Failed to get the application information. | 754| 10000007 | Failed to get the system time. | 755 756**Example** 757 758```ts 759import { BusinessError } from '@ohos.base'; 760 761usageStatistics.queryBundleEvents(0, 20000000000000, (err: BusinessError, res: Array<usageStatistics.BundleEvents>) => { 762 if (err) { 763 console.log('BUNDLE_ACTIVE queryBundleEvents callback failed. code is: ' + err.code + ',message is: ' + err.message); 764 } else { 765 console.log('BUNDLE_ACTIVE queryBundleEvents callback success.'); 766 for (let i = 0; i < res.length; i++) { 767 console.log('BUNDLE_ACTIVE queryBundleEvents callback number : ' + (i + 1)); 768 console.log('BUNDLE_ACTIVE queryBundleEvents callback result ' + JSON.stringify(res[i])); 769 } 770 } 771}); 772``` 773 774## usageStatistics.queryBundleEvents 775 776queryBundleEvents(begin: number, end: number): Promise<Array<BundleEvents>> 777 778Queries events of all applications based on the specified start time and end time. This API uses a promise to return the result. 779 780**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 781 782**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 783 784**System API**: This is a system API. 785 786**Parameters** 787 788| Name | Type | Mandatory | Description | 789| ----- | ------ | ---- | ----- | 790| begin | number | Yes | Start time, in milliseconds.| 791| end | number | Yes | End time, in milliseconds.| 792 793**Return value** 794 795| Type | Description | 796| ---------------------------------------- | -------------------------------------- | 797| Promise<Array<[BundleEvents](#bundleevents)>> | Promise used to return the events.| 798 799**Error codes** 800 801For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 802 803| ID | Error Message | 804| ---------- | ---------------------------- | 805| 10000001 | Memory operation failed. | 806| 10000002 | Parcel operation failed. | 807| 10000003 | System service operation failed. | 808| 10000004 | IPC failed. | 809| 10000006 | Failed to get the application information. | 810| 10000007 | Failed to get the system time. | 811 812**Example** 813 814```ts 815import { BusinessError } from '@ohos.base'; 816 817usageStatistics.queryBundleEvents(0, 20000000000000).then((res: Array<usageStatistics.BundleEvents>) => { 818 console.log('BUNDLE_ACTIVE queryBundleEvents promise success.'); 819 for (let i = 0; i < res.length; i++) { 820 console.log('BUNDLE_ACTIVE queryBundleEvents promise number : ' + (i + 1)); 821 console.log('BUNDLE_ACTIVE queryBundleEvents promise result ' + JSON.stringify(res[i])); 822 } 823}).catch((err: BusinessError) => { 824 console.log('BUNDLE_ACTIVE queryBundleEvents promise failed. code is: ' + err.code + ',message is: ' + err.message); 825}); 826``` 827 828## usageStatistics.queryCurrentBundleEvents 829 830queryCurrentBundleEvents(begin: number, end: number, callback: AsyncCallback<Array<BundleEvents>>): void 831 832Queries events of this application based on the specified start time and end time. This API uses an asynchronous callback to return the result. 833 834**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 835 836**System API**: This is a system API. 837 838**Parameters** 839 840| Name | Type | Mandatory | Description | 841| -------- | ---------------------------------------- | ---- | --------------------------------------- | 842| begin | number | Yes | Start time, in milliseconds. | 843| end | number | Yes | End time, in milliseconds. | 844| callback | AsyncCallback<Array<[BundleEvents](#bundleevents)>> | Yes | Callback used to return the events.| 845 846**Error codes** 847 848For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 849 850| ID | Error Message | 851| ---------- | ---------------------------- | 852| 10000001 | Memory operation failed. | 853| 10000002 | Parcel operation failed. | 854| 10000003 | System service operation failed. | 855| 10000004 | IPC failed. | 856| 10000006 | Failed to get the application information. | 857| 10000007 | Failed to get the system time. | 858 859**Example** 860 861```ts 862import { BusinessError } from '@ohos.base'; 863 864usageStatistics.queryCurrentBundleEvents(0, 20000000000000, (err: BusinessError, res: Array<usageStatistics.BundleEvents>) => { 865 if (err) { 866 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback failed. code is: ' + err.code + ',message is: ' + err.message); 867 } else { 868 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback success.'); 869 for (let i = 0; i < res.length; i++) { 870 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback number : ' + (i + 1)); 871 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback result ' + JSON.stringify(res[i])); 872 } 873 } 874}); 875``` 876 877## usageStatistics.queryCurrentBundleEvents 878 879queryCurrentBundleEvents(begin: number, end: number): Promise<Array<BundleEvents>> 880 881Queries events of this application based on the specified start time and end time. This API uses a promise to return the result. 882 883**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 884 885**System API**: This is a system API. 886 887**Parameters** 888 889| Name | Type | Mandatory | Description | 890| ----- | ------ | ---- | ----- | 891| begin | number | Yes | Start time, in milliseconds.| 892| end | number | Yes | End time, in milliseconds.| 893 894**Return value** 895 896| Type | Description | 897| ---------------------------------------- | -------------------------------------- | 898| Promise<Array<[BundleEvents](#bundleevents)>> | Promise used to return the events.| 899 900**Error codes** 901 902For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 903 904| ID | Error Message | 905| ---------- | ---------------------------- | 906| 10000001 | Memory operation failed. | 907| 10000002 | Parcel operation failed. | 908| 10000003 | System service operation failed. | 909| 10000004 | IPC failed. | 910| 10000006 | Failed to get the application information. | 911| 10000007 | Failed to get the system time. | 912 913**Example** 914 915```ts 916import { BusinessError } from '@ohos.base'; 917 918usageStatistics.queryCurrentBundleEvents(0, 20000000000000).then((res: Array<usageStatistics.BundleEvents>) => { 919 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise success.'); 920 for (let i = 0; i < res.length; i++) { 921 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise number : ' + (i + 1)); 922 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise result ' + JSON.stringify(res[i])); 923 } 924}).catch((err: BusinessError) => { 925 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise failed. code is: ' + err.code + ',message is: ' + err.message); 926}); 927``` 928 929## usageStatistics.queryDeviceEventStats 930 931queryDeviceEventStats(begin: number, end: number): Promise<Array<DeviceEventStats>> 932 933Queries statistics about system events (hibernation, wakeup, unlocking, and locking) that occur between the specified start time and end time. This API uses a promise to return the result. 934 935**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 936 937**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 938 939**System API**: This is a system API. 940 941**Parameters** 942 943| Name | Type | Mandatory | Description | 944| ----- | ------ | ---- | ----- | 945| begin | number | Yes | Start time, in milliseconds.| 946| end | number | Yes | End time, in milliseconds.| 947 948**Return value** 949 950| Type | Description | 951| ---------------------------------------- | ---------------------------------------- | 952| Promise<Array<[DeviceEventStats](#deviceeventstats)>> | Promise used to return the statistics about system events.| 953 954**Error codes** 955 956For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 957 958| ID | Error Message | 959| ---------- | ---------------------------- | 960| 10000001 | Memory operation failed. | 961| 10000002 | Parcel operation failed. | 962| 10000003 | System service operation failed. | 963| 10000004 | IPC failed. | 964| 10000006 | Failed to get the application information. | 965| 10000007 | Failed to get the system time. | 966 967**Example** 968 969```ts 970import { BusinessError } from '@ohos.base'; 971 972usageStatistics.queryDeviceEventStats(0, 20000000000000).then((res: Array<usageStatistics.DeviceEventStats>) => { 973 console.log('BUNDLE_ACTIVE queryDeviceEventStates promise success.'); 974 console.log('BUNDLE_ACTIVE queryDeviceEventStates promise result ' + JSON.stringify(res)); 975}).catch((err: BusinessError) => { 976 console.log('BUNDLE_ACTIVE queryDeviceEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message); 977}); 978``` 979 980## usageStatistics.queryDeviceEventStats 981 982queryDeviceEventStats(begin: number, end: number, callback: AsyncCallback<Array<DeviceEventStats>>): void 983 984Queries statistics about system events (hibernation, wakeup, unlocking, and locking) that occur between the specified start time and end time. This API uses an asynchronous callback to return the result. 985 986**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 987 988**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 989 990**System API**: This is a system API. 991 992**Parameters** 993 994| Name | Type | Mandatory | Description | 995| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 996| begin | number | Yes | Start time, in milliseconds. | 997| end | number | Yes | End time, in milliseconds. | 998| callback | AsyncCallback<Array<[DeviceEventStats](#deviceeventstats)>> | Yes | Callback used to return the statistics about system events.| 999 1000**Error codes** 1001 1002For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1003 1004| ID | Error Message | 1005| ---------- | ---------------------------- | 1006| 10000001 | Memory operation failed. | 1007| 10000002 | Parcel operation failed. | 1008| 10000003 | System service operation failed. | 1009| 10000004 | IPC failed. | 1010| 10000006 | Failed to get the application information. | 1011| 10000007 | Failed to get the system time. | 1012 1013**Example** 1014 1015```ts 1016import { BusinessError } from '@ohos.base'; 1017 1018usageStatistics.queryDeviceEventStats(0, 20000000000000, (err: BusinessError, res: Array<usageStatistics.DeviceEventStats>) => { 1019 if(err) { 1020 console.log('BUNDLE_ACTIVE queryDeviceEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message); 1021 } else { 1022 console.log('BUNDLE_ACTIVE queryDeviceEventStats callback success.'); 1023 console.log('BUNDLE_ACTIVE queryDeviceEventStats callback result ' + JSON.stringify(res)); 1024 } 1025}); 1026``` 1027 1028## usageStatistics.queryNotificationEventStats 1029 1030queryNotificationEventStats(begin: number, end: number): Promise<Array<DeviceEventStats>> 1031 1032Queries the number of notifications from all applications based on the specified start time and end time. This API uses a promise to return the result. 1033 1034**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1035 1036**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1037 1038**System API**: This is a system API. 1039 1040**Parameters** 1041 1042| Name | Type | Mandatory | Description | 1043| ----- | ------ | ---- | ----- | 1044| begin | number | Yes | Start time, in milliseconds.| 1045| end | number | Yes | End time, in milliseconds.| 1046 1047**Return value** 1048 1049| Type | Description | 1050| ---------------------------------------- | ---------------------------------------- | 1051| Promise<Array<[DeviceEventStats](#deviceeventstats)>> | Promise used to return the number of notifications.| 1052 1053**Error codes** 1054 1055For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1056 1057| ID | Error Message | 1058| ---------- | ---------------------------- | 1059| 10000001 | Memory operation failed. | 1060| 10000002 | Parcel operation failed. | 1061| 10000003 | System service operation failed. | 1062| 10000004 | IPC failed. | 1063| 10000006 | Failed to get the application information. | 1064| 10000007 | Failed to get the system time. | 1065 1066**Example** 1067 1068```ts 1069import { BusinessError } from '@ohos.base'; 1070 1071usageStatistics.queryNotificationEventStats(0, 20000000000000).then((res: Array<usageStatistics.DeviceEventStats>) => { 1072 console.log('BUNDLE_ACTIVE queryNotificationEventStats promise success.'); 1073 console.log('BUNDLE_ACTIVE queryNotificationEventStats promise result ' + JSON.stringify(res)); 1074}).catch((err: BusinessError) => { 1075 console.log('BUNDLE_ACTIVE queryNotificationEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message); 1076}); 1077``` 1078 1079## usageStatistics.queryNotificationEventStats 1080 1081queryNotificationEventStats(begin: number, end: number, callback: AsyncCallback<Array<DeviceEventStats>>): void 1082 1083Queries the number of notifications from all applications based on the specified start time and end time. This API uses an asynchronous callback to return the result. 1084 1085**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1086 1087**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1088 1089**System API**: This is a system API. 1090 1091**Parameters** 1092 1093| Name | Type | Mandatory | Description | 1094| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1095| begin | number | Yes | Start time, in milliseconds. | 1096| end | number | Yes | End time, in milliseconds. | 1097| callback | AsyncCallback<Array<[DeviceEventStats](#deviceeventstats)>> | Yes | Callback used to return the number of notifications.| 1098 1099**Error codes** 1100 1101For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1102 1103| ID | Error Message | 1104| ---------- | ---------------------------- | 1105| 10000001 | Memory operation failed. | 1106| 10000002 | Parcel operation failed. | 1107| 10000003 | System service operation failed. | 1108| 10000004 | IPC failed. | 1109| 10000006 | Failed to get the application information. | 1110| 10000007 | Failed to get the system time. | 1111 1112**Example** 1113 1114```ts 1115import { BusinessError } from '@ohos.base'; 1116 1117usageStatistics.queryNotificationEventStats(0, 20000000000000, (err: BusinessError, res: Array<usageStatistics.DeviceEventStats>) => { 1118 if(err) { 1119 console.log('BUNDLE_ACTIVE queryNotificationEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message); 1120 } else { 1121 console.log('BUNDLE_ACTIVE queryNotificationEventStats callback success.'); 1122 console.log('BUNDLE_ACTIVE queryNotificationEventStats callback result ' + JSON.stringify(res)); 1123 } 1124}); 1125``` 1126 1127## usageStatistics.queryModuleUsageRecords 1128 1129queryModuleUsageRecords(): Promise<Array<HapModuleInfo>> 1130 1131Queries the usage records of unused HAP files for each application in the FA model. If the HAP file contains FA widgets, the usage records also contain the widget information. This API uses a promise to return the result. 1132 1133Queries FA usage records. This API uses a promise to return a maximum of 1000 FA usage records sorted by time (most recent first). 1134 1135**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1136 1137**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1138 1139**System API**: This is a system API. 1140 1141**Return value** 1142 1143| Type | Description | 1144| ---------------------------------------- | ---------------------------------- | 1145| Promise<Array<[HapModuleInfo](#hapmoduleinfo)>> | Promise used to return the result. A maximum of 1000 usage records can be returned.| 1146 1147**Error codes** 1148 1149For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1150 1151| ID | Error Message | 1152| ---------- | ---------------------------- | 1153| 10000001 | Memory operation failed. | 1154| 10000002 | Parcel operation failed. | 1155| 10000003 | System service operation failed. | 1156| 10000004 | IPC failed. | 1157| 10000006 | Failed to get the application information. | 1158| 10000007 | Failed to get the system time. | 1159 1160**Example** 1161 1162```ts 1163// Invocation when maxNum is not passed 1164import { BusinessError } from '@ohos.base'; 1165 1166usageStatistics.queryModuleUsageRecords().then((res: Array<usageStatistics.HapModuleInfo>) => { 1167 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); 1168 for (let i = 0; i < res.length; i++) { 1169 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); 1170 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); 1171 } 1172}).catch((err: BusinessError) => { 1173 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message); 1174}); 1175``` 1176 1177## usageStatistics.queryModuleUsageRecords 1178 1179queryModuleUsageRecords(callback: AsyncCallback<Array<HapModuleInfo>>): void 1180 1181Queries the usage records of unused HAP files for each application in the FA model. If the HAP file contains FA widgets, the usage records also contain the widget information. This API uses an asynchronous callback to return the result. 1182 1183**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1184 1185**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1186 1187**System API**: This is a system API. 1188 1189**Parameters** 1190 1191| Name | Type | Mandatory | Description | 1192| -------- | ---------------------------------------- | ---- | ----------------------------------- | 1193| callback | AsyncCallback<Array<[HapModuleInfo](#hapmoduleinfo)>> | Yes | Callback used to return the result. A maximum of 1000 usage records can be returned.| 1194 1195**Error codes** 1196 1197For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1198 1199| ID | Error Message | 1200| ---------- | ---------------------------- | 1201| 10000001 | Memory operation failed. | 1202| 10000002 | Parcel operation failed. | 1203| 10000003 | System service operation failed. | 1204| 10000004 | IPC failed. | 1205| 10000006 | Failed to get the application information. | 1206| 10000007 | Failed to get the system time. | 1207 1208**Example** 1209 1210```ts 1211import { BusinessError } from '@ohos.base'; 1212 1213usageStatistics.queryModuleUsageRecords((err: BusinessError, res: Array<usageStatistics.HapModuleInfo>) => { 1214 if(err) { 1215 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message); 1216 } else { 1217 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); 1218 for (let i = 0; i < res.length; i++) { 1219 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); 1220 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); 1221 } 1222 } 1223}); 1224``` 1225 1226## usageStatistics.queryModuleUsageRecords 1227 1228queryModuleUsageRecords(maxNum: number): Promise<Array<HapModuleInfo>> 1229 1230Queries a given number of usage records of unused HAP files for each application in the FA model. If the HAP file contains FA widgets, the usage records also contain the widget information. This API uses a promise to return the result. 1231 1232**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1233 1234**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1235 1236**System API**: This is a system API. 1237 1238**Parameters** 1239 1240| Name | Type | Mandatory | Description | 1241| ------ | ------ | ---- | ---------------------------------- | 1242| maxNum | number | Yes | Number of usage records, in the range [1, 1000].| 1243 1244**Return value** 1245 1246| Type | Description | 1247| ---------------------------------------- | ---------------------------------- | 1248| Promise<Array<[HapModuleInfo](#hapmoduleinfo)>> | Promise used to return the result. The usage records returned does not exceed the value of **maxNum**.| 1249 1250**Error codes** 1251 1252For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1253 1254| ID | Error Message | 1255| ---------- | ---------------------------- | 1256| 10000001 | Memory operation failed. | 1257| 10000002 | Parcel operation failed. | 1258| 10000003 | System service operation failed. | 1259| 10000004 | IPC failed. | 1260| 10000006 | Failed to get the application information. | 1261| 10000007 | Failed to get the system time. | 1262 1263**Example** 1264 1265```ts 1266import { BusinessError } from '@ohos.base'; 1267 1268usageStatistics.queryModuleUsageRecords(1000).then((res: Array<usageStatistics.HapModuleInfo>) => { 1269 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); 1270 for (let i = 0; i < res.length; i++) { 1271 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); 1272 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); 1273 } 1274}).catch((err: BusinessError) => { 1275 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message); 1276}); 1277``` 1278 1279## usageStatistics.queryModuleUsageRecords 1280 1281queryModuleUsageRecords(maxNum: number, callback: AsyncCallback<Array<HapModuleInfo>>): void 1282 1283Queries a given number of usage records of unused HAP files for each application in the FA model. If the HAP file contains FA widgets, the usage records also contain the widget information. This API uses an asynchronous callback to return the result. 1284 1285**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1286 1287**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1288 1289**System API**: This is a system API. 1290 1291**Parameters** 1292 1293| Name | Type | Mandatory | Description | 1294| -------- | ---------------------------------------- | ---- | ----------------------------------- | 1295| maxNum | number | Yes | Number of usage records, in the range [1, 1000].| 1296| callback | AsyncCallback<Array<[HapModuleInfo](#hapmoduleinfo)>> | Yes | Callback used to return the result. The usage records returned does not exceed the value of **maxNum**.| 1297 1298**Error codes** 1299 1300For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1301 1302| ID | Error Message | 1303| ---------- | ---------------------------- | 1304| 10000001 | Memory operation failed. | 1305| 10000002 | Parcel operation failed. | 1306| 10000003 | System service operation failed. | 1307| 10000004 | IPC failed. | 1308| 10000006 | Failed to get the application information. | 1309| 10000007 | Failed to get the system time. | 1310 1311**Example** 1312 1313```ts 1314import { BusinessError } from '@ohos.base'; 1315 1316usageStatistics.queryModuleUsageRecords(1000, (err: BusinessError, res: Array<usageStatistics.HapModuleInfo>) => { 1317 if(err) { 1318 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message); 1319 } else { 1320 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); 1321 for (let i = 0; i < res.length; i++) { 1322 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); 1323 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); 1324 } 1325 } 1326}); 1327``` 1328 1329## usageStatistics.registerAppGroupCallBack 1330 1331registerAppGroupCallBack(groupCallback: Callback<AppGroupCallbackInfo>): Promise<void> 1332 1333Registers a callback for application group changes. When an application group of the user changes, an [AppGroupCallbackInfo](#appgroupcallbackinfo) instance is returned to all applications that have registered the callback. This API uses a promise to return the result. 1334 1335**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1336 1337**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1338 1339**System API**: This is a system API. 1340 1341**Parameters** 1342 1343| Name | Type | Mandatory| Description | 1344| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 1345| groupCallback | Callback<[AppGroupCallbackInfo](#appgroupcallbackinfo)> | Yes | Application group change information.| 1346 1347**Return value** 1348 1349| Type | Description | 1350| ------------- | ----------------------- | 1351| Promise<void> | Promise that returns no value.| 1352 1353**Error codes** 1354 1355For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1356 1357| ID | Error Message | 1358| ---------- | ---------------------------- | 1359| 10000001 | Memory operation failed. | 1360| 10000002 | Parcel operation failed. | 1361| 10000003 | System service operation failed. | 1362| 10000004 | IPC failed. | 1363| 10100001 | Repeated operation on the application group. | 1364 1365 1366**Example** 1367 1368```ts 1369import { BusinessError } from '@ohos.base'; 1370 1371function onBundleGroupChanged(res: usageStatistics.AppGroupCallbackInfo) { 1372 console.log('BUNDLE_ACTIVE registerAppGroupCallBack RegisterGroupCallBack callback success.'); 1373 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); 1374 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); 1375 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); 1376 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); 1377 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); 1378}; 1379usageStatistics.registerAppGroupCallBack(onBundleGroupChanged).then( () => { 1380 console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise succeeded.'); 1381}).catch((err: BusinessError) => { 1382 console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message); 1383}); 1384``` 1385 1386## usageStatistics.registerAppGroupCallBack 1387 1388registerAppGroupCallBack(groupCallback: Callback<AppGroupCallbackInfo>, callback: AsyncCallback<void>): void 1389 1390Registers a callback for application group changes. When an application group of the user changes, an [AppGroupCallbackInfo](#appgroupcallbackinfo) instance is returned to all applications that have registered the callback. This API uses an asynchronous callback to return the result. 1391 1392**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1393 1394**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1395 1396**System API**: This is a system API. 1397 1398**Parameters** 1399 1400| Name | Type | Mandatory| Description | 1401| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1402| groupCallback | Callback<[AppGroupCallbackInfo](#appgroupcallbackinfo)> | Yes | Application group change information. | 1403| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1404 1405**Error codes** 1406 1407For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1408 1409| ID | Error Message | 1410| ---------- | ---------------------------- | 1411| 10000001 | Memory operation failed. | 1412| 10000002 | Parcel operation failed. | 1413| 10000003 | System service operation failed. | 1414| 10000004 | IPC failed. | 1415| 10100001 | Repeated operation on the application group. | 1416 1417 1418**Example** 1419 1420```ts 1421import { BusinessError } from '@ohos.base'; 1422 1423function onBundleGroupChanged(res: usageStatistics.AppGroupCallbackInfo) { 1424 console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); 1425 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); 1426 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); 1427 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); 1428 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); 1429 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); 1430}; 1431usageStatistics.registerAppGroupCallBack(onBundleGroupChanged, (err: BusinessError) => { 1432 if(err) { 1433 console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message); 1434 } else { 1435 console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback success.'); 1436 } 1437}); 1438``` 1439 1440## usageStatistics.unregisterAppGroupCallBack 1441 1442unregisterAppGroupCallBack(): Promise<void> 1443 1444Unregisters the callback for application group changes. This API uses a promise to return the result. 1445 1446**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1447 1448**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1449 1450**System API**: This is a system API. 1451 1452**Return value** 1453 1454| Type | Description | 1455| ------------- | ------------------------ | 1456| Promise<void> | Promise that returns no value.| 1457 1458**Error codes** 1459 1460For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1461 1462| ID | Error Message | 1463| ---------- | ---------------------------- | 1464| 10000001 | Memory operation failed. | 1465| 10000002 | Parcel operation failed. | 1466| 10000003 | System service operation failed. | 1467| 10000004 | IPC failed. | 1468| 10100001 | Repeated operation on the application group. | 1469 1470**Example** 1471 1472```ts 1473import { BusinessError } from '@ohos.base'; 1474 1475usageStatistics.unregisterAppGroupCallBack().then( () => { 1476 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise succeeded.'); 1477}).catch((err: BusinessError) => { 1478 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message); 1479}); 1480``` 1481 1482## usageStatistics.unregisterAppGroupCallBack 1483 1484unregisterAppGroupCallBack(callback: AsyncCallback<void>): void; 1485 1486Unregisters the callback for application group changes. This API uses an asynchronous callback to return the result. 1487 1488**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1489 1490**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1491 1492**System API**: This is a system API. 1493 1494**Parameters** 1495 1496| Name | Type | Mandatory | Description | 1497| -------- | ------------------- | ---- | -------------- | 1498| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1499 1500**Error codes** 1501 1502For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1503 1504| ID | Error Message | 1505| ---------- | ---------------------------- | 1506| 10000001 | Memory operation failed. | 1507| 10000002 | Parcel operation failed. | 1508| 10000003 | System service operation failed. | 1509| 10000004 | IPC failed. | 1510| 10100001 | Repeated operation on the application group. | 1511 1512**Example** 1513 1514```ts 1515import { BusinessError } from '@ohos.base'; 1516 1517usageStatistics.unregisterAppGroupCallBack((err: BusinessError) => { 1518 if(err) { 1519 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message); 1520 } else { 1521 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback success.'); 1522 } 1523}); 1524``` 1525 1526## HapModuleInfo 1527 1528Defines the information about the usage record in the FA model. 1529 1530**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1531 1532**System API**: This is a system API. 1533 1534| Name | Type | Mandatory | Description | 1535| -------------------- | ---------------------------------------- | ---- | ----------------------------- | 1536| deviceId | string | No | Device ID. | 1537| bundleName | string | Yes | Bundle name. | 1538| moduleName | string | Yes | Name of the module to which the FA belongs. | 1539| abilityName | string | No | **MainAbility** name of the FA. | 1540| appLabelId | number | No | Application label ID of the FA. | 1541| labelId | number | No | Label ID of the module to which the FA belongs. | 1542| descriptionId | number | No | Description ID of the application to which the FA belongs. | 1543| abilityLableId | number | No | **MainAbility** label ID of the FA. | 1544| abilityDescriptionId | number | No | **MainAbility** description ID of the FA.| 1545| abilityIconId | number | No | **MainAbility** icon ID of the FA. | 1546| launchedCount | number | Yes | Number of FA startup times. | 1547| lastModuleUsedTime | number | Yes | Last time when the FA was used. | 1548| formRecords | Array<[HapFormInfo](#hapforminfo)> | Yes | Array of widget usage records in the FA. | 1549 1550## HapFormInfo 1551 1552Defines the information about the usage record of FA widgets. 1553 1554**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1555 1556**System API**: This is a system API. 1557 1558| Name | Type | Mandatory | Description | 1559| ---------------- | ------ | ---- | ----------- | 1560| formName | string | Yes | Widget name. | 1561| formDimension | number | Yes | Widget dimensions. | 1562| formId | number | Yes | Widget ID. | 1563| formLastUsedTime | number | Yes | Last time when the widget was clicked.| 1564| count | number | Yes | Number of clicks on the widget. | 1565 1566## AppGroupCallbackInfo 1567 1568Provides the application group changes returned through a callback. 1569 1570**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1571 1572**System API**: This is a system API. 1573 1574| Name | Type | Mandatory| Description | 1575| ---------------- | ------ | ---- | ---------------- | 1576| appOldGroup | number | Yes | Application group before the change.| 1577| appNewGroup | number | Yes | Application group after the change.| 1578| userId | number | Yes | User ID. | 1579| changeReason | number | Yes | Reason for the group change.<br>- 256 (default): A record is initially created.<br>- 512: An exception occurs when the priority group is calculated.<br>- 768: The usage duration changes.<br>- 1024: Another application forcibly sets a priority group for the current application.| 1580| bundleName | string | Yes | Bundle name. | 1581 1582## BundleStatsInfo 1583 1584Provides the usage duration information of an application. 1585 1586**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1587 1588**System API**: This is a system API. 1589 1590| Name | Type | Mandatory | Description | 1591| ------------------------ | ------ | ---- | ---------------------------------------- | 1592| bundleName | string | No | Bundle name of the application. | 1593| abilityPrevAccessTime | number | No | Last time when the application was used. | 1594| abilityInFgTotalTime | number | No | Total time that the application runs in the foreground. | 1595| id | number | Yes | User ID.| 1596| abilityPrevSeenTime | number | No | Last time when the application was visible in the foreground.| 1597| abilitySeenTotalTime | number | No | Total time that the application is visible in the foreground.| 1598| fgAbilityAccessTotalTime | number | No | Total time that the application accesses the foreground.| 1599| fgAbilityPrevAccessTime | number | No | Last time when the application accessed the foreground.| 1600| infosBeginTime | number | No | Time logged in the first application usage record in the **BundleActiveInfo** object.| 1601| infosEndTime | number | No | Time logged in the last application usage record in the **BundleActiveInfo** object.| 1602 1603## BundleEvents 1604 1605Provides information about an application event. 1606 1607**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1608 1609**System API**: This is a system API. 1610 1611| Name | Type | Mandatory | Description | 1612| --------------------- | ------ | ---- | ---------------------------------------- | 1613| bundleName | string | No | Bundle name of the application. | 1614| eventId | number | No | Application event type. | 1615| eventOccurredTime | number | No | Timestamp when the application event occurs. | 1616| appGroup | number | No | Group of the application by usage priority.| 1617| indexOfLink | string | No | Shortcut ID.| 1618| nameOfClass | string | No | Class name.| 1619 1620## BundleStatsMap 1621 1622Provides the usage duration information of an application. 1623 1624**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1625 1626**System API**: This is a system API. 1627 1628|Name | Description | 1629| ------------------------------ | ---------------------------------------- | 1630| Record<string, [BundleStatsInfo](#bundlestatsinfo)> | Usage duration information by application.| 1631 1632## DeviceEventStats 1633 1634Provides statistics about notifications and system events. 1635 1636**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1637 1638**System API**: This is a system API. 1639 1640| Name | Type | Mandatory | Description | 1641| ------- | ------ | ---- | ----------------- | 1642| name | string | Yes | Bundle name of the notification sending application or system event name. | 1643| eventId | number | Yes | Type of the notification or system event. | 1644| count | number | Yes | Number of application notifications or system event triggering times.| 1645 1646## IntervalType 1647 1648Enumerates the interval types for querying the application usage duration. 1649 1650**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1651 1652**System API**: This is a system API. 1653 1654| Name | Value | Description | 1655| ------------ | ---- | ---------------------------------------- | 1656| BY_OPTIMIZED | 0 | The system queries the application usage duration statistics in the specified time frame at the interval the system deems appropriate.| 1657| BY_DAILY | 1 | The system queries the application usage duration statistics in the specified time frame on a daily basis. | 1658| BY_WEEKLY | 2 | The system queries the application usage duration statistics in the specified time frame on a weekly basis. | 1659| BY_MONTHLY | 3 | The system queries the application usage duration statistics in the specified time frame on a monthly basis. | 1660| BY_ANNUALLY | 4 | The system queries the application usage duration statistics in the specified time frame on an annual basis. | 1661 1662## GroupType 1663 1664Enumerates the application group types. 1665 1666**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1667 1668**System API**: This is a system API. 1669 1670| Name | Value | Description | 1671| ------------------ | ---- | ----------------- | 1672| ALIVE_GROUP | 10 | Group of active applications. | 1673| DAILY_GROUP | 20 | Group of frequently used applications that are not in the active state. | 1674| FIXED_GROUP | 30 | Group of applications that are used periodically but not every day.| 1675| RARE_GROUP | 40 | Group of rarely used applications. | 1676| LIMITED_GROUP | 50 | Group of restricted applications. | 1677| NEVER_GROUP | 60 | Group of applications that have been installed but never run. | 1678