Event Callbacks

The SDK provides callbacks to integrate with your application's logic.

The snippets below show the callback shapes you'd assign to the element (e.g. flow.onFinish = ...) or set inside config. For full mounting examples (vanilla, React, Angular, Vue) see IncodeFlow Component and Framework Integration.

IncodeFlow Callbacks

onFinish

Called when the verification flow finishes. This is the primary callback you should set:

flow.onFinish = (result) => {
  console.log('Action:', result?.action); // 'approved' | 'rejected' | 'none'
  console.log('Status:', result?.scoreStatus); // 'OK' | 'WARN' | 'FAIL' | ...
  console.log('Redirect:', result?.redirectionUrl);

  if (result?.action === 'approved') {
    // Proceed with your flow
  }
};

result may be undefined (the signature is (result?: FinishStatus, meta?: IncodeFinishMeta) => void), so always null-check.

Knowing whether the SDK already drew a finish screen

onFinish receives an optional second argument. Read meta.sdkOwnsTerminalScreen to avoid stacking your own completion screen on top of one the SDK already rendered:

import type { IncodeFinishMeta } from '@incodetech/web/workflow';

workflow.onFinish = (result, meta) => {
  notifyBackend(result); // side effects always run

  if (!meta?.sdkOwnsTerminalScreen) {
    showMyCompletionScreen(result);
  }
};

It is true when the SDK has drawn its own terminal screen. Today, that means <incode-workflow> with the status-specific finish screen enabled. onFinish still fires either way, so side effects such as notifying a parent frame keep working.

The flag is advisory. The SDK cannot stop your page from rendering, so it only helps if you read it. Existing single-argument handlers keep working unchanged, and meta is undefined for modules that do not set it.

onError

Called when an error occurs:

flow.onError = (error, code) => {
  console.error('Verification error:', error, code);
  // Show error UI or redirect
};

onModuleLoading / onModuleLoaded

Track lazy-loading of each module's UI chunk. These are config callbacks, not element callbacks:

flow.config = {
  token: session.token,
  onModuleLoading: (moduleKey) => setLoading(moduleKey),
  onModuleLoaded: (moduleKey) => setLoading(null),
};

onWasmWarmup

Called when ML models begin loading:

flow.config = {
  token: session.token,
  onWasmWarmup: (pipelines) => console.log('Loading ML models:', pipelines),
};

onFlowEvent

Subscribe to curated flow milestones. For raw analytics events such as screenOpened or elementClicked, use subscribeEvent from @incodetech/core/events instead.

flow.config = {
  token: session.token,
  onFlowEvent: (event) => console.log('Flow event:', event.type, event),
};

Branch on event.type. The FlowEvent union and its member types are exported from @incodetech/core/flow-events:

import type { FlowEvent } from '@incodetech/core/flow-events';

flow.config = {
  token: session.token,
  onFlowEvent: (event: FlowEvent) => {
    if (event.type === 'flow.module.started') {
      console.log(`Starting ${event.module}`);
    }
  },
};

Every event also carries timestamp (epoch milliseconds) and an optional interviewId. All events except flow.started also carry an optional flowId.

FlowEventListener types the callback itself, and FlowEventSubscribable types a manager that exposes this stream.

Individual Module Callbacks

The standalone module elements (<incode-phone>, <incode-selfie>, <incode-id>, …) follow the same property-assignment pattern.

onFinish

phone.onFinish = () => console.log('Phone verified!');

onError

selfie.onError = (error) => console.error('Selfie error:', error);

Finish Status

The onFinish callback on IncodeFlow receives a FinishStatus object:

import type { FinishStatus } from '@incodetech/core/flow';

// FinishStatus shape:
// {
//   redirectionUrl: string;
//   action: 'approved' | 'rejected' | 'none';
//   scoreStatus: 'OK' | 'WARN' | 'MANUAL_OK' | 'FAIL' | 'UNKNOWN' | 'MANUAL_FAIL';
// }

FinishStatus is also re-exported from @incodetech/core/session if you prefer that grouping.

Dashboard Events

For tracking events to the Incode dashboard (module opens, screen transitions, custom events), see Dashboard Events.

See Also

• IncodeFlow Component: Full component reference
• Individual Modules: Module-specific callbacks
• Dashboard Events: Tracking events to the dashboard