GuidesAPI ResourcesValidicSupportStatusChangelog
Guides
Start typing to search…

Using Apple Health in the iOS Mobile Inform SDK

Native iOS ==> Apple Health framework

⚠️

Recent behavior in iOS 26 may cause older summary records to surface more frequently, potentially leading to delays in new data processing.

We’ve released SDK updates that help reduce unnecessary processing. Make sure you are using the following version or later:

  • Inform iOS Native SDK v2.1.0

Updating now ensures your app remains as performant as possible and we’re here if you need support.

The Validic Inform iOS Mobile SDK offers native mobile libraries which you can implement into your mobile project to power data syncing with the Apple Health data aggregation platform.

The Validic Inform iOS Mobile SDK supports Apple Health for native iOS. 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 other fitness and health apps, as well as the Apple Watches.

Installation

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

You can find more details on the installation process 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


⚠️

Recent behavior in iOS 26 may cause older summary records to surface more frequently, potentially leading to delays in new data processing.

We’ve released SDK updates that help reduce unnecessary processing. Make sure you are using the following version or later:

  • Inform iOS Native SDK v2.1.0

Updating now ensures your app remains as performant as possible and we’re here if you need support.

This project integrates Apple Health with the Validic Mobile Inform SDK 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.

Subscribe to new health data

Subscribing to HealthKit data only needs to be done once for a user session. The subscriptions will be persisted across app launches in the VLDSession object. A typical use of the Validic HealthKit framework would be to create a UISwitch that adds the required subscriptions when turned on and removes them when turned off. Example:

func toggleHealthKit(_ sender: UISwitch) {
    if sender.isOn {
        // To subscribe to specific sample types (e.g. steps, body mass, and sleep analysis):
        let sampleTypes = [HKQuantityType(.stepCount), HKQuantityType(.bodyMass), HKCategoryType(.sleepAnalysis)]
        // OR, to subscribe to all supported sample types (not recommended):
        let sampleTypes = VLDHealthKitSubscription.supportedObjectTypes() as! Set<HKSampleType>

        VLDHealthKitManager.sharedInstance().setSubscriptions(Array(sampleTypes), completion: nil)
    }
    else {
        VLDHealthKitManager.sharedInstance().setSubscriptions([], completion: nil)
    }
}

Retrieve data continuously

To properly enable the continuous delivery of data in the background and foreground, the subscription observers need to be recreated immediately when the app is launched from a suspended or terminated state. To do this, you need to call [VLDHealthKitManager -observeCurrentSubscriptions] inside your application delegate's application:didFinishLaunchingWithOptions: function. For example:

func application(_ application: UIApplication didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool {
    VLDHealthKitManager.sharedInstance().observeCurrentSubscriptions()
    return true
}

Note: Calling [[VLDSession] sharedInstance] endSession] in Objective-C or VLDSession.sharedInstance().end() in Swift will remove all HealthKit subscriptions and stop listening for new data.

Please note, there are some special considerations that you need to be aware of when working with Apple Health.

Subscribe to Intraday steps

The Validic Mobile library supports retrieving fine-grained step data through VLDInformIntraday. This is a premium feature and is not enabled by default. If you have access, you can set VLDHealthKitManager.sharedInstance().processIntraday to true to enable sending intraday step data to Inform. When processIntraday is enabled, intraday data will automatically be gathered as long as the user is subscribed to the HKQuantityTypeIdentifierStepCount sample type.

For more information on intraday activity data, please see High-Frequency Data.

Fetch historical data

By sample type (recommended)

The ValidicHealthKit framework provides the ability to query up to 180 days of historical data for a subset of data types provided by HealthKit by passing a list of HKSampleTypes.

To fetch historical HealthKit data, call the fetchHistoricalSampleTypes: method on VLDHealthKitManager and pass in the HKSampleTypes you want to fetch, along with from and to parameters.

The sampleTypes array parameter can include any HKSampleTypes that are supported (see VLDHealthKitSubscription.supportedObjectTypes()).

Important Notes:

  • Passing any HKSampleTypes that the user has not yet been prompted for permission to access will cause HealthKit to display a permissions dialog. To avoid this, we recommend only fetching historical data for sample types the user is subscribed to.
  • If the list of HKSampleTypes passed to fetchHistoricalSampleTypes: is incomplete for a given Validic record type, existing records of that type may be overwritten with partial data. For example, if the user is subscribed to these types, a subscription-based Summary record will include steps, flights climbed, and stand hours; fetching history with only the step count type will remove the flights climbed and stand hours values from any existing records with dates that overlap the historical request dates. To avoid this, we recommend always including all subscribed sample types that are used in the record type - use VLDHealthKitSubscription.sampleTypes(forRecordType:) and intersect it with the user's current subscriptions.
  • Fetching historical data for the step count type will only create Summary records, not Intraday records. To fetch historical Intraday data, continue to use the fetchHistoricalSets: API.

The from and to parameters should be DateComponents with the year, month, and day components defined. Data is always pulled in full-day increments, so any time data on the DateComponents (hour, minute, second, etc) will be ignored. Historical data cannot go back more than 179 days before the current day.

Example pulling 30 days of historical Summary data, limited to current user-subscribed summary types to avoid a HealthKit permissions prompt:

// Get a list of current subscriptions that are used in Summary records
let currentSubscriptions = Set(VLDHealthKitManager.sharedInstance().subscriptions() ?? [])
let summarySubscriptions = Set(VLDHealthKitSubscription.sampleTypes(forRecordType: .summary))
let currentSummarySubscriptions = currentSubscriptions.intersection(summarySubscriptions)

let toDate = Calendar.current.startOfDay(for: Date())
let toDateComponents = Calendar.current.dateComponents([.year, .month, .day], from: toDate)
let fromDate = Calendar.current.date(byAdding: .day, value: -29, to: toDate, wrappingComponents: false)!
let fromDateComponents = Calendar.current.dateComponents([.year, .month, .day], from: fromDate)
VLDHealthKitManager.sharedInstance().fetchHistoricalSampleTypes(
    Array(currentSummarySubscriptions),
    from: fromDateComponents,
    to: toDateComponents)
    { (results: [String: NSNumber]?, error: Error?) in
    // Historical fetch complete - only summary records were created
    }

By VLDHealthKitHistoricalSet (old way)

The ValidicHealthKit framework also provides the ability to query up to 180 days of historical data for a subset of data types provided by HealthKit by using one of more values of the VLDHealthKitHistoricalSet enum.

Three historical sets are available:

  • VLDHealthKitHistoricalSetSummary - Step data
  • VLDHealthKitHistoricalSetWorkout - Workout data
  • VLDHealthKitHistoricalSetIntraday - Intraday step data (Premium feature, with access to only 7 days of historical data)

To fetch historical HealthKit data, call the fetchHistoricalSets: method on VLDHealthKitManager and pass in the historical sets you want to fetch, along with from and to parameters.

The from and to parameters should be DateComponents with the year, month, and day components defined. Data is always pulled in full-day increments, so any time data on the DateComponents (hour, minute, second, etc) will be ignored. Historical data cannot go back more than 179 days before the current day.

Example pulling 30 days of history:

The ValidicHealthKit framework provides the ability to query up to 180 days of historical data for a subset of data types provided by HealthKit by using one of more values of the VLDHealthKitHistoricalSet enum.

Three historical sets are available:

VLDHealthKitHistoricalSetSummary - Step data
VLDHealthKitHistoricalSetWorkout - Workout data
VLDHealthKitHistoricalSetIntraday - Intraday step data (Premium feature, with access to only 7 days of historical data)
To fetch historical HealthKit data, call the fetchHistoricalSets: method on VLDHealthKitManager and pass in the historical sets you want to fetch, along with from and to parameters.

The from and to parameters should be DateComponents with the year, month, and day components defined. Data is always pulled in full-day increments, so any time data on the DateComponents (hour, minute, second, etc) will be ignored. Historical data cannot go back more than 179 days before the current day.

Example pulling 30 days of history:

Doing this may display a permission dialog 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 is advisable to display an activity indicator to the user until the completion block is called.

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 amount of history fetched and 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. 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.

Updated 10 days ago