@capgo/capacitor-android-usagestatsmanager 8.1.2 → 8.2.1
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 +159 -4
- package/android/src/main/java/ee/forgr/capacitor_android_usagestatsmanager/CapacitorUsageStatsManagerPlugin.java +209 -4
- package/dist/docs.json +308 -2
- package/dist/esm/definitions.d.ts +197 -4
- package/dist/esm/definitions.js.map +1 -1
- package/dist/esm/web.d.ts +21 -1
- package/dist/esm/web.js +24 -0
- package/dist/esm/web.js.map +1 -1
- package/dist/plugin.cjs.js +24 -0
- package/dist/plugin.cjs.js.map +1 -1
- package/dist/plugin.js +24 -0
- package/dist/plugin.js.map +1 -1
- package/ios/Sources/CapacitorUsageStatsManagerPlugin/CapacitorUsageStatsManagerPlugin.swift +26 -1
- package/package.json +1 -1
package/dist/docs.json
CHANGED
|
@@ -40,10 +40,10 @@
|
|
|
40
40
|
},
|
|
41
41
|
{
|
|
42
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
|
|
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 packageName: 'com.example.app',\n});\n\nfor (const [packageName, usageData] of Object.entries(stats)) {\n console.log(`${packageName}: ${usageData.totalTimeInForeground}ms`);\n}\n```"
|
|
44
44
|
}
|
|
45
45
|
],
|
|
46
|
-
"docs": "Queries and aggregates usage stats for the given time range.",
|
|
46
|
+
"docs": "Queries and aggregates usage stats for the given time range.\n\nAndroid reads pre-aggregated daily/weekly/monthly/yearly buckets and sums\nevery bucket that intersects `[beginTime, endTime)`, without clipping to it.\n`totalTimeInForeground` can therefore include usage from outside the window.\nUse `queryUsageStats` for the unmerged per-interval buckets, or `queryEvents`\nfor timestamped lifecycle events in the requested range.",
|
|
47
47
|
"complexTypes": [
|
|
48
48
|
"Record",
|
|
49
49
|
"UsageStats",
|
|
@@ -51,6 +51,86 @@
|
|
|
51
51
|
],
|
|
52
52
|
"slug": "queryandaggregateusagestats"
|
|
53
53
|
},
|
|
54
|
+
{
|
|
55
|
+
"name": "queryUsageStats",
|
|
56
|
+
"signature": "(options: QueryUsageStatsOptions) => Promise<QueryUsageStatsResult>",
|
|
57
|
+
"parameters": [
|
|
58
|
+
{
|
|
59
|
+
"name": "options",
|
|
60
|
+
"docs": "- The interval type, time range, and optional package filter",
|
|
61
|
+
"type": "QueryUsageStatsOptions"
|
|
62
|
+
}
|
|
63
|
+
],
|
|
64
|
+
"returns": "Promise<QueryUsageStatsResult>",
|
|
65
|
+
"tags": [
|
|
66
|
+
{
|
|
67
|
+
"name": "param",
|
|
68
|
+
"text": "options - The interval type, time range, and optional package filter"
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"name": "returns",
|
|
72
|
+
"text": "Promise that resolves to the matching usage stats buckets"
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
"name": "throws",
|
|
76
|
+
"text": "Error if the permission is not granted or query fails"
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
"name": "since",
|
|
80
|
+
"text": "8.1.3"
|
|
81
|
+
},
|
|
82
|
+
{
|
|
83
|
+
"name": "example",
|
|
84
|
+
"text": "```typescript\nconst startOfDay = new Date().setHours(0, 0, 0, 0);\nconst { stats } = await UsageStatsManager.queryUsageStats({\n intervalType: 0, // INTERVAL_DAILY\n beginTime: startOfDay,\n endTime: Date.now(),\n packageName: 'com.example.app',\n});\nstats.forEach((bucket) => {\n console.log(`${bucket.packageName}: ${bucket.totalTimeInForeground}ms`);\n});\n```"
|
|
85
|
+
}
|
|
86
|
+
],
|
|
87
|
+
"docs": "Queries usage stats for the given interval type and time range.\n\nWraps Android `UsageStatsManager.queryUsageStats`. Unlike\n`queryAndAggregateUsageStats`, this does not merge buckets: the result is\none `UsageStats` object per package per overlapping interval. Android may\nexpand `[beginTime, endTime)` to the nearest whole interval period, so\n`totalTimeInForeground` can include usage from outside the window.\n\nOn Android R (API 30) and above, the OS returns no data while the user is\nlocked; this plugin then resolves `{ stats: [] }`, which must not be treated\nas zero foreground usage.\n\nThis uses the same `PACKAGE_USAGE_STATS` permission as\n`queryAndAggregateUsageStats`.",
|
|
88
|
+
"complexTypes": [
|
|
89
|
+
"QueryUsageStatsResult",
|
|
90
|
+
"QueryUsageStatsOptions"
|
|
91
|
+
],
|
|
92
|
+
"slug": "queryusagestats"
|
|
93
|
+
},
|
|
94
|
+
{
|
|
95
|
+
"name": "queryEvents",
|
|
96
|
+
"signature": "(options: QueryEventsOptions) => Promise<QueryEventsResult>",
|
|
97
|
+
"parameters": [
|
|
98
|
+
{
|
|
99
|
+
"name": "options",
|
|
100
|
+
"docs": "- The time range and optional package filter",
|
|
101
|
+
"type": "QueryEventsOptions"
|
|
102
|
+
}
|
|
103
|
+
],
|
|
104
|
+
"returns": "Promise<QueryEventsResult>",
|
|
105
|
+
"tags": [
|
|
106
|
+
{
|
|
107
|
+
"name": "param",
|
|
108
|
+
"text": "options - The time range and optional package filter"
|
|
109
|
+
},
|
|
110
|
+
{
|
|
111
|
+
"name": "returns",
|
|
112
|
+
"text": "Promise that resolves to the matching usage events"
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
"name": "throws",
|
|
116
|
+
"text": "Error if the permission is not granted or query fails"
|
|
117
|
+
},
|
|
118
|
+
{
|
|
119
|
+
"name": "since",
|
|
120
|
+
"text": "8.1.3"
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
"name": "example",
|
|
124
|
+
"text": "```typescript\nconst startOfDay = new Date().setHours(0, 0, 0, 0);\nconst { events } = await UsageStatsManager.queryEvents({\n beginTime: startOfDay,\n endTime: Date.now(),\n packageName: 'com.example.app',\n});\nevents.forEach((event) => {\n console.log(`${event.packageName} type=${event.eventType} at ${event.timeStamp}`);\n});\n```"
|
|
125
|
+
}
|
|
126
|
+
],
|
|
127
|
+
"docs": "Queries the raw usage event log for the given time range.\n\nReturns lifecycle events whose timestamps fall in `[beginTime, endTime)`.\nAndroid does not emit a synthetic event for \"already in foreground at\nbeginTime\" or \"still in foreground at endTime\". To measure duration across\nthose boundaries, pass an earlier `beginTime` as lookback and clip locally:\ntreat an unmatched pause as starting at the window start, and an unmatched\nresume as ending at the window end.\n\nAndroid retains events for only a few days. Older ranges may return an\nincomplete or empty list; that is not the same as zero foreground usage.\nOn Android R (API 30) and above, the OS also returns no events while the\nuser is locked; this plugin then resolves `{ events: [] }`, which likewise\nmust not be treated as zero foreground usage.\n\nCallers can sum resumed-to-paused intervals from the returned events.\nDo not treat `DEVICE_SHUTDOWN` as a pause: it is a reset marker, not an\ninterval close. This uses the same `PACKAGE_USAGE_STATS` permission as\n`queryAndAggregateUsageStats`.\n\nOnly lifecycle events are returned, to keep the bridge payload small:\n- `1` — ACTIVITY_RESUMED / MOVE_TO_FOREGROUND\n- `2` — ACTIVITY_PAUSED / MOVE_TO_BACKGROUND\n- `23` — ACTIVITY_STOPPED\n- `26` — DEVICE_SHUTDOWN (device-wide reset marker; still returned when\n `packageName` is set. Android typically reports package `\"android\"`.\n `packageName` is omitted if the OS does not attach one. The timestamp\n is the last UsageStats persist before shutdown, not the actual\n power-off. Open resume events without a matching pause between this\n marker and the next boot have unknown duration and must be ignored.)",
|
|
128
|
+
"complexTypes": [
|
|
129
|
+
"QueryEventsResult",
|
|
130
|
+
"QueryEventsOptions"
|
|
131
|
+
],
|
|
132
|
+
"slug": "queryevents"
|
|
133
|
+
},
|
|
54
134
|
{
|
|
55
135
|
"name": "isUsageStatsPermissionGranted",
|
|
56
136
|
"signature": "() => Promise<UsageStatsPermissionResult>",
|
|
@@ -280,6 +360,232 @@
|
|
|
280
360
|
"docs": "The exclusive end of the range of stats to include in the results.\nDefined in terms of \"Unix time\"",
|
|
281
361
|
"complexTypes": [],
|
|
282
362
|
"type": "number"
|
|
363
|
+
},
|
|
364
|
+
{
|
|
365
|
+
"name": "packageName",
|
|
366
|
+
"tags": [
|
|
367
|
+
{
|
|
368
|
+
"text": "8.1.3",
|
|
369
|
+
"name": "since"
|
|
370
|
+
}
|
|
371
|
+
],
|
|
372
|
+
"docs": "Optional package name. When set, only stats for this package are returned.\nOmit to return stats for every package (previous behavior).\nAn empty string is rejected.",
|
|
373
|
+
"complexTypes": [],
|
|
374
|
+
"type": "string | undefined"
|
|
375
|
+
}
|
|
376
|
+
]
|
|
377
|
+
},
|
|
378
|
+
{
|
|
379
|
+
"name": "QueryUsageStatsResult",
|
|
380
|
+
"slug": "queryusagestatsresult",
|
|
381
|
+
"docs": "Result of a `queryUsageStats` call.",
|
|
382
|
+
"tags": [
|
|
383
|
+
{
|
|
384
|
+
"text": "8.1.3",
|
|
385
|
+
"name": "since"
|
|
386
|
+
}
|
|
387
|
+
],
|
|
388
|
+
"methods": [],
|
|
389
|
+
"properties": [
|
|
390
|
+
{
|
|
391
|
+
"name": "stats",
|
|
392
|
+
"tags": [],
|
|
393
|
+
"docs": "Usage stats buckets in the requested range, ordered as returned by the OS.\nThe same package can appear more than once when multiple intervals overlap.",
|
|
394
|
+
"complexTypes": [
|
|
395
|
+
"UsageStats"
|
|
396
|
+
],
|
|
397
|
+
"type": "UsageStats[]"
|
|
398
|
+
}
|
|
399
|
+
]
|
|
400
|
+
},
|
|
401
|
+
{
|
|
402
|
+
"name": "QueryUsageStatsOptions",
|
|
403
|
+
"slug": "queryusagestatsoptions",
|
|
404
|
+
"docs": "Options for querying per-interval usage statistics.",
|
|
405
|
+
"tags": [
|
|
406
|
+
{
|
|
407
|
+
"text": "8.1.3",
|
|
408
|
+
"name": "since"
|
|
409
|
+
}
|
|
410
|
+
],
|
|
411
|
+
"methods": [],
|
|
412
|
+
"properties": [
|
|
413
|
+
{
|
|
414
|
+
"name": "intervalType",
|
|
415
|
+
"tags": [],
|
|
416
|
+
"docs": "Interval type from `android.app.usage.UsageStatsManager`:\n- `0` — INTERVAL_DAILY\n- `1` — INTERVAL_WEEKLY\n- `2` — INTERVAL_MONTHLY\n- `3` — INTERVAL_YEARLY\n- `4` — INTERVAL_BEST",
|
|
417
|
+
"complexTypes": [],
|
|
418
|
+
"type": "number"
|
|
419
|
+
},
|
|
420
|
+
{
|
|
421
|
+
"name": "beginTime",
|
|
422
|
+
"tags": [],
|
|
423
|
+
"docs": "The inclusive beginning of the range of stats to include in the results.\nDefined in terms of \"Unix time\"",
|
|
424
|
+
"complexTypes": [],
|
|
425
|
+
"type": "number"
|
|
426
|
+
},
|
|
427
|
+
{
|
|
428
|
+
"name": "endTime",
|
|
429
|
+
"tags": [],
|
|
430
|
+
"docs": "The exclusive end of the range of stats to include in the results.\nDefined in terms of \"Unix time\"",
|
|
431
|
+
"complexTypes": [],
|
|
432
|
+
"type": "number"
|
|
433
|
+
},
|
|
434
|
+
{
|
|
435
|
+
"name": "packageName",
|
|
436
|
+
"tags": [],
|
|
437
|
+
"docs": "Optional package name. When set, only stats for this package are returned.\nAn empty string is rejected.",
|
|
438
|
+
"complexTypes": [],
|
|
439
|
+
"type": "string | undefined"
|
|
440
|
+
}
|
|
441
|
+
]
|
|
442
|
+
},
|
|
443
|
+
{
|
|
444
|
+
"name": "QueryEventsResult",
|
|
445
|
+
"slug": "queryeventsresult",
|
|
446
|
+
"docs": "Result of a `queryEvents` call.",
|
|
447
|
+
"tags": [
|
|
448
|
+
{
|
|
449
|
+
"text": "8.1.3",
|
|
450
|
+
"name": "since"
|
|
451
|
+
}
|
|
452
|
+
],
|
|
453
|
+
"methods": [],
|
|
454
|
+
"properties": [
|
|
455
|
+
{
|
|
456
|
+
"name": "events",
|
|
457
|
+
"tags": [],
|
|
458
|
+
"docs": "Lifecycle usage events in the requested range, ordered as returned by the OS.",
|
|
459
|
+
"complexTypes": [
|
|
460
|
+
"UsageEvent"
|
|
461
|
+
],
|
|
462
|
+
"type": "UsageEvent[]"
|
|
463
|
+
}
|
|
464
|
+
]
|
|
465
|
+
},
|
|
466
|
+
{
|
|
467
|
+
"name": "UsageEvent",
|
|
468
|
+
"slug": "usageevent",
|
|
469
|
+
"docs": "Represents a single usage event.\n\n`queryEvents` currently populates `className`, `timeStamp`, and `eventType`.\n`packageName` is set when Android attaches one (DEVICE_SHUTDOWN usually uses\n`\"android\"`) and omitted otherwise. Other fields remain optional for\ncompatibility.",
|
|
470
|
+
"tags": [
|
|
471
|
+
{
|
|
472
|
+
"text": "1.0.0",
|
|
473
|
+
"name": "since"
|
|
474
|
+
}
|
|
475
|
+
],
|
|
476
|
+
"methods": [],
|
|
477
|
+
"properties": [
|
|
478
|
+
{
|
|
479
|
+
"name": "packageName",
|
|
480
|
+
"tags": [],
|
|
481
|
+
"docs": "Package name of the app.\nOmitted when Android does not attach a package. DEVICE_SHUTDOWN typically\nuses `\"android\"`.",
|
|
482
|
+
"complexTypes": [],
|
|
483
|
+
"type": "string | undefined"
|
|
484
|
+
},
|
|
485
|
+
{
|
|
486
|
+
"name": "className",
|
|
487
|
+
"tags": [],
|
|
488
|
+
"docs": "Class name (might be null)",
|
|
489
|
+
"complexTypes": [],
|
|
490
|
+
"type": "string | undefined"
|
|
491
|
+
},
|
|
492
|
+
{
|
|
493
|
+
"name": "timeStamp",
|
|
494
|
+
"tags": [],
|
|
495
|
+
"docs": "Timestamp in milliseconds since epoch",
|
|
496
|
+
"complexTypes": [],
|
|
497
|
+
"type": "number"
|
|
498
|
+
},
|
|
499
|
+
{
|
|
500
|
+
"name": "eventType",
|
|
501
|
+
"tags": [],
|
|
502
|
+
"docs": "Event type constant from `android.app.usage.UsageEvents.Event`.\n`queryEvents` returns lifecycle types only:\n- `1` — ACTIVITY_RESUMED / MOVE_TO_FOREGROUND\n- `2` — ACTIVITY_PAUSED / MOVE_TO_BACKGROUND\n- `23` — ACTIVITY_STOPPED\n- `26` — DEVICE_SHUTDOWN (reset marker, not an interval close)",
|
|
503
|
+
"complexTypes": [],
|
|
504
|
+
"type": "number"
|
|
505
|
+
},
|
|
506
|
+
{
|
|
507
|
+
"name": "configuration",
|
|
508
|
+
"tags": [],
|
|
509
|
+
"docs": "Configuration object (requires API 28+)",
|
|
510
|
+
"complexTypes": [],
|
|
511
|
+
"type": "any"
|
|
512
|
+
},
|
|
513
|
+
{
|
|
514
|
+
"name": "shortcutId",
|
|
515
|
+
"tags": [],
|
|
516
|
+
"docs": "Shortcut ID (requires API 28+)",
|
|
517
|
+
"complexTypes": [],
|
|
518
|
+
"type": "string | undefined"
|
|
519
|
+
},
|
|
520
|
+
{
|
|
521
|
+
"name": "standbyBucket",
|
|
522
|
+
"tags": [],
|
|
523
|
+
"docs": "App standby bucket (requires API 28+)",
|
|
524
|
+
"complexTypes": [],
|
|
525
|
+
"type": "number | undefined"
|
|
526
|
+
},
|
|
527
|
+
{
|
|
528
|
+
"name": "notificationChannelId",
|
|
529
|
+
"tags": [],
|
|
530
|
+
"docs": "Notification channel ID (requires API 29+)",
|
|
531
|
+
"complexTypes": [],
|
|
532
|
+
"type": "string | undefined"
|
|
533
|
+
},
|
|
534
|
+
{
|
|
535
|
+
"name": "instanceId",
|
|
536
|
+
"tags": [],
|
|
537
|
+
"docs": "Instance ID (requires API 30+)",
|
|
538
|
+
"complexTypes": [],
|
|
539
|
+
"type": "number | undefined"
|
|
540
|
+
},
|
|
541
|
+
{
|
|
542
|
+
"name": "taskRootPackageName",
|
|
543
|
+
"tags": [],
|
|
544
|
+
"docs": "Task root package name (requires API 31+)",
|
|
545
|
+
"complexTypes": [],
|
|
546
|
+
"type": "string | undefined"
|
|
547
|
+
},
|
|
548
|
+
{
|
|
549
|
+
"name": "taskRootClassName",
|
|
550
|
+
"tags": [],
|
|
551
|
+
"docs": "Task root class name (requires API 31+)",
|
|
552
|
+
"complexTypes": [],
|
|
553
|
+
"type": "string | undefined"
|
|
554
|
+
}
|
|
555
|
+
]
|
|
556
|
+
},
|
|
557
|
+
{
|
|
558
|
+
"name": "QueryEventsOptions",
|
|
559
|
+
"slug": "queryeventsoptions",
|
|
560
|
+
"docs": "Options for querying the raw usage event log.",
|
|
561
|
+
"tags": [
|
|
562
|
+
{
|
|
563
|
+
"text": "8.1.3",
|
|
564
|
+
"name": "since"
|
|
565
|
+
}
|
|
566
|
+
],
|
|
567
|
+
"methods": [],
|
|
568
|
+
"properties": [
|
|
569
|
+
{
|
|
570
|
+
"name": "beginTime",
|
|
571
|
+
"tags": [],
|
|
572
|
+
"docs": "The inclusive beginning of the range of events to include in the results.\nDefined in terms of \"Unix time\"",
|
|
573
|
+
"complexTypes": [],
|
|
574
|
+
"type": "number"
|
|
575
|
+
},
|
|
576
|
+
{
|
|
577
|
+
"name": "endTime",
|
|
578
|
+
"tags": [],
|
|
579
|
+
"docs": "The exclusive end of the range of events to include in the results.\nDefined in terms of \"Unix time\"",
|
|
580
|
+
"complexTypes": [],
|
|
581
|
+
"type": "number"
|
|
582
|
+
},
|
|
583
|
+
{
|
|
584
|
+
"name": "packageName",
|
|
585
|
+
"tags": [],
|
|
586
|
+
"docs": "Optional package name. When set, only events for this package are returned,\nplus device-wide `DEVICE_SHUTDOWN` events. An empty string is rejected.\nKeeps the Capacitor bridge payload small when you care about one app.",
|
|
587
|
+
"complexTypes": [],
|
|
588
|
+
"type": "string | undefined"
|
|
283
589
|
}
|
|
284
590
|
]
|
|
285
591
|
},
|
|
@@ -61,6 +61,14 @@ export interface UsageStatsOptions {
|
|
|
61
61
|
* Defined in terms of "Unix time"
|
|
62
62
|
*/
|
|
63
63
|
endTime: number;
|
|
64
|
+
/**
|
|
65
|
+
* Optional package name. When set, only stats for this package are returned.
|
|
66
|
+
* Omit to return stats for every package (previous behavior).
|
|
67
|
+
* An empty string is rejected.
|
|
68
|
+
*
|
|
69
|
+
* @since 8.1.3
|
|
70
|
+
*/
|
|
71
|
+
packageName?: string;
|
|
64
72
|
}
|
|
65
73
|
/**
|
|
66
74
|
* Result of a usage stats permission check.
|
|
@@ -82,6 +90,12 @@ export interface CapacitorUsageStatsManagerPlugin {
|
|
|
82
90
|
/**
|
|
83
91
|
* Queries and aggregates usage stats for the given time range.
|
|
84
92
|
*
|
|
93
|
+
* Android reads pre-aggregated daily/weekly/monthly/yearly buckets and sums
|
|
94
|
+
* every bucket that intersects `[beginTime, endTime)`, without clipping to it.
|
|
95
|
+
* `totalTimeInForeground` can therefore include usage from outside the window.
|
|
96
|
+
* Use `queryUsageStats` for the unmerged per-interval buckets, or `queryEvents`
|
|
97
|
+
* for timestamped lifecycle events in the requested range.
|
|
98
|
+
*
|
|
85
99
|
* @param options - The time range options for the query
|
|
86
100
|
* @returns Promise that resolves to a record of package names and their corresponding usage stats
|
|
87
101
|
* @throws Error if the permission is not granted or query fails
|
|
@@ -92,7 +106,8 @@ export interface CapacitorUsageStatsManagerPlugin {
|
|
|
92
106
|
* const now = Date.now();
|
|
93
107
|
* const stats = await UsageStatsManager.queryAndAggregateUsageStats({
|
|
94
108
|
* beginTime: oneDayAgo,
|
|
95
|
-
* endTime: now
|
|
109
|
+
* endTime: now,
|
|
110
|
+
* packageName: 'com.example.app',
|
|
96
111
|
* });
|
|
97
112
|
*
|
|
98
113
|
* for (const [packageName, usageData] of Object.entries(stats)) {
|
|
@@ -101,6 +116,91 @@ export interface CapacitorUsageStatsManagerPlugin {
|
|
|
101
116
|
* ```
|
|
102
117
|
*/
|
|
103
118
|
queryAndAggregateUsageStats(options: UsageStatsOptions): Promise<Record<string, UsageStats>>;
|
|
119
|
+
/**
|
|
120
|
+
* Queries usage stats for the given interval type and time range.
|
|
121
|
+
*
|
|
122
|
+
* Wraps Android `UsageStatsManager.queryUsageStats`. Unlike
|
|
123
|
+
* `queryAndAggregateUsageStats`, this does not merge buckets: the result is
|
|
124
|
+
* one `UsageStats` object per package per overlapping interval. Android may
|
|
125
|
+
* expand `[beginTime, endTime)` to the nearest whole interval period, so
|
|
126
|
+
* `totalTimeInForeground` can include usage from outside the window.
|
|
127
|
+
*
|
|
128
|
+
* On Android R (API 30) and above, the OS returns no data while the user is
|
|
129
|
+
* locked; this plugin then resolves `{ stats: [] }`, which must not be treated
|
|
130
|
+
* as zero foreground usage.
|
|
131
|
+
*
|
|
132
|
+
* This uses the same `PACKAGE_USAGE_STATS` permission as
|
|
133
|
+
* `queryAndAggregateUsageStats`.
|
|
134
|
+
*
|
|
135
|
+
* @param options - The interval type, time range, and optional package filter
|
|
136
|
+
* @returns Promise that resolves to the matching usage stats buckets
|
|
137
|
+
* @throws Error if the permission is not granted or query fails
|
|
138
|
+
* @since 8.1.3
|
|
139
|
+
* @example
|
|
140
|
+
* ```typescript
|
|
141
|
+
* const startOfDay = new Date().setHours(0, 0, 0, 0);
|
|
142
|
+
* const { stats } = await UsageStatsManager.queryUsageStats({
|
|
143
|
+
* intervalType: 0, // INTERVAL_DAILY
|
|
144
|
+
* beginTime: startOfDay,
|
|
145
|
+
* endTime: Date.now(),
|
|
146
|
+
* packageName: 'com.example.app',
|
|
147
|
+
* });
|
|
148
|
+
* stats.forEach((bucket) => {
|
|
149
|
+
* console.log(`${bucket.packageName}: ${bucket.totalTimeInForeground}ms`);
|
|
150
|
+
* });
|
|
151
|
+
* ```
|
|
152
|
+
*/
|
|
153
|
+
queryUsageStats(options: QueryUsageStatsOptions): Promise<QueryUsageStatsResult>;
|
|
154
|
+
/**
|
|
155
|
+
* Queries the raw usage event log for the given time range.
|
|
156
|
+
*
|
|
157
|
+
* Returns lifecycle events whose timestamps fall in `[beginTime, endTime)`.
|
|
158
|
+
* Android does not emit a synthetic event for "already in foreground at
|
|
159
|
+
* beginTime" or "still in foreground at endTime". To measure duration across
|
|
160
|
+
* those boundaries, pass an earlier `beginTime` as lookback and clip locally:
|
|
161
|
+
* treat an unmatched pause as starting at the window start, and an unmatched
|
|
162
|
+
* resume as ending at the window end.
|
|
163
|
+
*
|
|
164
|
+
* Android retains events for only a few days. Older ranges may return an
|
|
165
|
+
* incomplete or empty list; that is not the same as zero foreground usage.
|
|
166
|
+
* On Android R (API 30) and above, the OS also returns no events while the
|
|
167
|
+
* user is locked; this plugin then resolves `{ events: [] }`, which likewise
|
|
168
|
+
* must not be treated as zero foreground usage.
|
|
169
|
+
*
|
|
170
|
+
* Callers can sum resumed-to-paused intervals from the returned events.
|
|
171
|
+
* Do not treat `DEVICE_SHUTDOWN` as a pause: it is a reset marker, not an
|
|
172
|
+
* interval close. This uses the same `PACKAGE_USAGE_STATS` permission as
|
|
173
|
+
* `queryAndAggregateUsageStats`.
|
|
174
|
+
*
|
|
175
|
+
* Only lifecycle events are returned, to keep the bridge payload small:
|
|
176
|
+
* - `1` — ACTIVITY_RESUMED / MOVE_TO_FOREGROUND
|
|
177
|
+
* - `2` — ACTIVITY_PAUSED / MOVE_TO_BACKGROUND
|
|
178
|
+
* - `23` — ACTIVITY_STOPPED
|
|
179
|
+
* - `26` — DEVICE_SHUTDOWN (device-wide reset marker; still returned when
|
|
180
|
+
* `packageName` is set. Android typically reports package `"android"`.
|
|
181
|
+
* `packageName` is omitted if the OS does not attach one. The timestamp
|
|
182
|
+
* is the last UsageStats persist before shutdown, not the actual
|
|
183
|
+
* power-off. Open resume events without a matching pause between this
|
|
184
|
+
* marker and the next boot have unknown duration and must be ignored.)
|
|
185
|
+
*
|
|
186
|
+
* @param options - The time range and optional package filter
|
|
187
|
+
* @returns Promise that resolves to the matching usage events
|
|
188
|
+
* @throws Error if the permission is not granted or query fails
|
|
189
|
+
* @since 8.1.3
|
|
190
|
+
* @example
|
|
191
|
+
* ```typescript
|
|
192
|
+
* const startOfDay = new Date().setHours(0, 0, 0, 0);
|
|
193
|
+
* const { events } = await UsageStatsManager.queryEvents({
|
|
194
|
+
* beginTime: startOfDay,
|
|
195
|
+
* endTime: Date.now(),
|
|
196
|
+
* packageName: 'com.example.app',
|
|
197
|
+
* });
|
|
198
|
+
* events.forEach((event) => {
|
|
199
|
+
* console.log(`${event.packageName} type=${event.eventType} at ${event.timeStamp}`);
|
|
200
|
+
* });
|
|
201
|
+
* ```
|
|
202
|
+
*/
|
|
203
|
+
queryEvents(options: QueryEventsOptions): Promise<QueryEventsResult>;
|
|
104
204
|
/**
|
|
105
205
|
* Checks if the usage stats permission is granted.
|
|
106
206
|
*
|
|
@@ -165,19 +265,112 @@ export interface CapacitorUsageStatsManagerPlugin {
|
|
|
165
265
|
version: string;
|
|
166
266
|
}>;
|
|
167
267
|
}
|
|
268
|
+
/**
|
|
269
|
+
* Options for querying per-interval usage statistics.
|
|
270
|
+
*
|
|
271
|
+
* @since 8.1.3
|
|
272
|
+
*/
|
|
273
|
+
export interface QueryUsageStatsOptions {
|
|
274
|
+
/**
|
|
275
|
+
* Interval type from `android.app.usage.UsageStatsManager`:
|
|
276
|
+
* - `0` — INTERVAL_DAILY
|
|
277
|
+
* - `1` — INTERVAL_WEEKLY
|
|
278
|
+
* - `2` — INTERVAL_MONTHLY
|
|
279
|
+
* - `3` — INTERVAL_YEARLY
|
|
280
|
+
* - `4` — INTERVAL_BEST
|
|
281
|
+
*/
|
|
282
|
+
intervalType: number;
|
|
283
|
+
/**
|
|
284
|
+
* The inclusive beginning of the range of stats to include in the results.
|
|
285
|
+
* Defined in terms of "Unix time"
|
|
286
|
+
*/
|
|
287
|
+
beginTime: number;
|
|
288
|
+
/**
|
|
289
|
+
* The exclusive end of the range of stats to include in the results.
|
|
290
|
+
* Defined in terms of "Unix time"
|
|
291
|
+
*/
|
|
292
|
+
endTime: number;
|
|
293
|
+
/**
|
|
294
|
+
* Optional package name. When set, only stats for this package are returned.
|
|
295
|
+
* An empty string is rejected.
|
|
296
|
+
*/
|
|
297
|
+
packageName?: string;
|
|
298
|
+
}
|
|
299
|
+
/**
|
|
300
|
+
* Result of a `queryUsageStats` call.
|
|
301
|
+
*
|
|
302
|
+
* @since 8.1.3
|
|
303
|
+
*/
|
|
304
|
+
export interface QueryUsageStatsResult {
|
|
305
|
+
/**
|
|
306
|
+
* Usage stats buckets in the requested range, ordered as returned by the OS.
|
|
307
|
+
* The same package can appear more than once when multiple intervals overlap.
|
|
308
|
+
*/
|
|
309
|
+
stats: UsageStats[];
|
|
310
|
+
}
|
|
311
|
+
/**
|
|
312
|
+
* Options for querying the raw usage event log.
|
|
313
|
+
*
|
|
314
|
+
* @since 8.1.3
|
|
315
|
+
*/
|
|
316
|
+
export interface QueryEventsOptions {
|
|
317
|
+
/**
|
|
318
|
+
* The inclusive beginning of the range of events to include in the results.
|
|
319
|
+
* Defined in terms of "Unix time"
|
|
320
|
+
*/
|
|
321
|
+
beginTime: number;
|
|
322
|
+
/**
|
|
323
|
+
* The exclusive end of the range of events to include in the results.
|
|
324
|
+
* Defined in terms of "Unix time"
|
|
325
|
+
*/
|
|
326
|
+
endTime: number;
|
|
327
|
+
/**
|
|
328
|
+
* Optional package name. When set, only events for this package are returned,
|
|
329
|
+
* plus device-wide `DEVICE_SHUTDOWN` events. An empty string is rejected.
|
|
330
|
+
* Keeps the Capacitor bridge payload small when you care about one app.
|
|
331
|
+
*/
|
|
332
|
+
packageName?: string;
|
|
333
|
+
}
|
|
334
|
+
/**
|
|
335
|
+
* Result of a `queryEvents` call.
|
|
336
|
+
*
|
|
337
|
+
* @since 8.1.3
|
|
338
|
+
*/
|
|
339
|
+
export interface QueryEventsResult {
|
|
340
|
+
/**
|
|
341
|
+
* Lifecycle usage events in the requested range, ordered as returned by the OS.
|
|
342
|
+
*/
|
|
343
|
+
events: UsageEvent[];
|
|
344
|
+
}
|
|
168
345
|
/**
|
|
169
346
|
* Represents a single usage event.
|
|
170
347
|
*
|
|
348
|
+
* `queryEvents` currently populates `className`, `timeStamp`, and `eventType`.
|
|
349
|
+
* `packageName` is set when Android attaches one (DEVICE_SHUTDOWN usually uses
|
|
350
|
+
* `"android"`) and omitted otherwise. Other fields remain optional for
|
|
351
|
+
* compatibility.
|
|
352
|
+
*
|
|
171
353
|
* @since 1.0.0
|
|
172
354
|
*/
|
|
173
355
|
export interface UsageEvent {
|
|
174
|
-
/**
|
|
175
|
-
|
|
356
|
+
/**
|
|
357
|
+
* Package name of the app.
|
|
358
|
+
* Omitted when Android does not attach a package. DEVICE_SHUTDOWN typically
|
|
359
|
+
* uses `"android"`.
|
|
360
|
+
*/
|
|
361
|
+
packageName?: string;
|
|
176
362
|
/** Class name (might be null) */
|
|
177
363
|
className?: string;
|
|
178
364
|
/** Timestamp in milliseconds since epoch */
|
|
179
365
|
timeStamp: number;
|
|
180
|
-
/**
|
|
366
|
+
/**
|
|
367
|
+
* Event type constant from `android.app.usage.UsageEvents.Event`.
|
|
368
|
+
* `queryEvents` returns lifecycle types only:
|
|
369
|
+
* - `1` — ACTIVITY_RESUMED / MOVE_TO_FOREGROUND
|
|
370
|
+
* - `2` — ACTIVITY_PAUSED / MOVE_TO_BACKGROUND
|
|
371
|
+
* - `23` — ACTIVITY_STOPPED
|
|
372
|
+
* - `26` — DEVICE_SHUTDOWN (reset marker, not an interval close)
|
|
373
|
+
*/
|
|
181
374
|
eventType: number;
|
|
182
375
|
/** Configuration object (requires API 28+) */
|
|
183
376
|
configuration?: any;
|
|
@@ -1 +1 @@
|
|
|
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 * @param options - Optional query settings\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({ includeIcon: true });\n * packages.forEach(pkg => {\n * console.log(`${pkg.appName} (${pkg.packageName}): category=${pkg.category}`);\n * });\n * ```\n */\n queryAllPackages(options?: QueryAllPackagesOptions): 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 * Options for querying installed packages.\n *\n * @since 8.0.33\n */\nexport interface QueryAllPackagesOptions {\n /**\n * When true, includes each app's launcher icon as a base64 data URL.\n * Defaults to false because icons significantly increase the response size.\n *\n * @default false\n */\n includeIcon?: boolean;\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 * Application category from `ApplicationInfo.category`.\n * Only available on Android 8.0 (API level 26) and above.\n *\n * Common values:\n * - `0` — undefined\n * - `1` — game\n * - `2` — audio\n * - `3` — video\n * - `4` — image\n * - `5` — social\n * - `6` — news\n * - `7` — maps\n * - `8` — productivity\n *\n * @since 8.0.33\n */\n category?: number;\n /**\n * App icon as a base64 data URL (`data:image/png;base64,...`).\n * Only present when `queryAllPackages({ includeIcon: true })` is used.\n *\n * @since 8.0.33\n */\n icon?: string;\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 * Optional package name. When set, only stats for this package are returned.\n * Omit to return stats for every package (previous behavior).\n * An empty string is rejected.\n *\n * @since 8.1.3\n */\n packageName?: string;\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 * Android reads pre-aggregated daily/weekly/monthly/yearly buckets and sums\n * every bucket that intersects `[beginTime, endTime)`, without clipping to it.\n * `totalTimeInForeground` can therefore include usage from outside the window.\n * Use `queryUsageStats` for the unmerged per-interval buckets, or `queryEvents`\n * for timestamped lifecycle events in the requested 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 * packageName: 'com.example.app',\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 * Queries usage stats for the given interval type and time range.\n *\n * Wraps Android `UsageStatsManager.queryUsageStats`. Unlike\n * `queryAndAggregateUsageStats`, this does not merge buckets: the result is\n * one `UsageStats` object per package per overlapping interval. Android may\n * expand `[beginTime, endTime)` to the nearest whole interval period, so\n * `totalTimeInForeground` can include usage from outside the window.\n *\n * On Android R (API 30) and above, the OS returns no data while the user is\n * locked; this plugin then resolves `{ stats: [] }`, which must not be treated\n * as zero foreground usage.\n *\n * This uses the same `PACKAGE_USAGE_STATS` permission as\n * `queryAndAggregateUsageStats`.\n *\n * @param options - The interval type, time range, and optional package filter\n * @returns Promise that resolves to the matching usage stats buckets\n * @throws Error if the permission is not granted or query fails\n * @since 8.1.3\n * @example\n * ```typescript\n * const startOfDay = new Date().setHours(0, 0, 0, 0);\n * const { stats } = await UsageStatsManager.queryUsageStats({\n * intervalType: 0, // INTERVAL_DAILY\n * beginTime: startOfDay,\n * endTime: Date.now(),\n * packageName: 'com.example.app',\n * });\n * stats.forEach((bucket) => {\n * console.log(`${bucket.packageName}: ${bucket.totalTimeInForeground}ms`);\n * });\n * ```\n */\n queryUsageStats(options: QueryUsageStatsOptions): Promise<QueryUsageStatsResult>;\n\n /**\n * Queries the raw usage event log for the given time range.\n *\n * Returns lifecycle events whose timestamps fall in `[beginTime, endTime)`.\n * Android does not emit a synthetic event for \"already in foreground at\n * beginTime\" or \"still in foreground at endTime\". To measure duration across\n * those boundaries, pass an earlier `beginTime` as lookback and clip locally:\n * treat an unmatched pause as starting at the window start, and an unmatched\n * resume as ending at the window end.\n *\n * Android retains events for only a few days. Older ranges may return an\n * incomplete or empty list; that is not the same as zero foreground usage.\n * On Android R (API 30) and above, the OS also returns no events while the\n * user is locked; this plugin then resolves `{ events: [] }`, which likewise\n * must not be treated as zero foreground usage.\n *\n * Callers can sum resumed-to-paused intervals from the returned events.\n * Do not treat `DEVICE_SHUTDOWN` as a pause: it is a reset marker, not an\n * interval close. This uses the same `PACKAGE_USAGE_STATS` permission as\n * `queryAndAggregateUsageStats`.\n *\n * Only lifecycle events are returned, to keep the bridge payload small:\n * - `1` — ACTIVITY_RESUMED / MOVE_TO_FOREGROUND\n * - `2` — ACTIVITY_PAUSED / MOVE_TO_BACKGROUND\n * - `23` — ACTIVITY_STOPPED\n * - `26` — DEVICE_SHUTDOWN (device-wide reset marker; still returned when\n * `packageName` is set. Android typically reports package `\"android\"`.\n * `packageName` is omitted if the OS does not attach one. The timestamp\n * is the last UsageStats persist before shutdown, not the actual\n * power-off. Open resume events without a matching pause between this\n * marker and the next boot have unknown duration and must be ignored.)\n *\n * @param options - The time range and optional package filter\n * @returns Promise that resolves to the matching usage events\n * @throws Error if the permission is not granted or query fails\n * @since 8.1.3\n * @example\n * ```typescript\n * const startOfDay = new Date().setHours(0, 0, 0, 0);\n * const { events } = await UsageStatsManager.queryEvents({\n * beginTime: startOfDay,\n * endTime: Date.now(),\n * packageName: 'com.example.app',\n * });\n * events.forEach((event) => {\n * console.log(`${event.packageName} type=${event.eventType} at ${event.timeStamp}`);\n * });\n * ```\n */\n queryEvents(options: QueryEventsOptions): Promise<QueryEventsResult>;\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 * @param options - Optional query settings\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({ includeIcon: true });\n * packages.forEach(pkg => {\n * console.log(`${pkg.appName} (${pkg.packageName}): category=${pkg.category}`);\n * });\n * ```\n */\n queryAllPackages(options?: QueryAllPackagesOptions): 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 * Options for querying per-interval usage statistics.\n *\n * @since 8.1.3\n */\nexport interface QueryUsageStatsOptions {\n /**\n * Interval type from `android.app.usage.UsageStatsManager`:\n * - `0` — INTERVAL_DAILY\n * - `1` — INTERVAL_WEEKLY\n * - `2` — INTERVAL_MONTHLY\n * - `3` — INTERVAL_YEARLY\n * - `4` — INTERVAL_BEST\n */\n intervalType: number;\n\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 * Optional package name. When set, only stats for this package are returned.\n * An empty string is rejected.\n */\n packageName?: string;\n}\n\n/**\n * Result of a `queryUsageStats` call.\n *\n * @since 8.1.3\n */\nexport interface QueryUsageStatsResult {\n /**\n * Usage stats buckets in the requested range, ordered as returned by the OS.\n * The same package can appear more than once when multiple intervals overlap.\n */\n stats: UsageStats[];\n}\n\n/**\n * Options for querying the raw usage event log.\n *\n * @since 8.1.3\n */\nexport interface QueryEventsOptions {\n /**\n * The inclusive beginning of the range of events 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 events to include in the results.\n * Defined in terms of \"Unix time\"\n */\n endTime: number;\n\n /**\n * Optional package name. When set, only events for this package are returned,\n * plus device-wide `DEVICE_SHUTDOWN` events. An empty string is rejected.\n * Keeps the Capacitor bridge payload small when you care about one app.\n */\n packageName?: string;\n}\n\n/**\n * Result of a `queryEvents` call.\n *\n * @since 8.1.3\n */\nexport interface QueryEventsResult {\n /**\n * Lifecycle usage events in the requested range, ordered as returned by the OS.\n */\n events: UsageEvent[];\n}\n\n/**\n * Represents a single usage event.\n *\n * `queryEvents` currently populates `className`, `timeStamp`, and `eventType`.\n * `packageName` is set when Android attaches one (DEVICE_SHUTDOWN usually uses\n * `\"android\"`) and omitted otherwise. Other fields remain optional for\n * compatibility.\n *\n * @since 1.0.0\n */\nexport interface UsageEvent {\n /**\n * Package name of the app.\n * Omitted when Android does not attach a package. DEVICE_SHUTDOWN typically\n * uses `\"android\"`.\n */\n packageName?: string;\n /** Class name (might be null) */\n className?: string;\n /** Timestamp in milliseconds since epoch */\n timeStamp: number;\n /**\n * Event type constant from `android.app.usage.UsageEvents.Event`.\n * `queryEvents` returns lifecycle types only:\n * - `1` — ACTIVITY_RESUMED / MOVE_TO_FOREGROUND\n * - `2` — ACTIVITY_PAUSED / MOVE_TO_BACKGROUND\n * - `23` — ACTIVITY_STOPPED\n * - `26` — DEVICE_SHUTDOWN (reset marker, not an interval close)\n */\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 * Options for querying installed packages.\n *\n * @since 8.0.33\n */\nexport interface QueryAllPackagesOptions {\n /**\n * When true, includes each app's launcher icon as a base64 data URL.\n * Defaults to false because icons significantly increase the response size.\n *\n * @default false\n */\n includeIcon?: boolean;\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 * Application category from `ApplicationInfo.category`.\n * Only available on Android 8.0 (API level 26) and above.\n *\n * Common values:\n * - `0` — undefined\n * - `1` — game\n * - `2` — audio\n * - `3` — video\n * - `4` — image\n * - `5` — social\n * - `6` — news\n * - `7` — maps\n * - `8` — productivity\n *\n * @since 8.0.33\n */\n category?: number;\n /**\n * App icon as a base64 data URL (`data:image/png;base64,...`).\n * Only present when `queryAllPackages({ includeIcon: true })` is used.\n *\n * @since 8.0.33\n */\n icon?: string;\n}\n"]}
|
package/dist/esm/web.d.ts
CHANGED
|
@@ -1,9 +1,29 @@
|
|
|
1
1
|
import { WebPlugin } from '@capacitor/core';
|
|
2
|
-
import type { CapacitorUsageStatsManagerPlugin, PackageInfo } from './definitions';
|
|
2
|
+
import type { CapacitorUsageStatsManagerPlugin, PackageInfo, QueryEventsOptions, QueryEventsResult, QueryUsageStatsOptions, QueryUsageStatsResult } from './definitions';
|
|
3
3
|
export declare class CapacitorUsageStatsManagerWeb extends WebPlugin implements CapacitorUsageStatsManagerPlugin {
|
|
4
4
|
isUsageStatsPermissionGranted(): Promise<any>;
|
|
5
5
|
openUsageStatsSettings(): Promise<void>;
|
|
6
|
+
/**
|
|
7
|
+
* Android-only. Web does not expose UsageStatsManager.
|
|
8
|
+
*
|
|
9
|
+
* @param _options Time range and optional package filter
|
|
10
|
+
* @returns Never; web always throws
|
|
11
|
+
*/
|
|
6
12
|
queryAndAggregateUsageStats(_options: any): Promise<Record<string, any>>;
|
|
13
|
+
/**
|
|
14
|
+
* Android-only. Web does not expose UsageStatsManager.
|
|
15
|
+
*
|
|
16
|
+
* @param _options Interval type, time range, and optional package filter
|
|
17
|
+
* @returns Never; web always throws
|
|
18
|
+
*/
|
|
19
|
+
queryUsageStats(_options: QueryUsageStatsOptions): Promise<QueryUsageStatsResult>;
|
|
20
|
+
/**
|
|
21
|
+
* Android-only. Web does not expose UsageStatsManager events.
|
|
22
|
+
*
|
|
23
|
+
* @param _options Time range and optional package filter
|
|
24
|
+
* @returns Never; web always throws
|
|
25
|
+
*/
|
|
26
|
+
queryEvents(_options: QueryEventsOptions): Promise<QueryEventsResult>;
|
|
7
27
|
queryAllPackages(_options?: {
|
|
8
28
|
includeIcon?: boolean;
|
|
9
29
|
}): Promise<{
|