CircadifySDK for iOS

Contactless vital sign measurement using your device camera.

Installation • Quick Start • Features • Full Documentation • License

---

Overview

CircadifySDK enables iOS apps to measure vital signs — heart rate, HRV, respiratory rate, SpO2, and blood pressure — using only the front-facing camera. No wearables. No additional hardware.

The SDK captures a short video, performs real-time quality analysis with on-device computer vision, uploads the recording, and returns clinical-grade measurements from the Circadify cloud.

---

Features

Feature	Description
Heart Rate	Beats per minute via remote photoplethysmography (rPPG)
HRV	Heart rate variability in milliseconds
Respiratory Rate	Breaths per minute
SpO2	Blood oxygen saturation percentage
Blood Pressure	Systolic and diastolic (mmHg)
Real-Time Quality	On-device brightness, contrast, motion, and face detection analysis
Offline Fallback	Generates fallback vitals when connectivity is limited

---

Requirements

	Minimum
iOS	15.0+
Xcode	14.0+
Swift	5.7+
Device	Physical device with front camera

---

Installation

Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/AYHealthTech/circadify-ios-sdk.git", from: "1.0.0")
]

Or in Xcode:

1. File → Add Package Dependencies
2. Enter https://github.com/AYHealthTech/circadify-ios-sdk.git
3. Select version rule and add to your target

---

Quick Start

1. Add Camera Permission

Add to your Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for vital sign measurement.</string>

2. Initialize the SDK

import CircadifySDK

let circadify = try CircadifySDK(apiKey: "YOUR_API_KEY")

3. Measure Vitals

let vitals = try await circadify.measureVitals()

print("Heart Rate: \(vitals.heartRate) BPM")
print("SpO2: \(vitals.spo2 ?? 0)%")
print("Blood Pressure: \(vitals.systolicBp ?? 0)/\(vitals.diastolicBp ?? 0)")
print("Confidence: \(vitals.confidence)")

---

Real-Time Quality Feedback

The SDK analyzes camera frames during capture and provides quality warnings so your UI can guide the user:

circadify.onQualityWarning = { warning in
    // warning.type: .lighting, .motion, .facePosition, .occlusion
    // warning.severity: .low, .medium, .high
    print(warning.message)
}

Example messages:

• "Scene is too dark. Please move to a well-lit area."
• "Too much motion detected. Please hold still."
• "No face detected. Please center your face in the frame."

---

Progress Tracking

Monitor measurement progress through four phases:

circadify.onProgress = { update in
    // update.phase: .initializing, .capturing, .uploading, .processing
    // update.percent: 0-100
    print("\(update.phase.rawValue): \(Int(update.percent))%")
}

---

Advanced Configuration

let config = CircadifyConfig(
    apiKey: "YOUR_API_KEY",
    baseUrl: "https://api.circadify.com",   // Custom endpoint
    measurementDuration: 30,                 // Seconds (default: 30)
    debug: false                             // Console logging
)

let circadify = try CircadifySDK(config: config)

Demographics for Improved Accuracy

let options = MeasurementOptions(
    demographics: Demographics(
        age: 35,
        sex: .male,
        fitzpatrick: 3   // Skin type (1-6)
    )
)

let vitals = try await circadify.measureVitals(options: options)

---

Error Handling

All errors conform to CircadifyError with descriptive messages and a isRetryable property:

do {
    let vitals = try await circadify.measureVitals()
} catch let error as CircadifyError {
    print(error.errorDescription ?? "Unknown error")

    if error.isRetryable {
        // Safe to retry: network issues, timeouts, rate limits
    }
}

---

Cancellation

// Cancel an in-progress measurement
circadify.cancel()

---

Architecture

┌─────────────────────────────────────────────────┐
│                  Your iOS App                    │
├─────────────────────────────────────────────────┤
│               CircadifySDK                       │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │
│  │ Camera   │  │ Frame    │  │  API Client   │ │
│  │ Capture  │→ │ Analyzer │  │  (Session,    │ │
│  │ (AV)     │  │ (Vision) │  │   Upload,     │ │
│  └──────────┘  └──────────┘  │   Polling)    │ │
│       │              │       └───────┬───────┘ │
│       │         Quality              │         │
│       │         Warnings             │         │
│       ▼                              ▼         │
│   .mp4 video ──── Upload ────→ Circadify Cloud │
│                                      │         │
│                              Vital Signs       │
│                              Result ←──────────┘
└─────────────────────────────────────────────────┘

---

Documentation

For complete integration guides including SwiftUI and UIKit examples, error handling, and best practices:

Full Documentation →

---

Security

Found a vulnerability? Please report it responsibly. See SECURITY.md for details.

---

License

MIT License. Copyright (c) 2026 A.Y. Health Technologies Inc.

See LICENSE for the full text.