Track the ID and Face Validation journey

The onJourneyEvent callback reports structured progress from the IdAndFaceValidation flow. Use it to answer questions such as:

• Did the user reach ID capture or face liveness?
• Which documents did the user capture?
• Did the user retry a capture?
• Which stages did the user complete?
• Did the user explicitly exit, and from where?

Journey events contain progress metadata only. They never contain captured images, document contents, submission requests, or validation responses.

Add the callback

import {
  IdAndFaceValidation,
  type IdAndFaceValidationJourneyEvent,
} from "idmission-web-sdk";
 
function reportJourneyEvent(event: IdAndFaceValidationJourneyEvent) {
  analytics.track(event.name, event);
}
 
export default function App() {
  return (
    <IdAndFaceValidation
      sessionId={getSessionId}
      onJourneyEvent={reportJourneyEvent}
      onApproved={handleApproved}
      onDenied={handleDenied}
    />
  );
}

IDmissionSDK.renderIdAndFaceValidation("#target-element", {
  sessionId: getSessionId,
  onJourneyEvent: (event) => {
    analytics.track(event.name, event);
  },
  onApproved: handleApproved,
  onDenied: handleDenied,
});

Every event has the same envelope:

type IdAndFaceValidationJourneyEventEnvelope = {
  version: 1;
  flow: "id-and-face-validation";
  timestamp: string; // ISO 8601 UTC timestamp
  name: string;
  [eventSpecificField: string]: unknown;
};

Use your own journey or analytics identifier to correlate events from a mounted flow instance. The flow field identifies the SDK flow type; it is not a unique instance ID.

Event reference

Stages

Document types

document.captured reports one of idCardFront, idCardBack, passport, or singlePage. Additional-document collection is represented by its stage events; it does not emit document.captured for each additional document.

Exit reasons

Journey telemetry does not add or change exit controls. For example, onUserCancel must still be supplied for the cancel control to be shown, and onExitAfterTamperSealPopped must be supplied for the tamper-screen exit control to be shown. Continue to use those callbacks to navigate away or unmount the flow. A flow.exited event reports the action but does not close the flow by itself.

Example sequence

A typical ID-card and face-liveness journey produces events in this order:

flow.started
stage.started                  stage=id-capture
document.captured              stage=id-capture documentType=idCardFront
document.captured              stage=id-capture documentType=idCardBack
stage.completed                stage=id-capture
stage.started                  stage=face-liveness
selfie.captured                stage=face-liveness
stage.completed                stage=face-liveness

Configured optional stages appear in the same stage.started / stage.completed sequence. If an asynchronous captureSignature or captureSignatureVideo condition skips its stage, that stage still reports stage.started followed by stage.completed; there is no separate stage.skipped event.

The exact sequence depends on the flow configuration and user actions. For example, a passport journey emits one document.captured event with documentType: 'passport', and a retry can insert capture.retried before the next capture event.

Handle event variants safely

The exported TypeScript event type is a discriminated union, so checking event.name narrows the event-specific fields:

import type { IdAndFaceValidationJourneyEvent } from "idmission-web-sdk";
 
function reportJourneyEvent(event: IdAndFaceValidationJourneyEvent) {
  switch (event.name) {
    case "document.captured":
      analytics.track("identity_document_captured", {
        documentType: event.documentType,
        occurredAt: event.timestamp,
      });
      break;
 
    case "capture.retried":
      analytics.track("identity_capture_retried", {
        stage: event.stage,
        attempt: event.attempt,
        occurredAt: event.timestamp,
      });
      break;
 
    case "flow.exited":
      analytics.track("identity_flow_exited", {
        stage: event.stage,
        reason: event.reason,
        occurredAt: event.timestamp,
      });
      break;
 
    default:
      analytics.track(event.name, event);
  }
}

Treat attempt and the exit event’s stage as optional. Currently, face liveness retries provide an attempt number; ID and video signature retries do not.

Journey progress versus final outcomes

onJourneyEvent describes what the user did inside the capture experience. It does not report the final validation decision and there is no flow.completed journey event. Keep the existing completion callbacks for business outcomes:

Combining these callbacks gives you journey telemetry without treating a completed capture stage as a successful validation.

Delivery behavior

Events are delivered synchronously and in causal order. The SDK does not wait for a returned promise. If the callback throws, the SDK logs the error and continues the capture journey.

Keep the handler fast. Enqueue or batch network work instead of blocking it, and handle delivery retries in your analytics client. The SDK does not buffer or replay events if the browser closes or the network is unavailable.

const pendingEvents: IdAndFaceValidationJourneyEvent[] = [];
 
function reportJourneyEvent(event: IdAndFaceValidationJourneyEvent) {
  pendingEvents.push(event);
  scheduleAnalyticsFlush();
}

Precapture and abandonment behavior

• Documents supplied through precapturedDocuments do not emit document.captured. A later recapture of the same document type does.
• A precaptured selfie can bypass face liveness and does not emit selfie.captured.
• Closing the tab, refreshing, losing power, or navigating away outside an SDK exit control does not emit flow.exited. If abandonment telemetry is required, add host-page lifecycle tracking such as pagehide and use navigator.sendBeacon where appropriate.

Privacy guidance

Journey events are intentionally image-free, but they still describe identity verification activity. Send only the fields your telemetry system needs, use a customer-controlled correlation ID instead of personal data, and apply your organization’s retention, consent, and access-control policies.