buildfire.services.health
The Buildfire Health Service allows plugins to query HealthKit and Google Health Connect data.
Requirements
Adding Health Feature
Android Health Connect Requires sub-features along side the "health"
feature in order to read the user health data.
Android Permission Declaration
Android Health Connect requires declaration of permissions for each datatype the app wants to read, to simplify the process we grouped them into main categories. However, iOS does not require such declaration.
In plugin.json, add {"name" : "health"}
along with the desired sub-feature in your features
array.
Remember to add "health"
feature when adding a health sub-feature
Examples
Example of an app that needs to read nutrition records to suggest nutrition daily recommendations:
"features" : [
{"name" : "health"},
{"name" : "health->Android-Nutrition"}
]
Example of an app that keeps track of user workout routine and fitness:
"features" : [
{"name" : "health"},
{"name" : "health->Android-Activity"},
{"name" : "health->Android-BodyMeasurements"}
]
Widget
Include healthAPI.js
file in your widget's <head>
, right after buildfire.min.js
<head>
<script src="../../../scripts/buildfire.min.js"></script>
<script src="../../../scripts/buildfire/services/health/healthAPI.js"></script>
</head>
Methods
requestAuthorization()
function buildfire.services.health.requestAuthorization(dataTypes<Array>, callback<Function>)
Requests read and write access to a set of data types. This method must be called before using the query methods, even if the authorization has already been given at some point in the past.
Arguments
Name | Type | Required | Description | Default |
---|---|---|---|---|
dataTypes | Array | Yes | Array of data types you want to be granted access to. You can also specify read or write only permissions. | N/A |
callback | Function | No | Executed when the request is complete. Returns an error if something went wrong. | N/A |
dataTypes
Name | Type | Required | Description | Default |
---|---|---|---|---|
STRING_VALUE | String | N/A | Data type string to request. Grants read and write access. | N/A |
OBJECT_VALUE | Object | N/A | Object of separate read and write permissions. | N/A |
dataTypes[OBJECT_VALUE]
Name | Type | Required | Description | Default |
---|---|---|---|---|
read | Array | N/A | Array of data type strings to request read access for. | N/A |
write | Array | N/A | Array of data type strings to request write access for. | N/A |
Currently, we only support reading data
callback(error<String>)
Name | Type | Description |
---|---|---|
error | String | error string, null when operation is successful. |
Example
// Data types to request read permission for
const dataTypes = [{
read: ['steps', 'height', 'weight']
}];
// Request permissions
buildfire.services.health.requestAuthorization(dataTypes, (err) => {
if (err) console.log(err);
});
query()
function buildfire.services.health.query(options<Object>, callback<Function>)
Fetches all the data points of a certain data type within a certain time window.
Arguments
Name | Type | Required | Description | Default |
---|---|---|---|---|
options | Object | Yes | An object that defines the search parametrs, along with the dataTypes to query. | N/A |
callback | Function | No | Returns an array of result objects when the request is sucessful. Returns an error if something went wrong. | N/A |
options
Name | Type | Required | Description | Default |
---|---|---|---|---|
dataType | string | yes | Data type to query. See Data Types. | N/A |
limit | number | no | Sets a maximum number of returned values. | 1000 |
startDate | Date | yes | Start date for the query. | N/A |
endDate | Date | yes | End date for the query. | N/A |
callback(error<String>, results<Array>)
Name | Type | Description |
---|---|---|
error | String | Error string, null when operation is successful. |
results | Array | Array of result objects. |
results
Name | Type | Description |
---|---|---|
id | String | Unique Identifier. |
unit | String | The unit of measure. |
value | Number | Measured value. |
sourceName | String | Measuring device name. |
sourceBundleId | String | Measuring application bundleId. |
sourceProductType | String | Measuring device product identifier (ex: iPhone 12,2). |
sourceOSVersion | String | Measuring device OS version. |
startDate | String | Starting date string. |
endDate | String | Ending date string. |
deviceName | String | Name of the device that generated the data. |
deviceModel | String | Model of the device that generated the data. |
deviceManufacturer | String | Manufacturer of the device that generated the data. |
deviceHardwareVersion | String | String representing the hardware version of the device. |
deviceSoftwareVersion | String | String representing the software version of the device. |
deviceFirmwareVersion | String | String representing the current version of the firmware running on the device. |
metadata | Object | Metadata object. |
Example
const options = {
dataType: 'steps',
limit: 1000,
startDate: new Date(new Date().getTime() - 3 * 864e5),
endDate: new Date(),
};
buildfire.services.health.query(options, (error, results) => {
if (error) return console.error(error);
results.forEach(result => {
console.log(result);
});
});
queryAggregated()
function buildfire.services.health.queryAggregated(options<Object>, callback<Function>)
Fetches all the data points of a certain data type within a certain time window. Aggregates results into buckets.
Arguments
Name | Type | Required | Description | Default |
---|---|---|---|---|
options | Object | Yes | An object that defines the search parametrs, along with the dataTypes to query. | N/A |
callback | Function | No | Returns an array of result objects when the request is sucessful. Returns an error if something went wrong. | N/A |
options
Name | Type | Required | Description | Default |
---|---|---|---|---|
dataType | String | yes | Data type to query. See Supported Data Types. | N/A |
bucket | String | no | Time scale to segment data by. | N/A |
startDate | Date | yes | Start date for the query. | N/A |
endDate | Date | yes | End date for the query. | N/A |
callback(error<String>, results<Array>)
Name | Type | Description |
---|---|---|
error | String | Error string, null when operation is successful. |
results | Array | Array of results. If no bucket is passed, returns only the first object. |
results
Name | Type | Description |
---|---|---|
unit | String | The unit of measure |
value | Number | Measured value |
startDate | String | Starting date string |
endDate | String | Ending date string |
Example
const options = {
dataType: 'steps',
bucket: 'day',
startDate: new Date(new Date().getTime() - 3 * 864e5),
endDate: new Date(),
};
buildfire.services.health.queryAggregated(options, (error, results) => {
if (error) return console.error(error);
results.forEach(result => {
console.log(result);
});
});
Data Types
The Health service supports the following data types:
Body and Physical
Data Type | Unit | HealthKit | Health Connect |
---|---|---|---|
abdominal_cramps | Severity | ✅ | |
acne | Severity | ✅ | |
activity | activityType | ✅ | ✅ |
activitySummary | N/A | ✅ | |
appetite_changes | Severity | ✅ | |
appleExerciseTime | min | ✅ | |
audio_exposure_event | N/A | ✅ | |
bladder_incontinence | Severity | ✅ | |
bloating | Severity | ✅ | |
blood_alcohol_content | percent | ✅ | |
blood_glucose | mg/dL | ✅ | ✅ |
blood_pressure | mmHg | ✅ | ✅ |
blood_pressure_diastolic | mmHg | ✅ | |
blood_pressure_systolic | mmHg | ✅ | |
bmi | count | ✅ | |
body_ache | Severity | ✅ | |
breast_pain | Severity | ✅ | |
calories | kcal | ✅ | ✅ |
calories.active | kcal | ✅ | ✅ |
calories.basal | kcal | ✅ | ✅ |
cervical_mucus_quality | Severity | ✅ | ✅ |
chills | Severity | ✅ | |
constipation | Severity | ✅ | |
contraceptives | ContraceptiveType | ✅ | |
coughing | Severity | ✅ | |
date_of_birth | ✅ | ||
diarrhea | Severity | ✅ | |
distance | m | ✅ | ✅ |
distance.walkingRunning | m | ✅ | |
distance.cycling | m | ✅ | |
distance.wheelchair | m | ✅ | |
dizziness | Severity | ✅ | |
dry_skin | Severity | ✅ | |
electrocardiogram | ✅ | ||
electrodermal_activity | mcS | ✅ | |
environmental_audio_exposure | dB | ✅ | |
environmental_audio_exposure_event | N/A | ✅ | |
fainting | Severity | ✅ | |
fat_percentage | % | ✅ | ✅ |
fatigue | Severity | ✅ | |
fever | Severity | ✅ | |
flights_climbed | count | ✅ | |
forced_expiratory_volume1 | L | ✅ | |
forced_vital_capacity | L | ✅ | |
gender | ✅ | ||
hair_loss | Severity | ✅ | |
handwashing_event | N/A | ✅ | |
headache | Severity | ✅ | |
headphone_audio_exposure | dB | ✅ | |
headphone_audio_exposure_event | N/A | ✅ | |
heart_rate | count/min | ✅ | ✅ |
heart_rate_variability_sdnn | ms | ✅ | |
heart_rate.resting | count/min | ✅ | ✅ |
heart_rate.variability | ms | ✅ | ✅ |
heartburn | Severity | ✅ | |
height | m | ✅ | ✅ |
high_heart_rate_event | N/A | ✅ | |
hot_flashes | Severity | ✅ | |
inhaler_usage | count | ✅ | |
insulin | IU | ✅ | |
intermenstrual_bleeding | Severity | ✅ | ✅ |
irregular_heart_rhythm_event | N/A | ✅ | |
lactation | N/A | ✅ | |
lean_body_mass | kg | ✅ | ✅ |
loss_of_smell | Severity | ✅ | |
loss_of_taste | Severity | ✅ | |
low_cardio_event | N/A | ✅ | |
low_heart_rate_event | N/A | ✅ | |
lower_back_pain | Severity | ✅ | |
memory_lapse | Severity | ✅ | |
menstrual_flow | Flow | ✅ | |
mindfulness | min | ✅ | |
mindfulness | sec | ✅ | |
mood_changes | Severity | ✅ | |
nausea | Severity | ✅ | |
night_sweats | Severity | ✅ | |
number_of_alcoholic_beverages | count | ✅ | |
number_of_times_fallen | count | ✅ | |
nutrition | nutrition | ✅ | |
nutrition.biotin | mcg | ✅ | ✅ |
nutrition.caffeine | g | ✅ | ✅ |
nutrition.calcium | mg | ✅ | ✅ |
nutrition.calories | kcal | ✅ | ✅ |
nutrition.carbs.total | g | ✅ | ✅ |
nutrition.chloride | mg | ✅ | ✅ |
nutrition.cholesterol | mg | ✅ | ✅ |
nutrition.chromium | mcg | ✅ | ✅ |
nutrition.copper | mg | ✅ | ✅ |
nutrition.dietary_fiber | g | ✅ | ✅ |
nutrition.fat.monounsaturated | g | ✅ | ✅ |
nutrition.fat.polyunsaturated | g | ✅ | ✅ |
nutrition.fat.saturated | g | ✅ | ✅ |
nutrition.fat.unsaturated | g | ✅ | |
nutrition.fat.trans | g | ✅ | |
nutrition.fat.total | g | ✅ | ✅ |
nutrition.folate | mcg | ✅ | ✅ |
nutrition.iodine | mcg | ✅ | ✅ |
nutrition.iron | mg | ✅ | ✅ |
nutrition.magnesium | mg | ✅ | ✅ |
nutrition.molybdenum | mg | ✅ | ✅ |
nutrition.niacin | mg | ✅ | ✅ |
nutrition.pantothenic_acid | mg | ✅ | ✅ |
nutrition.phosphorus | mg | ✅ | ✅ |
nutrition.potassium | mg | ✅ | ✅ |
nutrition.protein | g | ✅ | ✅ |
nutrition.riboflavin | mg | ✅ | ✅ |
nutrition.selenium | mcg | ✅ | ✅ |
nutrition.sodium | mg | ✅ | ✅ |
nutrition.sugar | g | ✅ | ✅ |
nutrition.thiamin | mg | ✅ | ✅ |
nutrition.vitamin_a | mcg (HK), IU (GF) | ✅ | ✅ |
nutrition.vitamin_B12 | mcg | ✅ | ✅ |
nutrition.vitamin_B6 | mg | ✅ | ✅ |
nutrition.vitamin_c | mg | ✅ | ✅ |
nutrition.vitamin_D | mcg | ✅ | ✅ |
nutrition.vitamin_E | mg | ✅ | ✅ |
nutrition.vitamin_K | mcg | ✅ | ✅ |
nutrition.water | ml | ✅ | ✅ |
nutrition.zinc | mg | ✅ | ✅ |
nutrition.manganese | mg | ✅ | |
ovulation_test_result | TestResult | ✅ | ✅ |
oxygen_saturation | % | ✅ | ✅ |
peak_expiratory_flow_rate | L/min | ✅ | |
pelvic_pain | Severity | ✅ | |
peripheral_perfusion_index | percent | ✅ | |
pregnancy | N/A | ✅ | |
pregnancy_test_result | TestResult | ✅ | |
progesterone_test_result | TestResult | ✅ | |
rapid_or_fluttering_heartbeat | Severity | ✅ | |
resp_rate | count/min | ✅ | ✅ |
runny_nose | Severity | ✅ | |
sexual_activity | N/A | ✅ | ✅ |
shortness_of_breath | Severity | ✅ | |
sinus_congestion | Severity | ✅ | |
six_minute_walk_test_distance | m | ✅ | |
skipped_heartbeat | Severity | ✅ | |
sleep | SleepStages | ✅ | ✅ |
sleep_changes | Severity | ✅ | |
sore_throat | Severity | ✅ | |
stair_ascent_speed | m/s | ✅ | |
stair_descent_speed | m/s | ✅ | |
stairs | count | ✅ | |
stand_time | s | ✅ | |
steps | count | ✅ | ✅ |
temperature | degC | ✅ | ✅ |
temperature.basal | degC | ✅ | ✅ |
tightness_or_pain | Severity | ✅ | |
toothbrushing_event | N/A | ✅ | |
uv_exposure | count | ✅ | |
vaginal_dryness | Severity | ✅ | |
vo2max | ml/(kg * min) | ✅ | ✅ |
vomiting | Severity | ✅ | |
waist_circumference | m | ✅ | |
walking_asymmetry_percentage | percent | ✅ | |
walking_double_support_percentage | percent | ✅ | |
walking_speed | m/s | ✅ | |
walking_steadiness | percent | ✅ | |
walking_steadiness_event | N/A | ✅ | |
walking_step_length | cm | ✅ | |
weight | kg | ✅ | ✅ |
wheezing | Severity | ✅ | |
menstruation_period | count | ✅ | |
wheelchair_pushes | pushes | ✅ | |
floors_climbed | floors | ✅ | |
bone_mass | kg | ✅ | |
cycling_pedaling_cadence | rpm | ✅ | |
elevation | m | ✅ | |
power | watts | ✅ | |
speed | m/s | ✅ | |
water_mass | kg | ✅ | |
steps_cadence | m/s | ✅ |
Units
Severity
Value | Description |
---|---|
1 | not present |
2 | mild |
3 | moderate |
4 | severe |
0 | unspecified |
OvulationTestResult
Value | Description |
---|---|
1 | negative |
2 | luteinizing hormone surge |
3 | indeterminate |
4 | estrogen surge |
Flow
Value | Description |
---|---|
1 | unspecified |
2 | light |
3 | medium |
4 | heavy |
5 | none |
TestResult
Value | Description |
---|---|
1 | negative |
2 | positive |
3 | indeterminate |
ContraceptiveType
Value | Description |
---|---|
1 | unspecified |
2 | implant |
3 | injection |
4 | intrauterine device |
5 | intravaginal ring |
6 | oral |
7 | patch |
SleepStages
Value | Description |
---|---|
0 | in bed |
1 | unspecified |
2 | awake |
3 | core |
4 | deep |
5 | REM |
Activities
Activity Name | HealthKit | Health Connect |
---|---|---|
archery | ✅ | |
badminton | ✅ | ✅ |
barre | ✅ | |
baseball | ✅ | ✅ |
basketball | ✅ | ✅ |
biking | ✅ | ✅ |
biking.hand | ✅ | ✅ |
biking.mountain | ✅ | |
biking.road | ✅ | |
biking.spinning | ✅ | |
biking.stationary | ✅ | ✅ |
biking.utility | ✅ | |
bowling | ✅ | |
boxing | ✅ | ✅ |
cooldown | ✅ | |
core_training | ✅ | ✅ |
cricket | ✅ | ✅ |
crossfit | ✅ | |
curling | ✅ | |
dancing | ✅ | ✅ |
dancing.social | ✅ | ✅ |
disc_sports | ✅ | |
diving | ✅ | |
elliptical | ✅ | ✅ |
fencing | ✅ | ✅ |
fishing | ✅ | |
fitness_gaming | ✅ | |
flexibility | ✅ | ✅ |
football.american | ✅ | ✅ |
football.australian | ✅ | ✅ |
football.soccer | ✅ | ✅ |
functional_strength | ✅ | |
golf | ✅ | ✅ |
gymnastics | ✅ | ✅ |
handball | ✅ | ✅ |
hiking | ✅ | ✅ |
hockey | ✅ | ✅ |
horseback_riding | ✅ | |
hunting | ✅ | |
ice_skating | ✅ | ✅ |
interval_training | ✅ | |
interval_training.high_intensity | ✅ | ✅ |
jump_rope | ✅ | |
kayaking | ✅ | |
kick_scooter | ✅ | |
kickboxing | ✅ | |
lacrosse | ✅ | |
martial_arts | ✅ | ✅ |
martial_arts.mixed | ✅ | |
meditation | ✅ | |
mixed_metabolic_cardio | ✅ | |
other | ✅ | ✅ |
paddle_sports | ✅ | ✅ |
pickleball | ✅ | ✅ |
pilates | ✅ | ✅ |
play | ✅ | |
preparation_and_recovery | ✅ | |
racquetball | ✅ | ✅ |
rock_climbing | ✅ | ✅ |
rowing | ✅ | ✅ |
rowing.machine | ✅ | ✅ |
rugby | ✅ | ✅ |
running | ✅ | ✅ |
running.jogging | ✅ | |
running.sand | ✅ | |
running.treadmill | ✅ | ✅ |
sailing | ✅ | ✅ |
scuba_diving | ✅ | ✅ |
skateboarding | ✅ | |
skating | ✅ | ✅ |
skating.cross | ✅ | |
skating.indoor | ✅ | |
skating.inline | ✅ | |
skiing | ✅ | ✅ |
skiing.back_country | ✅ | |
skiing.cross_country | ✅ | |
skiing.downhill | ✅ | |
skiing.kite | ✅ | |
skiing.roller | ✅ | |
sledding | ✅ | |
sleep | ✅ | |
sleep.awake | ✅ | |
sleep.deep | ✅ | |
sleep.inBed | ✅ | |
sleep.light | ✅ | |
sleep.rem | ✅ | |
snow_sports | ✅ | |
snowboarding | ✅ | ✅ |
snowmobile | ✅ | |
snowshoeing | ✅ | ✅ |
softball | ✅ | |
squash | ✅ | ✅ |
stair_climbing | ✅ | ✅ |
stair_climbing.machine | ✅ | ✅ |
stairs | ✅ | ✅ |
standup_paddleboarding | ✅ | |
strength_training | ✅ | ✅ |
surfing | ✅ | ✅ |
swimming | ✅ | |
swimming.open_water | ✅ | ✅ |
swimming.pool | ✅ | ✅ |
table_tennis | ✅ | ✅ |
tai_chi | ✅ | |
tennis | ✅ | ✅ |
track_and_field | ✅ | ✅ |
volleyball | ✅ | ✅ |
volleyball.beach | ✅ | |
volleyball.indoor | ✅ | |
wakeboarding | ✅ | |
walking | ✅ | ✅ |
walking.fitness | ✅ | |
walking.nordic | ✅ | |
walking.stroller | ✅ | |
walking.treadmill | ✅ | |
water_fitness | ✅ | |
water_polo | ✅ | |
water_sports | ✅ | |
weightlifting | ✅ | ✅ |
wheelchair | ✅ | ✅ |
wheelchair.runpace | ✅ | |
wheelchair.walkpace | ✅ | |
windsurfing | ✅ | |
wrestling | ✅ | |
yoga | ✅ |
Android Permission Sub-Features
To reduce the likelihood of Google rejecting your app, only include the necessary sub-features.
Android Permission Sub-Features | Datatypes |
---|---|
health->Android-Activity | activity , steps , calories , calories.active , vo2max , floors_climbed , distance , power , speed , elevation , wheelchair_pushes , cycling_pedaling_cadence , steps_cadence |
health->Android-BodyMeasurements | weight , height , calories.basal , fat_percentage , water_mass , lean_body_mass , bone_mass |
health->Android-Vitals | temperature.basal , blood_glucose , blood_pressure , temperature , heart_rate , heart_rate.variability , oxygen_saturation , resp_rate , heart_rate.resting |
health->Android-CycleTracking | cervical_mucus_quality , intermenstrual_bleeding , menstruation_period , menstrual_flow , ovulation_test_result , sexual_activity |
health->Android-Nutrition | nutrition , nutrition.water , nutrition.biotin , nutrition.caffeine , nutrition.calcium , nutrition.carbs.total , nutrition.chloride , nutrition.cholesterol , nutrition.chromium , nutrition.copper , nutrition.dietary_fiber , nutrition.fat.monounsaturated , nutrition.fat.polyunsaturated , nutrition.fat.saturated , nutrition.fat.unsaturated , nutrition.fat.trans , nutrition.fat.total , nutrition.folate , nutrition.iodine , nutrition.iron , nutrition.magnesium , nutrition.molybdenum , nutrition.niacin , nutrition.pantothenic_acid , nutrition.phosphorus , nutrition.potassium , nutrition.protein , nutrition.riboflavin , nutrition.selenium , nutrition.sodium , nutrition.sugar , nutrition.thiamin , nutrition.vitamin_a , nutrition.vitamin_B12 , nutrition.vitamin_B6 , nutrition.vitamin_c , nutrition.vitamin_D , nutrition.vitamin_E , nutrition.vitamin_K , nutrition.zinc |
health->Android-Sleep | sleep |
Electrocardiograms (iOS Only)
The health
service can query for electrocardiogram
as a data type. Electrocardiogram samples contain the following data:
Name | Type | Description |
---|---|---|
algorithmVersion | Number | Version numbers for the algorithm Apple Watch uses to generate an ECG reading |
averageHeartRate | Number | Average heart rate over ECG duration |
classification | String | ECG’s classification (ex: "SinusRhythm") |
samplingFrequency | Number | The frequency at which the voltage is sampled |
voltageMeasurements | Array | Collection of voltage values representing waveforms |
{
id: "ECF3C1B4-AEFA-4656-B7F2-B110951835EA",
startDate: "2021-06-06T11:11:43.000Z",
endDate: "2021-06-06T11:12:13.000Z",
algorithmVersion: 1,
averageHeartRate: 62,
classification: "SinusRhythm",
samplingFrequency: 513.7265625,
sourceName: "ECG",
sourceBundleId: "com.apple.NanoHeartRhythm",
sourceProductType: "Watch5,4",
sourceOSVersion: "7.4.1",
deviceName: "Apple Watch",
deviceModel: "Watch",
deviceManufacturer: "Apple Inc.",
deviceLocalIdentifier: "",
deviceHardwareVersion: "Watch5,4",
deviceSoftwareVersion: "7.4.1",
deviceFirmwareVersion: "",
voltageMeasurements: [
[0,-0.00016570074462890624],
[0.0019465608224219476,-0.00019473405456542969],
[0.003893121644843895,-0.00021828952026367186],
[0.005839682467265842,-0.00023469168090820312],
[0.00778624328968779,-0.00024280212402343749]
// ...
]
}