The Health Kit namespace, introduced in iOS 8, allows applications to record, track, and access health-related information to a common persistent store.
To use Health Kit services, applications must be developed using an "Explicit App ID" and a provisioning profile that includes the explicit ID and Health Kit permissions.
In addition, applications must have an Entitlements.plist that contains the key com.apple.developer.healthkit of type Boolean with a value of true.
At runtime, the application must request access to the specific types of health data in which it is interested. The user will interact with a permissions dialog in the Health app that allows them fine-grained control over what health information they will allow.
C# Example
var temperatureKey = HKQuantityTypeIdentifierKey.BodyTemperature; var tempQuantityType = HKObjectType.GetQuantityType (temperatureKey); var hks = new HKHealthStore (); var success = await hks.RequestAuthorizationToShareAsync (new NSSet (new [] { tempQuantityType }), new NSSet ());
The result of the HealthKit.HKHealthStore.RequestAuthorizationtoShareAsync method indicates only that the user interacted with the permissions dialog, it does not indicate whether the user allowed any data sharing. For that, applications can use the HealthKit.HKHealthStore.GetAuthorizationStatus method:
C# Example
var access = healthKitStore.GetAuthorizationStatus (HKObjectType.GetQuantityType (HKQuantityTypeIdentifierKey.HeartRate)); if (access.HasFlag (HKAuthorizationStatus.SharingAuthorized)) { //...etc...
Once permissions have been granted, creating and storing data involves creating an HealthKit.HKSample of a particular HealthKit.HKSampleType and then calling HealthKit.HKHealthStore.SaveObject or HealthKit.HKHealthStore.SaveObjectAsync.
Apple's philosophy regarding attempts to store or read non-permitted information is that such attempts should not cause runtime exceptions. Rather, methods such as HealthKit.HKHealthStore.RequestAuthorizationToShare and HealthKit.HKStore.SaveObject are defined with completion callback handlers that are passed a non-null Foundation.NSError argument in the case of an error. Application developers using such methods should take special care to check for success, as it is highly likely that users will be cautious about access to their health data.
In contrast, Xamarin's asynchronous versions of such methods (such as HealthKit.HKHealthStore.RequestAutorizationToShareAsync and HealthKit.HKHealthStore.SaveObjectAsync) will throw an Foundation.NSErrorException on failure or if the method is not allowed by the end user.
C# Example
//Apple's philosophy: no exception var myCurrentTemp = HKQuantity.FromQuantity (HKUnit.DegreeFahrenheit, 98.6); var tempSample = HKQuantitySample.FromType (tempQuantityType, myCurrentTemp, new NSDate (), new NSDate (), new NSDictionary()); hks.SaveObject(tempSample, (success, error) => { if(error != null) { //...etc...
C# Example
//Xamarin's philosophy: Lack of permissions raises exception protected async void StoreAsync(HKHealthStore store, HKQuantitySample sample) { try { var success = await store.SaveObjectAsync (sample); }catch(NSErrorException x) { Console.WriteLine (x); } }
There are several types of HealthKit.HKObjecTypes:
HealthKit.HKCharacteristicType objects represent static characterics of the user, such as date of birth or blood type (see HealthKit.HKCharacteristicTypeIdentifierKey), while HealthKit.HKSampleType objects represent data that are sampled over time. As of iOS 8, there is only one type of HealthKit.HKCategorySample, which is HealthKit.HKCategoryTypeIdentifierKey.SleepAnalysis. The large majority of Health Kit data types are defined in HealthKit.HKQuantityTypeIdentifierKey.
Manipulating data samples involves both an HealthKit.HKSampleType object and an HealthKit.HKSample to carry the data:
HealthKit.HKQuantitySamples may refer to an instantaneous measurement, in which case their HealthKit.HKQuantitySample.StartDate and HealthKit.HKQuantitySample.EndDate properties should be set to the same value. Other samples, such as step count, are measured over time and the start and end time should be set appropriately.
Data may have metadata associated with it. There are a number of predefined metadata keys in HealthKit.HKMetadataKey, but application developers are encouraged to created their own keys for metadata as well.
Health Kit supports units of measurement in the categories of mass, length, volume, and energy. This support includes conversion of values between measurement systems (for instance, if a user prefers Fahrenheit degrees but has a sensor that reports its data in Celsius). This is automatically supported within the Health app, but explicit conversions are also possible, as shown in the following example:
C# Example
var myFahrenheitTemp = HKQuantity.FromQuantity (HKUnit.DegreeFahrenheit, 98.6); var myCelsiusTemp = myFahrenheitTemp.GetDoubleValue (HKUnit.DegreeCelsius);
Type | Reason |
---|---|
HKAnchoredObjectQuery | An HealthKit.HKQuery that on its initial call returns the most recent result and in subsequent calls returns only data added after the initial call. |
HKAnchoredObjectResultHandler | The completion handler for HealthKit.HKAnchoredObjectQuery.ctor. |
HKAuthorizationStatus | Enumerates the permission of the app to read or write health data. |
HKBiologicalSex | Enumerates the biological sexes. |
HKBiologicalSexObject | Returned by HealthKit.HKHealthStore.GetBiologicalSex. |
HKBloodType | Enumerates known blood types. |
HKBloodTypeObject | Returned by HealthKit.HKHealthStore.GetBloodType |
HKBodyTemperatureSensorLocation | Enumerates the positions at which a thermometer takes its reading. |
HKCategorySample | An HealthKit.HKSample whose value is one of an enumerated type. |
HKCategoryType | An HealthKit.HKSampleType that currently has only one form: sleep analysis. |
HKCategoryTypeIdentifier | Enumerates the types of HealthKit.HKCategory; currently there is only the one form (Sleep Analysis). |
HKCategoryTypeIdentifierKey | Defines the keys to identify HealthKit.HKCategoryTypes. Currently just the one key for sleep analysis. |
HKCategoryValueSleepAnalysis | Enumerates the states of the slumberer: whether they are asleep or merely resting in bed. |
HKCharacteristicType | An HealthKit.HKObjectType that specifies a permanent aspect of the user. |
HKCharacteristicTypeIdentifier | Enumerates the forms of HealthKit.HKCharacteristicType. |
HKCharacteristicTypeIdentifierKey | Defines the constant name for a HealthKit.HKCharacteristicType. |
HKCorrelation | A correlation between two pieces of health data (for instance, blood pressure). |
HKCorrelationQuery | An HealthKit.HKQuery that returns only data that had been stored with correlations. (Note: Systolic and diastolic blood pressure readings are not correlated.) |
HKCorrelationQueryResultHandler | Completion handler for HealthKit.HKCorrelationQuery. |
HKCorrelationType | An HealthKit.HKSampleType that specifies a correlation between two types of data (for instance, blood pressure). |
HKCorrelationTypeKey | Defines the forms of HealthKit.HKCorrelation. |
HKErrorCode | Enumerates common errors made when accessing health data. |
HKHealthStore | HealthKit.HKHealthStore A connection to the system-wide database of health-related information. |
HKHeartRateSensorLocation | Enumerates the locations at which a heart rate monitor is attached. |
HKMetadata | A key-value store for various types of health-related metadata. |
HKMetadataKey | Defines the keys in the HealthKit.HKMetadata key-value dictionary. |
HKMetricPrefix | Enumerates metric prefixes, e.g., Centi-, Deca-, Deci-. Used with factory methods of HealthKit.HKUnit. |
HKObject | Base class to HealthKit.HKSample, which defines sampling data. |
HKObjectType | Base class for types of data storable in the Health Kit database. |
HKObserverQuery | An HealthKit.HKQuery that runs once initially and then is automatically executed when relevant data is added to the database . |
HKObserverQueryUpdateHandler | Update handler for HealthKit.HKObserverQuery objects. |
HKPredicateKeyPath | Documentation for this section has not yet been entered. |
HKQuantity | Represents a measurable quantity of a certain type of unit, with a double value and a HealthKit.HKUnit type. |
HKQuantityAggregationStyle | Enumerates whether an HealthKit.HKQuantityType is a cumulative measure (for instance, "active energy burned") or a discrete value (such as "blood alcohol content"). |
HKQuantitySample | A HealthKit.HKSample that has a magnitude (see HealthKit.HKQuantitySample.Quantity). |
HKQuantityType | A HKSampleType that represents either a cumulative or discrete sample. |
HKQuantityTypeIdentifier | Enumerates the types of HealthKit.HKQuantityType. |
HKQuantityTypeIdentifierKey | Types of HealthKit.HKQuantityType. |
HKQuery | Base class for querying Health Kit databases. |
HKQueryOptions | Enumerates options available for use with the HKQuery.GetPredicateForSamples method. |
HKSample | A measurement of health information. Base class for HealthKit.HKQuantitySample and HealthKit.HKCategorySample. |
HKSampleQuery | An HealthKit.HKQuery that retrieves HealthKit.HKSampleType data from the database. |
HKSampleQueryResultsHandler | Result handler for HealthKit.HKSampleQuery. |
HKSampleType | An HealthKit.HKObject that represents data that is sampled at a specific time or sampled over a time period. |
HKSource | A provider of health data, such as a particular sensor or application. |
HKSourceQuery | Documentation for this section has not yet been entered. |
HKSourceQueryCompletionHandler | Completion handler for HealthKit.HKSourceQuery. |
HKStatistics | Provides basic statistical operations on health information. |
HKStatisticsCollection | A group of related statistics (generally representing a time series). |
HKStatisticsCollectionEnumerator | Delegate handler for HealthKit.HKStatisticsCollection.EnumerateStatistics. |
HKStatisticsCollectionQuery | An HealthKit.HKQuery that produces a collection of statistics (for instance, number of steps per day for the previous month). |
HKStatisticsCollectionQueryInitialResultsHandler | Results handler for HealthKit.HKStatisticsCollectionQuery.SetInitialResultsHandler and HealthKit.HKStatisticsCollectionQuery.SetStatisticsUpdateHandler. |
HKStatisticsOptions | Enumerates options applicable to HealthKit.HKStatisticsQuery and HealthKit.HKStatisticsCollectionQuery objets. |
HKStatisticsQuery | An HealthKit.HKQuery that can calculate basic statistics (such as the sum and mean) on its constituent data. |
HKStatisticsQueryHandler | Results handler for HKStatisticsQuery. |
HKStoreSampleAddedCallback | Completion handler for HealthKit.HKHealthStore.AddSamples. |
HKUnit | Definitions and utility methods for manipulating measurements of mass, length, volume, and energy. |
HKUpdateFrequency | Enumerates the frequences for background delivery of data (see HealthKit.HKHealthStore.EnableBackgroundDelivery). |
HKWorkout | An HealthKit.HKSample that represents a physical workout. |
HKWorkoutActivityType | Enumerates various activities that are considered workouts. |
HKWorkoutEvent | A pause or resumption of a workout. |
HKWorkoutEventType | Enumerates events that can occur during a workout (Pause, Resume). |
HKWorkoutType | An HealthKit.HKSampleType representing a workout. |