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