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