Circadify

Configuration

Configure the Circadify Web SDK with all available options.

The SDK accepts a configuration object when you create a new CircadifySDK instance. Only apiKey is required.

Basic Configuration

import { CircadifySDK } from '@circadify/web-sdk';
 
const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
});
typescript

Full Configuration

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  baseUrl: 'https://api.circadify.com',
  measurementDuration: 30,
  debug: false,
  onDeviceOnly: true,
 
  // Per-frame callbacks for rendering custom UI:
  onProgress:        (e) => { /* phase + percent */ },
  onQualityState:    (q) => { /* full per-frame quality */ },
  onQualityWarning:  (w) => { /* transient warnings */ },
  onLandmarks:       (lm) => { /* normalized face landmarks */ },
  onCameraReady:     ({ stream, video }) => { /* mirror stream */ },
});
typescript

Configuration Reference

OptionTypeDefaultDescription
apiKeystring—Required. Your API key (ck_live_*).
baseUrlstring'https://api.circadify.com'Custom API base URL.
measurementDurationnumber30Target measurement duration in seconds.
debugbooleanfalseEnable debug logging to the browser console.
onDeviceOnlybooleantrueRequests the standard local capture and measurement payload preparation path. This does not mean results are computed fully on-device.
onProgress(e: ProgressEvent) => void—Phase + percent updates throughout measurement.
onQualityState(q: QualityState) => void—Full per-frame quality state (lighting, motion, pose, readiness). Use for live quality meters.
onQualityWarning(w: QualityWarning) => void—Fires on transient warnings (lighting, motion, face_position, occlusion).
onLandmarks(lm: Landmark[]) => void—Normalized face landmarks. Use to render your own face overlay.
onCameraReady({ stream, video }) => void—Fires once after the camera is acquired. Useful for mirroring the SDK-owned video into custom UI.
wasmConfigWasmConfig—Override CDN URLs for approved self-hosted runtime assets.

CircadifyConfig Interface

interface CircadifyConfig {
  apiKey: string;
  baseUrl?: string;
  measurementDuration?: number;
  debug?: boolean;
  onDeviceOnly?: boolean;
  onProgress?: (event: ProgressEvent) => void;
  onQualityState?: (state: QualityState) => void;
  onQualityWarning?: (warning: QualityWarning) => void;
  onLandmarks?: (landmarks: Landmark[]) => void;
  onCameraReady?: (info: { stream: MediaStream; video: HTMLVideoElement }) => void;
  wasmConfig?: WasmConfig;
}
typescript

Progress Callback

The onProgress callback fires throughout measurement with a ProgressEvent object:

interface ProgressEvent {
  percent: number;    // 0-100
  phase: 'initializing' | 'readiness' | 'capturing' | 'uploading' | 'processing';
  elapsed: number;    // Seconds since measurement started
  remaining?: number; // Estimated seconds remaining (when available)
}
typescript
PhaseProgressWhat's happening
initializing0–5%Creating session and preparing the SDK runtime
readiness5–10%Opening camera, waiting for quality checks to pass
capturing10–60%Capturing the measurement
uploading60–80%Uploading the measurement payload
processing80–100%Waiting for cloud processing

Quality State Callback

The onQualityState callback fires every frame during readiness and capture with the full quality picture. Use it to drive live quality meters or pills.

interface QualityState {
  lighting: { brightness: number; stability: number; isTooDark: boolean; isTooBright: boolean; isUnstable: boolean; isOk: boolean };
  motion:   { motionMagnitude: number; isStill: boolean };
  pose:     { yaw: number; pitch: number; isFacingForward: boolean };
  isReady:  boolean;
  messages: string[];
}
typescript

Quality Warning Callback

The onQualityWarning callback fires on transient quality drops:

interface QualityWarning {
  type: 'lighting' | 'motion' | 'face_position' | 'occlusion';
  message: string;
  severity: 'low' | 'medium' | 'high';
}
typescript

Use this for short-lived toasts ("Hold still", "Move to better lighting"). For sustained UI state, prefer onQualityState.

Landmarks Callback

The onLandmarks callback emits normalized face landmarks during measurement. Use it to render your own face overlay.

interface Landmark {
  x: number; // 0-1 normalized, NOT mirrored
  y: number; // 0-1 normalized, NOT mirrored
  z: number; // depth (relative)
}
typescript
Want a face / heat-glow overlay?

You usually shouldn't build one from this callback. Drop in CircadifyScanView from the Web SDK's React bindings for a ready-made glow overlay. If you need a custom one, prefer a 2D <canvas> in immediate mode — see Custom UI → Face overlay. Avoid a hand-rolled three.js / @react-three/fiber overlay (a known freeze bug from creating BufferGeometry in useMemo); if you must, follow Advanced: a 3D (r3f) overlay.

Camera Ready Callback

When you don't pass a videoElement to measureVitals(), the SDK creates an off-DOM <video> and reads from it directly. onCameraReady fires once with the live stream so you can mirror it into your own UI:

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  onCameraReady: ({ stream, video }) => {
    myPreviewVideo.srcObject = stream;
  },
});
typescript

Self-Hosting Runtime Assets

For air-gapped or regulated environments, host required SDK runtime assets on your own infrastructure:

interface WasmConfig {
  visionWasmUrl?: string;
  visionModelUrl?: string;
  geometryEngineUrl?: string;
}
typescript
const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  wasmConfig: {
    visionWasmUrl: 'https://your-cdn.example.com/runtime/',
    visionModelUrl: 'https://your-cdn.example.com/runtime/',
    geometryEngineUrl: 'https://your-cdn.example.com/runtime/geometry.js',
  },
});
typescript

Contact support@circadify.com for approved self-hosting instructions.

Tip

Runtime assets are lazy-loaded on first measurement and cached by the browser. Subsequent measurements skip the download when the cache is valid.

Next Steps