Selfie Module

The Selfie module captures a user's face with ML-powered liveness detection to prevent spoofing.

This module follows the camera-capture pattern. See that page for the shared manager lifecycle, capture sub-states, and skeleton; the rest of this page covers Selfie-specific config, detection statuses, and methods.

Tag

<incode-selfie> is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.

import '@incodetech/web/selfie';
import '@incodetech/web/selfie/styles.css';

Properties

Set these as JavaScript properties on the element (not as HTML attributes):

WASM Requirements

The Selfie module uses WebAssembly for face detection and liveness analysis. Pre-warm WASM during setup() so models are ready before the user reaches the camera step:

await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  token: 'your-session-token',
  wasm: { pipelines: ['selfie'] },
});

See WASM Configuration for self-hosted paths and the lower-level warmupWasm() API.

Usage

Vanilla HTML / TypeScript

<incode-selfie></incode-selfie>

<script type="module">
  import { setup } from '@incodetech/core';
  import '@incodetech/web/selfie';
  import '@incodetech/web/selfie/styles.css';

  await setup({
    apiURL: 'https://demo-api.incodesmile.com',
    token: 'your-session-token',
    wasm: { pipelines: ['selfie'] },
  });

  const selfie = document.querySelector('incode-selfie');
  selfie.onFinish = () => console.log('Selfie captured!');
  selfie.onError = (err) => console.error('Selfie error:', err);
</script>

React

React 18 or earlier: add the one-time JSX augmentation from Framework Integration → TypeScript: JSX support for incode-* tags. React 19+ doesn't need it, and can also use the simpler form from Framework Integration → React 19+ shortcut.

import { useEffect, useRef } from 'react';
import { setup } from '@incodetech/core';
import type { SelfieConfig } from '@incodetech/core/selfie';
import '@incodetech/web/selfie';
import '@incodetech/web/selfie/styles.css';

type SelfieElement = HTMLElement & {
  config?: SelfieConfig;
  onFinish: () => void;
  onError: (error: string) => void;
};

await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  token: 'your-session-token',
  wasm: { pipelines: ['selfie'] },
});

export function SelfieCapture() {
  const ref = useRef<SelfieElement>(null);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    el.onFinish = () => console.log('Selfie captured!');
    el.onError = (err) => console.error('Selfie error:', err);
  }, []);

  return <incode-selfie ref={ref} />;
}

For Angular (CUSTOM_ELEMENTS_SCHEMA) and Vue (compilerOptions.isCustomElement) setup, see Framework Integration.

Headless Mode

For complete UI control, use the createSelfieManager from @incodetech/core/selfie.

Quick Start

import { setup } from '@incodetech/core';
import { createSelfieManager } from '@incodetech/core/selfie';
import { resolveDashboardModuleConfig } from '@incodetech/core/flow';
import { warmupWasm } from '@incodetech/core/wasm';

await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  token: 'your-session-token',
});

await warmupWasm({
  wasmPath: '/wasm/webLib.wasm',
  glueCodePath: '/wasm/webLib.js',
  modelsBasePath: '/wasm/models',
  pipelines: ['selfie'],
});

const config = await resolveDashboardModuleConfig({ moduleKey: 'SELFIE' });
const manager = createSelfieManager({ config });

manager.subscribe((state) => {
  console.log('Status:', state.status);

  if (state.status === 'capture') {
    console.log('Detection:', state.detectionStatus);
    console.log('Stream ready:', !!state.stream);
  }

  if (state.status === 'finished') {
    console.log('Selfie captured!', state.processResponse);
    manager.stop();
  }
});

manager.load();

The core factory requires a complete SelfieConfig. This example resolves it from the active dashboard Flow, which must contain a SELFIE module. Standalone UI components accept partial overrides; those are not a complete core-manager config.

State Machine Flow

flowchart LR
    idle -->|load| tutorial
    tutorial -->|nextStep| permissions
    permissions -->|granted| capture
    capture -->|upload done| processing
    processing -->|success| finished

States Reference

Manual upload

In 2.3.0, tutorial always includes showManualUploadLink: boolean. Render an upload action only when it is true, and call goToManualUpload() from that action.

These properties exist in manualUpload. Add that status to exhaustive SelfieState switches. Typed tutorial fixtures must include showManualUploadLink.

Selfie's manualUploadSelectFile(file) takes one argument. ID Capture's method takes (side, file); do not share the ID call signature with Selfie.

Capture State Properties

When status === 'capture':

Removed: debugFrame (ImageData?) is gone from the selfie, authentication, and ID capture state types. It had already stopped carrying frames — the per-frame emission was dropped because storing a full-resolution frame roughly ten times a second re-rendered the capture screen and starved it on lower-tier devices. Reading state.debugFrame is now a type error rather than a silent undefined. If you relied on per-frame pipeline frames, contact Incode: an opt-in hook is the intended replacement.

These are read-only presentation fields. In error, error: string carries the message and moduleErrorCode?: string carries an optional code. Forward that code unchanged when reporting failure to a Flow or Workflow manager.

Detection Status Values

Permission Status Values

When status === 'permissions':

Handling cancellation (closed)

When the user dismisses the selfie flow either by calling manager.close() or by clicking the SDK's built-in close button, the manager transitions to closed. closed** is a final state**: the manager won't re-emit further updates from there, and reset() doesn't apply (it is only valid from error). Custom UIs need to decide what to do next.

The two common patterns:

Inside an orchestrated flow: call flowManager.completeModule() to skip the selfie step and let the orchestrator advance:

selfieManager.subscribe((state) => {
  if (state.status === 'closed') {
    // Optional: render a brief "Cancelled — continuing…" screen, then advance.
    setTimeout(() => flowManager.completeModule(), 800);
  }
});

Standalone (no orchestrator): there's nowhere to advance to, so navigate the user out of the selfie surface entirely:

selfieManager.subscribe((state) => {
  if (state.status === 'closed') {
    selfieManager.stop(); // tear down resources
    navigate('/onboarding/cancelled');
  }
});

Common UX choice: render a brief "Cancelled — continuing…" screen for ~800 ms before calling flowManager.completeModule(), so the cancellation isn't jarring.

API Methods

React Example

import { useState, useEffect, useRef } from 'react';
import { createSelfieManager, type SelfieState, type SelfieConfig } from '@incodetech/core/selfie';

function CustomSelfie({ config }: { config: SelfieConfig }) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const [manager] = useState(() =>
    createSelfieManager({ config }),
  );
  const [state, setState] = useState<SelfieState>({ status: 'idle' });

  useEffect(() => {
    const unsubscribe = manager.subscribe(setState);
    manager.load();
    return () => {
      unsubscribe();
      manager.stop();
    };
  }, [manager]);

  useEffect(() => {
    if (state.status === 'capture' && state.stream && videoRef.current) {
      videoRef.current.srcObject = state.stream;
    }
  }, [state]);

  switch (state.status) {
    case 'tutorial':
      return (
        <div>
          <h2>Take a Selfie</h2>
          <ul>
            <li>Ensure good lighting</li>
            <li>Remove glasses and hats</li>
            <li>Look directly at the camera</li>
          </ul>
          <button onClick={() => manager.nextStep()}>Continue</button>
          {state.showManualUploadLink && <button onClick={() => manager.goToManualUpload()}>Upload a photo</button>}
        </div>
      );

    case 'permissions':
      if (state.permissionStatus === 'denied') {
        return (
          <div>
            <p>Camera access is required.</p>
            <p>Please enable camera in your browser settings.</p>
          </div>
        );
      }
      return (
        <div>
          <p>We need camera access to take your selfie.</p>
          <button onClick={() => manager.requestPermission()}>
            Allow Camera
          </button>
        </div>
      );

    case 'capture':
      return (
        <div>
          <video ref={videoRef} autoPlay playsInline muted />
          <p>{getDetectionMessage(state.detectionStatus)}</p>
          {state.captureStatus === 'uploading' && <p>Uploading...</p>}
          {!state.onDeviceMode && state.detectionStatus === 'manualCapture' && (
            <button onClick={() => manager.capture()}>Take Photo</button>
          )}
          {state.captureStatus === 'uploadError' && (
            <div>
              <p className="error">{state.uploadError}</p>
              <button onClick={() => manager.retryCapture()}>Retry</button>
            </div>
          )}
        </div>
      );

    case 'processing':
      return <div>Processing...</div>;

    case 'manualUpload':
      return (
        <div>
          <input type="file" accept="image/*" disabled={state.phase === 'uploading'}
            onChange={(event) => {
              const file = event.currentTarget.files?.[0];
              if (file) manager.manualUploadSelectFile(file);
            }} />
          {state.errorKey && <p role="alert">{state.errorKey}</p>}
          <button disabled={!state.canContinue} onClick={() => manager.manualUploadContinue()}>Continue</button>
        </div>
      );

    case 'finished':
      return <div>✅ Selfie captured successfully!</div>;

    case 'error':
      return <div className="error">Error: {state.error}</div>;

    default:
      return <div>Loading...</div>;
  }
}

function getDetectionMessage(status: string): string {
  const messages: Record<string, string> = {
    idle: 'Preparing camera...',
    detecting: 'Detecting face...',
    noFace: 'Position your face in the frame',
    tooManyFaces: 'Only one face should be visible',
    tooFar: 'Move closer',
    tooClose: 'Move back',
    blur: 'Hold still, image is blurry',
    dark: 'Improve lighting conditions',
    faceAngle: 'Face your camera directly',
    centerFace: 'Center your face',
    lenses: 'Remove glasses or lenses',
    faceMask: 'Remove face mask',
    capturing: 'Capturing...',
    manualCapture: 'Ready - tap to capture',
  };
  return messages[status] || 'Detecting face...';
}

Capture-only flow

createSelfieCaptureOnlyManager exposes the same state machine and API surface as createSelfieManager, but bypasses Incode's /omni/add/face upload. Instead of submitting the captured frame and waiting on server-side processing, the manager invokes a customer-supplied onCapture(response) callback with the raw face image and reaches finished locally. Use it when you want to capture in the browser but route the bytes through your own pipeline.

The config exposes supported capture UX options plus a required onCapture callback. It omits assistedOnboarding, enableFaceRecording, and deepsightLiveness:

import { setup } from '@incodetech/core';
import { initializeSession } from '@incodetech/core/session';
import {
  createSelfieCaptureOnlyManager,
  type SelfieCaptureOnlyConfig,
  type FaceCaptureOnlyResponse,
} from '@incodetech/core/selfie';

await setup({
  apiURL: 'https://demo-api.incodesmile.com',
  wasm: { pipelines: ['selfie'] },
});
await initializeSession({ token: 'your-session-token' });

const config: SelfieCaptureOnlyConfig = {
  showTutorial: true,
  showPreview: false,
  autoCaptureTimeout: 10,
  captureAttempts: 3,
  validateLenses: true,
  validateFaceMask: true,
  validateHeadCover: true,
  validateClosedEyes: true,
  validateBrightness: true,
  onCapture: async (response: FaceCaptureOnlyResponse) => {
    const { image } = response;
    await uploadToMyBackend(image.blob);
  },
};

const manager = createSelfieCaptureOnlyManager({ config });
manager.subscribe((state) => {
  if (state.status === 'finished') manager.stop();
});
manager.load();

The FaceCaptureOnlyResponse payload is:

type FaceCaptureOnlyResponse = {
  image: FaceCapturedImageData;
};

type FaceCapturedImageData = {
  imageBase64: string; // The unprocessed full frame, base64-encoded
  blob: Blob; // Same content as Blob
  url: string; // Object-URL for direct rendering
  metadata: string; // Capture metadata (serialized)
  videoBase64: string | undefined; // Local-recording bytes — see note below
};

createSelfieCaptureOnlyManagerFromActor is also exported for advanced cases where you supply a pre-built XState actor.

Configuration Options

SelfieConfig is FlowModuleConfig['SELFIE'] & BaseFaceCaptureConfig. The FlowModuleConfig half is the dashboard-driven shape and its fields are required from your perspective; BaseFaceCaptureConfig adds a few optional UI overrides.

Orchestrated vs headless: when <incode-selfie> runs inside <incode-flow> (or createOrchestratedFlowManager), the orchestrator supplies the complete dashboard configuration. createSelfieManager({ config }) also requires a complete configuration. The standalone <incode-selfie>.config property accepts partial overrides and resolves remaining dashboard fields when configuration merging is enabled (the default).

Face concealment

Privacy Lens is the OPTION_SILHOUETTE concealment option. selfieConcealmentOption replaces the live camera preview with a cosmetic stand-in, for flows where users are reluctant to see themselves on screen:

The option is display-only. Face detection, quality checks, liveness, age estimation, and upload all continue to run on the real camera frames, so concealment never changes the verification result. An absent or unrecognized value renders the live preview.

Inside <incode-flow> or createOrchestratedFlowManager, the value comes from the SELFIE node configuration in your dashboard and the orchestrator passes it through — you do not set it yourself. Standalone integrators set the field on config directly.

Self-hosting the avatar runtime

The avatar options load their runtime — a face-tracking library and the avatar assets — from Incode's CDN. Deployments that block third-party origins can serve them from their own host with avatarAssets:

const config: Partial<SelfieConfig> = {
  selfieConcealmentOption: 'OPTION_2D',
  avatarAssets: { basePath: 'https://your-cdn.example.com/incode-avatar' },
};

Per-asset path overrides also exist for deployments that cannot keep the expected directory layout. Ask your Incode account team for the asset manifest and required headers before mirroring — the file set differs per avatar option, and a partial mirror falls back to the live camera preview rather than failing loudly.

Omit avatarAssets and the SDK uses its defaults. The field is read only when selfieConcealmentOption selects an avatar, so it has no effect on OPTION_NONE.

Troubleshooting

Face Not Detected

• Ensure good lighting (avoid backlighting)
• Remove glasses or hats if possible
• Position face within the outline
• Check WASM is properly initialized

Camera Issues

• Ensure HTTPS (camera requires secure context)
• Check browser permissions
• Try closing other apps using camera
• See Troubleshooting – Camera Issues

Upload Errors

• Check network connectivity
• Verify session token is valid
• Check WASM files are accessible

See Also

• Headless Mode: Complete headless API reference
• WASM Configuration: Setting up WebAssembly
• Individual Modules: Overview of all modules