Configuration

Create one CircadifySDK instance for the screen or flow that performs measurements. Only apiKey is required.

Basic initialization

import com.circadify.sdk.CircadifySDK

val sdk = CircadifySDK(
    context = context,
    apiKey = "ck_live_your_key_here",
)

For full control, pass a CircadifyConfig:

import com.circadify.sdk.CircadifyCallbacks
import com.circadify.sdk.CircadifyConfig
import com.circadify.sdk.CircadifySDK

val sdk = CircadifySDK(
    context = context,
    config = CircadifyConfig(
        apiKey = "ck_live_your_key_here",
        baseUrl = "https://api.circadify.com",
        measurementDurationSeconds = 30,
        targetCaptureFps = 10,
        minimumAcceptedFrames = 150,
        maximumAcceptedFrames = 720,
        debug = false,
        onDeviceOnly = true,
        callbacks = CircadifyCallbacks(
            onProgress = { event -> updateProgress(event.percent, event.phase) },
            onQualityState = { state -> updateQualityMeters(state) },
            onQualityWarning = { warning -> showQualityHint(warning.message) },
            onLandmarks = { landmarks -> renderFaceOverlay(landmarks) },
            onCameraReady = { info -> showPreviewReady(info.hasPreviewSurface) },
        ),
    ),
)

Configuration reference

Property	Type	Default	Description
`apiKey`	`String`	-	Required. Your API key (`ck_live_*`).
`baseUrl`	`String`	`"https://api.circadify.com"`	API base URL.
`measurementDurationSeconds`	`Int`	`30`	Target measurement window and timeout basis. Upload can start earlier once enough quality frames are accepted.
`targetCaptureFps`	`Int`	`10`	Analysis frame-rate target. Lower values reduce CPU, heat, and bitmap allocation pressure on lower-end devices.
`minimumAcceptedFrames`	`Int`	`150`	Minimum quality frames required before a measurement can finish.
`maximumAcceptedFrames`	`Int`	`720`	Safety cap for accepted frames and in-memory tensor size.
`debug`	`Boolean`	`false`	Enables Android logcat debug logging.
`onDeviceOnly`	`Boolean`	`true`	Requests the standard on-device capture and measurement preparation path.
`callbacks`	`CircadifyCallbacks`	empty callbacks	Progress, quality, landmark, and camera readiness callbacks.

Callbacks

Callbacks are optional. Use them to build the scan UI around the headless SDK.

data class CircadifyCallbacks(
    val onProgress: ((ProgressEvent) -> Unit)? = null,
    val onQualityWarning: ((QualityWarning) -> Unit)? = null,
    val onQualityState: ((QualityState) -> Unit)? = null,
    val onLandmarks: ((List<Landmark>) -> Unit)? = null,
    val onCameraReady: ((CameraReadyInfo) -> Unit)? = null,
)

SDK callbacks are delivered on the Android main thread. Heavy capture, ROI extraction, tensor preparation, upload, and result polling are dispatched internally by the SDK.

Progress

callbacks = CircadifyCallbacks(
    onProgress = { event ->
        progressBar.progress = event.percent
        statusText.text = event.phase.name.lowercase()
        qualityFramesText.text = "${event.acceptedFrames ?: 0}/${event.targetFrames ?: 0}"
    },
)

Phase	Description
`INITIALIZING`	Creating a session and preparing capture
`READINESS`	Waiting for a scan-ready face and acceptable quality
`CAPTURING`	Capturing the measurement
`UPLOADING`	Uploading the measurement payload
`PROCESSING`	Waiting for results

During CAPTURING, ProgressEvent can include acceptedFrames, targetFrames, captureFps, and remainingSeconds. Use these fields for developer diagnostics or subtle scan copy, but avoid making users interpret raw frame counts.

Quality state

onQualityState emits the current lighting, motion, pose, readiness flag, and messages. Use it for persistent UI such as quality meters.

callbacks = CircadifyCallbacks(
    onQualityState = { state ->
        if (!state.isReady && state.messages.isNotEmpty()) {
            statusText.text = state.messages.first()
        }
    },
)

Quality warnings

onQualityWarning emits short-lived guidance such as lighting, motion, face position, or occlusion warnings.

callbacks = CircadifyCallbacks(
    onQualityWarning = { warning ->
        showToast(warning.message)
    },
)

Landmarks

onLandmarks emits normalized face landmarks. Use it only when you need a custom overlay.

callbacks = CircadifyCallbacks(
    onLandmarks = { landmarks ->
        overlayView.render(landmarks)
    },
)

Measurement options

Pass MeasurementOptions each time you call measureVitals().

val cancellationSignal = CancellationSignal()

val result = sdk.measureVitals(
    MeasurementOptions(
        lifecycleOwner = lifecycleOwner,
        previewView = previewView,
        demographics = Demographics(age = 35, sex = Sex.M, fitzpatrick = 3),
        cancellationSignal = cancellationSignal,
    ),
)

Property	Type	Required	Description
`lifecycleOwner`	`LifecycleOwner`	Yes	Lifecycle used by CameraX to bind and release camera use cases.
`previewView`	`PreviewView?`	No	Caller-owned CameraX preview surface. Pass `null` for headless capture.
`demographics`	`Demographics?`	No	Optional age, sex, and Fitzpatrick skin type.
`cancellationSignal`	`CancellationSignal?`	No	Cancels the measurement without cancelling the whole coroutine scope.

Demographics

Demographics is optional but can improve measurement accuracy when provided.

Field	Type	Notes
`age`	`Int?`	User age in years. Constructor enforces `0..130`.
`sex`	`Sex?`	`Sex.M` or `Sex.F`. Each constant’s `apiValue` is what gets sent on the wire.
`fitzpatrick`	`Int?`	Fitzpatrick skin type. Constructor enforces `1..6`.

Next Steps

Methods - SDK method reference
Performance & Device Support - Capture tuning and lower-end device guidance
Camera & Permissions - Runtime permission flow
Error Handling - Handle failures and retries