@asiriindatissa/capacitor-health 8.3.0 → 8.3.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 +42 -12
- package/android/src/main/AndroidManifest.xml +1 -0
- package/dist/docs.json +28 -11
- package/dist/esm/definitions.d.ts +16 -4
- package/dist/esm/definitions.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,7 +26,7 @@ npx cap sync
|
|
|
26
26
|
This plugin now uses [Health Connect](https://developer.android.com/health-and-fitness/guides/health-connect) instead of Google Fit. Make sure your app meets the requirements below:
|
|
27
27
|
|
|
28
28
|
1. **Min SDK 26+.** Health Connect is only available on Android 8.0 (API 26) and above. The plugin's Gradle setup already targets this level.
|
|
29
|
-
2. **Declare Health permissions.** The plugin manifest ships with the required `<uses-permission>` declarations (`READ_/WRITE_STEPS`, `READ_/WRITE_DISTANCE`, `READ_/WRITE_ACTIVE_CALORIES_BURNED`, `READ_/WRITE_HEART_RATE`, `READ_/WRITE_WEIGHT`, `READ_/WRITE_HEIGHT`). Your app does not need to duplicate them, but you must surface a user-facing rationale because the permissions are considered health sensitive.
|
|
29
|
+
2. **Declare Health permissions.** The plugin manifest ships with the required `<uses-permission>` declarations (`READ_/WRITE_STEPS`, `READ_/WRITE_DISTANCE`, `READ_/WRITE_ACTIVE_CALORIES_BURNED`, `READ_/WRITE_HEART_RATE`, `READ_/WRITE_WEIGHT`, `READ_/WRITE_HEIGHT`, `READ_EXERCISE`). Your app does not need to duplicate them, but you must surface a user-facing rationale because the permissions are considered health sensitive.
|
|
30
30
|
3. **Ensure Health Connect is installed.** Devices on Android 14+ include it by default. For earlier versions the user must install _Health Connect by Android_ from the Play Store. The `Health.isAvailable()` helper exposes the current status so you can prompt accordingly.
|
|
31
31
|
4. **Request runtime access.** The plugin opens the Health Connect permission UI when you call `requestAuthorization`. You should still handle denial flows (e.g., show a message if `checkAuthorization` reports missing scopes).
|
|
32
32
|
5. **Provide a Privacy Policy.** Health Connect requires apps to display a privacy policy explaining how health data is used. See the [Privacy Policy Setup](#privacy-policy-setup) section below.
|
|
@@ -95,8 +95,9 @@ if (!availability.available) {
|
|
|
95
95
|
}
|
|
96
96
|
|
|
97
97
|
// Ask for separate read/write access scopes
|
|
98
|
+
// Include 'workouts' if you need to query workout sessions
|
|
98
99
|
await Health.requestAuthorization({
|
|
99
|
-
read: ['steps', 'heartRate', 'weight'],
|
|
100
|
+
read: ['steps', 'heartRate', 'weight', 'workouts'],
|
|
100
101
|
write: ['weight'],
|
|
101
102
|
});
|
|
102
103
|
|
|
@@ -128,6 +129,27 @@ await Health.saveSample({
|
|
|
128
129
|
|
|
129
130
|
All write operations expect the default unit shown above. On Android the `metadata` option is currently ignored by Health Connect.
|
|
130
131
|
|
|
132
|
+
### Workouts
|
|
133
|
+
|
|
134
|
+
To query workout sessions, you need to request read permission for `'workouts'`:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
// Request permission to read workouts
|
|
138
|
+
await Health.requestAuthorization({
|
|
139
|
+
read: ['workouts', 'steps', 'heartRate'], // Include 'workouts' for queryWorkouts()
|
|
140
|
+
write: [],
|
|
141
|
+
});
|
|
142
|
+
|
|
143
|
+
// Query recent workouts
|
|
144
|
+
const { workouts } = await Health.queryWorkouts({
|
|
145
|
+
startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
|
|
146
|
+
endDate: new Date().toISOString(),
|
|
147
|
+
limit: 10,
|
|
148
|
+
});
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Note: `'workouts'` is a special read-only permission type. You cannot write workouts with this plugin.
|
|
152
|
+
|
|
131
153
|
## API
|
|
132
154
|
|
|
133
155
|
<docgen-index>
|
|
@@ -304,20 +326,20 @@ Queries workout sessions from the native health store on Android (Health Connect
|
|
|
304
326
|
|
|
305
327
|
#### AuthorizationStatus
|
|
306
328
|
|
|
307
|
-
| Prop | Type
|
|
308
|
-
| --------------------- |
|
|
309
|
-
| **`readAuthorized`** | <code>
|
|
310
|
-
| **`readDenied`** | <code>
|
|
311
|
-
| **`writeAuthorized`** | <code>HealthDataType[]</code> |
|
|
312
|
-
| **`writeDenied`** | <code>HealthDataType[]</code> |
|
|
329
|
+
| Prop | Type | Description |
|
|
330
|
+
| --------------------- | ------------------------------------ | ----------------------------------------------------------- |
|
|
331
|
+
| **`readAuthorized`** | <code>ReadAuthorizationType[]</code> | Data types (and 'workouts') that are authorized for reading |
|
|
332
|
+
| **`readDenied`** | <code>ReadAuthorizationType[]</code> | Data types (and 'workouts') that are denied for reading |
|
|
333
|
+
| **`writeAuthorized`** | <code>HealthDataType[]</code> | Data types that are authorized for writing |
|
|
334
|
+
| **`writeDenied`** | <code>HealthDataType[]</code> | Data types that are denied for writing |
|
|
313
335
|
|
|
314
336
|
|
|
315
337
|
#### AuthorizationOptions
|
|
316
338
|
|
|
317
|
-
| Prop | Type
|
|
318
|
-
| ----------- |
|
|
319
|
-
| **`read`** | <code>
|
|
320
|
-
| **`write`** | <code>HealthDataType[]</code>
|
|
339
|
+
| Prop | Type | Description |
|
|
340
|
+
| ----------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
341
|
+
| **`read`** | <code>ReadAuthorizationType[]</code> | Data types that should be readable after authorization. Include 'workouts' to enable queryWorkouts() method. |
|
|
342
|
+
| **`write`** | <code>HealthDataType[]</code> | Data types that should be writable after authorization. |
|
|
321
343
|
|
|
322
344
|
|
|
323
345
|
#### ReadSamplesResult
|
|
@@ -399,6 +421,14 @@ Queries workout sessions from the native health store on Android (Health Connect
|
|
|
399
421
|
### Type Aliases
|
|
400
422
|
|
|
401
423
|
|
|
424
|
+
#### ReadAuthorizationType
|
|
425
|
+
|
|
426
|
+
Data types that can be requested for read authorization.
|
|
427
|
+
Includes 'workouts' for querying workout sessions via queryWorkouts().
|
|
428
|
+
|
|
429
|
+
<code><a href="#healthdatatype">HealthDataType</a> | 'workouts'</code>
|
|
430
|
+
|
|
431
|
+
|
|
402
432
|
#### HealthDataType
|
|
403
433
|
|
|
404
434
|
<code>'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'height'</code>
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
<uses-permission android:name="android.permission.health.WRITE_WEIGHT" />
|
|
12
12
|
<uses-permission android:name="android.permission.health.READ_HEIGHT" />
|
|
13
13
|
<uses-permission android:name="android.permission.health.WRITE_HEIGHT" />
|
|
14
|
+
<uses-permission android:name="android.permission.health.READ_EXERCISE" />
|
|
14
15
|
|
|
15
16
|
<!-- Query for Health Connect availability -->
|
|
16
17
|
<queries>
|
package/dist/docs.json
CHANGED
|
@@ -217,25 +217,25 @@
|
|
|
217
217
|
{
|
|
218
218
|
"name": "readAuthorized",
|
|
219
219
|
"tags": [],
|
|
220
|
-
"docs": "",
|
|
220
|
+
"docs": "Data types (and 'workouts') that are authorized for reading",
|
|
221
221
|
"complexTypes": [
|
|
222
|
-
"
|
|
222
|
+
"ReadAuthorizationType"
|
|
223
223
|
],
|
|
224
|
-
"type": "
|
|
224
|
+
"type": "ReadAuthorizationType[]"
|
|
225
225
|
},
|
|
226
226
|
{
|
|
227
227
|
"name": "readDenied",
|
|
228
228
|
"tags": [],
|
|
229
|
-
"docs": "",
|
|
229
|
+
"docs": "Data types (and 'workouts') that are denied for reading",
|
|
230
230
|
"complexTypes": [
|
|
231
|
-
"
|
|
231
|
+
"ReadAuthorizationType"
|
|
232
232
|
],
|
|
233
|
-
"type": "
|
|
233
|
+
"type": "ReadAuthorizationType[]"
|
|
234
234
|
},
|
|
235
235
|
{
|
|
236
236
|
"name": "writeAuthorized",
|
|
237
237
|
"tags": [],
|
|
238
|
-
"docs": "",
|
|
238
|
+
"docs": "Data types that are authorized for writing",
|
|
239
239
|
"complexTypes": [
|
|
240
240
|
"HealthDataType"
|
|
241
241
|
],
|
|
@@ -244,7 +244,7 @@
|
|
|
244
244
|
{
|
|
245
245
|
"name": "writeDenied",
|
|
246
246
|
"tags": [],
|
|
247
|
-
"docs": "",
|
|
247
|
+
"docs": "Data types that are denied for writing",
|
|
248
248
|
"complexTypes": [
|
|
249
249
|
"HealthDataType"
|
|
250
250
|
],
|
|
@@ -262,11 +262,11 @@
|
|
|
262
262
|
{
|
|
263
263
|
"name": "read",
|
|
264
264
|
"tags": [],
|
|
265
|
-
"docs": "Data types that should be readable after authorization.",
|
|
265
|
+
"docs": "Data types that should be readable after authorization.\nInclude 'workouts' to enable queryWorkouts() method.",
|
|
266
266
|
"complexTypes": [
|
|
267
|
-
"
|
|
267
|
+
"ReadAuthorizationType"
|
|
268
268
|
],
|
|
269
|
-
"type": "
|
|
269
|
+
"type": "ReadAuthorizationType[] | undefined"
|
|
270
270
|
},
|
|
271
271
|
{
|
|
272
272
|
"name": "write",
|
|
@@ -605,6 +605,23 @@
|
|
|
605
605
|
],
|
|
606
606
|
"enums": [],
|
|
607
607
|
"typeAliases": [
|
|
608
|
+
{
|
|
609
|
+
"name": "ReadAuthorizationType",
|
|
610
|
+
"slug": "readauthorizationtype",
|
|
611
|
+
"docs": "Data types that can be requested for read authorization.\nIncludes 'workouts' for querying workout sessions via queryWorkouts().",
|
|
612
|
+
"types": [
|
|
613
|
+
{
|
|
614
|
+
"text": "HealthDataType",
|
|
615
|
+
"complexTypes": [
|
|
616
|
+
"HealthDataType"
|
|
617
|
+
]
|
|
618
|
+
},
|
|
619
|
+
{
|
|
620
|
+
"text": "'workouts'",
|
|
621
|
+
"complexTypes": []
|
|
622
|
+
}
|
|
623
|
+
]
|
|
624
|
+
},
|
|
608
625
|
{
|
|
609
626
|
"name": "HealthDataType",
|
|
610
627
|
"slug": "healthdatatype",
|
|
@@ -1,15 +1,27 @@
|
|
|
1
1
|
export type HealthDataType = 'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'height';
|
|
2
2
|
export type HealthUnit = 'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram';
|
|
3
|
+
/**
|
|
4
|
+
* Data types that can be requested for read authorization.
|
|
5
|
+
* Includes 'workouts' for querying workout sessions via queryWorkouts().
|
|
6
|
+
*/
|
|
7
|
+
export type ReadAuthorizationType = HealthDataType | 'workouts';
|
|
3
8
|
export interface AuthorizationOptions {
|
|
4
|
-
/**
|
|
5
|
-
|
|
9
|
+
/**
|
|
10
|
+
* Data types that should be readable after authorization.
|
|
11
|
+
* Include 'workouts' to enable queryWorkouts() method.
|
|
12
|
+
*/
|
|
13
|
+
read?: ReadAuthorizationType[];
|
|
6
14
|
/** Data types that should be writable after authorization. */
|
|
7
15
|
write?: HealthDataType[];
|
|
8
16
|
}
|
|
9
17
|
export interface AuthorizationStatus {
|
|
10
|
-
|
|
11
|
-
|
|
18
|
+
/** Data types (and 'workouts') that are authorized for reading */
|
|
19
|
+
readAuthorized: ReadAuthorizationType[];
|
|
20
|
+
/** Data types (and 'workouts') that are denied for reading */
|
|
21
|
+
readDenied: ReadAuthorizationType[];
|
|
22
|
+
/** Data types that are authorized for writing */
|
|
12
23
|
writeAuthorized: HealthDataType[];
|
|
24
|
+
/** Data types that are denied for writing */
|
|
13
25
|
writeDenied: HealthDataType[];
|
|
14
26
|
}
|
|
15
27
|
export interface AvailabilityResult {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export type HealthDataType = 'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'height';\n\nexport type HealthUnit = 'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram';\n\nexport interface AuthorizationOptions {\n
|
|
1
|
+
{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["export type HealthDataType = 'steps' | 'distance' | 'calories' | 'heartRate' | 'weight' | 'height';\n\nexport type HealthUnit = 'count' | 'meter' | 'kilocalorie' | 'bpm' | 'kilogram';\n\n/**\n * Data types that can be requested for read authorization.\n * Includes 'workouts' for querying workout sessions via queryWorkouts().\n */\nexport type ReadAuthorizationType = HealthDataType | 'workouts';\n\nexport interface AuthorizationOptions {\n /**\n * Data types that should be readable after authorization.\n * Include 'workouts' to enable queryWorkouts() method.\n */\n read?: ReadAuthorizationType[];\n /** Data types that should be writable after authorization. */\n write?: HealthDataType[];\n}\n\nexport interface AuthorizationStatus {\n /** Data types (and 'workouts') that are authorized for reading */\n readAuthorized: ReadAuthorizationType[];\n /** Data types (and 'workouts') that are denied for reading */\n readDenied: ReadAuthorizationType[];\n /** Data types that are authorized for writing */\n writeAuthorized: HealthDataType[];\n /** Data types that are denied for writing */\n writeDenied: HealthDataType[];\n}\n\nexport interface AvailabilityResult {\n available: boolean;\n /** Platform specific details (for debugging/diagnostics). */\n platform?: 'android' | 'web';\n reason?: string;\n}\n\nexport interface QueryOptions {\n /** The type of data to retrieve from the health store. */\n dataType: HealthDataType;\n /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n startDate?: string;\n /** Exclusive ISO 8601 end date (defaults to now). */\n endDate?: string;\n /** Maximum number of samples to return (defaults to 100). */\n limit?: number;\n /** Return results sorted ascending by start date (defaults to false). */\n ascending?: boolean;\n}\n\nexport interface HealthSample {\n dataType: HealthDataType;\n value: number;\n unit: HealthUnit;\n startDate: string;\n endDate: string;\n sourceName?: string;\n sourceId?: string;\n}\n\nexport interface ReadSamplesResult {\n samples: HealthSample[];\n}\n\nexport type WorkoutType =\n | 'running'\n | 'cycling'\n | 'walking'\n | 'swimming'\n | 'yoga'\n | 'strengthTraining'\n | 'hiking'\n | 'tennis'\n | 'basketball'\n | 'soccer'\n | 'americanFootball'\n | 'baseball'\n | 'crossTraining'\n | 'elliptical'\n | 'rowing'\n | 'stairClimbing'\n | 'traditionalStrengthTraining'\n | 'waterFitness'\n | 'waterPolo'\n | 'waterSports'\n | 'wrestling'\n | 'other';\n\nexport interface QueryWorkoutsOptions {\n /** Optional workout type filter. If omitted, all workout types are returned. */\n workoutType?: WorkoutType;\n /** Inclusive ISO 8601 start date (defaults to now - 1 day). */\n startDate?: string;\n /** Exclusive ISO 8601 end date (defaults to now). */\n endDate?: string;\n /** Maximum number of workouts to return (defaults to 100). */\n limit?: number;\n /** Return results sorted ascending by start date (defaults to false). */\n ascending?: boolean;\n}\n\nexport interface Workout {\n /** The type of workout. */\n workoutType: WorkoutType;\n /** Duration of the workout in seconds. */\n duration: number;\n /** Total energy burned in kilocalories (if available). */\n totalEnergyBurned?: number;\n /** Total distance in meters (if available). */\n totalDistance?: number;\n /** ISO 8601 start date of the workout. */\n startDate: string;\n /** ISO 8601 end date of the workout. */\n endDate: string;\n /** Source name that recorded the workout. */\n sourceName?: string;\n /** Source bundle identifier. */\n sourceId?: string;\n /** Additional metadata (if available). */\n metadata?: Record<string, string>;\n}\n\nexport interface QueryWorkoutsResult {\n workouts: Workout[];\n}\n\nexport interface WriteSampleOptions {\n dataType: HealthDataType;\n value: number;\n /**\n * Optional unit override. If omitted, the default unit for the data type is used\n * (count for `steps`, meter for `distance`, kilocalorie for `calories`, bpm for `heartRate`, kilogram for `weight`, meter for `height`).\n */\n unit?: HealthUnit;\n /** ISO 8601 start date for the sample. Defaults to now. */\n startDate?: string;\n /** ISO 8601 end date for the sample. Defaults to startDate. */\n endDate?: string;\n /** Metadata key-value pairs forwarded to the native APIs where supported. */\n metadata?: Record<string, string>;\n}\n\nexport interface HealthPlugin {\n /** Returns whether the current platform supports the native health SDK. */\n isAvailable(): Promise<AvailabilityResult>;\n /** Requests read/write access to the provided data types. */\n requestAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>;\n /** Checks authorization status for the provided data types without prompting the user. */\n checkAuthorization(options: AuthorizationOptions): Promise<AuthorizationStatus>;\n /** Reads samples for the given data type within the specified time frame. */\n readSamples(options: QueryOptions): Promise<ReadSamplesResult>;\n /** Writes a single sample to the native health store. */\n saveSample(options: WriteSampleOptions): Promise<void>;\n\n /**\n * Get the native Capacitor plugin version\n *\n * @returns {Promise<{ version: string }>} a Promise with version for this device\n * @throws An error if something went wrong\n */\n getPluginVersion(): Promise<{ version: string }>;\n\n /**\n * Opens the Health Connect settings screen.\n *\n * Use this to direct users to manage their Health Connect permissions\n * or to install Health Connect if not available.\n *\n * @throws An error if Health Connect settings cannot be opened\n */\n openHealthConnectSettings(): Promise<void>;\n\n /**\n * Shows the app's privacy policy for Health Connect.\n *\n * This displays the same privacy policy screen that Health Connect shows\n * when the user taps \"Privacy policy\" in the permissions dialog.\n *\n * The privacy policy URL can be configured by adding a string resource\n * named \"health_connect_privacy_policy_url\" in your app's strings.xml,\n * or by placing an HTML file at www/privacypolicy.html in your assets.\n *\n * @throws An error if the privacy policy cannot be displayed\n */\n showPrivacyPolicy(): Promise<void>;\n\n /**\n * Queries workout sessions from the native health store on Android (Health Connect).\n *\n * @param options Query options including optional workout type filter, date range, limit, and sort order\n * @returns A promise that resolves with the workout sessions\n * @throws An error if something went wrong\n */\n queryWorkouts(options: QueryWorkoutsOptions): Promise<QueryWorkoutsResult>;\n}\n"]}
|
package/package.json
CHANGED