Handling Document Capture Results

<yesid-document-capture> (and DocumentCapture) dispatch standard DOM events. In React, map them to onSuccess, onFailure, onSessionValidated, and onSessionInvalid.

Events

Event	When it fires	event.detail
yesid:success	Capture, extraction, submission, and OCR complete	{ response, submission }
yesid:failure	Component, OCR, or submission failure	{ message, error?, response?, submission? }
yesid:session-validated	Session accepted by the API	{ sessionId, stepType, documentCapture }
yesid:session-invalid	Session invalid or expired	{ sessionId, reason, code, message }
yesid:side-change	Active side changes in front + back mode	{ side: 'front' | 'back' }
yesid:detect	Corner detection completes	{ side, corners }
yesid:corners-change	User adjusts crop corners	{ side, corners }

You can import the event names instead of hardcoding strings:

import { YESID_EVENTS } from '@yesid/document-scanner';

scanner.addEventListener(YESID_EVENTS.success, (event) => {
  console.log(event.detail);
});

Success payload

interface CaptureCompleteEvent {
  response: {
    sessionId: string;
    stepType: 'DOCUMENT_CAPTURE';
    status: 'PENDING' | 'RUNNING' | 'PASSED' | 'FAILED' | 'ERROR' | 'REVIEW' | 'SKIPPED';
    completedAt: string;
    ocr?: OcrResult;
    resultData?: { ocr?: OcrResult };
  } | null;
  submission: {
    images: {
      imageDataUrl: string;
      side: 'front' | 'back';
      sourceMode?: 'camera' | 'upload';
    }[];
    selectedDocument?: { type: string; country: string };
  };
}

OCR is on response.resultData.ocr or response.ocr. Captured images are on submission.images.

Common OCR fields

ocr.documentData is an array of { name, value, confidence }. Typical name values:

Field	Example
documentNumber	"A12345678"
documentType	"national_id"
firstName	"John"
middleName	"Kwame"
lastName	"Doe"
fullName	"John Kwame Doe"
sex	"M"
dateOfBirth	"1990-01-01"
dateOfIssue	"2020-01-01"
dateOfExpiry	"2030-01-01"
issuingCountry	"TZ"
issuingCountryName	"Tanzania"

ocr.portrait is the cropped face photo from the document (base64 or data URL). ocr.documentType and ocr.overallConfidence describe the document as a whole.

Example — extract OCR and the portrait

function getOcr(detail) {
  return (
    detail?.response?.resultData?.ocr ??
    detail?.response?.ocr ??
    detail?.resultData?.ocr ??
    null
  );
}

scanner.addEventListener('yesid:success', (event) => {
  const ocr = getOcr(event.detail);
  const fields = new Map(
    (ocr?.documentData ?? []).map((item) => [item.name, item.value]),
  );

  const firstName = fields.get('firstName') ?? '';
  const documentNumber = fields.get('documentNumber') ?? '';
  const portrait = ocr?.portrait ?? event.detail.submission?.images?.[0]?.imageDataUrl;

  if (!fields.size && !portrait) {
    // Poor lighting, blur, or an unsupported document — prompt a retry
    return;
  }
});

React:

<DocumentCapture
  publishableKey={publishableKey}
  sessionId={sessionId}
  onSuccess={(detail) => {
    const ocr = detail.response?.resultData?.ocr ?? detail.response?.ocr;
    const portrait = ocr?.portrait;
    const documentData = ocr?.documentData ?? [];
  }}
/>

Session-validated payload

Use this to build a document-type picker when the session allows more than one type:

scanner.addEventListener('yesid:session-validated', (event) => {
  const allowed = event.detail?.documentCapture?.allowedDocuments ?? [];
  // [{ type: 'national_id', country: 'TZ', requiredSides: 2 }, ...]
});

Empty or failed OCR

If documentData is empty and there is no portrait, the session could not extract data. The usual causes are poor lighting, motion blur, or an unsupported document. Prompt the user to retry. yesid:failure fires when submission itself fails.

Support

The SDK is tested on current Chrome, Safari, Firefox, and Opera. Camera capture requires a secure context (https or localhost).