The Cordova Inform SDK Wrapper offers modules which you can implement into your mobile project to power data syncing with the Apple Health health data aggregation platform.

The Cordova Inform SDK Wrapper supports Healthkit for iOS and iPadOS. This document lays out the installation and use of the Apple Health integration.

Apple Health allows health and fitness apps to store and share the same on-device data within a unified ecosystem. It also offers a single place for users to control which apps can read and write health and fitness data.

Apple Health combines data from a variety of fitness and health apps along with data captured by Apple Watches (watchOS).

Installation

Apple Health has its own module in the Cordova Wrapper, therefore the following modules are required to use the Apple Health integration:

Session (core)
Apple Health (healthkit)

Installation instructions are detailed in Installation.

Session

A valid session is required in order to use the Apple Health integration in the Validic Inform SDK. See Session for more information.

Record types

The record types used in the Validic Inform Mobile SDK are described in Record Types.

Record Identifiers

More information on record identifiers can be found in Record Identifiers.

Listening for InformRecord Upload

More information on record events can be found in Record Events.

Apple Health

This project integrates Apple Health with the Cordova Inform SDK Wrapper to passively collect data on behalf of an end user. Validic ensures that our Mobile SDK makes use of the minimal scopes needed for our supported data types.

Availability

Not all devices support HealthKit (e.g. iPads running iOS 16 or lower and other platforms such as Android). To check if HealthKit is available, Apple provides an API: [HKHealthStore isHealthDataAvailable]. For convenience, Validic provides a Cordova method to check this value: ValidicMobile.InformHealthKit.isHealthKitAvailable(). Check if HealthKit is available on the device before attempting to access health data:

const healthKitAvailable = await ValidicMobile.InformHealthKit.isHealthKitAvailable();
if (!healthKitAvailable) {
    console.log('HealthKit is not available on this device.');
    return;
}

// Do HealthKit stuff here

Sample Types

Supported Sample types are available in the ValidicMobile.InformHealthKit.SampleType object. Currently, the supported sample types are:

HKCategoryTypeIdentifierAppleStandHour
HKCategoryTypeIdentifierMindfulSession
HKCategoryTypeIdentifierSleepAnalysis
HKCorrelationTypeIdentifierBloodPressure
HKCorrelationTypeIdentifierFood
HKQuantityTypeIdentifierActiveEnergyBurned
HKQuantityTypeIdentifierAppleExerciseTime
HKQuantityTypeIdentifierBasalEnergyBurned
HKQuantityTypeIdentifierBloodGlucose
HKQuantityTypeIdentifierBloodPressureDiastolic
HKQuantityTypeIdentifierBloodPressureSystolic
HKQuantityTypeIdentifierBodyFatPercentage
HKQuantityTypeIdentifierBodyMass
HKQuantityTypeIdentifierBodyMassIndex
HKQuantityTypeIdentifierBodyTemperature
HKQuantityTypeIdentifierDietaryCalcium
HKQuantityTypeIdentifierDietaryCarbohydrates
HKQuantityTypeIdentifierDietaryCholesterol
HKQuantityTypeIdentifierDietaryEnergyConsumed
HKQuantityTypeIdentifierDietaryFatSaturated
HKQuantityTypeIdentifierDietaryFatTotal
HKQuantityTypeIdentifierDietaryFiber
HKQuantityTypeIdentifierDietaryProtein
HKQuantityTypeIdentifierDietarySodium
HKQuantityTypeIdentifierDietaryWater
HKQuantityTypeIdentifierDistanceWalkingRunning
HKQuantityTypeIdentifierDistanceWheelchair
HKQuantityTypeIdentifierFlightsClimbed
HKQuantityTypeIdentifierHeartRate
HKQuantityTypeIdentifierHeight
HKQuantityTypeIdentifierInsulinDelivery
HKQuantityTypeIdentifierOxygenSaturation
HKQuantityTypeIdentifierPushCount
HKQuantityTypeIdentifierRestingHeartRate
HKQuantityTypeIdentifierStepCount
HKWorkoutTypeIdentifier

Subscriptions

Set Subscriptions

To subscribe to HealthKit sample types, pass an array of ValidicMobile.InformHealthKit.SampleType values (which are HealthKit sample type identifier strings) to setSubscriptions:

// Subscribe to body mass and steps
const sampleTypes = [ValidicMobile.InformHealthKit.SampleType.HKQuantityTypeIdentifierBodyMass, ValidicMobile.InformHealthKit.SampleType.HKQuantityTypeIdentifierStepCount]
await ValidicMobile.InformHealthKit.setSubscriptions(sampleTypes);

Calling this function a second time will replace any existing subscriptions with the new sampleTypes list.

To remove all subscriptions, pass an empty array:

await ValidicMobile.InformHealthKit.setSubscriptions([]);

Note: Calling ValidicMobile.InformCore.endSession(); will remove all HealthKit subscriptions and stop listening for new data.

Fetching Historical Data

The Validic Mobile library provides the ability to query up to 180 days of data for a subset of data types provided by HealthKit by specifying one of more values of the HealthKit.HistoricalSet enum.

Two historical sets are available:

HealthKit.HistoricalSet.SUMMARY - Daily activity data (including steps)
HealthKit.HistoricalSet.WORKOUT - Workout data

To fetch historical HealthKit data, call the HealthKit.fetchHistoricalSets function and pass in an object with the datasets you want to fetch under the historicalSets key. You can also pass in from and to keys as Dates or ISO8601 date strings to limit the time period that gets fetched. The function returns a promise that resolves when historical records have been queued for upload to the server.

On success, promise resolves with an object that contains the number of records processed for each record type. The promise rejects with an error message if invalid parameters are passed.

// Define dates to fetch (optional - if omitted, last 180 days will be fetched)
const start = new Date();
const end = new Date();
start.setDate(end.getDate()-29);

const result = await ValidicMobile.InformHealthKit.fetchHistoricalSets({
    historicalSets: [ValidicMobile.InformHealthKit.HistoricalSet.SUMMARY, ValidicMobile.InformHealthKit.HistoricalSet.WORKOUT],
    from: start,
    to: end
}});

Doing this may display a permission dialogue from HealthKit, so it's important to call this at an appropriate time in your app. It is recommended to explain to the user why you want this data before attempting to fetch it. This operation may take several seconds to complete, so it would be advisable to display an activity indicator to the user until the promise resolves.

When the fetch completes, all the data has been fetched locally and queued up for submission to the server. The amount of time needed to upload the records may vary based on the user's internet speed. The queued records are uploaded automatically by the library based on connectivity, but it is possible for the user to suspend the app before all the records have been uploaded, in which case the remaining records will be uploaded when the user resumes the app. This should be kept in mind when receiving records from the Validic server.

Apple Health Events

A ValidicMobile.InformHealthKit.RecordsProcessedEvent event will be fired every time HealthKit processes new records. The event contains a summary of the number of records collected per InformRecordType. To listen for the event, add an event listener to the document:

document.addEventListener(ValidicMobile.InformHealthKit.RecordsProcessedEvent, (summary) => {
    console.log(JSON.stringify(summary)); // {"Summary": 1, "Measurement": 2}
});