Methods

Complete reference for all Circadify Web SDK methods.

Reference for all public methods on the CircadifySDK instance.

`measureVitals(options?)`

Runs the full measurement flow: camera access, scan capture, upload, and result delivery. Returns a promise that resolves with the vital signs result.

The SDK is headless — you render the <video> element and any overlays. The SDK drives the camera, measurement preparation, and upload, and emits per-frame events via the callbacks set on the constructor.

const result = await sdk.measureVitals({
  videoElement: document.getElementById('preview') as HTMLVideoElement,
  demographics: { age: 35, sex: 'M', fitzpatrick: 3 },
  signal: abortController.signal,
});

typescript

Parameters (MeasurementOptions):

Name	Type	Required	Description
`videoElement`	`HTMLVideoElement`	No	Caller-owned `<video>`. The SDK binds the camera stream to it. If omitted, the SDK creates an off-DOM video and emits `onCameraReady` with the stream.
`demographics`	`Demographics`	No	User demographics to improve accuracy.
`signal`	`AbortSignal`	No	Cancel the measurement mid-scan via `AbortController`.

Demographics:

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

typescript

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

typescript

Tip

A confidence above 0.7 indicates a reliable measurement. Below 0.4 suggests quality issues and should usually prompt a retry.

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`	Required SDK runtime assets failed to load
`BROWSER_NOT_SUPPORTED`	Browser lacks required APIs (WebAssembly, MediaDevices)
`RATE_LIMITED`	Sandbox request rate limit, or monthly scan quota, exceeded
`CANCELLED`	The `AbortController` signal was triggered
`NETWORK_ERROR`	Network request failed (retryable)
`UPLOAD_FAILED`	Secure upload failed (retryable)
`TIMEOUT`	Polling for results timed out (retryable)

Building UI from per-frame callbacks

Render quality meters, face overlays, and progress UI from the callbacks set on the SDK constructor. See Configuration for the full list. The most common are onProgress, onQualityState, and onLandmarks.

const sdk = new CircadifySDK({
  apiKey: 'ck_live_your_key_here',
  onProgress:     (e)  => updateProgressBar(e.phase, e.percent),
  onQualityState: (q)  => updateQualityMeters(q),
  onLandmarks:    (lm) => renderFaceOverlay(lm), // 2D canvas; or use CircadifyScanView for a ready-made glow overlay
});
 
const result = await sdk.measureVitals({ videoElement: myVideoEl });

typescript

Face / heat-glow overlay

For the face/heat-glow visual, mount CircadifyScanView from the Web SDK's React bindings rather than building it from onLandmarks. If you need a custom overlay, prefer a 2D <canvas> — see Custom UI → Face overlay. Avoid a hand-rolled three.js / @react-three/fiber overlay (Advanced: a 3D (r3f) overlay has the rules and the known freeze bug).

`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.');
}

typescript

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)

typescript

Returns: DeviceCapabilities

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

typescript

`cancel()`

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

sdk.cancel();

typescript

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

`destroy()`

Releases all resources, including active camera streams and SDK runtime resources.

sdk.destroy();

typescript

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

Caution

After destroy(), the instance cannot be reused. Create a new CircadifySDK instance for another measurement.

React cleanup example

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

typescript

The Web SDK's React bindings' <CircadifyProvider> does this automatically when it unmounts.

Next Steps

Configuration — All SDK options and per-frame callbacks
Events — Progress and quality events
Error Codes — Full error reference