Skip to content

Cordova plugin for the HealthKit and Google Fit frameworks

License

Notifications You must be signed in to change notification settings

hardikdevios/cordova-plugin-health

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Cordova Health Plugin

A plugin that abstracts fitness and health repositories like Apple HealthKit or Google Fit.

This work is based on cordova plugin googlefit and on cordova healthkit plugin

For an introduction about Google Fit versus HealthKit see this very good article.

This plugin is kept up to date and requires a recent version of cordova (6 and on) as well as recent iOS and Android SDKs.

Warning

Google discourages from using Google Fit for medical apps. See the official terms.

Installation

In Cordova:

cordova plugin add cordova-plugin-health --variable HEALTH_READ_PERMISSION='App needs read access' --variable HEALTH_WRITE_PERMISSION='App needs write access'

HEALTH_READ_PERMISSION and HEALTH_WRITE_PERMISSION are shown when the app tries to grant access to data in HealthKit.

Phonegap Build config.xml:

<!-- Health plugin -->
<plugin name="cordova-plugin-health" source="npm">

<!-- Only if iOS -->

<!-- Read access -->
<config-file platform="ios" parent="NSHealthShareUsageDescription">
  <string>App needs read access</string>
</config-file>
<!-- Write access -->
<config-file platform="ios" parent="NSHealthUpdateUsageDescription">
  <string>App needs write access</string>
</config-file>

iOS requirements

  • Make sure your app id has the 'HealthKit' entitlement when this plugin is installed (see iOS dev center).
  • Also, make sure your app and App Store description comply with the Apple review guidelines.
  • There are two keys to be added to the info.plist file: NSHealthShareUsageDescription and NSHealthUpdateUsageDescription. These are assigned with a default string by the plugin, but you may want to contextualise them for your app.

Android requirements

  • You need to have the Google Services API downloaded in your SDK.
  • Be sure to give your app access to the Google Fitness API, see this and this.
  • If you are wondering what key your compiled app is using, you can type keytool -list -printcert -jarfile yourapp.apk.
  • You can use the Google Fitness API even if the user doesn't have Google Fit installed, but there has to be some other fitness app putting data into the Fitness API otherwise your queries will always be empty. See the the original documentation.
  • This plugin is set to use the latest version of the Google Play Services API (<framework src="com.google.android.gms:play-services-fitness:+" />). This is done to likely guarantee the compatibility with other plugins using Google Play Services, but bear in mind that a) the plugin was tested until version 9.8.0 of the APIs and b) other plugins may be using a different version of the API. If you run into an issue, check the generated gradle file (build.gradle) under dependencies between // SUB-PROJECT DEPENDENCIES START and // SUB-PROJECT DEPENDENCIES END and make sure that all versions of the com.google.android.gms:play-services-xxxx are the same.

Supported data types

As HealthKit does not allow adding custom data types, only a subset of data types supported by HealthKit has been chosen. Google Fit is limited to fitness data and, for health, custom data types are defined with the suffix of the package name of your project.

Data type Unit HealthKit equivalent Google Fit equivalent
steps count HKQuantityTypeIdentifierStepCount TYPE_STEP_COUNT_DELTA
distance m HKQuantityTypeIdentifierDistanceWalkingRunning + HKQuantityTypeIdentifierDistanceCycling TYPE_DISTANCE_DELTA
calories kcal HKQuantityTypeIdentifierActiveEnergyBurned + HKQuantityTypeIdentifierBasalEnergyBurned TYPE_CALORIES_EXPENDED
calories.active kcal HKQuantityTypeIdentifierActiveEnergyBurned TYPE_CALORIES_EXPENDED - (TYPE_BASAL_METABOLIC_RATE * time window)
calories.basal kcal HKQuantityTypeIdentifierBasalEnergyBurned TYPE_BASAL_METABOLIC_RATE * time window
activity HKWorkoutTypeIdentifier + HKCategoryTypeIdentifierSleepAnalysis TYPE_ACTIVITY_SEGMENT
height m HKQuantityTypeIdentifierHeight TYPE_HEIGHT
weight kg HKQuantityTypeIdentifierBodyMass TYPE_WEIGHT
heart_rate count/min HKQuantityTypeIdentifierHeartRate TYPE_HEART_RATE_BPM
fat_percentage % HKQuantityTypeIdentifierBodyFatPercentage TYPE_BODY_FAT_PERCENTAGE
blood_glucose mmol/L HKQuantityTypeIdentifierBloodGlucose Not yet supported
gender HKCharacteristicTypeIdentifierBiologicalSex custom (YOUR_PACKAGE_NAME.gender)
date_of_birth HKCharacteristicTypeIdentifierDateOfBirth custom (YOUR_PACKAGE_NAME.date_of_birth)
nutrition HKCorrelationTypeIdentifierFood TYPE_NUTRITION
nutrition.calories kcal HKQuantityTypeIdentifierDietaryEnergyConsumed TYPE_NUTRITION, NUTRIENT_CALORIES
nutrition.fat.total g HKQuantityTypeIdentifierDietaryFatTotal TYPE_NUTRITION, NUTRIENT_TOTAL_FAT
nutrition.fat.saturated g HKQuantityTypeIdentifierDietaryFatSaturated TYPE_NUTRITION, NUTRIENT_SATURATED_FAT
nutrition.fat.unsaturated g NA TYPE_NUTRITION, NUTRIENT_UNSATURATED_FAT
nutrition.fat.polyunsaturated g HKQuantityTypeIdentifierDietaryFatPolyunsaturated TYPE_NUTRITION, NUTRIENT_POLYUNSATURATED_FAT
nutrition.fat.monounsaturated g HKQuantityTypeIdentifierDietaryFatMonounsaturated TYPE_NUTRITION, NUTRIENT_MONOUNSATURATED_FAT
nutrition.fat.trans g NA TYPE_NUTRITION, NUTRIENT_TRANS_FAT (g)
nutrition.cholesterol mg HKQuantityTypeIdentifierDietaryCholesterol TYPE_NUTRITION, NUTRIENT_CHOLESTEROL
nutrition.sodium mg HKQuantityTypeIdentifierDietarySodium TYPE_NUTRITION, NUTRIENT_SODIUM
nutrition.potassium mg HKQuantityTypeIdentifierDietaryPotassium TYPE_NUTRITION, NUTRIENT_POTASSIUM
nutrition.carbs.total g HKQuantityTypeIdentifierDietaryCarbohydrates TYPE_NUTRITION, NUTRIENT_TOTAL_CARBS
nutrition.dietary_fiber g HKQuantityTypeIdentifierDietaryFiber TYPE_NUTRITION, NUTRIENT_DIETARY_FIBER
nutrition.sugar g HKQuantityTypeIdentifierDietarySugar TYPE_NUTRITION, NUTRIENT_SUGAR
nutrition.protein g HKQuantityTypeIdentifierDietaryProtein TYPE_NUTRITION, NUTRIENT_PROTEIN
nutrition.vitamin_a mcg (HK), IU (GF) HKQuantityTypeIdentifierDietaryVitaminA TYPE_NUTRITION, NUTRIENT_VITAMIN_A
nutrition.vitamin_c mg HKQuantityTypeIdentifierDietaryVitaminC TYPE_NUTRITION, NUTRIENT_VITAMIN_C
nutrition.calcium mg HKQuantityTypeIdentifierDietaryCalcium TYPE_NUTRITION, NUTRIENT_CALCIUM
nutrition.iron mg HKQuantityTypeIdentifierDietaryIron TYPE_NUTRITION, NUTRIENT_IRON
nutrition.water ml HKQuantityTypeIdentifierDietaryWater TYPE_HYDRATION
nutrition.caffeine g HKQuantityTypeIdentifierDietaryCaffeine NA

Note: units of measurement are fixed!

Returned objects contain a set of fixed fields:

  • startDate: {type: Date} a date indicating when the data point starts
  • endDate: {type: Date} a date indicating when the data point ends
  • sourceBundleId: {type: String} the identifier of the app that produced the data
  • sourceName: {type: String} the name of the app that produced the data (as it appears to the user)
  • unit: {type: String} the unit of measurement
  • value: the actual value

Example values:

Data type Value
steps 34
distance 101.2
calories 245.3
activity "walking"
Note: recognized activities and their mappings in Google Fit / HealthKit can be found here
height 185.9
weight 83.3
heart_rate 66
fat_percentage 31.2
blood_glucose 5.5
Note: to convert to mg/dL, multiply by 18.01559 (The molar mass of glucose is 180.1559).
gender "male"
date_of_birth { day: 3, month: 12, year: 1978 }
nutrition { item: "cheese", meal_type: "lunch", brand_name: "McDonald's", nutrients: { nutrition.fat.saturated: 11.5, nutrition.calories: 233.1 } }
Note: the brand_name property is only available on iOS
nutrition.X 12.4

Methods

isAvailable()

Tells if either Google Fit or HealthKit are available.

navigator.health.isAvailable(successCallback, errorCallback)
  • successCallback: {type: function(available)}, if available a true is passed as argument, false otherwise
  • errorCallback: {type: function(err)}, called if something went wrong, err contains a textual description of the problem

promptInstallFit() - Android only

Checks if recent Google Play Services and Google Fit are installed. If the play services are not installed, or are obsolete, it will show a pop-up suggesting to download them. If Google Fit is not installed, it will open the Play Store at the location of the Google Fit app. The plugin does not wait until the missing packages are installed, it will return immediately. If both Play Services and Google Fit are available, this function just returns without any visible effect.

This function is only available on Android.

navigator.health.promptInstallFit(successCallback, errorCallback)
  • successCallback: {type: function()}, called if the function was called
  • errorCallback: {type: function(err)}, called if something went wrong

requestAuthorization()

Requests read and write access to a set of data types. It is recommendable to always explain why the app needs access to the data before asking the user to authorize it.

Important: this method must be called before using the query and store methods, even if the authorization has already been given at some point in the past. Failure to do so may cause your app to crash, or in the case of Android, Google Fit may not be ready.

navigator.health.requestAuthorization(datatypes, successCallback, errorCallback)
  • datatypes: {type: Mixed array}, a list of data types you want to be granted access to. You can also specify read or write only permissions.
[
  'calories', 'distance',   // Read and write permissions
  {
    read : ['steps'],       // Read only permission
    write : ['height', 'weight']  // Write only permission
  }
]
  • successCallback: {type: function}, called if all OK
  • errorCallback: {type: function(err)}, called if something went wrong, err contains a textual description of the problem

Android quirks

  • It will try to get authorization from the Google fitness APIs. It is necessary that the app's package name and the signing key are registered in the Google API console (see here).
  • Be aware that if the activity is destroyed (e.g. after a rotation) or is put in background, the connection to Google Fit may be lost without any callback. Going through the authorization will ensure that the app is connected again.
  • In Android 6 and over, this function will also ask for some dynamic permissions if needed (e.g. in the case of "distance", it will need access to ACCESS_FINE_LOCATION).

isAuthorized()

Check if the app has authorization to read/write a set of datatypes.

navigator.health.isAuthorized(datatypes, successCallback, errorCallback)
  • datatypes: {type: Mixed array}, a list of data types you want to check access of, same as in requestAuthorization
  • successCallback: {type: function(authorized)}, if the argument is true, the app is authorized
  • errorCallback: {type: function(err)}, called if something went wrong, err contains a textual description of the problem

iOS quirks

  • This method will only check authorization status for writeable data. Read-only data will always be considered as not authorized. This is an intended behaviour of HealthKit.

query()

Gets all the data points of a certain data type within a certain time window.

Warning: if the time span is big, it can generate long arrays!

navigator.health.query({
  startDate: new Date(new Date().getTime() - 3 * 24 * 60 * 60 * 1000), // three days ago
  endDate: new Date(), // now
  dataType: 'height'
}, successCallback, errorCallback)
  • startDate: {type: Date}, start date from which to get data
  • endDate: {type: Date}, end data to which to get the data
  • dataType: {type: String}, the data type to be queried (see above)
  • successCallback: {type: function(data) }, called if all OK, data contains the result of the query in the form of an array of: { startDate: Date, endDate: Date, value: xxx, unit: 'xxx', sourceName: 'aaaa', sourceBundleId: 'bbbb' }
  • errorCallback: {type: function(err)}, called if something went wrong, err contains a textual description of the problem

iOS quirks

  • The amount of datapoints is limited to 1000 by default. You can override this by adding a limit: xxx to your query object.
  • Datapoints are ordered in an descending fashion (from newer to older). You can revert this behaviour by adding ascending: true to your query object.
  • HealthKit does not calculate active and basal calories - these must be inputted from an app
  • HealthKit does not detect specific activities - these must be inputted from an app
  • Activities in HealthKit may include two extra fields: calories (kcal) and distance (m)
  • When querying for nutrition, HealthKit only returns those stored as correlation. To be sure to get all stored quantities, it's better to query nutrients individually (e.g. MyFitnessPal doesn't store meals as correlations).
  • nutrition.vitamin_a is given in micrograms. Automatic conversion to international units is not trivial and depends on the actual substance (see here).
  • When querying for activities, only events whose startDate and endDate are both in the query range will be returned.

Android quirks

  • It is possible to query for "raw" steps or to select those as filtered by the Google Fit app. In the latter case the query object must contain the field filtered: true.
  • calories.basal is returned as an average per day, and usually is not available in all days.
  • calories.active is computed by subtracting the basal calories from the total. As basal energy expenditure, an average is computed from the week before endDate.
  • Active and basal calories can be automatically calculated
  • Some activities can be determined automatically (still, walking, running, biking, in vehicle)
  • When querying for nutrition, Google Fit always returns all the nutrition elements it has.
  • nutrition.vitamin_a is given in international units. Automatic conversion to micrograms is not trivial and depends on the actual substance (see here).
  • When querying for activities, if an event's startDate is out of the query range but its endDate is within, Google Fit will truncate the startDate to match that of the query.

queryAggregated()

Gets aggregated data in a certain time window. Usually the sum is returned for the given quantity.

navigator.health.queryAggregated({
  startDate: new Date(new Date().getTime() - 3 * 24 * 60 * 60 * 1000), // three days ago
  endDate: new Date(), // now
  dataType: 'steps',
  bucket: 'day'
}, successCallback, errorCallback)
  • startDate: {type: Date}, start date from which to get data
  • endDate: {type: Date}, end data to which to get the data
  • dataType: {type: String}, the data type to be queried (see below for supported data types)
  • bucket: {type: String}, if specified, aggregation is grouped an array of "buckets" (windows of time), supported values are: 'hour', 'day', 'week', 'month', 'year'
  • successCallback: {type: function(data)}, called if all OK, data contains the result of the query, see below for returned data types. If no buckets is specified, the result is an object. If a bucketing strategy is specified, the result is an array.
  • errorCallback: {type: function(err)}, called if something went wrong, err contains a textual description of the problem

Not all data types are supported for aggregated queries. The following table shows what types are supported and examples of the returned object:

Data type Example of returned object
steps { startDate: Date, endDate: Date, value: 5780, unit: 'count' }
distance { startDate: Date, endDate: Date, value: 12500.0, unit: 'm' }
calories { startDate: Date, endDate: Date, value: 25698.1, unit: 'kcal' }
calories.active { startDate: Date, endDate: Date, value: 3547.4, unit: 'kcal' }
calories.basal { startDate: Date, endDate: Date, value: 13146.1, unit: 'kcal' }
activity { startDate: Date, endDate: Date, value: { still: { duration: 520000, calories: 30, distance: 0 }, walking: { duration: 223000, calories: 20, distance: 15 }}, unit: 'activitySummary' }
Note: duration is expressed in milliseconds, distance in meters and calories in kcal
nutrition { startDate: Date, endDate: Date, value: { nutrition.fat.saturated: 11.5, nutrition.calories: 233.1 }, unit: 'nutrition' }
Note: units of measurement for nutrients are fixed according to the table at the beginning of this README
nutrition.x { startDate: Date, endDate: Date, value: 23, unit: 'mg'}

Quirks

  • The start and end dates returned are the date of the first and the last available samples. If no samples are found, start and end may not be set.
  • When bucketing, buckets will include the whole hour / day / month / week / year where start and end times fall into. For example, if your start time is 2016-10-21 10:53:34, the first daily bucket will start at 2016-10-21 00:00:00.
  • Weeks start on Monday.

iOS quirks

  • Activities in HealthKit may include two extra fields: calories (kcal) and distance (m)
  • When querying for nutrition, HealthKit only returns those stored as correlation. To be sure to get all stored quantities, it's better to query nutrients individually (e.g. MyFitnessPal doesn't store meals as correlations).
  • nutrition.vitamin_a is given in micrograms. Automatic conversion to international units is not trivial and depends on the actual substance (see here).

Android quirks

  • To query for steps as filtered by the Google Fit app, the flag filtered: true must be added into the query object.
  • nutrition.vitamin_a is given in international units. Automatic conversion to micrograms is not trivial and depends on the actual substance (see here).

store()

Stores a data point.

navigator.health.store({
	startDate:  new Date(new Date().getTime() - 3 * 60 * 1000), // three minutes ago
	endDate: new Date(),
	dataType: 'steps',
	value: 180,
	sourceName: 'my_app',
	sourceBundleId: 'com.example.my_app'
}, successCallback, errorCallback)
  • startDate: {type: Date}, start date from which the new data starts
  • endDate: {type: Date}, end date to which he new data ends
  • dataType: {type: a String}, the data type
  • value: {type: a number or an Object}, the value, depending on the actual data type. In the case of activity, the value must be set as the activity name.
  • sourceName: {type: String}, the source that produced this data. In iOS this is ignored and set automatically to the name of your app.
  • sourceBundleId: {type: String}, the complete package of the source that produced this data. In Android, if not specified, it's assigned to the package of the App. In iOS this is ignored and set automatically to the bundle id of the app.
  • successCallback: {type: function}, called if all OK
  • errorCallback: {type: function(err)}, called if something went wrong, err contains a textual description of the problem

iOS quirks

  • In iOS, when storing an activity, you can also specify calories (active, in kcal) and distance (walked or run, in meters). For example: dataType: 'activity', value: 'walking', calories: 20, distance: 520. Be aware, though, that you need permission to write calories and distance first, or the call will fail.
  • In iOS you cannot store the total calories, you need to specify either basal or active. If you use total calories, the active ones will be stored.
  • In iOS distance is assumed to be of type WalkingRunning, if you want to explicitly set it to Cycling you need to add the field cycling: true.

Android quirks

  • Google Fit doesn't allow you to overwrite data points that overlap with others already stored of the same type (see here). At the moment there is no support for update.
  • Storing of nutrients is not supported at the moment in Android.
  • In Android you can only store active calories, as the basal are estimated automatically. If you store total calories, these will be treated as active.

delete()

Deletes a range of data points.

navigator.health.delete({
	startDate:  new Date(new Date().getTime() - 3 * 60 * 1000), // three minutes ago
	endDate: new Date(),
	dataType: 'steps'
}, successCallback, errorCallback)
  • startDate: {type: Date}, start date from which to delete data
  • endDate: {type: Date}, end date to which to delete the data
  • dataType: {type: a String}, the data type to be deleted
  • successCallback: {type: function}, called if all OK
  • errorCallback: {type: function(err)}, called if something went wrong, err contains a textual description of the problem

iOS quirks

  • You cannot delete the total calories, you need to specify either basal or active. If you use total calories, the active ones will be delete.
  • Distance is assumed to be of type WalkingRunning, if you want to explicitly set it to Cycling you need to add the field cycling: true.
  • Deleting sleep activities is not supported at the moment.

Android quirks

  • Google Fit doesn't allow you to delete data points that were generated by other apps
  • You can only delete active calories, as the basal are estimated automatically. If you try to delete total calories, these will be treated as active.

Differences between HealthKit and Google Fit

  • HealthKit includes medical data (e.g. blood glucose), whereas Google Fit is only meant for fitness data (although now supports some medical data).
  • HealthKit provides a data model that is not extensible, whereas Google Fit allows defining custom data types.
  • HealthKit allows to insert data with the unit of measurement of your choice, and automatically translates units when queried, whereas Google Fit uses fixed units of measurement.
  • HealthKit automatically counts steps and distance when you carry your phone with you and if your phone has the CoreMotion chip, whereas Google Fit also detects the kind of activity (sedentary, running, walking, cycling, in vehicle).
  • HealthKit can only compute distance for running/walking activities, whereas Google Fit can also do so for bicycle events.

External resources

Roadmap

Short term:

  • Add storing of nutrition
  • Add more datatypes Body fat percentage Oxygen saturation Blood pressure Storing of blood glucose on iOS Blood glucose on Android Temperature Respiratory rate

Long term:

  • Include Core Motion Activity API
  • Add registration to updates (e.g. in Google Fit: HistoryApi#registerDataUpdateListener()).
  • Add support for Samsung Health as an alternate health record for Android.

Contributions

Any help is more than welcome!

I don't know Objective C and I am not interested in learning it now, so I would particularly appreciate someone who could give me a hand with the iOS part. Also, I would love to know from you if the plugin is currently used in any app actually available online. Just send me an email to my_username at gmail.com. For donations, I have a PayPal account at the same email address.

Thanks!

About

Cordova plugin for the HealthKit and Google Fit frameworks

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Objective-C 50.4%
  • Java 32.6%
  • JavaScript 17.0%