buildfire.services.health

The Buildfire Health Service allows plugins to query HealthKit and Google Health Connect data.

Requirements

Adding Health Feature

note

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.

caution

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

warning

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

caution

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]
        // ...
    ]
}