JavaScript AutoCapture¶

The startAutoCapture and stopAutoCapture methods are available on the Biometrid instance after initialization and provide automatic document and face capture for web applications.

startAutoCapture(options)¶

Accepts an IAutoCaptureOptions object. Returns Promise<string | null> — a base64 image string on success, or null if the capture was stopped without a result.

interface IAutoCaptureOptions {
  folder?: string;
  documentUrl?: string;
  faceUrl?: string;
  container?: HTMLElement;
  pageContainer?: HTMLElement;
  type?: EType;
  threshold?: number;
  margin?: number;
  cameraSettings?: boolean;
  timerCapture?: number;
  takePhoto?: any;
  i18n?: any;
  style?: any;
  mode?: EMode;
  docType?: string;
  captureType?: ECaptureType;
  hasFrame?: boolean;
  side?: ECaptureSide;
  forceLandscape?: boolean;
  forceBackCamera?: boolean;
  image?: string;
  validations?: boolean;
  overlay?: boolean;
}

Parameter	Type	Required	Description
`container`	`HTMLElement`	yes	DOM element where the capture UI will be rendered
`type`	`EType`	no	Capture source type: `EType.VIDEO` or `EType.FILE`
`docType`	`string`	no	Document type: `"idcard"`, `"passport"`, or `"other"`
`captureType`	`ECaptureType`	no	Capture mode: `ECaptureType.AUTOMATIC` or `ECaptureType.MANUAL`
`side`	`ECaptureSide`	no	Document side to capture: `ECaptureSide.FRONT` or `ECaptureSide.BACK`
`threshold`	`number`	no	Detection confidence threshold (0–1, default: `0.7`)
`margin`	`number`	no	Margin around the detection area in pixels
`cameraSettings`	`boolean`	no	Whether to show camera settings controls (default: `false`)
`timerCapture`	`number`	no	Seconds to wait before auto-capturing (default: `3`)
`hasFrame`	`boolean`	no	Whether to display a document frame overlay (default: `true`)
`forceLandscape`	`boolean`	no	Force landscape orientation for capture (default: `false`)
`forceBackCamera`	`boolean`	no	Force the use of the rear camera on mobile (default: `false`)
`validations`	`boolean`	no	Whether to enable document validations (default: `true`)
`overlay`	`boolean`	no	Whether to enable overlay blur on capture (default: `true`)
`takePhoto`	`any`	no	Configuration for manual photo capture — see example
`i18n`	`any`	no	Internationalization strings for UI labels — see i18n
`style`	`any`	no	Style overrides for the capture UI — see Style
`mode`	`EMode`	no	Capture target: `EMode.DOCUMENT` or `EMode.FACE`
`folder`	`string`	no	Destination folder for models (default: `.`).
`documentUrl`	`string`	no	URL to model.json https://.../autocapture/document_model/model.json
`faceUrl`	`string`	no	URL to model.json https://.../autocapture/face_model/model.json
`pageContainer`	`HTMLElement`	no	Parent page container element
`image`	`string`	no	Base64 image string for offline detection

stopAutoCapture()¶

Stops the capture session and releases camera resources. Takes no parameters. Returns true.

Enums¶

ECaptureType¶

Constant	Value
`ECaptureType.AUTOMATIC`	`"automatic"`
`ECaptureType.MANUAL`	`"manual"`

ECaptureSide¶

Constant	Value
`ECaptureSide.FRONT`	`"front"`
`ECaptureSide.BACK`	`"back"`

EMode¶

Constant	Value
`EMode.DOCUMENT`	`"document"`
`EMode.FACE`	`"face"`

EType¶

Constant	Value
`EType.VIDEO`	`"video"`
`EType.FILE`	`"file"`

i18n¶

All i18n strings are optional. Pass only the keys you want to override.

Key	Type	Description
`title`	`string`	Title displayed in the capture UI
`instruction`	`string`	Main instruction text shown to the user
`holdStill`	`string`	Text shown when waiting for the timer (prefix)
`seconds`	`string`	Label for seconds unit used with `holdStill`
`success`	`string`	Message shown on successful capture
`settingsTitle`	`string`	Title of the camera selection dialog
`settingsOk`	`string`	Confirm button label in the camera selection dialog
`tooManyFacesTitle`	`string`	Title when multiple faces are detected
`tooManyFacesText`	`string`	Body text when multiple faces are detected
`cameraWarningTitle`	`string`	Title when a camera is already in use
`cameraWarningText`	`string`	Body text when a camera is already in use
`cameraWarningOk`	`string`	Confirm button label in the camera warning dialog
`environment.dark`	`string`	Warning when environment is too dark
`environment.bright`	`string`	Warning when environment is too bright
`environment.flares`	`string`	Warning when glares or flares are detected
`cameraQuality.blurred`	`string`	Warning when the camera image is too blurred
`cameraQuality.noisy`	`string`	Warning when the camera image is too grainy
`card.closer`	`string`	Instruction to move the card closer
`card.back`	`string`	Instruction to move the card back

i18n: {
  title: string;
  instruction: string;
  holdStill: string;
  seconds: string;
  success: string;
  settingsTitle: string;
  settingsOk: string;
  tooManyFacesTitle: string;
  tooManyFacesText: string;
  cameraWarningTitle: string;
  cameraWarningText: string;
  cameraWarningOk: string;
  environment: {
    dark: string;
    bright: string;
    flares: string;
  }
  cameraQuality: {
    blurred: string;
    noisy: string;
  }
  card: {
    closer: string;
    back: string;
  }
}

Style¶

All style properties are optional. Pass only the keys you want to override.

Key	Type	Description
`blurFactor`	`number`	Blur intensity applied outside the capture frame
`borderWidth`	`number`	Width of the capture frame border in pixels
`typography.heading`	`[number, number, number]`	Heading font: `[fontSize, lineHeight, letterSpacing]`
`borderColor`	`string`	Color of the capture frame border
`borderColorSuccess`	`string`	Border color when capture is successful
`successColor`	`string`	Color of the success indicator
`textColor`	`string`	Color of text elements in the UI
`toastBackgroundColor`	`string`	Background color of toast notifications
`primaryColor`	`string`	Primary accent color
`secondaryColor`	`string`	Secondary accent color

style: {
  blurFactor: number;
  borderWidth: number;
  typography: {
    heading: [number, number, number]; // font-size, line-height, letter-spacing
  }
  borderColor: string;
  borderColorSuccess: string;
  successColor: string;
  textColor: string;
  toastBackgroundColor: string;
  primaryColor: string;
  secondaryColor: string;
}

Video Example¶

const options = {
  container: document.getElementById("example"), // mandatory
  type: "video",
  mode: "document",
  docType: "idcard",
  threshold: 0.75,
  margin: 40,
  cameraSettings: true,
  side: "front",
  timerCapture: 3,
  hasFrame: true,
  forceLandscape: true,
  forceBackCamera: false,
  validations: true,
  overlay: true,
  takePhoto: {
    active: true,
    timer: 30,
    callback: (status) => {
      if (status) {
        console.log("Photo taken");
      } else {
        console.log("Photo to be retaken");
      }
    },
  },
  i18n: {
    title: "Front card",
    instruction: "Please center your card within the frame",
    holdStill: "Please hold for ",
    seconds: "seconds",
    success: "Your card was successfully scanned",
    settingsTitle: "Choose below the camera you want to use",
    settingsOk: "Confirm",
    tooManyFacesTitle: "Multiple faces",
    tooManyFacesText:
      "We found multiple faces on the screen. Please make sure to be the only one in frame",
    cameraWarningTitle: "Camera(s) in use",
    cameraWarningText:
      "One or more cameras on this device are already in use; one available will be used for this process.",
    cameraWarningOk: "Ok",
    environment: {
      dark: "Environment is too dark",
      bright: "Environment is too bright",
      flares: "Remove any glares or flares",
    },
    cameraQuality: {
      blurred: "Camera image is too blurred",
      noisy: "Camera image is too grainy",
    },
    card: {
      closer: "Move the card closer",
      back: "Move the card back",
    },
  },
  style: {
    blurFactor: 10,
    borderWidth: 5,
    typography: {
      heading: [26, 18, 0], // font-size, line-height and letter-spacing
    },
    borderColor: "#FFFFFF",
    borderColorSuccess: "#00BA9A",
    successColor: "#00876E",
    textColor: "#FFFFFF",
    toastBackgroundColor: "#3D3D3D",
    primaryColor: "#4880FF",
    secondaryColor: "#EDF2FF",
  },
};

biometrid.startAutoCapture(options);

File Example¶

const options = {
  container: document.getElementById("example"), // mandatory
  type: "file",
  mode: "document",
  docType: "idcard",
  threshold: 0.75,
  margin: 40,
};

biometrid.startAutoCapture(options);