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