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