iOS HealthKit SDK

Introduction

The Open Wearables iOS SDK (OpenWearablesHealthSDK) is a native Swift SDK for secure background synchronization of health data from Apple HealthKit to the Open Wearables platform. This is the core native implementation that powers health data sync on iOS. The Flutter SDK uses this SDK under the hood as a wrapper.

GitHub Repository

View source code, report issues, and contribute to the iOS SDK.

Features

Background Sync - Health data syncs even when your app is in the background via HealthKit observer queries and BGTaskScheduler
Streaming Sync - Memory-efficient streaming processing for large datasets
Resumable Sessions - Sync sessions survive app restarts and device reboots
Dual Authentication - Token-based auth with auto-refresh or API key authentication
Secure Storage - Credentials stored in iOS Keychain with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
Automatic Retry - Persistent outbox with retry logic for failed uploads
Per-User Isolation - State isolation between different user sessions
Network Monitoring - Connectivity-aware sync with automatic resume
Wide Data Support - Steps, heart rate, workouts, sleep, and 40+ data types

Requirements

Requirement	Details
iOS Version	iOS 15.0+
Swift	Swift 5.0+ (Swift tools 5.9)
Xcode	Xcode 15+
Apple Developer Account	Required for HealthKit entitlement
HealthKit Capability	Must be enabled in Xcode
Physical Device	HealthKit doesn’t work in iOS Simulator

Installation

Swift Package Manager
CocoaPods

Add the package to your Package.swift:

dependencies: [
    .package(url: "https://github.com/the-momentum/open_wearables_ios_sdk", from: "0.13.0")
]

Or in Xcode: File → Add Package Dependencies → paste the repository URL.

Add to your Podfile:

pod 'OpenWearablesHealthSDK', '~> 0.8.0'

Then run:

pod install

iOS Configuration

Add the following to your Info.plist:

<!-- Health data permission -->
<key>NSHealthShareUsageDescription</key>
<string>This app syncs your health data to your account.</string>

<!-- Background modes for sync -->
<key>UIBackgroundModes</key>
<array>
    <string>fetch</string>
    <string>processing</string>
</array>

<!-- Background task identifiers -->
<key>BGTaskSchedulerPermittedIdentifiers</key>
<array>
    <string>com.openwearables.healthsdk.task.refresh</string>
    <string>com.openwearables.healthsdk.task.process</string>
</array>

Then enable HealthKit capability in Xcode:

Open your .xcodeproj or .xcworkspace in Xcode
Select your target → Signing & Capabilities
Click + Capability → Add HealthKit
Check Background Delivery if you want updates while app is closed

Quick Start

Here’s the minimal code to get health sync working:

import OpenWearablesHealthSDK

class HealthService {
    let sdk = OpenWearablesHealthSDK.shared

    func initialize() {
        // 1. Set up logging (optional)
        sdk.onLog = { message in
            print("[Health] \(message)")
        }

        // 2. Set log level (optional — default is .debug)
        sdk.setLogLevel(.always)

        // 3. Handle auth errors (optional)
        sdk.onAuthError = { statusCode, message in
            print("Auth error: \(statusCode) - \(message)")
        }

        // 4. Configure the SDK with your host
        sdk.configure(host: "https://api.openwearables.io")

        // 5. Check if already signed in (session restored from Keychain)
        if sdk.isSessionValid {
            print("Session restored")
            return
        }

        // 6. Get credentials from YOUR backend, then sign in
        let credentials = yourBackend.getHealthCredentials()

        sdk.signIn(
            userId: credentials.userId,
            accessToken: credentials.accessToken,
            refreshToken: credentials.refreshToken,
            apiKey: nil
        )

        // 7. Request health permissions
        sdk.requestAuthorization(types: [.steps, .heartRate, .sleep, .workout]) { granted in
            if granted {
                // 8. Start background sync (sync last 90 days of data)
                sdk.startBackgroundSync(syncDaysBack: 90) { started in
                    print("Sync started: \(started)")
                }
            }
        }
    }
}

AppDelegate Setup

For background URL session support, add to your AppDelegate:

func application(
    _ application: UIApplication,
    handleEventsForBackgroundURLSession identifier: String,
    completionHandler: @escaping () -> Void
) {
    OpenWearablesHealthSDK.setBackgroundCompletionHandler(completionHandler)
}

Documentation

Integration Guide

Complete guide to integrating the SDK including authentication flow, backend setup, and best practices.

Troubleshooting

Common issues and their solutions for native iOS.

Supported Health Data Types

The SDK supports 40+ health data types via the HealthDataType enum. Pass these as enum values to requestAuthorization(types:completion:):

sdk.requestAuthorization(types: [.steps, .heartRate, .sleep, .workout]) { granted in
    // ...
}

Activity & Fitness

Enum Case	Description
`.steps`	Step count
`.distanceWalkingRunning`	Walking/running distance
`.distanceCycling`	Cycling distance
`.flightsClimbed`	Floors climbed
`.walkingSpeed`	Average walking speed
`.walkingStepLength`	Step length
`.walkingAsymmetryPercentage`	Walking asymmetry percentage
`.walkingDoubleSupportPercentage`	Walking double support percentage
`.sixMinuteWalkTestDistance`	6-minute walk test
`.activeEnergy`	Active energy burned
`.basalEnergy`	Basal (resting) energy burned

Heart & Vitals

Enum Case	Description
`.heartRate`	Heart rate measurements
`.restingHeartRate`	Resting heart rate
`.heartRateVariabilitySDNN`	HRV (SDNN)
`.vo2Max`	VO2 max
`.oxygenSaturation`	Blood oxygen
`.respiratoryRate`	Breathing rate

Body Measurements

Enum Case	Description
`.bodyMass`	Weight
`.height`	Height
`.bmi`	Body Mass Index
`.bodyFatPercentage`	Body fat %
`.leanBodyMass`	Lean body mass
`.waistCircumference`	Waist circumference (iOS 16+)
`.bodyTemperature`	Body temperature

Blood & Metabolic

Enum Case	Description
`.bloodGlucose`	Blood glucose level
`.insulinDelivery`	Insulin delivery (iOS 16+)
`.bloodPressureSystolic`	Systolic blood pressure
`.bloodPressureDiastolic`	Diastolic blood pressure
`.bloodPressure`	Blood pressure (correlation type)

Sleep & Mindfulness

Enum Case	Description
`.sleep`	Sleep sessions and stages
`.mindfulSession`	Meditation/mindfulness sessions

Reproductive Health

Enum Case	Description
`.menstrualFlow`	Menstrual flow
`.cervicalMucusQuality`	Cervical mucus quality
`.ovulationTestResult`	Ovulation test result
`.sexualActivity`	Sexual activity

Nutrition

Enum Case	Description
`.dietaryEnergyConsumed`	Calories consumed
`.dietaryCarbohydrates`	Carbs
`.dietaryProtein`	Protein
`.dietaryFatTotal`	Total fat
`.dietaryWater`	Water intake

Workouts

Enum Case	Description
`.workout`	All workout types with metadata (distance, energy, heart rate, running metrics, elevation, weather, swimming)

Aliases

Enum Case	Alias For
`.restingEnergy`	`.basalEnergy`
`.bloodOxygen`	`.oxygenSaturation`

Getting started

Architecture

Health Scores

Providers

Rabts Mobile App

Sync SDK

MCP Server

Developer Guides

Configuration

Support

Introduction

GitHub Repository

Features

Requirements

Installation

iOS Configuration

Quick Start

AppDelegate Setup

Documentation

Integration Guide

Troubleshooting

Supported Health Data Types

Next Steps

Integration Guide

API Reference

​Introduction

GitHub Repository

​Features

​Requirements

​Installation

​iOS Configuration

​Quick Start

​AppDelegate Setup

​Documentation

Integration Guide

Troubleshooting

​Supported Health Data Types

​Next Steps

Integration Guide

API Reference

Introduction

Features

Requirements

Installation

iOS Configuration

Quick Start

AppDelegate Setup

Documentation

Supported Health Data Types

Next Steps