iOS Guides | Samples

MonoTouch.HealthKit Namespace

The HealthKit namespace provides secure data storage and retrieval of health-related information.

Remarks

The Health Kit namespace, introduced in iOS 8, allows applications to record, track, and access health-related information to a common persistent store.

Provisioning, Permissions, and Profiles

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 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 HKHealthStore.GetAuthorizationStatus method:

C# Example

var access = healthKitStore.GetAuthorizationStatus (HKObjectType.GetQuantityType (HKQuantityTypeIdentifierKey.HeartRate));
if (access.HasFlag (HKAuthorizationStatus.SharingAuthorized)) {
//...etc...

Creating and storing data

Once permissions have been granted, creating and storing data involves creating an HKSample of a particular HKSampleType and then calling HKHealthStore.SaveObject or HKHealthStore.SaveObjectAsync.

Exception-handling differences between async and non-async methods

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 HKHealthStore.RequestAuthorizationToShare and HKStore.SaveObject are defined with completion callback handlers that are passed a non-null 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 HKHealthStore.RequestAutorizationToShareAsync and HKHealthStore.SaveObjectAsync) will throw an 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 HKObjecTypes:

HKCharacteristicType objects represent static characterics of the user, such as date of birth or blood type (see HKCharacteristicTypeIdentifierKey), while HKSampleType objects represent data that are sampled over time. As of iOS 8, there is only one type of HKCategorySample, which is HKCategoryTypeIdentifierKey.SleepAnalysis. The large majority of Health Kit data types are defined in HKQuantityTypeIdentifierKey.

Manipulating data samples involves both an HKSampleType object and an HKSample to carry the data:

HKQuantitySamples may refer to an instantaneous measurement, in which case their HKQuantitySample.StartDate and 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 HKMetadataKey, but application developers are encouraged to created their own keys for metadata as well.

Units of measurement and conversion

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);

Classes

TypeReason
HKActivitySummarySummarizes user activity for a specific day.
HKActivitySummaryQueryGets HKActivitySummary instances that match an NSPredicate.
HKActivitySummaryTypeObect that is used to request permission to read HKActivitySummary objects.
HKAnchoredObjectQueryAn HKQuery that on its initial call returns the most recent result and in subsequent calls returns only data added after the initial call.
HKAnchoredObjectResultHandlerThe completion handler for HKAnchoredObjectQuery.ctor.
HKAnchoredObjectResultHandler2Completion handler for anchored object queries.
HKAnchoredObjectUpdateHandler
HKAuthorizationStatusEnumerates the permission of the app to read or write health data.
HKBiologicalSexEnumerates the biological sexes.
HKBiologicalSexObjectReturned by HKHealthStore.GetBiologicalSex.
HKBloodTypeEnumerates known blood types.
HKBloodTypeObjectReturned by HKHealthStore.GetBloodType
HKBodyTemperatureSensorLocationEnumerates the positions at which a thermometer takes its reading.
HKCategorySampleAn HKSample whose value is one of an enumerated type.
HKCategoryTypeAn HKSampleType that currently has only one form: sleep analysis.
HKCategoryTypeIdentifierEnumerates the types of HKCategory; currently there is only the one form (Sleep Analysis).
HKCategoryTypeIdentifierKeyDefines the keys to identify HKCategoryTypes. Currently just the one key for sleep analysis.
HKCategoryValueContains a single value that indicates that a category value is not applicable to the category.
HKCategoryValueAppleStandHourEnumerates whether the user stood or not during an hour.
HKCategoryValueCervicalMucusQualityEnumerates the user's cervical mucus quality.
HKCategoryValueMenstrualFlowEnumerates the amount of menstrual flow.
HKCategoryValueOvulationTestResultEnumerates the results of an ovulation test.
HKCategoryValueSleepAnalysisEnumerates the states of the slumberer: whether they are asleep or merely resting in bed.
HKCdaDocumentContains the information that is represented in XML in a HealthKit store health document.
HKCdaDocumentSampleContains the information that is represented in XML in a HealthKit store health document.
HKCharacteristicTypeAn HKObjectType that specifies a permanent aspect of the user.
HKCharacteristicTypeIdentifierEnumerates the forms of HKCharacteristicType.
HKCharacteristicTypeIdentifierKeyDefines the constant name for a HKCharacteristicType.
HKCorrelationA correlation between two pieces of health data (for instance, blood pressure).
HKCorrelationQueryAn HKQuery that returns only data that had been stored with correlations. (Note: Systolic and diastolic blood pressure readings are not correlated.)
HKCorrelationQueryResultHandlerCompletion handler for HKCorrelationQuery.
HKCorrelationTypeAn HKSampleType that specifies a correlation between two types of data (for instance, blood pressure).
HKCorrelationTypeIdentifierContains constants that identify HealthKit correlation types.
HKCorrelationTypeKeyDefines the forms of HKCorrelation.
HKDeletedObjectRepresents samples that have been deleted from the store.
HKDetailedCdaErrors
HKDeviceHardware that generates or consumes HealthKit data.
HKDevicePropertyKeyHolds keys whose constant values relate to properties of a HKDevice.
HKDocumentQueryQueries for documents in the HealthKit store.
HKDocumentSampleAbstract HealthKit store health document.
HKDocumentTypeContains a constant that identifies the CDA document type.
HKDocumentTypeIdentifierEnumerates HealthKit document types.
HKDocumentTypeIdentifierExtensions
HKErrorCodeEnumerates common errors made when accessing health data.
HKErrorCodeExtensionsExtension methods for the MonoTouch.HealthKit.HKErrorCode enumeration.
HKFitzpatrickSkinTypeEnumerates skin types using the Fitzpatrick scale.
HKFitzpatrickSkinTypeObjectHolds skin-type data.
HKHealthStoreMonoTouch.HealthKit.HKHealthStore A connection to the system-wide database of health-related information.
HKHealthStore+NotificationsClass that contains handlers for Health Kit store notifications.
HKHeartRateSensorLocationEnumerates the locations at which a heart rate monitor is attached.
HKMetadataA key-value store for various types of health-related metadata.
HKMetadataKeyDefines the keys in the HKMetadata key-value dictionary.
HKMetricPrefixEnumerates metric prefixes, e.g., Centi-, Deca-, Deci-. Used with factory methods of HKUnit.
HKObjectBase class to HKSample, which defines sampling data.
HKObjectTypeBase class for types of data storable in the Health Kit database.
HKObserverQueryAn HKQuery that runs once initially and then is automatically executed when relevant data is added to the database .
HKObserverQueryUpdateHandlerUpdate handler for HKObserverQuery objects.
HKPredicateKeyPathContains constants that represent keys that identify predicate key paths for selecting HealthKit values.
HKQuantityRepresents a measurable quantity of a certain type of unit, with a double value and a HKUnit type.
HKQuantityAggregationStyleEnumerates whether an HKQuantityType is a cumulative measure (for instance, "active energy burned") or a discrete value (such as "blood alcohol content").
HKQuantitySampleA HKSample that has a magnitude (see HKQuantitySample.Quantity).
HKQuantityTypeA HKSampleType that represents either a cumulative or discrete sample.
HKQuantityTypeIdentifierEnumerates the types of HKQuantityType.
HKQuantityTypeIdentifierKeyTypes of HKQuantityType.
HKQueryBase class for querying Health Kit databases.
HKQueryAnchorRepresents the most recent sample that was returned by a previous anchored object query.
HKQueryOptionsEnumerates options available for use with the HKQuery.GetPredicateForSamples method.
HKSampleA measurement of health information. Base class for HKQuantitySample and HKCategorySample.
HKSampleQueryAn HKQuery that retrieves HKSampleType data from the database.
HKSampleQueryResultsHandlerResult handler for HealthKit.HKSampleQuery.
HKSampleTypeAn HKObject that represents data that is sampled at a specific time or sampled over a time period.
HKSourceA provider of health data, such as a particular sensor or application.
HKSourceQueryClass that represents a query for HealthKit data.
HKSourceQueryCompletionHandlerCompletion handler for HealthKit.HKSourceQuery.
HKSourceRevisionWraps HKSource, adding version information.
HKStatisticsProvides basic statistical operations on health information.
HKStatisticsCollectionA group of related statistics (generally representing a time series).
HKStatisticsCollectionEnumeratorDelegate handler for HKStatisticsCollection.EnumerateStatistics.
HKStatisticsCollectionQueryAn HKQuery that produces a collection of statistics (for instance, number of steps per day for the previous month).
HKStatisticsCollectionQueryInitialResultsHandlerResults handler for HKStatisticsCollectionQuery.SetInitialResultsHandler and HKStatisticsCollectionQuery.SetStatisticsUpdateHandler.
HKStatisticsCollectionQueryStatisticsUpdateHandler
HKStatisticsOptionsEnumerates options applicable to HKStatisticsQuery and HKStatisticsCollectionQuery objets.
HKStatisticsQueryAn HKQuery that can calculate basic statistics (such as the sum and mean) on its constituent data.
HKStatisticsQueryHandlerResults handler for MonoTouch.HKStatisticsQuery.
HKStoreSampleAddedCallbackCompletion handler for HKHealthStore.AddSamples.
HKSwimmingStrokeStyle
HKUnitDefinitions and utility methods for manipulating measurements of mass, length, volume, and energy.
HKUpdateFrequencyEnumerates the frequences for background delivery of data (see HKHealthStore.EnableBackgroundDelivery).
HKWeatherConditionEnumerates weather types.
HKWheelchairUseEnumerates constants that describe wheelchair use.
HKWheelchairUseObjectContains an enumeration that describes wheelchair use.
HKWorkoutAn HKSample that represents a physical workout.
HKWorkoutActivityTypeEnumerates various activities that are considered workouts.
HKWorkoutConfigurationContains workout configuration information.
HKWorkoutEventA pause or resumption of a workout.
HKWorkoutEventTypeEnumerates events that can occur during a workout (Pause, Resume).
HKWorkoutSessionLocationTypeEnumerates workout locations.
HKWorkoutSwimmingLocationType
HKWorkoutTypeAn HKSampleType representing a workout.