Configuration

Configure the Circadify iOS SDK — initialization, callbacks, and measurement options.

Initialization

The simplest way to initialize the SDK is with just your API key:

import CircadifySDK
 
let sdk = try CircadifySDK(apiKey: "ck_live_your_key_here")

For full control, pass a CircadifyConfig:

let config = CircadifyConfig(
    apiKey: "ck_live_your_key_here",
    baseUrl: "https://api.circadify.com",
    measurementDuration: 30,
    debug: false
)
 
let sdk = try CircadifySDK(config: config)

The Camera

CircadifyCamera owns the single AVCaptureSession that is shared by both the live preview and the measurement. You create one camera, render it with CircadifyCameraPreview(camera:), and hand the same instance to measureVitals(camera:) so the scan records the exact session the user is already looking at.

@State private var camera = CircadifyCamera()

Because the camera and the SDK are decoupled, the preview can be live (with face tracking showing whether the user is framed, via camera.scanFace) before any measurement starts.

CircadifyCameraPreview(camera: camera)
    .ignoresSafeArea()

Front or back camera

By default CircadifyCamera() uses the front (selfie) camera — the right choice for self-scans, where the user watches the live preview to frame their own face. Pass position: .back for the rear camera instead:

let camera = CircadifyCamera(position: .back)

Reach for the rear camera when an operator measures another person (or in a kiosk / tripod setup). Its preview is not mirrored, and because the phone's screen no longer acts as a fill light for the subject (it faces away from them), ensure good ambient lighting. Both positions feed the identical on-device pipeline and produce the same measurements — see init(position:) in the method reference.

Configuration Reference

public struct CircadifyConfig: Sendable {
    public let apiKey: String
    public var baseUrl: String
    public var measurementDuration: TimeInterval
    public var targetCaptureFps: Int
    public var minimumAcceptedFrames: Int
    public var maximumAcceptedFrames: Int
    public var debug: Bool
}

Callbacks

Progress updates are reported by the SDK, while quality warnings are reported by the camera. Both callbacks are delivered on the main thread.

Progress Updates

Set onProgress on the SDK instance to track a measurement as it runs:

sdk.onProgress = { update in
    print("Phase: \(update.phase) — \(Int(update.percent))%")
}

public struct ProgressUpdate {
    public let percent: Double       // 0-100
    public let phase: Phase          // .initializing, .capturing, .uploading, .processing
    public let elapsed: TimeInterval
    public let remaining: TimeInterval?
}

Quality Warnings

Quality warnings come from the camera, not the SDK. Set onQualityWarning on your CircadifyCamera. Warnings are emitted only while a measurement is running — the framing phase before measureVitals(camera:) produces face geometry, not warnings. For pre-scan guidance, read the camera's observable scanFace (present or absent, plus its geometry) to tell whether the user is framed; once the measurement starts, quality warnings take over.

camera.onQualityWarning = { warning in
    print("[\(warning.severity)] \(warning.type): \(warning.message)")
}

public struct QualityWarning {
    public let type: WarningType     // .lighting, .motion, .facePosition, .occlusion
    public let message: String
    public let severity: Severity    // .low, .medium, .high
}

Use these to show guidance in your UI — "Hold still", "Move to better lighting", etc.

Measurement Options

Pass MeasurementOptions to measureVitals(camera:) to provide demographics for improved accuracy:

let options = MeasurementOptions(
    demographics: Demographics(age: 35, sex: .male, fitzpatrick: 3)
)
 
let result = try await sdk.measureVitals(camera: camera, options: options)

Demographics are optional but can improve measurement accuracy when provided.

Next Steps

• Methods — Full method reference
• Camera & Permissions — Handle camera access
• Error Handling — Handle failures gracefully