1# @ohos.bundleState (Device Usage Statistics) 2 3This module provides APIs for collecting statistics on device usage. 4 5> **NOTE** 6> 7> The APIs of this module are deprecated since API version 9. The substitute APIs are open only to system applications. 8> 9> 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. 10 11 12## Modules to Import 13 14```js 15import bundleState from '@ohos.bundleState' 16``` 17 18## bundleState.isIdleState 19 20isIdleState(bundleName: string, callback: AsyncCallback<boolean>): void 21 22Checks 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. 23 24**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 25 26**Parameters** 27 28| Name | Type | Mandatory | Description | 29| ---------- | ---------------------------- | ---- | ---------------------------------------- | 30| bundleName | string | Yes | Bundle name of an application. | 31| 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. | 32 33**Example** 34 35```ts 36import { BusinessError } from '@ohos.base'; 37 38bundleState.isIdleState("com.ohos.camera", (err: BusinessError, res: boolean) => { 39 if (err) { 40 console.error('BUNDLE_ACTIVE isIdleState callback failed, because: ' + err.code); 41 } else { 42 console.log('BUNDLE_ACTIVE isIdleState callback succeeded, result: ' + JSON.stringify(res)); 43 } 44}); 45``` 46 47## bundleState.isIdleState 48 49isIdleState(bundleName: string): Promise<boolean> 50 51Checks 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. 52 53**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 54 55**Parameters** 56 57| Name | Type | Mandatory | Description | 58| ---------- | ------ | ---- | -------------- | 59| bundleName | string | Yes | Bundle name of an application. | 60 61**Return value** 62 63| Type | Description | 64| ---------------------- | ---------------------------------------- | 65| 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. | 66 67**Example** 68 69```ts 70import { BusinessError } from '@ohos.base'; 71 72bundleState.isIdleState("com.ohos.camera").then((res: boolean) => { 73 console.log('BUNDLE_ACTIVE isIdleState promise succeeded, result: ' + JSON.stringify(res)); 74}).catch((err: BusinessError) => { 75 console.error('BUNDLE_ACTIVE isIdleState promise failed, because: ' + err.code); 76}); 77``` 78 79## bundleState.queryAppUsagePriorityGroup 80 81queryAppUsagePriorityGroup(): Promise<number> 82 83Queries the priority group of this application. This API uses a promise to return the result. 84 85**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 86 87**Return value** 88 89| Type | Description | 90| --------------- | --------------------------- | 91| Promise<number> | Promise used to return the priority group. | 92 93**Example** 94 95```ts 96import { BusinessError } from '@ohos.base'; 97 98bundleState.queryAppUsagePriorityGroup().then((res: number) => { 99 console.log('BUNDLE_ACTIVE QueryPackageGroup promise succeeded. result: ' + JSON.stringify(res)); 100}).catch((err: BusinessError) => { 101 console.error('BUNDLE_ACTIVE QueryPackageGroup promise failed. because: ' + err.code); 102}); 103``` 104 105## bundleState.queryAppUsagePriorityGroup 106 107queryAppUsagePriorityGroup(callback: AsyncCallback<number>): void 108 109Queries the priority group of this application. This API uses an asynchronous callback to return the result. 110 111**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.AppGroup 112 113**Parameters** 114 115| Name | Type | Mandatory | Description | 116| -------- | --------------------- | ---- | -------------------------- | 117| callback | AsyncCallback<number> | Yes | Callback used to return the priority group. | 118 119**Example** 120 121```ts 122import { BusinessError } from '@ohos.base'; 123 124bundleState.queryAppUsagePriorityGroup((err: BusinessError, res: number) => { 125 if(err) { 126 console.error('BUNDLE_ACTIVE QueryPackageGroup callback failed. because: ' + err.code); 127 } else { 128 console.log('BUNDLE_ACTIVE QueryPackageGroup callback succeeded. result: ' + JSON.stringify(res)); 129 } 130}); 131``` 132 133## bundleState.queryCurrentBundleActiveStates 134 135queryCurrentBundleActiveStates(begin: number, end: number, callback: AsyncCallback<Array<BundleActiveState>>): void 136 137Queries events of this application based on the specified start time and end time. This API uses an asynchronous callback to return the result. 138 139**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 140 141**Parameters** 142 143| Name | Type | Mandatory | Description | 144| -------- | ---------------------------------------- | ---- | --------------------------------------- | 145| begin | number | Yes | Start time, in milliseconds. | 146| end | number | Yes | End time, in milliseconds. | 147| callback | AsyncCallback<Array<[BundleActiveState](#bundleactivestate)>> | Yes | Callback used to return the events obtained. | 148 149**Example** 150 151```ts 152import { BusinessError } from '@ohos.base'; 153 154bundleState.queryCurrentBundleActiveStates(0, 20000000000000, (err: BusinessError, res: Array<bundleState.BundleActiveState>) => { 155 if (err) { 156 console.error('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback failed, because: ' + err.code); 157 } else { 158 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback success.'); 159 for (let i = 0; i < res.length; i++) { 160 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback number : ' + (i + 1)); 161 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates callback result ' + JSON.stringify(res[i])); 162 } 163 } 164}); 165``` 166 167## bundleState.queryCurrentBundleActiveStates 168 169queryCurrentBundleActiveStates(begin: number, end: number): Promise<Array<BundleActiveState>> 170 171Queries events of this application based on the specified start time and end time. This API uses a promise to return the result. 172 173**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 174 175**Parameters** 176 177| Name | Type | Mandatory | Description | 178| ----- | ------ | ---- | ----- | 179| begin | number | Yes | Start time, in milliseconds. | 180| end | number | Yes | End time, in milliseconds. | 181 182**Return value** 183 184| Type | Description | 185| ---------------------------------------- | -------------------------------------- | 186| Promise<Array<[BundleActiveState](#bundleactivestate)>> | Promise used to return the events obtained. | 187 188**Example** 189 190```ts 191import { BusinessError } from '@ohos.base'; 192 193bundleState.queryCurrentBundleActiveStates(0, 20000000000000).then((res: Array<bundleState.BundleActiveState>) => { 194 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise success.'); 195 for (let i = 0; i < res.length; i++) { 196 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise number : ' + (i + 1)); 197 console.log('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise result ' + JSON.stringify(res[i])); 198 } 199}).catch((err: BusinessError) => { 200 console.error('BUNDLE_ACTIVE queryCurrentBundleActiveStates promise failed, because: ' + err.code); 201}); 202``` 203 204## BundleStateInfo 205 206Provides the usage duration information of an application. 207 208### Attributes 209 210**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 211 212| Name | Type | Mandatory | Description | 213| ------------------------ | ------ | ---- | ---------------------------------------- | 214| bundleName | string | No | Bundle name of an application. | 215| abilityPrevAccessTime | number | No | Last time when the application was used. | 216| abilityInFgTotalTime | number | No | Total time that the application runs in the foreground. | 217| id | number | Yes | User ID.| 218| abilityPrevSeenTime | number | No | Last time when the application was visible in the foreground.| 219| abilitySeenTotalTime | number | No | Total time that the application is visible in the foreground.| 220| fgAbilityAccessTotalTime | number | No | Total time that the application accesses the foreground.| 221| fgAbilityPrevAccessTime | number | No | Last time when the application accessed the foreground.| 222| infosBeginTime | number | No | Time logged in the first application usage record in the **BundleActiveInfo** object.| 223| infosEndTime | number | No | Time logged in the last application usage record in the **BundleActiveInfo** object.| 224 225### merge<sup>(deprecated)</sup> 226 227merge(toMerge: BundleStateInfo): void 228 229Merges the device usage statistics of applications with the same bundle name. 230 231**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 232 233**Parameters** 234 235| Name | Type | Mandatory | Description | 236| -------- | -------- | -------- | -------- | 237| toMerge | [BundleStateInfo](#bundlestateinfo) | Yes | Device usage statistics to merge.| 238 239## BundleActiveState 240 241Provides information about an application event. 242 243Provides the usage duration information of applications. 244 245**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 246 247| Name | Type | Mandatory | Description | 248| --------------------- | ------ | ---- | ---------------------------------------- | 249| bundleName | string | No | Bundle name of an application. | 250| stateType | number | No | Application event type. | 251| stateOccurredTime | number | No | Timestamp when the application event occurs. | 252| appUsagePriorityGroup | number | No | Usage priority group of the application.| 253| indexOfLink | string | No | Shortcut ID.| 254| nameOfClass | string | No | Class name.| 255 256## BundleActiveInfoResponse 257 258Provides the usage duration information of applications. 259 260**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 261 262| Name | Type | Mandatory | Description | 263| ------------------------------ | ---------------------------------------- | ---- | -------------- | 264| [key: string]: BundleStateInfo | [key: string]: [BundleStateInfo](#bundlestateinfo) | Yes | Usage duration information by application. | 265 266## IntervalType 267 268Enumerates the interval types for querying the application usage duration. 269 270**System capability**: SystemCapability.ResourceSchedule.UsageStatistics.App 271 272| Name | Value | Description | 273| ------------ | ---- | ---------------------------------------- | 274| BY_OPTIMIZED | 0 | The system obtains the application usage duration statistics in the specified time frame at the interval the system deems appropriate. | 275| BY_DAILY | 1 | The system obtains the application usage duration statistics in the specified time frame on a daily basis. | 276| BY_WEEKLY | 2 | The system obtains the application usage duration statistics in the specified time frame on a weekly basis. | 277| BY_MONTHLY | 3 | The system obtains the application usage duration statistics in the specified time frame on a monthly basis. | 278| BY_ANNUALLY | 4 | The system obtains the application usage duration statistics in the specified time frame on an annual basis. | 279