iOS HealthKit Integration Guide

Overview

This guide walks you through the complete integration of the Open Wearables iOS SDK into a native Swift application, from backend setup to production deployment.

Set up backend authentication endpoint

Configure the SDK in your iOS app

Implement sign-in flow

Request health permissions

Start background sync

Read the Mobile SDK Integration Guide first. It covers what is the same on every platform: authentication, the backend token endpoint, the SDK lifecycle, and the production checklist. This page shows the Swift code for each step.

Step 1: Backend Setup

Your backend exchanges your app credentials for user-scoped SDK tokens and forwards them to the app - the app never sees app_id / app_secret. See Backend Endpoint for the setup and example code.

Step 2: SDK Configuration

Configure the SDK once at app startup, typically in your AppDelegate or app initialization code.

import OpenWearablesHealthSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        let sdk = OpenWearablesHealthSDK.shared

        // Optional: Set up logging
        sdk.onLog = { message in
            print("[HealthSDK] \(message)")
        }

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

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

        return true
    }

    // Required for background URL session support
    func application(
        _ application: UIApplication,
        handleEventsForBackgroundURLSession identifier: String,
        completionHandler: @escaping () -> Void
    ) {
        OpenWearablesHealthSDK.setBackgroundCompletionHandler(completionHandler)
    }
}

Configuration Options

Parameter	Description
`host`	The Open Wearables API base URL — host only, without path suffix (e.g. `https://api.openwearables.io`)

Provide only the base host URL, e.g. https://your-domain.com. Do not append /api/v1/ or any other path — the SDK adds the required path prefix automatically.

// For self-hosted Open Wearables
sdk.configure(host: "https://your-domain.com")

Session Restoration

The SDK automatically persists credentials in the iOS Keychain. On app launch, call configure() to restore any existing session:

sdk.configure(host: "https://api.openwearables.io")

// Check if user was previously signed in
if sdk.isSessionValid {
    print("Welcome back!")
    // User is already signed in, can resume sync
} else {
    // Need to sign in first
}

After getting credentials from your backend, sign in with the SDK. The SDK supports two authentication modes:

The userId parameter is the Open Wearables User ID (UUID) — the id returned by the Create User endpoint. Do not pass your own external_user_id here.

Token-Based Authentication (Recommended)

func connectHealth() {
    // 1. Get tokens from YOUR backend (e.g. https://api.yourapp.com)
    yourAPI.post("/api/health/connect") { result in
        switch result {
        case .success(let credentials):
            // 2. Sign in with the SDK
            OpenWearablesHealthSDK.shared.signIn(
                userId: credentials.userId,
                accessToken: credentials.accessToken,
                refreshToken: credentials.refreshToken, // Optional: enables auto-refresh
                apiKey: nil
            )
            print("Connected: \(credentials.userId)")

        case .failure(let error):
            print("Failed to connect: \(error)")
        }
    }
}

API Key Authentication

For simpler setups (e.g. internal tools), you can use API key authentication directly:

OpenWearablesHealthSDK.shared.signIn(
    userId: "user123",
    accessToken: nil,
    refreshToken: nil,
    apiKey: "your_api_key"
)

API key authentication embeds the key in the app. Only use this for internal or trusted applications. For production apps, always use token-based authentication.

Automatic Token Refresh

When you provide a refreshToken, the SDK automatically handles 401 responses by refreshing the access token and retrying the request. No additional configuration is needed. You can also update tokens manually if needed:

OpenWearablesHealthSDK.shared.updateTokens(
    accessToken: newAccessToken,
    refreshToken: newRefreshToken
)

Step 4: Request Permissions

Request access to specific health data types using the HealthDataType enum:

func requestHealthPermissions() {
    OpenWearablesHealthSDK.shared.requestAuthorization(
        types: [
            .steps,
            .heartRate,
            .restingHeartRate,
            .sleep,
            .workout,
            .activeEnergy,
            .bodyMass,
        ]
    ) { granted in
        if granted {
            print("Health permissions granted")
        } else {
            print("Some permissions were denied")
        }
    }
}

The HealthDataType enum provides type-safe access to all supported health data types. The string-based requestAuthorization(types: [String], completion:) overload is deprecated — use the enum variant instead.

On iOS, users can grant partial permissions. The SDK will sync whatever data the user allows. Apple’s privacy model means your app cannot determine which specific types were denied.

iOS Permission UI

When requesting permissions, iOS shows a system dialog listing all requested data types. Users can toggle each type individually.

Request only the data types you actually need. Requesting too many types can overwhelm users and reduce acceptance rates.

Step 5: Start Background Sync

Enable background sync to keep data flowing even when your app is in the background:

OpenWearablesHealthSDK.shared.startBackgroundSync { started in
    print("Background sync started: \(started)")
}

Controlling Sync History Depth

By default, the SDK syncs all available historical data on the first sync. Use the syncDaysBack parameter to limit how far back the sync goes:

// Sync only the last 90 days of data
OpenWearablesHealthSDK.shared.startBackgroundSync(syncDaysBack: 90) { started in
    print("Sync started: \(started)")
}

// Sync last 30 days
OpenWearablesHealthSDK.shared.startBackgroundSync(syncDaysBack: 30) { started in
    print("Sync started: \(started)")
}

// Full sync — all available history (default)
OpenWearablesHealthSDK.shared.startBackgroundSync { started in
    print("Sync started: \(started)")
}

Parameter	Type	Default	Description
`syncDaysBack`	`Int?`	`nil`	Number of days of historical data to sync. Syncs from the start of the day that many days ago. When `nil`, syncs all available history. The value is persisted and used for subsequent background syncs until changed.

Background Sync Behavior

Mechanism	Description
HealthKit Observer Queries	Immediate delivery when new health data is written
BGAppRefreshTask	Scheduled every ~15 minutes (system-managed)
BGProcessingTask	Network-required background processing

Background sync frequency is controlled by iOS and may vary based on battery level, network conditions, and user behavior. The 15-minute interval is a minimum - actual syncs may be less frequent.

Stop Sync

OpenWearablesHealthSDK.shared.stopBackgroundSync()

Log Level

Control SDK log output using setLogLevel. By default, the SDK uses .debug, which outputs logs only in debug builds:

let sdk = OpenWearablesHealthSDK.shared

// Always show logs (including release builds)
sdk.setLogLevel(.always)

// Only show logs in debug builds (default)
sdk.setLogLevel(.debug)

// Disable all logs
sdk.setLogLevel(.none)

Level	Description
`.none`	No logs at all (neither console nor `onLog` callback)
`.always`	Logs are always emitted regardless of build configuration
`.debug`	Logs are emitted only in debug builds (default)

Set .always during development or when troubleshooting sync issues in production. Switch to .none if you want to suppress all SDK output.

Complete Integration Example

Here’s a complete service class showing the full integration:

import OpenWearablesHealthSDK
import Foundation

class HealthSyncService {
    static let shared = HealthSyncService()

    private let sdk = OpenWearablesHealthSDK.shared
    private let backendURL: String
    private var authToken: String?

    var isConnected: Bool {
        return sdk.isSessionValid
    }

    private init() {
        self.backendURL = "https://api.yourapp.com"
    }

    /// Initialize the health sync service
    func initialize() {
        sdk.onLog = { message in
            print("[HealthSync] \(message)")
        }

        // Enable logs in all builds for debugging (default is .debug)
        sdk.setLogLevel(.always)

        sdk.onAuthError = { statusCode, message in
            print("[HealthSync] Auth error \(statusCode): \(message)")
            if statusCode == 401 {
                // Handle token expiration in your app
                NotificationCenter.default.post(name: .healthAuthExpired, object: nil)
            }
        }

        sdk.configure(host: "https://api.openwearables.io")
    }

    /// Connect health data for the current user
    func connect(authToken: String, completion: @escaping (Result<Void, Error>) -> Void) {
        self.authToken = authToken

        // 1. Get tokens from YOUR backend (e.g. https://api.yourapp.com)
        var request = URLRequest(url: URL(string: "\(backendURL)/api/health/connect")!)
        request.httpMethod = "POST"
        request.setValue("Bearer \(authToken)", forHTTPHeaderField: "Authorization")
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")

        URLSession.shared.dataTask(with: request) { [weak self] data, response, error in
            guard let self = self else { return }

            if let error = error {
                completion(.failure(error))
                return
            }

            guard let data = data,
                  let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
                  let userId = json["userId"] as? String,
                  let accessToken = json["accessToken"] as? String else {
                completion(.failure(NSError(domain: "", code: -1, userInfo: [
                    NSLocalizedDescriptionKey: "Failed to parse credentials"
                ])))
                return
            }

            // 2. Sign in with SDK
            self.sdk.signIn(
                userId: userId,
                accessToken: accessToken,
                refreshToken: json["refreshToken"] as? String,
                apiKey: nil
            )

            // 3. Request permissions and start sync
            self.sdk.requestAuthorization(types: [
                .steps, .heartRate, .sleep, .workout, .activeEnergy
            ]) { granted in
                if granted {
                    self.sdk.startBackgroundSync(syncDaysBack: 90) { started in
                        if started {
                            completion(.success(()))
                        } else {
                            completion(.failure(NSError(domain: "", code: -1, userInfo: [
                                NSLocalizedDescriptionKey: "Failed to start sync"
                            ])))
                        }
                    }
                } else {
                    completion(.failure(NSError(domain: "", code: -1, userInfo: [
                        NSLocalizedDescriptionKey: "Health permissions not granted"
                    ])))
                }
            }
        }.resume()
    }

    /// Disconnect health data
    func disconnect() {
        sdk.stopBackgroundSync()
        sdk.signOut()
    }

    /// Force a full re-sync of all data
    func resyncAllData() {
        sdk.stopBackgroundSync()
        sdk.resetAnchors()
        sdk.startBackgroundSync { _ in }
    }
}

extension Notification.Name {
    static let healthAuthExpired = Notification.Name("healthAuthExpired")
}

Using the Service

class HealthViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        HealthSyncService.shared.initialize()
    }

    @IBAction func connectHealthTapped(_ sender: Any) {
        guard let authToken = getAuthToken() else { return }

        HealthSyncService.shared.connect(authToken: authToken) { result in
            DispatchQueue.main.async {
                switch result {
                case .success:
                    self.showAlert(title: "Success", message: "Health data connected!")
                case .failure(let error):
                    self.showAlert(title: "Error", message: error.localizedDescription)
                }
            }
        }
    }

    @IBAction func disconnectTapped(_ sender: Any) {
        HealthSyncService.shared.disconnect()
        showAlert(title: "Disconnected", message: "Health sync stopped.")
    }

    private func showAlert(title: String, message: String) {
        let alert = UIAlertController(title: title, message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }
}

Data Sync Endpoint

The SDK sends health data to:

POST {host}/api/v1/sdk/users/{userId}/sync

Data is automatically normalized to the Open Wearables unified data model and can be accessed through the standard API endpoints.

Internal Architecture

The SDK uses a modular architecture with several internal components:

Component	Purpose
Anchors	Per-user `HKQueryAnchor` persistence for incremental sync
Background	HealthKit observer queries + `BGTaskScheduler` management
Keychain	Secure credential storage using iOS Security framework
Outbox	Persistent upload queue with retry logic for failed uploads
Session	Resumable sync state tracking (survives app restarts)
Types	HealthKit type mapping and data serialization

Getting started

Architecture

Health Scores

Providers

Open Wearables Mobile App

Mobile SDK

MCP Server

Developer Portal

Developer Guides

Configuration

Deployment

Support

iOS HealthKit Integration Guide

Overview

Step 1: Backend Setup

Step 2: SDK Configuration

Configuration Options

Session Restoration

Token-Based Authentication (Recommended)

API Key Authentication

Automatic Token Refresh

Step 4: Request Permissions

iOS Permission UI

Step 5: Start Background Sync

Controlling Sync History Depth

Background Sync Behavior

Stop Sync

Log Level

Complete Integration Example

Using the Service

Data Sync Endpoint

Internal Architecture

Next Steps

Troubleshooting

Data Types

​Overview

​Step 1: Backend Setup

​Step 2: SDK Configuration

​Configuration Options

​Session Restoration

​Step 3: Sign In

​Token-Based Authentication (Recommended)

​API Key Authentication

​Automatic Token Refresh

​Step 4: Request Permissions

​iOS Permission UI

​Step 5: Start Background Sync

​Controlling Sync History Depth

​Background Sync Behavior

​Stop Sync

​Log Level

​Complete Integration Example

​Using the Service

​Data Sync Endpoint

​Internal Architecture

​Next Steps

Troubleshooting

Data Types

Overview

Step 1: Backend Setup

Step 2: SDK Configuration

Configuration Options

Session Restoration

Step 3: Sign In

Token-Based Authentication (Recommended)

API Key Authentication

Automatic Token Refresh

Step 4: Request Permissions

iOS Permission UI

Step 5: Start Background Sync

Controlling Sync History Depth

Background Sync Behavior

Stop Sync

Log Level

Complete Integration Example

Using the Service

Data Sync Endpoint

Internal Architecture

Next Steps