Configuration

Initialization

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

import CircadifySDK

let sdk = try CircadifySDK(apiKey: "ck_test_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)

Configuration Reference

public struct CircadifyConfig {
    public let apiKey: String
    public var baseUrl: String
    public var measurementDuration: TimeInterval
    public var debug: Bool
}

Property	Type	Default	Description
apiKey	String	—	Required. Your API key (ck_test_* or ck_live_*).
baseUrl	String	"https://api.circadify.com"	API base URL.
measurementDuration	TimeInterval	30	Target capture duration in seconds.
debug	Bool	false	Print debug logs to the console.

Callbacks

Set callbacks on the SDK instance to receive progress updates and quality warnings during measurement.

Progress Updates

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?
}

Phase	Description
.initializing	Setting up camera and vision engine
.capturing	Recording and analyzing video frames
.uploading	Uploading preprocessed data
.processing	Server-side inference running

Quality Warnings

sdk.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
}

Warning Type	Trigger
.lighting	Too dark, too bright, or flickering
.motion	Excessive movement
.facePosition	Head turned or tilted too far
.occlusion	Face partially blocked

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

Measurement Options

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

let options = MeasurementOptions(
    demographics: Demographics(age: 35, sex: .male, fitzpatrick: 3)
)

let result = try await sdk.measureVitals(options: options)

public struct Demographics: Codable {
    public var age: Int?
    public var sex: Sex?           // .male or .female
    public var fitzpatrick: Int?   // Skin type 1-6
}

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