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