Skip to main content

Widget

The Veridia widget is a single HTML custom element, <veridia-widget>. It runs the capture flow in the browser: camera permission, document front (and back), selfie, optional active-liveness challenge, quality checks, upload, and submit.

It is the fastest way to integrate Veridia. You do not write capture code, you do not touch the upload endpoint, and you do not handle image encoding.

<script src="https://widget.xxuxe.online/face-api.js"></script>
<script type="module" src="https://widget.xxuxe.online/veridia-widget.min.js"></script>

<veridia-widget
  publishable-key="qv_pubt_YOUR_KEY"
  country="PY"
  document-type="dni"
  locale="es">
</veridia-widget>

What the widget does​

  • Requests the camera and guides the user through each capture step.
  • Runs client-side quality checks (sharpness, brightness, glare, face presence) and asks for a retake when a frame is unusable.
  • Calls POST /v1/verify/init, uploads each image, and calls POST /v1/verify/submit.
  • Emits exactly two events: veridia:complete and veridia:error.

What the widget does not do​

It never gives you the verdict. This is the single most important thing to understand before you integrate.

veridia:complete fires when the submission was accepted, not when the person passed. Its status field (queued / processing / completed) describes the pipeline, not the outcome. The outcome — approved, review, rejected — lives on a different axis and is only readable with a secret key, from your server:

  • Preferred: receive the webhook.
  • Or: have your backend call GET /v1/verify/{id} with a qv_sec_* / qv_sect_* key.

The widget carries a publishable key (qv_pub_* / qv_pubt_*). That key can start and submit verifications. It cannot read verdicts, by design — it is visible to anyone who opens your page source. If it could read verdicts, anyone could read yours.

Branching on status to activate an account admits every rejected applicant. The widget cannot protect you from that; only reading verdict server-side can.

The publishable key is not an access control​

Publishable keys have an allowedOrigins list. Today every key is created with that list empty, and an empty list permits every origin. The check also only applies to browsers — a server-side client sends no Origin header and always passes.

Treat allowedOrigins as a way to delimit where your widget is expected to run, not as a perimeter. See Authentication.

The widget lets the user pick the document photo from their gallery instead of shooting it with the camera. It is optional, the user chooses, and it applies to the document only — the selfie and the liveness challenge can never be file-sourced. Details in Customization.

Where to go next​

  • Installation — plain HTML, React, Next.js, Vue, Angular, WebView, CSP.
  • Configuration — every attribute, its real default, and the programmatic config setter.
  • Events — the two events, their exact detail shape, and the full error-code table.
  • Customization — accent color, locale, sizing, subclassing the element.
  • Examples — complete, runnable integrations end to end.