Methods

Reference for all public methods on the CircadifySDK instance.

`measureVitals(options?)`

Runs the full measurement pipeline: camera access, face detection, frame capture, upload, and server-side inference. Returns a promise that resolves with the vital signs result.

const result = await sdk.measureVitals({
  container: document.getElementById('scan-container'),
  demographics: { age: 35, sex: 'M', fitzpatrick: 3 },
  signal: abortController.signal,
  ui: {
    showFaceGuide: true,
    showThermalGlow: true,
    accentColor: '#00D4FF',
  },
});

Parameters (MeasurementOptions):

Name	Type	Required	Description
`container`	`HTMLElement`	No	DOM element for the built-in scan UI. Omit for headless mode.
`demographics`	`Demographics`	No	User demographics to improve accuracy.
`signal`	`AbortSignal`	No	Cancel the measurement mid-scan via `AbortController`.
`ui`	`ScanningUIOptions`	No	Customize the built-in scan UI appearance.

Demographics:

interface Demographics {
  age?: number;
  sex?: 'M' | 'F';
  fitzpatrick?: 1 | 2 | 3 | 4 | 5 | 6;
}

UI Options:

Option	Type	Default	Description
`showFaceGuide`	`boolean`	`true`	Show face oval overlay
`showThermalGlow`	`boolean`	`true`	Show thermal glow animation during scan
`showQualityIndicators`	`boolean`	`true`	Show quality status banner
`accentColor`	`string`	`'#00D4FF'`	Accent color for UI elements
`borderRadius`	`string`	`'16px'`	Border radius for the video container

Returns: Promise<VitalSignsResult>

interface VitalSignsResult {
  heartRate: number;         // BPM (always present)
  hrv?: number;              // Heart rate variability (ms)
  respiratoryRate?: number;  // Breaths per minute
  spo2?: number;             // Blood oxygen saturation (%)
  systolicBp?: number;       // Systolic blood pressure (mmHg)
  diastolicBp?: number;      // Diastolic blood pressure (mmHg)
  confidence: number;        // 0-1 measurement reliability
  sessionId: string;         // Unique session identifier
  timestamp: number;         // Unix timestamp (ms)
}

Errors thrown:

Error Code	When
`MISSING_API_KEY`	No API key was provided
`CAMERA_PERMISSION_DENIED`	User denied camera access
`CAMERA_NOT_AVAILABLE`	No camera found on the device
`CAMERA_IN_USE`	Camera is already in use by another application
`FACE_NOT_DETECTED`	No face found in the camera feed
`FACE_DETECTION_TIMEOUT`	No face detected within 30 seconds
`QUALITY_TOO_LOW`	Capture quality was too poor to produce results
`WASM_LOAD_FAILED`	Vision engine modules failed to load
`BROWSER_NOT_SUPPORTED`	Browser lacks required APIs (WebAssembly, MediaDevices)
`QUOTA_EXCEEDED`	Monthly scan limit reached
`RATE_LIMITED`	Hourly request limit exceeded
`CANCELLED`	The `AbortController` signal was triggered
`NETWORK_ERROR`	Network request failed (retryable)
`UPLOAD_FAILED`	Upload to cloud storage failed (retryable)
`TIMEOUT`	Polling for results timed out (retryable)

Headless Mode

Omit container to run without any UI. Use the onProgress and onQualityWarning callbacks to drive your own interface:

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
  onProgress: (p) => updateProgressBar(p.phase, p.percent),
  onQualityWarning: (w) => showWarning(w.message),
});

const result = await sdk.measureVitals();

`checkCameraAccess()`

Checks whether the device has a camera and camera permissions are available. Does not prompt the user for permission.

const hasCamera = await sdk.checkCameraAccess();

if (!hasCamera) {
  showMessage('Camera not available on this device.');
}

Returns: Promise<boolean>

`getDeviceCapabilities()`

Returns information about the device’s camera support.

const capabilities = sdk.getDeviceCapabilities();

console.log(capabilities.hasCamera);         // true
console.log(capabilities.hasFrontCamera);    // true
console.log(capabilities.isSecureContext);   // true (HTTPS)

Returns: DeviceCapabilities

interface DeviceCapabilities {
  hasCamera: boolean;
  hasFrontCamera: boolean;
  isSecureContext: boolean;
  mediaDevicesSupported: boolean;
  maxResolution?: { width: number; height: number };
}

`cancel()`

Cancels a measurement that is currently in progress. Equivalent to aborting the AbortController signal.

sdk.cancel();

The measureVitals() promise will reject with a CircadifyError with code CANCELLED.

`destroy()`

Releases all resources: stops active camera streams, unloads WASM modules, and removes any UI elements.

sdk.destroy();

Call destroy() when the SDK is no longer needed — for example, on component unmount.

React cleanup example

useEffect(() => {
  const sdk = new CircadifySDK({ apiKey: 'ck_test_your_key_here' });
  // ...use sdk
  return () => sdk.destroy();
}, []);

Next Steps

Configuration — All SDK options
Events — Progress and quality events
Error Codes — Full error reference