Integrate the Neurofit Vitals SDK into Your iOS App

The Neurofit Vitals SDK gives your iOS app a fully self-contained 60-second rear-camera scan that measures heart rate, HRV, and respiration rate entirely on-device. This guide walks you through every step from adding the package to handling your first live result.

Add the SDK via Swift Package Manager

In Xcode, go to File → Add Package Dependencies, paste the repository URL https://sdk.neurofit.app/vitals-ios, and choose Up to Next Major Version starting from 1.0.0. Xcode resolves and links the NeuroFitVitals library automatically.If you manage dependencies in a Package.swift manifest instead, add the following entry to your dependencies array and include "NeuroFitVitals" in the appropriate target’s dependencies:

Package.swift

dependencies: [
    .package(url: "https://sdk.neurofit.app/vitals-ios", from: "1.0.0")
]

The SDK binary is under 1 MB and contains no third-party analytics or tracking frameworks. It does not store images or transmit scan data off-device.

Add the camera permission entry to Info.plist

The SDK requires rear-camera access to capture the photoplethysmography signal from the user’s fingertip. Add the following key to your app’s Info.plist. Apple requires a human-readable purpose string that is shown to the user in the system permission dialog.

Info.plist

<key>NSCameraUsageDescription</key>
<string>Used to measure your heart rate and HRV during a 60-second finger scan.</string>

If this key is missing, the OS will terminate your app when the SDK attempts to open the camera. Make sure the string accurately describes the use case — App Review will reject purpose strings that are vague or misleading.

Initialize the SDK at app startup

Call VitalsSDK.configure once before any scan is presented — the @main entry point or AppDelegate.application(_:didFinishLaunchingWithOptions:) are both suitable. Calling configure more than once is a no-op after the first successful initialization.

App entry point (SwiftUI)

import SwiftUI
import NeuroFitVitals

@main
struct MyApp: App {
    init() {
        VitalsSDK.configure(
            licenseKey: "YOUR_LICENSE_KEY",
            configuration: VitalsSDKConfiguration(
                locale: .current,
                tintColor: .systemBlue,
                enableHaptics: true
            )
        )
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

Store your license key in your app’s secrets manager or a .xcconfig file that is excluded from version control — never commit it directly to source code. Use Bundle.main.infoDictionary to read it at runtime.

Present the scan view controller

The SDK provides a ready-made scan UI that handles finger placement guidance, countdown, and quality feedback. You can present it from UIKit or embed it in SwiftUI.

UIKit
SwiftUI

Instantiate VitalsScanViewController, assign your delegate, and present it modally. The SDK manages its own navigation and dismissal.

UIKit

import NeuroFitVitals

let scanVC = VitalsScanViewController()
scanVC.delegate = self
navigationController?.present(scanVC, animated: true)

Use VitalsScanView inside a .sheet modifier. The closure-based API fits naturally into SwiftUI’s declarative model.

SwiftUI

import NeuroFitVitals

.sheet(isPresented: $showingScan) {
    VitalsScanView(
        onComplete: { result in
            handleResult(result)
        },
        onError: { error in
            handleError(error)
        }
    )
}

Implement VitalsScanDelegate or use result closures

The delegate pattern (UIKit) and the closure API (SwiftUI) both surface the same three events: scan completion, progress updates, and errors. The example below shows the full UIKit delegate implementation.

VitalsScanDelegate

import NeuroFitVitals

extension ScanHostViewController: VitalsScanDelegate {

    func vitalsScan(_ scan: VitalsScan, didComplete result: VitalsResult) {
        guard result.qualityTier == .accepted else {
            // Signal was too noisy — ask the user to try again
            showRetryPrompt()
            return
        }
        print("HR: \(result.heartRate) bpm | RMSSD: \(result.rmssd) ms | SDNN: \(result.sdnn) ms")
        print("Breathing: \(result.breathingRate.map { "\($0) bpm" } ?? "not available")")
    }

    func vitalsScan(_ scan: VitalsScan, didUpdate progress: ScanProgress) {
        // progress.fraction is a Double from 0.0 to 1.0
        progressBar.progress = Float(progress.fraction)
    }

    func vitalsScan(_ scan: VitalsScan, didFailWith error: VitalsError) {
        // Handle errors: .cameraPermissionDenied, .licenseInvalid, .scanInterrupted, .unknown
        showErrorAlert(error.localizedDescription)
    }
}

Always check qualityTier before reading any metric values. When the tier is .withheld, the numeric fields are not populated. See Processing and Storing Vitals Scan Results for the full result model.

Handle errors and edge cases

The SDK surfaces errors through VitalsError. The three most common cases and their recommended responses are listed below.

.cameraPermissionDenied

The user denied camera access or revoked it in Settings. Display a prompt explaining why the permission is needed and direct the user to Settings → Privacy & Security → Camera to re-enable it. You can deep-link there with UIApplication.openSettingsURLString.

.licenseInvalid

The license key was rejected by the on-device validator. Verify the key in your Neurofit developer dashboard and confirm you are reading it correctly from your app configuration. This error is not recoverable at runtime without a valid key.

.scanInterrupted

The scan was cancelled mid-session — for example, because the app moved to the background or the user navigated away. You can immediately offer a retry without any additional reset step.

.unknown

An unexpected condition occurred that does not map to any of the named error cases. Log the error for diagnostics and surface a generic failure message to the user. If this error occurs consistently, contact support@neurofit.app with your SDK version and reproduction steps.

The Neurofit Vitals SDK requires iOS 15 or later. Update your deployment target in your Xcode project settings if needed.

The camera is not available in the iOS Simulator. Always test scan functionality on a physical device. Attempting to present VitalsScanViewController in the Simulator will trigger a .cameraPermissionDenied error immediately.

Overview

Getting Started

Integration Guide

Metrics Reference

Help

Integrate the Neurofit Vitals SDK into Your iOS App