Events

The Circadify SDK provides two callback-based event mechanisms configured at initialization: onProgress for measurement lifecycle updates, and onQualityWarning for real-time scan quality feedback. These callbacks fire during measureVitals() and are the primary way to build responsive UIs around the measurement flow.

Callback API

Register callbacks when creating the SDK instance. They remain active for all measureVitals() calls on that instance.

import { CircadifySDK } from '@circadify/sdk';

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
  onProgress: (event) => {
    console.log(`Phase: ${event.phase}, Progress: ${event.percent}%`);
  },
  onQualityWarning: (warning) => {
    console.warn(`Quality issue: ${warning.type} — ${warning.message}`);
  },
});

To stop receiving events, call sdk.destroy(). There is no per-callback unsubscribe mechanism — callbacks are tied to the SDK instance lifecycle.

Progress Events

The onProgress callback fires as the measurement moves through each phase. Use it to update progress bars, status text, or step indicators.

interface ProgressEvent {
  phase: 'initializing' | 'readiness' | 'capturing' | 'uploading' | 'processing';
  percent: number; // 0–100
}

Phase	Description	Typical Duration
initializing	Loading WASM modules and initializing the Vision Engine	2–5 s (first load), under 100 ms (cached)
readiness	Waiting for face detection and quality checks to pass	User-dependent
capturing	Recording and preprocessing video frames	~24 s
uploading	Sending preprocessed data to the server	5-30 s (network dependent)
processing	Server-side inference and signal processing	60-90 s

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
  onProgress: (event) => {
    progressBar.style.width = `${event.percent}%`;
    statusLabel.textContent = phaseLabels[event.phase];
  },
});

Note

The percent value reflects progress within the current phase, not overall measurement progress. Each phase starts at 0 and ends at 100.

Quality Warning Events

The onQualityWarning callback fires when scan conditions degrade during the readiness or capturing phase. Use these to prompt the user to adjust their position, lighting, or movement.

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

Warning Type	Trigger	Example Message
lighting	Scene is too dark, too bright, or has flickering light	”Improve lighting conditions for a better scan”
motion	Excessive head or body movement detected	”Hold still during the scan”
face_position	Head is turned, tilted, or too far from camera	”Center your face in the frame”
occlusion	Part of the face is blocked (hand, mask, etc.)	”Make sure your face is fully visible”

Severity Levels

Severity	Meaning
low	Minor degradation; measurement can still proceed
medium	Noticeable impact on accuracy; user should correct
high	Measurement quality is severely compromised; prompt the user immediately

const sdk = new CircadifySDK({
  apiKey: 'ck_test_your_key_here',
  onQualityWarning: (warning) => {
    if (warning.severity === 'high') {
      showBlockingOverlay(warning.message);
    } else {
      showToast(warning.message);
    }
  },
});

Error Handling During Measurement

Errors during measureVitals() are thrown as CircadifyError exceptions, not delivered via callbacks. Wrap your measurement call in a try/catch block to handle failures.

import { CircadifySDK, CircadifyError, CircadifyErrorCode } from '@circadify/sdk';

try {
  const result = await sdk.measureVitals({
    container: document.getElementById('scan-container'),
  });
} catch (error) {
  if (error instanceof CircadifyError) {
    if (error.isRetryable) {
      showRetryPrompt(error.message);
    } else {
      showError(error.message);
    }
  }
}

See Error Codes for the full list of error codes and recovery strategies.

Next Steps

• Error Codes — Complete error code reference
• Methods — SDK method reference