Skip to main content

Capture IQ Events

The Capture IQ Web Component dispatches DOM CustomEvents from <glamar-captureiq> whenever the runtime changes state, the camera or quality pipeline updates, or capture completes. Register listeners with addEventListener; the payload is always on event.detail.

Use these hooks for analytics, custom UI, and error handling. For imperative control (init, start, capture), see Methods. For config validation errors, see Configuration.

Life Cycle Events​

ready​

Fired after initialization succeeds (license check and merged config are ready). event.detail includes apiKey, preset, resolved config, locale, and sdkVersion.

Wait for ready (or await init()) before assuming the widget is fully usable; avoid racing start() before init completes.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("ready", (event) => {
const { preset, locale, sdkVersion } = event.detail;
console.log("Capture IQ ready", preset, locale, sdkVersion);
// Safe to call start() or enable UI from here
});

error​

Fired for non-license failures: invalid JSON on config (parse), runtime errors, and similar. event.detail.error is a CaptureIqError with code, message, and optional severity, stage, and details.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("error", (event) => {
const { error, sdkVersion } = event.detail;
console.error("Capture IQ error", error.code, error.message, sdkVersion);
});

licenseError​

Fired when license validation fails (missing or invalid api-key, or a negative response from config.license.validateUrl if configured).

const el = document.querySelector("glamar-captureiq");

el.addEventListener("licenseError", (event) => {
const { error } = event.detail;
console.error("Capture IQ license", error.code, error.message);
});

configError​

Fired when config JSON parses but fails semantic validation (for example quality thresholds outside 0–1, or flow.steps missing required steps). event.detail.errors is a string array.

Invalid JSON syntax on the config attribute usually emits error with code config-parse-error instead of configError.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("configError", (event) => {
const { errors, sdkVersion } = event.detail;
console.error("Capture IQ config invalid", errors, sdkVersion);
});

Camera Events​

permission​

Fired when browser camera (or related) permission moves between prompt, granted, denied, or error. event.detail.resource is typically "camera".

const el = document.querySelector("glamar-captureiq");

el.addEventListener("permission", (event) => {
const { resource, status, error } = event.detail;
console.log("Permission", resource, status, error);
if (status === "denied") {
  // Show your own message; user may need browser settings
}
});

cameraStarted​

Fired when the live stream has started successfully. event.detail may include deviceId.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("cameraStarted", (event) => {
console.log("Camera started", event.detail.deviceId);
});

cameraStopped​

Fired when the camera stream is stopped (pause, teardown, or flow transition). event.detail may include deviceId.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("cameraStopped", (event) => {
console.log("Camera stopped", event.detail.deviceId);
});

cameraError​

Fired when getUserMedia or device enumeration fails. event.detail.source is "getUserMedia" or "enumerateDevices"; event.detail.error describes the failure.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("cameraError", (event) => {
const { source, error } = event.detail;
console.error("Camera error", source, error.code, error.message);
});

Quality and guidance events​

frameQuality​

Fired on a throttled schedule while the camera and quality engine are running. event.detail.metrics includes scores such as lighting, alignment, sharpness, and face presence; also frameIndex and sessionId.

Prefer sampling or aggregating this event for analytics—logging every frame can hurt performance on low-end devices.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("frameQuality", (event) => {
const { metrics, sessionId } = event.detail;
// Example: log occasionally, not every emission
if (event.detail.frameIndex % 30 === 0) {
  console.log("Quality snapshot", sessionId, metrics);
}
});

guidance​

Fired when on-screen guidance changes (distance, lighting, head pose, hold-steady countdown, etc.). event.detail.code is a stable string such as move-closer, improve-lighting, hold-still; message may include human-readable text (for example a countdown).

const el = document.querySelector("glamar-captureiq");

el.addEventListener("guidance", (event) => {
const { code, message, sessionId } = event.detail;
console.log("Guidance", code, message, sessionId);
});

Capture events​

captureAttempt​

Fired whenever an automatic capture is considered—either allowed (about to run) or blocked (reason such as cooldown, maxAttempts). Includes attempts, maxAttempts, and cooldownMs / optional cooldownRemainingMs.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("captureAttempt", (event) => {
const { allowed, reason, attempts, maxAttempts } = event.detail;
console.log("Capture attempt", { allowed, reason, attempts, maxAttempts });
});

captureStart​

Fired immediately before a capture runs (auto or manual). event.detail.mode is "auto" or "manual".

const el = document.querySelector("glamar-captureiq");

el.addEventListener("captureStart", (event) => {
const { mode, session } = event.detail;
console.log("Capture start", mode, session.sessionId);
});

captureSuccess​

Fired after the user confirms on the review step (Use photo / equivalent) and the final still-image quality check passes (average score ≥ 70). event.detail.result is the CaptureResult (artifact with blob, optional dataUrl, dimensions, mimeType; metadata with captureId, sessionId, preset, device info, timestamps, and optional quality snapshot).

captureSuccess is not emitted from capture() alone. It fires only after user confirmation and a passing final quality gate. See Methods for the capture() promise vs this event.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("captureSuccess", (event) => {
const { result, session } = event.detail;
const { blob, width, height } = result.artifact;
const { captureId, sessionId } = result.metadata;
console.log("Capture success", sessionId, captureId, width, height, blob);
// Upload blob or pass to your backend
});

captureFail​

Fired when a capture path fails (retry from review, technical error, etc.). event.detail.error is a CaptureIqError; result may be present if failure happened after a frame was produced.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("captureFail", (event) => {
const { error, session } = event.detail;
console.warn("Capture fail", session.sessionId, error.code, error.message);
});

Session events​

sessionStart​

Fired when a new session is created. event.detail.session includes sessionId, preset, and sources.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("sessionStart", (event) => {
const { session } = event.detail;
console.log("Session started", session.sessionId, session.preset);
});

sessionEnd​

Fired when a session ends. event.detail.reason is one of completed, cancelled, timeout, or error; error is set when applicable.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("sessionEnd", (event) => {
const { session, reason, error } = event.detail;
console.log("Session end", session.sessionId, reason, error);
});

Analytics events​

analytics​

Reserved for telemetry and product analytics envelopes. When enabled, payloads may include envelope (sdkVersion, sessionId, optional traceId, timestamp), type, and payload.

const el = document.querySelector("glamar-captureiq");

el.addEventListener("analytics", (event) => {
const { envelope, type, payload } = event.detail;
console.log("Analytics", type, envelope.sessionId, payload);
});

Development: log all events​

Use a single loop while integrating to see ordering and payloads (remove or gate in production).

const el = document.querySelector("glamar-captureiq");

[
"ready",
"error",
"licenseError",
"configError",
"permission",
"cameraStarted",
"cameraStopped",
"cameraError",
"frameQuality",
"guidance",
"captureAttempt",
"captureStart",
"captureSuccess",
"captureFail",
"sessionStart",
"sessionEnd",
"analytics",
].forEach((type) => {
el.addEventListener(type, (event) => {
  console.log("[Capture IQ]", type, event.detail);
});
});

See Methods for init, start, capture(), and how they interact with captureSuccess.