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