@capgo/capacitor-android-usagestatsmanager 7.1.0 → 7.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -16
- package/android/src/main/java/ee/forgr/capacitor_android_usagestatsmanager/CapacitorUsageStatsManagerPlugin.java +1 -1
- package/dist/docs.json +124 -39
- package/dist/esm/definitions.d.ts +104 -17
- package/dist/esm/definitions.js.map +1 -1
- package/ios/Sources/CapacitorUsageStatsManagerPlugin/CapacitorUsageStatsManagerPlugin.swift +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -37,6 +37,7 @@ npx cap sync
|
|
|
37
37
|
* [`isUsageStatsPermissionGranted()`](#isusagestatspermissiongranted)
|
|
38
38
|
* [`openUsageStatsSettings()`](#openusagestatssettings)
|
|
39
39
|
* [`queryAllPackages()`](#queryallpackages)
|
|
40
|
+
* [`getPluginVersion()`](#getpluginversion)
|
|
40
41
|
* [Interfaces](#interfaces)
|
|
41
42
|
* [Type Aliases](#type-aliases)
|
|
42
43
|
|
|
@@ -45,20 +46,24 @@ npx cap sync
|
|
|
45
46
|
<docgen-api>
|
|
46
47
|
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
|
|
47
48
|
|
|
49
|
+
Capacitor plugin for accessing Android UsageStatsManager API.
|
|
50
|
+
|
|
48
51
|
### queryAndAggregateUsageStats(...)
|
|
49
52
|
|
|
50
53
|
```typescript
|
|
51
54
|
queryAndAggregateUsageStats(options: UsageStatsOptions) => Promise<Record<string, UsageStats>>
|
|
52
55
|
```
|
|
53
56
|
|
|
54
|
-
Queries and aggregates usage stats for the given
|
|
57
|
+
Queries and aggregates usage stats for the given time range.
|
|
55
58
|
|
|
56
|
-
| Param | Type | Description
|
|
57
|
-
| ------------- | --------------------------------------------------------------- |
|
|
58
|
-
| **`options`** | <code><a href="#usagestatsoptions">UsageStatsOptions</a></code> | - The options for the query
|
|
59
|
+
| Param | Type | Description |
|
|
60
|
+
| ------------- | --------------------------------------------------------------- | -------------------------------------- |
|
|
61
|
+
| **`options`** | <code><a href="#usagestatsoptions">UsageStatsOptions</a></code> | - The time range options for the query |
|
|
59
62
|
|
|
60
63
|
**Returns:** <code>Promise<<a href="#record">Record</a><string, <a href="#usagestats">UsageStats</a>>></code>
|
|
61
64
|
|
|
65
|
+
**Since:** 1.0.0
|
|
66
|
+
|
|
62
67
|
--------------------
|
|
63
68
|
|
|
64
69
|
|
|
@@ -72,6 +77,8 @@ Checks if the usage stats permission is granted.
|
|
|
72
77
|
|
|
73
78
|
**Returns:** <code>Promise<<a href="#usagestatspermissionresult">UsageStatsPermissionResult</a>></code>
|
|
74
79
|
|
|
80
|
+
**Since:** 1.0.0
|
|
81
|
+
|
|
75
82
|
--------------------
|
|
76
83
|
|
|
77
84
|
|
|
@@ -85,6 +92,8 @@ Open the usage stats settings screen.
|
|
|
85
92
|
This will open the usage stats settings screen, which allows the user to grant the usage stats permission.
|
|
86
93
|
This will always open the settings screen, even if the permission is already granted.
|
|
87
94
|
|
|
95
|
+
**Since:** 1.0.0
|
|
96
|
+
|
|
88
97
|
--------------------
|
|
89
98
|
|
|
90
99
|
|
|
@@ -104,11 +113,28 @@ Requires the QUERY_ALL_PACKAGES permission.
|
|
|
104
113
|
--------------------
|
|
105
114
|
|
|
106
115
|
|
|
116
|
+
### getPluginVersion()
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
getPluginVersion() => Promise<{ version: string; }>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Get the native Capacitor plugin version.
|
|
123
|
+
|
|
124
|
+
**Returns:** <code>Promise<{ version: string; }></code>
|
|
125
|
+
|
|
126
|
+
**Since:** 1.0.0
|
|
127
|
+
|
|
128
|
+
--------------------
|
|
129
|
+
|
|
130
|
+
|
|
107
131
|
### Interfaces
|
|
108
132
|
|
|
109
133
|
|
|
110
134
|
#### UsageStats
|
|
111
135
|
|
|
136
|
+
Usage statistics for an Android app.
|
|
137
|
+
|
|
112
138
|
| Prop | Type | Description |
|
|
113
139
|
| ----------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
|
|
114
140
|
| **`firstTimeStamp`** | <code>number</code> | The first timestamp of the usage stats. |
|
|
@@ -124,6 +150,8 @@ Requires the QUERY_ALL_PACKAGES permission.
|
|
|
124
150
|
|
|
125
151
|
#### UsageStatsOptions
|
|
126
152
|
|
|
153
|
+
Options for querying usage statistics.
|
|
154
|
+
|
|
127
155
|
| Prop | Type | Description |
|
|
128
156
|
| --------------- | ------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
129
157
|
| **`beginTime`** | <code>number</code> | The inclusive beginning of the range of stats to include in the results. Defined in terms of "Unix time" |
|
|
@@ -132,6 +160,8 @@ Requires the QUERY_ALL_PACKAGES permission.
|
|
|
132
160
|
|
|
133
161
|
#### UsageStatsPermissionResult
|
|
134
162
|
|
|
163
|
+
Result of a usage stats permission check.
|
|
164
|
+
|
|
135
165
|
| Prop | Type | Description |
|
|
136
166
|
| ------------- | -------------------- | ---------------------------------------------- |
|
|
137
167
|
| **`granted`** | <code>boolean</code> | Whether the usage stats permission is granted. |
|
|
@@ -141,18 +171,14 @@ Requires the QUERY_ALL_PACKAGES permission.
|
|
|
141
171
|
|
|
142
172
|
Represents basic information about an installed package.
|
|
143
173
|
|
|
144
|
-
| Prop | Type |
|
|
145
|
-
| ---------------------- | ------------------- |
|
|
146
|
-
| **`packageName`** | <code>string</code> |
|
|
147
|
-
| **`appName`** | <code>string</code> |
|
|
148
|
-
| **`versionName`** | <code>string</code> |
|
|
149
|
-
| **`versionCode`** | <code>number</code> |
|
|
150
|
-
| **`firstInstallTime`** | <code>number</code> |
|
|
151
|
-
| **`lastUpdateTime`** | <code>number</code> |
|
|
152
|
-
|
|
153
|
-
| Method | Signature | Description |
|
|
154
|
-
| -------------------- | -------------------------------------------- | --------------------------------------- |
|
|
155
|
-
| **getPluginVersion** | () => Promise<{ version: string; }> | Get the native Capacitor plugin version |
|
|
174
|
+
| Prop | Type | Description |
|
|
175
|
+
| ---------------------- | ------------------- | ---------------------------------------------- |
|
|
176
|
+
| **`packageName`** | <code>string</code> | Package name |
|
|
177
|
+
| **`appName`** | <code>string</code> | App display name |
|
|
178
|
+
| **`versionName`** | <code>string</code> | Version name string |
|
|
179
|
+
| **`versionCode`** | <code>number</code> | Version code number |
|
|
180
|
+
| **`firstInstallTime`** | <code>number</code> | First install time in milliseconds since epoch |
|
|
181
|
+
| **`lastUpdateTime`** | <code>number</code> | Last update time in milliseconds since epoch |
|
|
156
182
|
|
|
157
183
|
|
|
158
184
|
### Type Aliases
|
|
@@ -25,7 +25,7 @@ import java.util.Map;
|
|
|
25
25
|
@CapacitorPlugin(name = "CapacitorUsageStatsManager")
|
|
26
26
|
public class CapacitorUsageStatsManagerPlugin extends Plugin {
|
|
27
27
|
|
|
28
|
-
private final String PLUGIN_VERSION = "7.
|
|
28
|
+
private final String PLUGIN_VERSION = "7.2.0";
|
|
29
29
|
|
|
30
30
|
@PluginMethod
|
|
31
31
|
public void queryAndAggregateUsageStats(final PluginCall call) {
|
package/dist/docs.json
CHANGED
|
@@ -2,8 +2,13 @@
|
|
|
2
2
|
"api": {
|
|
3
3
|
"name": "CapacitorUsageStatsManagerPlugin",
|
|
4
4
|
"slug": "capacitorusagestatsmanagerplugin",
|
|
5
|
-
"docs": "",
|
|
6
|
-
"tags": [
|
|
5
|
+
"docs": "Capacitor plugin for accessing Android UsageStatsManager API.",
|
|
6
|
+
"tags": [
|
|
7
|
+
{
|
|
8
|
+
"text": "1.0.0",
|
|
9
|
+
"name": "since"
|
|
10
|
+
}
|
|
11
|
+
],
|
|
7
12
|
"methods": [
|
|
8
13
|
{
|
|
9
14
|
"name": "queryAndAggregateUsageStats",
|
|
@@ -11,7 +16,7 @@
|
|
|
11
16
|
"parameters": [
|
|
12
17
|
{
|
|
13
18
|
"name": "options",
|
|
14
|
-
"docs": "- The options for the query
|
|
19
|
+
"docs": "- The time range options for the query",
|
|
15
20
|
"type": "UsageStatsOptions"
|
|
16
21
|
}
|
|
17
22
|
],
|
|
@@ -19,14 +24,26 @@
|
|
|
19
24
|
"tags": [
|
|
20
25
|
{
|
|
21
26
|
"name": "param",
|
|
22
|
-
"text": "options - The options for the query
|
|
27
|
+
"text": "options - The time range options for the query"
|
|
23
28
|
},
|
|
24
29
|
{
|
|
25
30
|
"name": "returns",
|
|
26
|
-
"text": "
|
|
31
|
+
"text": "Promise that resolves to a record of package names and their corresponding usage stats"
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"name": "throws",
|
|
35
|
+
"text": "Error if the permission is not granted or query fails"
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"name": "since",
|
|
39
|
+
"text": "1.0.0"
|
|
40
|
+
},
|
|
41
|
+
{
|
|
42
|
+
"name": "example",
|
|
43
|
+
"text": "```typescript\nconst oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;\nconst now = Date.now();\nconst stats = await UsageStatsManager.queryAndAggregateUsageStats({\n beginTime: oneDayAgo,\n endTime: now\n});\n\nfor (const [packageName, usageData] of Object.entries(stats)) {\n console.log(`${packageName}: ${usageData.totalTimeInForeground}ms`);\n}\n```"
|
|
27
44
|
}
|
|
28
45
|
],
|
|
29
|
-
"docs": "Queries and aggregates usage stats for the given
|
|
46
|
+
"docs": "Queries and aggregates usage stats for the given time range.",
|
|
30
47
|
"complexTypes": [
|
|
31
48
|
"Record",
|
|
32
49
|
"UsageStats",
|
|
@@ -42,7 +59,19 @@
|
|
|
42
59
|
"tags": [
|
|
43
60
|
{
|
|
44
61
|
"name": "returns",
|
|
45
|
-
"text": "
|
|
62
|
+
"text": "Promise that resolves to a permission result object"
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
"name": "throws",
|
|
66
|
+
"text": "Error if checking permission fails"
|
|
67
|
+
},
|
|
68
|
+
{
|
|
69
|
+
"name": "since",
|
|
70
|
+
"text": "1.0.0"
|
|
71
|
+
},
|
|
72
|
+
{
|
|
73
|
+
"name": "example",
|
|
74
|
+
"text": "```typescript\nconst { granted } = await UsageStatsManager.isUsageStatsPermissionGranted();\nif (!granted) {\n await UsageStatsManager.openUsageStatsSettings();\n}\n```"
|
|
46
75
|
}
|
|
47
76
|
],
|
|
48
77
|
"docs": "Checks if the usage stats permission is granted.",
|
|
@@ -56,7 +85,24 @@
|
|
|
56
85
|
"signature": "() => Promise<void>",
|
|
57
86
|
"parameters": [],
|
|
58
87
|
"returns": "Promise<void>",
|
|
59
|
-
"tags": [
|
|
88
|
+
"tags": [
|
|
89
|
+
{
|
|
90
|
+
"name": "returns",
|
|
91
|
+
"text": "Promise that resolves when the settings screen is opened"
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
"name": "throws",
|
|
95
|
+
"text": "Error if opening settings fails"
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
"name": "since",
|
|
99
|
+
"text": "1.0.0"
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
"name": "example",
|
|
103
|
+
"text": "```typescript\nawait UsageStatsManager.openUsageStatsSettings();\n```"
|
|
104
|
+
}
|
|
105
|
+
],
|
|
60
106
|
"docs": "Open the usage stats settings screen.\nThis will open the usage stats settings screen, which allows the user to grant the usage stats permission.\nThis will always open the settings screen, even if the permission is already granted.",
|
|
61
107
|
"complexTypes": [],
|
|
62
108
|
"slug": "openusagestatssettings"
|
|
@@ -67,9 +113,21 @@
|
|
|
67
113
|
"parameters": [],
|
|
68
114
|
"returns": "Promise<{ packages: PackageInfo[]; }>",
|
|
69
115
|
"tags": [
|
|
116
|
+
{
|
|
117
|
+
"name": "returns",
|
|
118
|
+
"text": "Promise that resolves with an array of package information"
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
"name": "throws",
|
|
122
|
+
"text": "Error if the permission is not granted or query fails"
|
|
123
|
+
},
|
|
70
124
|
{
|
|
71
125
|
"name": "since",
|
|
72
126
|
"text": "1.2.0"
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
"name": "example",
|
|
130
|
+
"text": "```typescript\nconst { packages } = await UsageStatsManager.queryAllPackages();\npackages.forEach(pkg => {\n console.log(`${pkg.appName} (${pkg.packageName}): v${pkg.versionName}`);\n});\n```"
|
|
73
131
|
}
|
|
74
132
|
],
|
|
75
133
|
"docs": "Queries all installed packages on the device.\nRequires the QUERY_ALL_PACKAGES permission.",
|
|
@@ -77,6 +135,33 @@
|
|
|
77
135
|
"PackageInfo"
|
|
78
136
|
],
|
|
79
137
|
"slug": "queryallpackages"
|
|
138
|
+
},
|
|
139
|
+
{
|
|
140
|
+
"name": "getPluginVersion",
|
|
141
|
+
"signature": "() => Promise<{ version: string; }>",
|
|
142
|
+
"parameters": [],
|
|
143
|
+
"returns": "Promise<{ version: string; }>",
|
|
144
|
+
"tags": [
|
|
145
|
+
{
|
|
146
|
+
"name": "returns",
|
|
147
|
+
"text": "Promise that resolves with the plugin version"
|
|
148
|
+
},
|
|
149
|
+
{
|
|
150
|
+
"name": "throws",
|
|
151
|
+
"text": "Error if getting the version fails"
|
|
152
|
+
},
|
|
153
|
+
{
|
|
154
|
+
"name": "since",
|
|
155
|
+
"text": "1.0.0"
|
|
156
|
+
},
|
|
157
|
+
{
|
|
158
|
+
"name": "example",
|
|
159
|
+
"text": "```typescript\nconst { version } = await UsageStatsManager.getPluginVersion();\nconsole.log('Plugin version:', version);\n```"
|
|
160
|
+
}
|
|
161
|
+
],
|
|
162
|
+
"docs": "Get the native Capacitor plugin version.",
|
|
163
|
+
"complexTypes": [],
|
|
164
|
+
"slug": "getpluginversion"
|
|
80
165
|
}
|
|
81
166
|
],
|
|
82
167
|
"properties": []
|
|
@@ -85,8 +170,13 @@
|
|
|
85
170
|
{
|
|
86
171
|
"name": "UsageStats",
|
|
87
172
|
"slug": "usagestats",
|
|
88
|
-
"docs": "",
|
|
89
|
-
"tags": [
|
|
173
|
+
"docs": "Usage statistics for an Android app.",
|
|
174
|
+
"tags": [
|
|
175
|
+
{
|
|
176
|
+
"text": "1.0.0",
|
|
177
|
+
"name": "since"
|
|
178
|
+
}
|
|
179
|
+
],
|
|
90
180
|
"methods": [],
|
|
91
181
|
"properties": [
|
|
92
182
|
{
|
|
@@ -157,8 +247,13 @@
|
|
|
157
247
|
{
|
|
158
248
|
"name": "UsageStatsOptions",
|
|
159
249
|
"slug": "usagestatsoptions",
|
|
160
|
-
"docs": "",
|
|
161
|
-
"tags": [
|
|
250
|
+
"docs": "Options for querying usage statistics.",
|
|
251
|
+
"tags": [
|
|
252
|
+
{
|
|
253
|
+
"text": "1.0.0",
|
|
254
|
+
"name": "since"
|
|
255
|
+
}
|
|
256
|
+
],
|
|
162
257
|
"methods": [],
|
|
163
258
|
"properties": [
|
|
164
259
|
{
|
|
@@ -180,8 +275,13 @@
|
|
|
180
275
|
{
|
|
181
276
|
"name": "UsageStatsPermissionResult",
|
|
182
277
|
"slug": "usagestatspermissionresult",
|
|
183
|
-
"docs": "",
|
|
184
|
-
"tags": [
|
|
278
|
+
"docs": "Result of a usage stats permission check.",
|
|
279
|
+
"tags": [
|
|
280
|
+
{
|
|
281
|
+
"text": "1.0.0",
|
|
282
|
+
"name": "since"
|
|
283
|
+
}
|
|
284
|
+
],
|
|
185
285
|
"methods": [],
|
|
186
286
|
"properties": [
|
|
187
287
|
{
|
|
@@ -197,68 +297,53 @@
|
|
|
197
297
|
"name": "PackageInfo",
|
|
198
298
|
"slug": "packageinfo",
|
|
199
299
|
"docs": "Represents basic information about an installed package.",
|
|
200
|
-
"tags": [
|
|
201
|
-
"methods": [
|
|
300
|
+
"tags": [
|
|
202
301
|
{
|
|
203
|
-
"
|
|
204
|
-
"
|
|
205
|
-
"parameters": [],
|
|
206
|
-
"returns": "Promise<{ version: string; }>",
|
|
207
|
-
"tags": [
|
|
208
|
-
{
|
|
209
|
-
"name": "returns",
|
|
210
|
-
"text": "an Promise with version for this device"
|
|
211
|
-
},
|
|
212
|
-
{
|
|
213
|
-
"name": "throws",
|
|
214
|
-
"text": "An error if the something went wrong"
|
|
215
|
-
}
|
|
216
|
-
],
|
|
217
|
-
"docs": "Get the native Capacitor plugin version",
|
|
218
|
-
"complexTypes": [],
|
|
219
|
-
"slug": "getpluginversion"
|
|
302
|
+
"text": "1.0.0",
|
|
303
|
+
"name": "since"
|
|
220
304
|
}
|
|
221
305
|
],
|
|
306
|
+
"methods": [],
|
|
222
307
|
"properties": [
|
|
223
308
|
{
|
|
224
309
|
"name": "packageName",
|
|
225
310
|
"tags": [],
|
|
226
|
-
"docs": "",
|
|
311
|
+
"docs": "Package name",
|
|
227
312
|
"complexTypes": [],
|
|
228
313
|
"type": "string"
|
|
229
314
|
},
|
|
230
315
|
{
|
|
231
316
|
"name": "appName",
|
|
232
317
|
"tags": [],
|
|
233
|
-
"docs": "",
|
|
318
|
+
"docs": "App display name",
|
|
234
319
|
"complexTypes": [],
|
|
235
320
|
"type": "string"
|
|
236
321
|
},
|
|
237
322
|
{
|
|
238
323
|
"name": "versionName",
|
|
239
324
|
"tags": [],
|
|
240
|
-
"docs": "",
|
|
325
|
+
"docs": "Version name string",
|
|
241
326
|
"complexTypes": [],
|
|
242
327
|
"type": "string"
|
|
243
328
|
},
|
|
244
329
|
{
|
|
245
330
|
"name": "versionCode",
|
|
246
331
|
"tags": [],
|
|
247
|
-
"docs": "",
|
|
332
|
+
"docs": "Version code number",
|
|
248
333
|
"complexTypes": [],
|
|
249
334
|
"type": "number"
|
|
250
335
|
},
|
|
251
336
|
{
|
|
252
337
|
"name": "firstInstallTime",
|
|
253
338
|
"tags": [],
|
|
254
|
-
"docs": "",
|
|
339
|
+
"docs": "First install time in milliseconds since epoch",
|
|
255
340
|
"complexTypes": [],
|
|
256
341
|
"type": "number"
|
|
257
342
|
},
|
|
258
343
|
{
|
|
259
344
|
"name": "lastUpdateTime",
|
|
260
345
|
"tags": [],
|
|
261
|
-
"docs": "",
|
|
346
|
+
"docs": "Last update time in milliseconds since epoch",
|
|
262
347
|
"complexTypes": [],
|
|
263
348
|
"type": "number"
|
|
264
349
|
}
|
|
@@ -1,4 +1,9 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Usage statistics for an Android app.
|
|
3
|
+
*
|
|
4
|
+
* @since 1.0.0
|
|
5
|
+
*/
|
|
6
|
+
export interface UsageStats {
|
|
2
7
|
/**
|
|
3
8
|
* The first timestamp of the usage stats.
|
|
4
9
|
*/
|
|
@@ -40,7 +45,12 @@ interface UsageStats {
|
|
|
40
45
|
*/
|
|
41
46
|
totalTimeVisible?: number;
|
|
42
47
|
}
|
|
43
|
-
|
|
48
|
+
/**
|
|
49
|
+
* Options for querying usage statistics.
|
|
50
|
+
*
|
|
51
|
+
* @since 1.0.0
|
|
52
|
+
*/
|
|
53
|
+
export interface UsageStatsOptions {
|
|
44
54
|
/**
|
|
45
55
|
* The inclusive beginning of the range of stats to include in the results.
|
|
46
56
|
* Defined in terms of "Unix time"
|
|
@@ -52,76 +62,153 @@ interface UsageStatsOptions {
|
|
|
52
62
|
*/
|
|
53
63
|
endTime: number;
|
|
54
64
|
}
|
|
55
|
-
|
|
65
|
+
/**
|
|
66
|
+
* Result of a usage stats permission check.
|
|
67
|
+
*
|
|
68
|
+
* @since 1.0.0
|
|
69
|
+
*/
|
|
70
|
+
export interface UsageStatsPermissionResult {
|
|
56
71
|
/**
|
|
57
72
|
* Whether the usage stats permission is granted.
|
|
58
73
|
*/
|
|
59
74
|
granted: boolean;
|
|
60
75
|
}
|
|
76
|
+
/**
|
|
77
|
+
* Capacitor plugin for accessing Android UsageStatsManager API.
|
|
78
|
+
*
|
|
79
|
+
* @since 1.0.0
|
|
80
|
+
*/
|
|
61
81
|
export interface CapacitorUsageStatsManagerPlugin {
|
|
62
82
|
/**
|
|
63
|
-
* Queries and aggregates usage stats for the given
|
|
83
|
+
* Queries and aggregates usage stats for the given time range.
|
|
84
|
+
*
|
|
85
|
+
* @param options - The time range options for the query
|
|
86
|
+
* @returns Promise that resolves to a record of package names and their corresponding usage stats
|
|
87
|
+
* @throws Error if the permission is not granted or query fails
|
|
88
|
+
* @since 1.0.0
|
|
89
|
+
* @example
|
|
90
|
+
* ```typescript
|
|
91
|
+
* const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;
|
|
92
|
+
* const now = Date.now();
|
|
93
|
+
* const stats = await UsageStatsManager.queryAndAggregateUsageStats({
|
|
94
|
+
* beginTime: oneDayAgo,
|
|
95
|
+
* endTime: now
|
|
96
|
+
* });
|
|
64
97
|
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
98
|
+
* for (const [packageName, usageData] of Object.entries(stats)) {
|
|
99
|
+
* console.log(`${packageName}: ${usageData.totalTimeInForeground}ms`);
|
|
100
|
+
* }
|
|
101
|
+
* ```
|
|
67
102
|
*/
|
|
68
103
|
queryAndAggregateUsageStats(options: UsageStatsOptions): Promise<Record<string, UsageStats>>;
|
|
69
104
|
/**
|
|
70
105
|
* Checks if the usage stats permission is granted.
|
|
71
106
|
*
|
|
72
|
-
* @returns
|
|
107
|
+
* @returns Promise that resolves to a permission result object
|
|
108
|
+
* @throws Error if checking permission fails
|
|
109
|
+
* @since 1.0.0
|
|
110
|
+
* @example
|
|
111
|
+
* ```typescript
|
|
112
|
+
* const { granted } = await UsageStatsManager.isUsageStatsPermissionGranted();
|
|
113
|
+
* if (!granted) {
|
|
114
|
+
* await UsageStatsManager.openUsageStatsSettings();
|
|
115
|
+
* }
|
|
116
|
+
* ```
|
|
73
117
|
*/
|
|
74
118
|
isUsageStatsPermissionGranted(): Promise<UsageStatsPermissionResult>;
|
|
75
119
|
/**
|
|
76
120
|
* Open the usage stats settings screen.
|
|
77
121
|
* This will open the usage stats settings screen, which allows the user to grant the usage stats permission.
|
|
78
122
|
* This will always open the settings screen, even if the permission is already granted.
|
|
123
|
+
*
|
|
124
|
+
* @returns Promise that resolves when the settings screen is opened
|
|
125
|
+
* @throws Error if opening settings fails
|
|
126
|
+
* @since 1.0.0
|
|
127
|
+
* @example
|
|
128
|
+
* ```typescript
|
|
129
|
+
* await UsageStatsManager.openUsageStatsSettings();
|
|
130
|
+
* ```
|
|
79
131
|
*/
|
|
80
132
|
openUsageStatsSettings(): Promise<void>;
|
|
81
133
|
/**
|
|
82
134
|
* Queries all installed packages on the device.
|
|
83
135
|
* Requires the QUERY_ALL_PACKAGES permission.
|
|
84
136
|
*
|
|
137
|
+
* @returns Promise that resolves with an array of package information
|
|
138
|
+
* @throws Error if the permission is not granted or query fails
|
|
85
139
|
* @since 1.2.0
|
|
140
|
+
* @example
|
|
141
|
+
* ```typescript
|
|
142
|
+
* const { packages } = await UsageStatsManager.queryAllPackages();
|
|
143
|
+
* packages.forEach(pkg => {
|
|
144
|
+
* console.log(`${pkg.appName} (${pkg.packageName}): v${pkg.versionName}`);
|
|
145
|
+
* });
|
|
146
|
+
* ```
|
|
86
147
|
*/
|
|
87
148
|
queryAllPackages(): Promise<{
|
|
88
149
|
packages: PackageInfo[];
|
|
89
150
|
}>;
|
|
151
|
+
/**
|
|
152
|
+
* Get the native Capacitor plugin version.
|
|
153
|
+
*
|
|
154
|
+
* @returns Promise that resolves with the plugin version
|
|
155
|
+
* @throws Error if getting the version fails
|
|
156
|
+
* @since 1.0.0
|
|
157
|
+
* @example
|
|
158
|
+
* ```typescript
|
|
159
|
+
* const { version } = await UsageStatsManager.getPluginVersion();
|
|
160
|
+
* console.log('Plugin version:', version);
|
|
161
|
+
* ```
|
|
162
|
+
*/
|
|
163
|
+
getPluginVersion(): Promise<{
|
|
164
|
+
version: string;
|
|
165
|
+
}>;
|
|
90
166
|
}
|
|
91
167
|
/**
|
|
92
168
|
* Represents a single usage event.
|
|
169
|
+
*
|
|
170
|
+
* @since 1.0.0
|
|
93
171
|
*/
|
|
94
172
|
export interface UsageEvent {
|
|
173
|
+
/** Package name of the app */
|
|
95
174
|
packageName: string;
|
|
175
|
+
/** Class name (might be null) */
|
|
96
176
|
className?: string;
|
|
177
|
+
/** Timestamp in milliseconds since epoch */
|
|
97
178
|
timeStamp: number;
|
|
179
|
+
/** Event type constant (e.g., MOVE_TO_FOREGROUND, MOVE_TO_BACKGROUND) */
|
|
98
180
|
eventType: number;
|
|
181
|
+
/** Configuration object (requires API 28+) */
|
|
99
182
|
configuration?: any;
|
|
183
|
+
/** Shortcut ID (requires API 28+) */
|
|
100
184
|
shortcutId?: string;
|
|
185
|
+
/** App standby bucket (requires API 28+) */
|
|
101
186
|
standbyBucket?: number;
|
|
187
|
+
/** Notification channel ID (requires API 29+) */
|
|
102
188
|
notificationChannelId?: string;
|
|
189
|
+
/** Instance ID (requires API 30+) */
|
|
103
190
|
instanceId?: number;
|
|
191
|
+
/** Task root package name (requires API 31+) */
|
|
104
192
|
taskRootPackageName?: string;
|
|
193
|
+
/** Task root class name (requires API 31+) */
|
|
105
194
|
taskRootClassName?: string;
|
|
106
195
|
}
|
|
107
196
|
/**
|
|
108
197
|
* Represents basic information about an installed package.
|
|
198
|
+
*
|
|
199
|
+
* @since 1.0.0
|
|
109
200
|
*/
|
|
110
201
|
export interface PackageInfo {
|
|
202
|
+
/** Package name */
|
|
111
203
|
packageName: string;
|
|
204
|
+
/** App display name */
|
|
112
205
|
appName: string;
|
|
206
|
+
/** Version name string */
|
|
113
207
|
versionName: string;
|
|
208
|
+
/** Version code number */
|
|
114
209
|
versionCode: number;
|
|
210
|
+
/** First install time in milliseconds since epoch */
|
|
115
211
|
firstInstallTime: number;
|
|
212
|
+
/** Last update time in milliseconds since epoch */
|
|
116
213
|
lastUpdateTime: number;
|
|
117
|
-
/**
|
|
118
|
-
* Get the native Capacitor plugin version
|
|
119
|
-
*
|
|
120
|
-
* @returns {Promise<{ id: string }>} an Promise with version for this device
|
|
121
|
-
* @throws An error if the something went wrong
|
|
122
|
-
*/
|
|
123
|
-
getPluginVersion(): Promise<{
|
|
124
|
-
version: string;
|
|
125
|
-
}>;
|
|
126
214
|
}
|
|
127
|
-
export {};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["interface UsageStats {\n /**\n * The first timestamp of the usage stats.\n */\n firstTimeStamp: number;\n /**\n * The last timestamp of the usage stats.\n */\n lastTimeStamp: number;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n lastTimeForegroundServiceUsed?: number;\n /**\n * The last time the app was used.\n */\n lastTimeUsed: number;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n lastTimeVisible?: number;\n /**\n * The name of the package.\n */\n packageName: string;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n totalForegroundServiceUsed?: number;\n /**\n * The total time the app was in the foreground.\n */\n totalTimeInForeground: number;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n totalTimeVisible?: number;\n}\n\
|
|
1
|
+
{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Usage statistics for an Android app.\n *\n * @since 1.0.0\n */\nexport interface UsageStats {\n /**\n * The first timestamp of the usage stats.\n */\n firstTimeStamp: number;\n /**\n * The last timestamp of the usage stats.\n */\n lastTimeStamp: number;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n lastTimeForegroundServiceUsed?: number;\n /**\n * The last time the app was used.\n */\n lastTimeUsed: number;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n lastTimeVisible?: number;\n /**\n * The name of the package.\n */\n packageName: string;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n totalForegroundServiceUsed?: number;\n /**\n * The total time the app was in the foreground.\n */\n totalTimeInForeground: number;\n /**\n * Only available on Android Q (API level 29) and above.\n * Will be undefined on lower Android versions.\n */\n totalTimeVisible?: number;\n}\n\n/**\n * Options for querying usage statistics.\n *\n * @since 1.0.0\n */\nexport interface UsageStatsOptions {\n /**\n * The inclusive beginning of the range of stats to include in the results.\n * Defined in terms of \"Unix time\"\n */\n beginTime: number;\n\n /**\n * The exclusive end of the range of stats to include in the results.\n * Defined in terms of \"Unix time\"\n */\n endTime: number;\n}\n\n/**\n * Result of a usage stats permission check.\n *\n * @since 1.0.0\n */\nexport interface UsageStatsPermissionResult {\n /**\n * Whether the usage stats permission is granted.\n */\n granted: boolean;\n}\n\n/**\n * Capacitor plugin for accessing Android UsageStatsManager API.\n *\n * @since 1.0.0\n */\nexport interface CapacitorUsageStatsManagerPlugin {\n /**\n * Queries and aggregates usage stats for the given time range.\n *\n * @param options - The time range options for the query\n * @returns Promise that resolves to a record of package names and their corresponding usage stats\n * @throws Error if the permission is not granted or query fails\n * @since 1.0.0\n * @example\n * ```typescript\n * const oneDayAgo = Date.now() - 24 * 60 * 60 * 1000;\n * const now = Date.now();\n * const stats = await UsageStatsManager.queryAndAggregateUsageStats({\n * beginTime: oneDayAgo,\n * endTime: now\n * });\n *\n * for (const [packageName, usageData] of Object.entries(stats)) {\n * console.log(`${packageName}: ${usageData.totalTimeInForeground}ms`);\n * }\n * ```\n */\n queryAndAggregateUsageStats(options: UsageStatsOptions): Promise<Record<string, UsageStats>>;\n\n /**\n * Checks if the usage stats permission is granted.\n *\n * @returns Promise that resolves to a permission result object\n * @throws Error if checking permission fails\n * @since 1.0.0\n * @example\n * ```typescript\n * const { granted } = await UsageStatsManager.isUsageStatsPermissionGranted();\n * if (!granted) {\n * await UsageStatsManager.openUsageStatsSettings();\n * }\n * ```\n */\n isUsageStatsPermissionGranted(): Promise<UsageStatsPermissionResult>;\n\n /**\n * Open the usage stats settings screen.\n * This will open the usage stats settings screen, which allows the user to grant the usage stats permission.\n * This will always open the settings screen, even if the permission is already granted.\n *\n * @returns Promise that resolves when the settings screen is opened\n * @throws Error if opening settings fails\n * @since 1.0.0\n * @example\n * ```typescript\n * await UsageStatsManager.openUsageStatsSettings();\n * ```\n */\n openUsageStatsSettings(): Promise<void>;\n\n /**\n * Queries all installed packages on the device.\n * Requires the QUERY_ALL_PACKAGES permission.\n *\n * @returns Promise that resolves with an array of package information\n * @throws Error if the permission is not granted or query fails\n * @since 1.2.0\n * @example\n * ```typescript\n * const { packages } = await UsageStatsManager.queryAllPackages();\n * packages.forEach(pkg => {\n * console.log(`${pkg.appName} (${pkg.packageName}): v${pkg.versionName}`);\n * });\n * ```\n */\n queryAllPackages(): Promise<{ packages: PackageInfo[] }>;\n\n /**\n * Get the native Capacitor plugin version.\n *\n * @returns Promise that resolves with the plugin version\n * @throws Error if getting the version fails\n * @since 1.0.0\n * @example\n * ```typescript\n * const { version } = await UsageStatsManager.getPluginVersion();\n * console.log('Plugin version:', version);\n * ```\n */\n getPluginVersion(): Promise<{ version: string }>;\n}\n\n/**\n * Represents a single usage event.\n *\n * @since 1.0.0\n */\nexport interface UsageEvent {\n /** Package name of the app */\n packageName: string;\n /** Class name (might be null) */\n className?: string;\n /** Timestamp in milliseconds since epoch */\n timeStamp: number;\n /** Event type constant (e.g., MOVE_TO_FOREGROUND, MOVE_TO_BACKGROUND) */\n eventType: number;\n /** Configuration object (requires API 28+) */\n configuration?: any;\n /** Shortcut ID (requires API 28+) */\n shortcutId?: string;\n /** App standby bucket (requires API 28+) */\n standbyBucket?: number;\n /** Notification channel ID (requires API 29+) */\n notificationChannelId?: string;\n /** Instance ID (requires API 30+) */\n instanceId?: number;\n /** Task root package name (requires API 31+) */\n taskRootPackageName?: string;\n /** Task root class name (requires API 31+) */\n taskRootClassName?: string;\n}\n\n/**\n * Represents basic information about an installed package.\n *\n * @since 1.0.0\n */\nexport interface PackageInfo {\n /** Package name */\n packageName: string;\n /** App display name */\n appName: string;\n /** Version name string */\n versionName: string;\n /** Version code number */\n versionCode: number;\n /** First install time in milliseconds since epoch */\n firstInstallTime: number;\n /** Last update time in milliseconds since epoch */\n lastUpdateTime: number;\n}\n"]}
|
|
@@ -7,7 +7,7 @@ import Capacitor
|
|
|
7
7
|
*/
|
|
8
8
|
@objc(CapacitorUsageStatsManagerPlugin)
|
|
9
9
|
public class CapacitorUsageStatsManagerPlugin: CAPPlugin, CAPBridgedPlugin {
|
|
10
|
-
private let PLUGIN_VERSION: String = "7.
|
|
10
|
+
private let PLUGIN_VERSION: String = "7.2.0"
|
|
11
11
|
public let identifier = "CapacitorUsageStatsManagerPlugin"
|
|
12
12
|
public let jsName = "CapacitorUsageStatsManager"
|
|
13
13
|
public let pluginMethods: [CAPPluginMethod] = [
|
package/package.json
CHANGED