@eidchain/biometric-sdk

Face capture with liveness for biometric: the hosted-quality camera screen on your own site.

The full guide, with every text key and error code, is in the biometric dashboard under Docs → Web SDK.

Install

npm i @eidchain/biometric-sdk

The face detection library is bundled and loads on demand: you don't install it or configure your bundler for it. Face models load from {baseUrl}/models/.

Show the camera

Your backend starts the session with POST /api/v1/sessions and your API key, and passes its capture_token (ct_…) to the page. Never put an sk_… key in a browser.

import { mountCapture } from "@eidchain/biometric-sdk";

const camera = mountCapture(document.getElementById("camera"), {
  baseUrl: "https://faces.example.com",
  captureToken: "ct_…",
  onFinish: ({ status }) => console.log(status), // "passed" or "failed"
  onError: ({ code }) => console.log(code),
});

// To remove it:
camera.destroy();

mountCapture brings its own React, so it works on any page. To show a new session in the same element, call destroy() first: mounting again without it leaves the first screen running.

Lobby kiosk

mountKiosk runs the lobby kiosk with the kiosk's dk_… token from POST /api/v1/collections/{id}/devices. Your page stores the token.

import { mountKiosk } from "@eidchain/biometric-sdk";

mountKiosk(document.getElementById("kiosk"), {
  baseUrl: "https://faces.example.com",
  deviceToken: "dk_…",
  onFinish: ({ status }) => console.log(status),
});

A guest taps Start check-in and the kiosk starts an identify session. With deviceToken: null, it shows that it isn't set up.

React

In a React app (React 18 or later), use the components from /react. They use your React and are marked "use client".

import { BiometricCapture, BiometricKiosk } from "@eidchain/biometric-sdk/react";

<BiometricCapture baseUrl="https://faces.example.com" captureToken={captureToken} onFinish={({ status }) => setStatus(status)} />
<BiometricKiosk baseUrl="https://faces.example.com" deviceToken={deviceToken} />

The screen starts again only when captureToken, deviceToken or baseUrl changes. The other props are read when it starts, except onFinish and onError, which always call your latest function.

Options

| Option | Type | Notes | |---|---|---| | baseUrl | string | Required. The address you call the API on. | | captureToken | string | Required for mountCapture. The session's capture_token. | | deviceToken | string | null | Required for mountKiosk. The kiosk's dk_… token, or null if it has none yet. | | locale | "en" | "id" | Default en. | | theme | object | accent, background, surface, text, textSoft, radius, font. Colours, lengths (also calc()) and font lists only. | | texts | object | Your own wording for any text; the rest come from locale. | | holdSeconds | number | How long one face must stay straight ahead before capture starts. Default 3. 0 starts at once. | | redirect | boolean | mountCapture only. true sends the page to the session's redirect_url 2 seconds after the result (https only, or http while your page is http). Default false. | | onFinish | function | Called with { status }: passed or failed. | | onError | function | Called with { code } when the screen can't go on, e.g. session_expired. |

Both functions return { destroy() }. The screen renders in a Shadow DOM: your page's CSS doesn't change it, and its CSS doesn't change your page.

Check in from the webhook

onFinish is for your screen only. Check guests in from the signed webhook, or from GET /api/v1/sessions/{id}.

HTTPS

The page must be HTTPS for the camera, except on localhost.

Content Security Policy

The SDK adds <style> elements, so style-src needs 'unsafe-inline'. connect-src needs your baseUrl (the API and the face models at {baseUrl}/models/) and data: (the face library warms up on a built-in image).

Tokens in your page

A page with a capture token in its URL should send Referrer-Policy: no-referrer, as the hosted page does, so the token doesn't reach other sites. A page that holds a kiosk's dk_… token can start checks: keep it behind a login or on the kiosk only.

/core

@eidchain/biometric-sdk/core holds the pure logic without any UI: the API client, texts, theme, challenges and consent text. Use it to build your own camera screen on the Capture API (Docs → Capture API).