`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"}
]

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

buildfire.services.health

Requirements​

Adding Health Feature​

Android Permission Declaration​

Examples​

Widget​

Methods​

requestAuthorization() ​

Arguments​

dataTypes​

dataTypes[OBJECT_VALUE]​

callback(error<String>)​

Example​

query()​

Arguments​

options​

callback(error<String>, results<Array>)​

results​

Example​

queryAggregated()​

Arguments​

options​

callback(error<String>, results<Array>)​

results​

Example​

Data Types​

Body and Physical​

Units​

Severity​

OvulationTestResult​

Flow​

TestResult​

ContraceptiveType​

SleepStages​

Activities​

Android Permission Sub-Features​

Electrocardiograms (iOS Only)​

`buildfire.services.health`

Requirements

Adding Health Feature

`Android Permission Declaration`

`Examples`

Widget

Methods

`requestAuthorization()`

Arguments

`dataTypes`

`dataTypes[OBJECT_VALUE]`

`callback(error<String>)`

Example

`query()`

Arguments

`options`

`callback(error<String>, results<Array>)`

`results`

Example

`queryAggregated()`

Arguments

`options`

`callback(error<String>, results<Array>)`

`results`

Example

Data Types

Body and Physical

Units

Severity

OvulationTestResult

Flow

TestResult

ContraceptiveType

SleepStages

Activities

Android Permission Sub-Features

Electrocardiograms (iOS Only)