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| Name | Type | Mandatory | Description | 563| -------- | ---------------------------------------- | ---- | --------------------------------------- | 564| begin | number | Yes | Start time, in milliseconds. | 565| end | number | Yes | End time, in milliseconds. | 566| callback | AsyncCallback<Array<[BundleEvents](#bundleevents)>> | Yes | Callback used to return the events obtained.| 567 568**Error codes** 569 570For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 571 572| ID | Error Message | 573| ---------- | ---------------------------- | 574| 10000001 | Memory operation failed. | 575| 10000002 | Parcel operation failed. | 576| 10000003 | System service operation failed. | 577| 10000004 | IPC failed. | 578| 10000006 | Failed to get the application information. | 579| 10000007 | Failed to get the system time. | 580 581**Example** 582 583 ```js 584 try{ 585 usageStatistics.queryCurrentBundleEvents(0, 20000000000000, (err, res) => { 586 if (err) { 587 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback failed. code is: ' + err.code + ',message is: ' + err.message); 588 } else { 589 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback success.'); 590 for (let i = 0; i < res.length; i++) { 591 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback number : ' + (i + 1)); 592 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents callback result ' + JSON.stringify(res[i])); 593 } 594 } 595 }); 596 } catch (error) { 597 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); 598 } 599 ``` 600 601## usageStatistics.queryCurrentBundleEvents 602 603queryCurrentBundleEvents(begin: number, end: number): Promise<Array<BundleEvents>> 604 605Queries events of this application based on the specified start time and end time. This API uses a promise to return the result. 606 607**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 608 609**System API**: This is a system API. 610 611**Parameters** 612| Name | Type | Mandatory | Description | 613| ----- | ------ | ---- | ----- | 614| begin | number | Yes | Start time, in milliseconds.| 615| end | number | Yes | End time, in milliseconds.| 616 617**Return value** 618 619| Type | Description | 620| ---------------------------------------- | -------------------------------------- | 621| Promise<Array<[BundleEvents](#bundleevents)>> | Promise used to return the events obtained.| 622 623**Error codes** 624 625For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 626 627| ID | Error Message | 628| ---------- | ---------------------------- | 629| 10000001 | Memory operation failed. | 630| 10000002 | Parcel operation failed. | 631| 10000003 | System service operation failed. | 632| 10000004 | IPC failed. | 633| 10000006 | Failed to get the application information. | 634| 10000007 | Failed to get the system time. | 635 636**Example** 637 638 ```js 639 try{ 640 usageStatistics.queryCurrentBundleEvents(0, 20000000000000).then( res => { 641 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise success.'); 642 for (let i = 0; i < res.length; i++) { 643 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise number : ' + (i + 1)); 644 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise result ' + JSON.stringify(res[i])); 645 } 646 }).catch( err => { 647 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents promise failed. code is: ' + err.code + ',message is: ' + err.message); 648 }); 649 } catch (error) { 650 console.log('BUNDLE_ACTIVE queryCurrentBundleEvents throw error, code is: ' + error.code + ',message is: ' + error.message); 651 } 652 ``` 653 654## usageStatistics.queryModuleUsageRecords 655 656queryModuleUsageRecords(): Promise<Array<HapModuleInfo>> 657 658Queries FA usage records. This API uses a promise to return a maximum of 1000 FA usage records sorted by time (most recent first). 659 660**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 661 662**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 663 664**System API**: This is a system API. 665 666**Return value** 667 668| Type | Description | 669| ---------------------------------------- | ---------------------------------- | 670| Promise<Array<[HapModuleInfo](#hapmoduleinfo)>> | Promise used to return a maximum of 1000 FA usage records.| 671 672**Error codes** 673 674For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 675 676| ID | Error Message | 677| ---------- | ---------------------------- | 678| 10000001 | Memory operation failed. | 679| 10000002 | Parcel operation failed. | 680| 10000003 | System service operation failed. | 681| 10000004 | IPC failed. | 682| 10000006 | Failed to get the application information. | 683| 10000007 | Failed to get the system time. | 684 685**Example** 686 687 ```js 688 // Invocation when maxNum is not passed 689 try{ 690 usageStatistics.queryModuleUsageRecords().then( res => { 691 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); 692 for (let i = 0; i < res.length; i++) { 693 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); 694 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); 695 } 696 }).catch( err=> { 697 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message); 698 }); 699 } catch (error) { 700 console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); 701 } 702 ``` 703 704## usageStatistics.queryModuleUsageRecords 705 706queryModuleUsageRecords(callback: AsyncCallback<Array<HapModuleInfo>>): void 707 708Queries FA usage records. This API uses an asynchronous callback to return a maximum of 1000 FA usage records sorted by time (most recent first). 709 710**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 711 712**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 713 714**System API**: This is a system API. 715 716**Parameters** 717 718| Name | Type | Mandatory | Description | 719| -------- | ---------------------------------------- | ---- | ----------------------------------- | 720| callback | AsyncCallback<Array<[HapModuleInfo](#hapmoduleinfo)>> | Yes | Callback used to return a maximum of **maxNum** FA usage records.| 721 722**Error codes** 723 724For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 725 726| ID | Error Message | 727| ---------- | ---------------------------- | 728| 10000001 | Memory operation failed. | 729| 10000002 | Parcel operation failed. | 730| 10000003 | System service operation failed. | 731| 10000004 | IPC failed. | 732| 10000006 | Failed to get the application information. | 733| 10000007 | Failed to get the system time. | 734 735**Example** 736 737 ```js 738 try{ 739 usageStatistics.queryModuleUsageRecords((err, res) => { 740 if(err) { 741 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message); 742 } else { 743 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); 744 for (let i = 0; i < res.length; i++) { 745 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); 746 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); 747 } 748 } 749 }); 750 } catch (error) { 751 console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); 752 } 753 ``` 754 755## usageStatistics.queryModuleUsageRecords 756 757queryModuleUsageRecords(maxNum: number): Promise<Array<HapModuleInfo>> 758 759Queries the number of FA usage records specified by **maxNum**. This API uses a promise to return the records sorted by time (most recent first). 760 761**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 762 763**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 764 765**System API**: This is a system API. 766 767**Parameters** 768 769| Name | Type | Mandatory | Description | 770| ------ | ------ | ---- | ---------------------------------- | 771| maxNum | number | Yes | Maximum number of returned records. The maximum and default value is **1000**.| 772 773**Return value** 774 775| Type | Description | 776| ---------------------------------------- | ---------------------------------- | 777| Promise<Array<[HapModuleInfo](#hapmoduleinfo)>> | Promise used to return a maximum of **maxNum** FA usage records.| 778 779**Error codes** 780 781For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 782 783| ID | Error Message | 784| ---------- | ---------------------------- | 785| 10000001 | Memory operation failed. | 786| 10000002 | Parcel operation failed. | 787| 10000003 | System service operation failed. | 788| 10000004 | IPC failed. | 789| 10000006 | Failed to get the application information. | 790| 10000007 | Failed to get the system time. | 791 792**Example** 793 794 ```js 795 try{ 796 usageStatistics.queryModuleUsageRecords(1000).then( res => { 797 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise succeeded'); 798 for (let i = 0; i < res.length; i++) { 799 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise number : ' + (i + 1)); 800 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise result ' + JSON.stringify(res[i])); 801 } 802 }).catch( err=> { 803 console.log('BUNDLE_ACTIVE queryModuleUsageRecords promise failed. code is: ' + err.code + ',message is: ' + err.message); 804 }); 805 } catch (error) { 806 console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); 807 } 808 ``` 809 810## usageStatistics.queryModuleUsageRecords 811 812queryModuleUsageRecords(maxNum: number, callback: AsyncCallback<Array<HapModuleInfo>>): void 813 814Queries the number of FA usage records. This API uses an asynchronous callback to return the records sorted by time (most recent first). 815 816**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 817 818**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 819 820**System API**: This is a system API. 821 822**Parameters** 823 824| Name | Type | Mandatory | Description | 825| -------- | ---------------------------------------- | ---- | ----------------------------------- | 826| maxNum | number | Yes | Maximum number of returned records. The maximum value is **1000**.| 827| callback | AsyncCallback<Array<[HapModuleInfo](#hapmoduleinfo)>> | Yes | Callback used to return a maximum of **maxNum** FA usage records.| 828 829**Error codes** 830 831For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 832 833| ID | Error Message | 834| ---------- | ---------------------------- | 835| 10000001 | Memory operation failed. | 836| 10000002 | Parcel operation failed. | 837| 10000003 | System service operation failed. | 838| 10000004 | IPC failed. | 839| 10000006 | Failed to get the application information. | 840| 10000007 | Failed to get the system time. | 841 842**Example** 843 844 ```js 845 try{ 846 usageStatistics.queryModuleUsageRecords(1000, (err, res) => { 847 if(err) { 848 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback failed. code is: ' + err.code + ',message is: ' + err.message); 849 } else { 850 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback succeeded.'); 851 for (let i = 0; i < res.length; i++) { 852 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback number : ' + (i + 1)); 853 console.log('BUNDLE_ACTIVE queryModuleUsageRecords callback result ' + JSON.stringify(res[i])); 854 } 855 } 856 }); 857 } catch (error) { 858 console.log('BUNDLE_ACTIVE queryModuleUsageRecords throw error, code is: ' + error.code + ',message is: ' + error.message); 859 } 860 ``` 861 862## usageStatistics.queryAppGroup 863 864queryAppGroup(bundleName : string): Promise<number> 865 866Queries the group of the application specified by **bundleName**. This API uses a promise to return the result. 867 868**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 869 870**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 871 872**System API**: This is a system API. 873 874**Parameters** 875 876| Name | Type | Mandatory | Description | 877| ---------- | ------ | ---- | ---------------------------------------- | 878| bundleName | string | Yes | Bundle name of the application.| 879 880**Return value** 881 882| Type | Description | 883| --------------- | --------------------------- | 884| Promise<number> | Promise used to return the group.| 885 886**Error codes** 887 888For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 889 890| ID | Error Message | 891| ---------- | ---------------------------- | 892| 10000001 | Memory operation failed. | 893| 10000002 | Parcel operation failed. | 894| 10000003 | System service operation failed. | 895| 10000004 | IPC failed. | 896| 10000005 | Application is not installed. | 897| 10000006 | Failed to get the application information. | 898| 10100002 | Failed to get the application group information. | 899 900**Example** 901 902```javascript 903// Promise mode when bundleName is specified 904 let bundleName = "com.ohos.camera"; 905 try{ 906 usageStatistics.queryAppGroup(bundleName).then( res => { 907 console.log('BUNDLE_ACTIVE queryAppGroup promise succeeded. result: ' + JSON.stringify(res)); 908 }).catch( err => { 909 console.log('BUNDLE_ACTIVE queryAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message); 910 }); 911 } catch (error) { 912 console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); 913 } 914``` 915 916## usageStatistics.queryAppGroup 917 918queryAppGroup(bundleName : string, callback: AsyncCallback<number>): void 919 920Queries the group of the application specified by **bundleName**. This API uses an asynchronous callback to return the result. 921 922**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 923 924**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 925 926**System API**: This is a system API. 927 928**Parameters** 929 930| Name | Type | Mandatory | Description | 931| ---------- | --------------------- | ---- | ---------------------------------------- | 932| bundleName | string | Yes | Bundle name of the application.| 933| callback | AsyncCallback<number> | Yes | Callback used to return the group.| 934 935**Error codes** 936 937For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 938 939| ID | Error Message | 940| ---------- | ---------------------------- | 941| 10000001 | Memory operation failed. | 942| 10000002 | Parcel operation failed. | 943| 10000003 | System service operation failed. | 944| 10000004 | IPC failed. | 945| 10000005 | Application is not installed. | 946| 10000006 | Failed to get the application information. | 947| 10100002 | Failed to get the application group information. | 948 949**Example** 950 951```javascript 952 let bundleName = "com.ohos.camera"; 953 try{ 954 usageStatistics.queryAppGroup(bundleName, (err, res) => { 955 if(err) { 956 console.log('BUNDLE_ACTIVE queryAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message); 957 } else { 958 console.log('BUNDLE_ACTIVE queryAppGroup callback succeeded. result: ' + JSON.stringify(res)); 959 } 960 }); 961 } catch (error) { 962 console.log('BUNDLE_ACTIVE queryAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); 963 } 964``` 965 966## usageStatistics.setAppGroup 967 968setAppGroup(bundleName: string, newGroup: GroupType): Promise<void> 969 970Sets a group for the application specified by **bundleName**. This API uses a promise to return the result. 971 972**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 973 974**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 975 976**System API**: This is a system API. 977 978**Parameters** 979 980| Name | Type | Mandatory | Description | 981| ---------- | --------- | ---- | ---- | 982| bundleName | string | Yes | Bundle name of the application.| 983| newGroup | [GroupType](#grouptype) | Yes | Group to set.| 984 985**Error codes** 986 987For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 988 989| ID | Error Message | 990| ---------- | ---------------------------- | 991| 10000001 | Memory operation failed. | 992| 10000002 | Parcel operation failed. | 993| 10000003 | System service operation failed. | 994| 10000004 | IPC failed. | 995| 10000006 | Failed to get the application information. | 996| 10100001 | Repeated operation on the application group. | 997 998**Return value** 999 1000| Type | Description | 1001| ------------- | ------------------------- | 1002| Promise<void> | Promise used to return the result. | 1003 1004**Example** 1005 1006```javascript 1007 let bundleName = "com.example.deviceUsageStatistics"; 1008 let newGroup = usageStatistics.GroupType.DAILY_GROUP; 1009 1010 try{ 1011 usageStatistics.setAppGroup(bundleName, newGroup).then( () => { 1012 console.log('BUNDLE_ACTIVE setAppGroup promise succeeded.'); 1013 }).catch( err => { 1014 console.log('BUNDLE_ACTIVE setAppGroup promise failed. code is: ' + err.code + ',message is: ' + err.message); 1015 }); 1016 } catch (error) { 1017 console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); 1018 } 1019``` 1020 1021## usageStatistics.setAppGroup 1022 1023setAppGroup(bundleName: string, newGroup: GroupType, callback: AsyncCallback<void>): void 1024 1025Sets a group for the application specified by **bundleName**. This API uses an asynchronous callback to return the result. 1026 1027**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1028 1029**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1030 1031**System API**: This is a system API. 1032 1033**Parameters** 1034 1035| Name | Type | Mandatory | Description | 1036| ---------- | ------------------- | ---- | ------------------------- | 1037| bundleName | string | Yes | Bundle name of the application. | 1038| newGroup | [GroupType](#grouptype) | Yes | Group to set. | 1039| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1040 1041**Error codes** 1042 1043For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1044 1045| ID | Error Message | 1046| ---------- | ---------------------------- | 1047| 10000001 | Memory operation failed. | 1048| 10000002 | Parcel operation failed. | 1049| 10000003 | System service operation failed. | 1050| 10000004 | IPC failed. | 1051| 10000006 | Failed to get the application information. | 1052| 10100001 | Repeated operation on the application group. | 1053 1054**Example** 1055 1056```javascript 1057 let bundleName = "com.example.deviceUsageStatistics"; 1058 let newGroup = usageStatistics.GroupType.DAILY_GROUP; 1059 1060 try{ 1061 usageStatistics.setAppGroup(bundleName, newGroup, (err) => { 1062 if(err) { 1063 console.log('BUNDLE_ACTIVE setAppGroup callback failed. code is: ' + err.code + ',message is: ' + err.message); 1064 } else { 1065 console.log('BUNDLE_ACTIVE setAppGroup callback succeeded.'); 1066 } 1067 }); 1068 } catch (error) { 1069 console.log('BUNDLE_ACTIVE setAppGroup throw error, code is: ' + error.code + ',message is: ' + error.message); 1070 } 1071``` 1072 1073## usageStatistics.registerAppGroupCallBack 1074 1075registerAppGroupCallBack(groupCallback: Callback<AppGroupCallbackInfo>): Promise<void> 1076 1077Registers 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. 1078 1079**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1080 1081**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1082 1083**System API**: This is a system API. 1084 1085**Parameters** 1086 1087| Name | Type | Mandatory| Description | 1088| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 1089| callback | Callback<[AppGroupCallbackInfo](#appgroupcallbackinfo)> | Yes | Callback used to return the application group changes.| 1090 1091**Error codes** 1092 1093For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1094 1095| ID | Error Message | 1096| ---------- | ---------------------------- | 1097| 10000001 | Memory operation failed. | 1098| 10000002 | Parcel operation failed. | 1099| 10000003 | System service operation failed. | 1100| 10000004 | IPC failed. | 1101| 10100001 | Repeated operation on the application group. | 1102 1103**Return value** 1104 1105| Type | Description | 1106| ------------- | ----------------------- | 1107| Promise<void> | Promise used to return the result. | 1108 1109**Example** 1110 1111```javascript 1112 let onBundleGroupChanged = (res) =>{ 1113 console.log('BUNDLE_ACTIVE registerAppGroupCallBack RegisterGroupCallBack callback success.'); 1114 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); 1115 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); 1116 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); 1117 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); 1118 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); 1119 }; 1120 try{ 1121 usageStatistics.registerAppGroupCallBack(onBundleGroupChanged).then( () => { 1122 console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise succeeded.'); 1123 }).catch( err => { 1124 console.log('BUNDLE_ACTIVE registerAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message); 1125 }); 1126 } catch (error) { 1127 console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); 1128 } 1129``` 1130 1131## usageStatistics.registerAppGroupCallBack 1132 1133registerAppGroupCallBack(groupCallback: Callback<AppGroupCallbackInfo>, callback: AsyncCallback<void>): void 1134 1135Registers 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. 1136 1137**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1138 1139**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1140 1141**System API**: This is a system API. 1142 1143**Parameters** 1144 1145| Name | Type | Mandatory| Description | 1146| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------- | 1147| groupCallback | Callback<[AppGroupCallbackInfo](#appgroupcallbackinfo)> | Yes | Callback used to return the application group changes. | 1148| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1149 1150**Error codes** 1151 1152For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1153 1154| ID | Error Message | 1155| ---------- | ---------------------------- | 1156| 10000001 | Memory operation failed. | 1157| 10000002 | Parcel operation failed. | 1158| 10000003 | System service operation failed. | 1159| 10000004 | IPC failed. | 1160| 10100001 | Repeated operation on the application group. | 1161 1162 1163**Example** 1164 1165```javascript 1166 // @ts-nocheck 1167 let onBundleGroupChanged = (err, res) =>{ 1168 console.log('BUNDLE_ACTIVE onBundleGroupChanged RegisterGroupCallBack callback success.'); 1169 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appOldGroup is : ' + res.appOldGroup); 1170 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result appNewGroup is : ' + res.appNewGroup); 1171 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result changeReason is : ' + res.changeReason); 1172 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result userId is : ' + res.userId); 1173 console.log('BUNDLE_ACTIVE registerAppGroupCallBack result bundleName is : ' + res.bundleName); 1174 }; 1175 try{ 1176 usageStatistics.registerAppGroupCallBack(onBundleGroupChanged, err => { 1177 if(err) { 1178 console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message); 1179 } else { 1180 console.log('BUNDLE_ACTIVE registerAppGroupCallBack callback success.'); 1181 } 1182 }); 1183 } catch (error) { 1184 console.log('BUNDLE_ACTIVE registerAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); 1185 } 1186``` 1187 1188## usageStatistics.unregisterAppGroupCallBack 1189 1190unregisterAppGroupCallBack(): Promise<void> 1191 1192Deregisters the callback for application group changes. This API uses a promise to return the result. 1193 1194**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1195 1196**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1197 1198**System API**: This is a system API. 1199 1200**Return value** 1201 1202| Type | Description | 1203| ------------- | ------------------------ | 1204| Promise<void> | Promise used to return the result. | 1205 1206**Error codes** 1207 1208For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1209 1210| ID | Error Message | 1211| ---------- | ---------------------------- | 1212| 10000001 | Memory operation failed. | 1213| 10000002 | Parcel operation failed. | 1214| 10000003 | System service operation failed. | 1215| 10000004 | IPC failed. | 1216| 10100001 | Repeated operation on the application group. | 1217 1218**Example** 1219 1220```javascript 1221 try{ 1222 usageStatistics.unregisterAppGroupCallBack().then( () => { 1223 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise succeeded.'); 1224 }).catch( err => { 1225 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack promise failed. code is: ' + err.code + ',message is: ' + err.message); 1226 }); 1227 } catch (error) { 1228 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); 1229 } 1230``` 1231 1232## usageStatistics.unregisterAppGroupCallBack 1233 1234unregisterAppGroupCallBack(callback: AsyncCallback<void>): void; 1235 1236Deregisters the callback for application group changes. This API uses an asynchronous callback to return the result. 1237 1238**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1239 1240**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1241 1242**System API**: This is a system API. 1243 1244**Parameters** 1245 1246| Name | Type | Mandatory | Description | 1247| -------- | ------------------- | ---- | -------------- | 1248| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1249 1250**Error codes** 1251 1252For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1253 1254| ID | Error Message | 1255| ---------- | ---------------------------- | 1256| 10000001 | Memory operation failed. | 1257| 10000002 | Parcel operation failed. | 1258| 10000003 | System service operation failed. | 1259| 10000004 | IPC failed. | 1260| 10100001 | Repeated operation on the application group. | 1261 1262**Example** 1263 1264```javascript 1265 try{ 1266 usageStatistics.unregisterAppGroupCallBack(err => { 1267 if(err) { 1268 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback failed. code is: ' + err.code + ',message is: ' + err.message); 1269 } else { 1270 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack callback success.'); 1271 } 1272 }); 1273 } catch (error) { 1274 console.log('BUNDLE_ACTIVE unregisterAppGroupCallBack throw error, code is: ' + error.code + ',message is: ' + error.message); 1275 } 1276``` 1277 1278## usageStatistics.queryDeviceEventStats 1279 1280queryDeviceEventStats(begin: number, end: number): Promise<Array<DeviceEventStats>> 1281 1282Queries 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. 1283 1284**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1285 1286**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1287 1288**System API**: This is a system API. 1289 1290**Parameters** 1291 1292| Name | Type | Mandatory | Description | 1293| ----- | ------ | ---- | ----- | 1294| begin | number | Yes | Start time, in milliseconds.| 1295| end | number | Yes | End time, in milliseconds.| 1296 1297**Return value** 1298 1299| Type | Description | 1300| ---------------------------------------- | ---------------------------------------- | 1301| Promise<Array<[DeviceEventStats](#deviceeventstats)>> | Promise used to return the result. | 1302 1303**Error codes** 1304 1305For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1306 1307| ID | Error Message | 1308| ---------- | ---------------------------- | 1309| 10000001 | Memory operation failed. | 1310| 10000002 | Parcel operation failed. | 1311| 10000003 | System service operation failed. | 1312| 10000004 | IPC failed. | 1313| 10000006 | Failed to get the application information. | 1314| 10000007 | Failed to get the system time. | 1315 1316**Example** 1317 1318 ```js 1319 try{ 1320 usageStatistics.queryDeviceEventStats(0, 20000000000000).then( res => { 1321 console.log('BUNDLE_ACTIVE queryDeviceEventStates promise success.'); 1322 console.log('BUNDLE_ACTIVE queryDeviceEventStates promise result ' + JSON.stringify(res)); 1323 }).catch( err=> { 1324 console.log('BUNDLE_ACTIVE queryDeviceEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message); 1325 }); 1326 } catch (error) { 1327 console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); 1328 } 1329 ``` 1330 1331## usageStatistics.queryDeviceEventStats 1332 1333queryDeviceEventStats(begin: number, end: number, callback: AsyncCallback<Array<DeviceEventStats>>): void 1334 1335 1336 1337**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1338 1339**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1340 1341**System API**: This is a system API. 1342 1343**Parameters** 1344 1345| Name | Type | Mandatory | Description | 1346| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1347| begin | number | Yes | Start time, in milliseconds. | 1348| end | number | Yes | End time, in milliseconds. | 1349| callback | AsyncCallback<Array<[DeviceEventStats](#deviceeventstats)>> | Yes | Callback used to return the result. | 1350 1351**Error codes** 1352 1353For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1354 1355| ID | Error Message | 1356| ---------- | ---------------------------- | 1357| 10000001 | Memory operation failed. | 1358| 10000002 | Parcel operation failed. | 1359| 10000003 | System service operation failed. | 1360| 10000004 | IPC failed. | 1361| 10000006 | Failed to get the application information. | 1362| 10000007 | Failed to get the system time. | 1363 1364**Example** 1365 1366 ```js 1367 try{ 1368 usageStatistics.queryDeviceEventStats(0, 20000000000000, (err, res) => { 1369 if(err) { 1370 console.log('BUNDLE_ACTIVE queryDeviceEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message); 1371 } else { 1372 console.log('BUNDLE_ACTIVE queryDeviceEventStats callback success.'); 1373 console.log('BUNDLE_ACTIVE queryDeviceEventStats callback result ' + JSON.stringify(res)); 1374 } 1375 }); 1376 } catch (error) { 1377 console.log('BUNDLE_ACTIVE queryDeviceEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); 1378 } 1379 ``` 1380 1381## usageStatistics.queryNotificationEventStats 1382 1383queryNotificationEventStats(begin: number, end: number): Promise<Array<DeviceEventStats>> 1384 1385Queries 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. 1386 1387**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1388 1389**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1390 1391**System API**: This is a system API. 1392 1393**Parameters** 1394 1395| Name | Type | Mandatory | Description | 1396| ----- | ------ | ---- | ----- | 1397| begin | number | Yes | Start time, in milliseconds.| 1398| end | number | Yes | End time, in milliseconds.| 1399 1400**Return value** 1401 1402| Type | Description | 1403| ---------------------------------------- | ---------------------------------------- | 1404| Promise<Array<[DeviceEventStats](#deviceeventstats)>> | Promise used to return the result. | 1405 1406**Error codes** 1407 1408For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1409 1410| ID | Error Message | 1411| ---------- | ---------------------------- | 1412| 10000001 | Memory operation failed. | 1413| 10000002 | Parcel operation failed. | 1414| 10000003 | System service operation failed. | 1415| 10000004 | IPC failed. | 1416| 10000006 | Failed to get the application information. | 1417| 10000007 | Failed to get the system time. | 1418 1419**Example** 1420 1421 ```js 1422 try{ 1423 usageStatistics.queryNotificationEventStats(0, 20000000000000).then( res => { 1424 console.log('BUNDLE_ACTIVE queryNotificationEventStats promise success.'); 1425 console.log('BUNDLE_ACTIVE queryNotificationEventStats promise result ' + JSON.stringify(res)); 1426 }).catch( err=> { 1427 console.log('BUNDLE_ACTIVE queryNotificationEventStats promise failed. code is: ' + err.code + ',message is: ' + err.message); 1428 }); 1429 } catch (error) { 1430 console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); 1431 } 1432 ``` 1433 1434## usageStatistics.queryNotificationEventStats 1435 1436queryNotificationEventStats(begin: number, end: number, callback: AsyncCallback<Array<DeviceEventStats>>): void 1437 1438Queries 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. 1439 1440**Required permissions**: ohos.permission.BUNDLE_ACTIVE_INFO 1441 1442**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1443 1444**System API**: This is a system API. 1445 1446**Parameters** 1447 1448| Name | Type | Mandatory | Description | 1449| -------- | ---------------------------------------- | ---- | ---------------------------------------- | 1450| begin | number | Yes | Start time, in milliseconds. | 1451| end | number | Yes | End time, in milliseconds. | 1452| callback | AsyncCallback<Array<[DeviceEventStats](#deviceeventstats)>> | Yes | Callback used to return the result. | 1453 1454**Error codes** 1455 1456For details about the error codes, see [DeviceUsageStatistics Error Codes](../errorcodes/errorcode-DeviceUsageStatistics.md). 1457 1458| ID | Error Message | 1459| ---------- | ---------------------------- | 1460| 10000001 | Memory operation failed. | 1461| 10000002 | Parcel operation failed. | 1462| 10000003 | System service operation failed. | 1463| 10000004 | IPC failed. | 1464| 10000006 | Failed to get the application information. | 1465| 10000007 | Failed to get the system time. | 1466 1467**Example** 1468 1469 ```js 1470 try{ 1471 usageStatistics.queryNotificationEventStats(0, 20000000000000, (err, res) => { 1472 if(err) { 1473 console.log('BUNDLE_ACTIVE queryNotificationEventStats callback failed. code is: ' + err.code + ',message is: ' + err.message); 1474 } else { 1475 console.log('BUNDLE_ACTIVE queryNotificationEventStats callback success.'); 1476 console.log('BUNDLE_ACTIVE queryNotificationEventStats callback result ' + JSON.stringify(res)); 1477 } 1478 }); 1479 } catch (error) { 1480 console.log('BUNDLE_ACTIVE queryNotificationEventStats throw error, code is: ' + error.code + ',message is: ' + error.message); 1481 } 1482 ``` 1483 1484## HapModuleInfo 1485Provides the information about the FA usage. 1486 1487**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1488 1489**System API**: This is a system API. 1490 1491| Name | Type | Mandatory | Description | 1492| -------------------- | ---------------------------------------- | ---- | ----------------------------- | 1493| deviceId | string | No | ID of the device to which the FA belongs. | 1494| bundleName | string | Yes | Name of the bundle to which the FA belongs. | 1495| moduleName | string | Yes | Name of the module to which the FA belongs. | 1496| abilityName | string | No | **MainAbility** name of the FA. | 1497| appLabelId | number | No | Application label ID of the FA. | 1498| labelId | number | No | Label ID of the module to which the FA belongs. | 1499| descriptionId | number | No | Description ID of the application to which the FA belongs. | 1500| abilityLableId | number | No | **MainAbility** label ID of the FA. | 1501| abilityDescriptionId | number | No | **MainAbility** description ID of the FA.| 1502| abilityIconId | number | No | **MainAbility** icon ID of the FA. | 1503| launchedCount | number | Yes | Number of FA startup times. | 1504| lastModuleUsedTime | number | Yes | Last time when the FA was used. | 1505| formRecords | Array<[HapFormInfo](#hapforminfo)> | Yes | Array of widget usage records in the FA. | 1506 1507## HapFormInfo 1508Provides the FA widget usage information. 1509 1510**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1511 1512**System API**: This is a system API. 1513 1514| Name | Type | Mandatory | Description | 1515| ---------------- | ------ | ---- | ----------- | 1516| formName | string | Yes | Widget name. | 1517| formDimension | number | Yes | Widget dimensions. | 1518| formId | number | Yes | Widget ID. | 1519| formLastUsedTime | number | Yes | Last time when the widget was clicked.| 1520| count | number | Yes | Number of clicks on the widget. | 1521 1522## AppGroupCallbackInfo 1523 1524Provides the application group changes returned through a callback. 1525 1526**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1527 1528**System API**: This is a system API. 1529 1530| Name | Type | Mandatory| Description | 1531| ---------------- | ------ | ---- | ---------------- | 1532| appOldGroup | number | Yes | Application group before the change.| 1533| appNewGroup | number | Yes | Application group after the change.| 1534| userId | number | Yes | User ID. | 1535| changeReason | number | Yes | Reason for the group change. | 1536| bundleName | string | Yes | Bundle name of the application. | 1537 1538## BundleStatsInfo 1539 1540Provides the usage duration information of an application. 1541 1542### Attributes 1543 1544**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1545 1546**System API**: This is a system API. 1547 1548| Name | Type | Mandatory | Description | 1549| ------------------------ | ------ | ---- | ---------------------------------------- | 1550| bundleName | string | Yes | Bundle name of the application. | 1551| abilityPrevAccessTime | number | Yes | Last time when the application was used. | 1552| abilityInFgTotalTime | number | Yes | Total time that the application runs in the foreground. | 1553| id | number | No | User ID.| 1554| abilityPrevSeenTime | number | No | Last time when the application was visible in the foreground.| 1555| abilitySeenTotalTime | number | No | Total time that the application is visible in the foreground.| 1556| fgAbilityAccessTotalTime | number | No | Total time that the application accesses the foreground.| 1557| fgAbilityPrevAccessTime | number | No | Last time when the application accessed the foreground.| 1558| infosBeginTime | number | No | Time logged in the first application usage record in the **BundleActiveInfo** object.| 1559| infosEndTime | number | No | Time logged in the last application usage record in the **BundleActiveInfo** object.| 1560 1561## BundleEvents 1562 1563Provides information about an application event. 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| bundleName | string | Yes | Bundle name of the application. | 1572| eventId | number | Yes | Application event type. | 1573| eventOccurredTime | number | Yes | Timestamp when the application event occurs. | 1574| appGroup | number | No | Usage priority group of the application.| 1575| indexOfLink | string | No | Shortcut ID.| 1576| nameOfClass | string | No | Class name.| 1577 1578## BundleStatsMap 1579 1580Provides the usage duration information of an application. 1581 1582**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1583 1584**System API**: This is a system API. 1585 1586| Name | Type | Mandatory | Description | 1587| ------------------------------ | ---------------------------------------- | ---- | -------------- | 1588| [key: string]: BundleStatsInfo | [key: string]: [BundleStatsInfo](#bundlestatsinfo) | Yes | Usage duration information by application.| 1589 1590## DeviceEventStats 1591 1592Provides statistics about notifications and system events. 1593 1594**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1595 1596**System API**: This is a system API. 1597 1598| Name | Type | Mandatory | Description | 1599| ------- | ------ | ---- | ----------------- | 1600| name | string | Yes | Bundle name of the notification sending application or system event name. | 1601| eventId | number | Yes | Type of the notification or system event. | 1602| count | number | Yes | Number of application notifications or system event triggering times.| 1603 1604## IntervalType 1605 1606Enumerates the interval types for querying the application usage duration. 1607 1608**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 1609 1610**System API**: This is a system API. 1611 1612| Name | Value | Description | 1613| ------------ | ---- | ---------------------------------------- | 1614| BY_OPTIMIZED | 0 | The system queries the application usage duration statistics in the specified time frame at the interval the system deems appropriate.| 1615| BY_DAILY | 1 | The system queries the application usage duration statistics in the specified time frame on a daily basis. | 1616| BY_WEEKLY | 2 | The system queries the application usage duration statistics in the specified time frame on a weekly basis. | 1617| BY_MONTHLY | 3 | The system queries the application usage duration statistics in the specified time frame on a monthly basis. | 1618| BY_ANNUALLY | 4 | The system queries the application usage duration statistics in the specified time frame on an annual basis. | 1619 1620## GroupType 1621 1622Enumerates the application group types. 1623 1624**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 1625 1626**System API**: This is a system API. 1627 1628| Name | Value | Description | 1629| ------------------ | ---- | ----------------- | 1630| ALIVE_GROUP | 10 | Group of active applications. | 1631| DAILY_GROUP | 20 | Group of frequently used applications that are not in the active state. | 1632| FIXED_GROUP | 30 | Group of applications that are used periodically but not every day.| 1633| RARE_GROUP | 40 | Group of rarely used applications. | 1634| LIMITED_GROUP | 50 | Group of restricted applications. | 1635| NEVER_GROUP | 60 | Group of applications that have been installed but never run. | 1636