Embeddable Widgets

A drop-in React component that captures a user's ID document plus a live anti-spoofing selfie and submits it to YeboVerify.

Overview

This is the full extent of widget support today:

• React — @yeboverify/react (not published to npm yet — install via npm install github:omegathesecond/yeboverify-react), a single <YeboVerifyWidget /> component. It renders ID front/back capture and a live-camera liveness challenge (or a single-shot selfie), then submits directly to POST /v1/verify.

Not implemented

There is no vanilla-JS SDK, no CDN bundle (cdn.yeboverify.com does not exist), no Vue component, and no framework-agnostic Web Component — despite what this page used to say. The React widget itself has no theme, language, borderRadius, mode, showProgress, allowRetry, or metadata config, no YeboVerify.init()/global object, no event system (.on/.off), and no start() / destroy() / getStatus() / setConfig() methods — it is one React component with the fixed prop surface below. If you need one of these, contact [email protected] — don't rely on any prop or API not documented on this page; an unknown prop is silently ignored, not honored.

---

Installation

npm install github:omegathesecond/yeboverify-react

Not published to npm yet — the package installs from GitHub, but its package.json name is @yeboverify/react, so it resolves in node_modules and imports exactly as shown below. react and react-dom (≥ 17) are peer dependencies.

Quick Start

import { YeboVerifyWidget } from '@yeboverify/react';

export function VerifyScreen() {
  return (
    <YeboVerifyWidget
      apiKey="yvk_your_api_key"
      externalRef={currentUser.id}
      documentType="National ID"
      onSubmit={(verificationId) => {
        console.log('Submitted:', verificationId);
      }}
      onResult={(result) => {
        if (result.decision === 'approved') unlockAccess();
      }}
      onError={(err) => toast.error(err.message)}
    />
  );
}

The widget renders the full ID + selfie capture flow itself and submits it to POST /v1/verify for you — there is no containerId/DOM-mount API, because it's a normal React component, not a script-tag widget with its own runtime.

Browser security: the widget calls the API directly with the apiKey you pass, so that key ships in your client-side JS bundle. Use a key scoped for the verify endpoint — never expose a full-privilege secret key in the browser.

---

Active Liveness (anti-spoofing)

By default (liveness={true}) the selfie step is a live-camera challenge, not a single photo upload. The widget:

1. Opens the front camera via getUserMedia.
2. Captures a neutral frame.
3. Prompts a randomized action — blink, smile, turn left, or turn right — and captures a second frame.
4. Submits both frames plus the challenge label with the verification.

A business with requireLiveness enabled cannot auto-approve a submission that arrives without these frames.

Pass liveness={false} to fall back to a single-shot selfie photo upload. Such submissions can never auto-approve for a requireLiveness business.

Live capture needs a secure context (HTTPS or localhost) and camera permission. If the camera is unavailable or access is denied, the widget surfaces the failure rather than silently submitting without liveness.

---

Props Reference

Prop	Type	Default	Description
apiKey	string	required	Your YeboVerify API key
baseUrl	string	'https://api.yeboverify.com'	API base URL — set to https://dev-api.yeboverify.com for dev
externalRef	string	-	Your reference ID (e.g. user ID)
documentType	string	'National ID'	e.g. "National ID", "Passport"
liveness	boolean	true	Active anti-spoofing liveness capture — see above
requireIdBack	boolean	false	Also capture the back of the ID document
showBack	boolean	-	Show a back button
onSubmit	(verificationId: string) => void	-	Called once the documents are accepted for processing
onResult	(result: VerificationResult) => void	-	Only fires if a result is polled or pushed back into the widget — treat your server-side webhook as the source of truth, not this callback
onError	(error: Error) => void	-	Called on error
primaryColor	string	'#16a34a'	Widget accent color
className	string	-	Custom container class

Any prop not in this table (theme, language, borderRadius, mode, showProgress, allowRetry, metadata, onCancel, onReady, containerId, ...) does not exist on this component. Passing one does nothing — same as any unrecognized prop on any React component — it is not validated or rejected.

VerificationResult

interface VerificationResult {
  verificationId: string;
  status: 'pending' | 'processing' | 'completed' | 'failed' | 'needs_review';
  decision?: 'approved' | 'rejected' | 'needs_review' | null;
  confidence?: 'high' | 'medium' | 'low' | null;
  faceScore?: number | null;
  extractedData?: {
    surname?: string;
    names?: string;
    dateOfBirth?: string;
    idNumber?: string;
    documentType?: string;
  } | null;
}

onResult only fires if a result is pushed or polled back into the widget — verify the outcome server-side via webhook, never trust a client-side callback alone. See SDKs & Libraries for webhook signature verification with @yeboverify/node, and Webhooks for the event payloads.

---

Company (KYB) verification is not available as a widget

@yeboverify/react deliberately does not support company/KYB verification:

• This widget's apiKey is passed straight into a browser-side fetch call and ships in your page's JS bundle. That's an acceptable trust model for one individual submitting their own ID + selfie, but KYB carries registration numbers, tax IDs, director PII, and AML-screening billing — never appropriate to drive from a public, unauthenticated browser context.
• The KYB signatory's own individual identity check doesn't go through this widget either. Creating a company verification server-side returns a verifyUrl pointing at the separate hosted flow at verify.yeboverify.com — send the signatory there directly. See White-Label Branding for how that hosted flow is themed.

---

Styling

The only visual customization is primaryColor — it sets the header background, upload-dropzone accent, and buttons. There is no CSS-variable theming API, no dark-mode prop, and no border-radius control; the widget ships as a fixed white card with rounded corners and a light theme only.

---

Support

• SDKs Overview: /sdks
• White-Label: /white-label
• API Reference: /api-reference
• Email: [email protected]