Options

Everything Handler.load() accepts: the measure strategy, the event callback, the eleven-colour palette, the screens, and the texts.

New integrations should use Saphere Scan v2. What follows documents the v1 options object.

Your options are validated, then merged over the defaults — and over any customisation applied by ?customizationId=, so what you pass in code wins over the customisation. Unknown top-level keys are rejected rather than ignored: load() throws Bad module options!.

Top level

KeyTypeDefaultNotes
createMeasureobject—Required. How a measure is obtained.
onEventfunction—Called on every event.
allowLeavebooleanfalseShows a control letting the user quit the widget.
allowSkipbooleanfalseShows a skip link on every guidance screen except the personal-information form. When the journey has that form and the user has not reached it yet, the link jumps to it, and the form then leads straight to the camera; otherwise it goes straight to the camera. Whatever lies in between, the consent screen included, is not shown.
langstringfirst browser language the widget supports, else "en"One of the ten supported languages.
useShadowbooleantrueMounts inside a shadow root.
isMobilebooleandevice detectionForces the phone or the desktop layout: illustrations, front camera, camera switch.
desiredVariablesstring[]—Handed to createMeasure; narrows what is computed once your server passes it on to POST /measures.
tagsstring[]—Handed to createMeasure; stored with the measure once your server passes them on.
colorsobjectsee Handler.defaultModuleOptionsThe eleven colours.
pagesobjectsee Handler.defaultModuleOptionsWhich screens the journey includes, and the logo.
textsobjectbuilt in, ten languagesEvery string, per language.

colors, pages and texts describe the appearance. Their shape is the one Handler.defaultModuleOptions shows, and any part of them may be passed. colors and pages are best prepared in the console rather than written in your code — see appearance below — but the console’s workshop, which has two tabs, Colors and Pages, covers only part of them: seven of the eleven colours (color04, color09, color10 and color11 are set in code), the guidance screens (pages.validates 1, 2 and 4 to 8), the logo and the notice. Everything else is set in code only: every string (texts), the personal-information form (pages.validates[3]: { ignore: false, fields: { … } }, with the six fields externalId, height, weight, age, sex and smokingStatus each given as { ignore }, at least one of them kept), pages.result, pages.staticFacePlacement and pages.finalForm. A colour is written #RGB or #RRGGBB. A partial payload is merged into the defaults, discriminant included: pages: { logo: { data: "data:image/png;base64,…" } } is enough to set a logo, with no ignore: false beside it, and a pages.validates entry that leaves ignore out keeps the one from the defaults.

useShadow: false lets your CSS reach inside

The default mounts the widget in a shadow root, which stops your stylesheet from affecting it and its own from affecting you. Turning that off is occasionally necessary in hybrid shells; when you do, expect your global CSS to reach the widget’s internals.

createMeasure

The widget needs a measure to attach the capture to. There are two strategies, and they differ in who makes the call.

delegate — the widget calls your endpoint

createMeasure: {
    strategy: "delegate",
    url: "/api/saphere-measure",
    headers: { "X-Session": sessionId }   // optional
}

The widget issues POST <url> with a JSON body carrying userData, desiredVariables and tags — each only when it has a value — and expects { "id": "<measureId>" } back. It sets Content-Type: application/json over your headers.

Your endpoint authenticates your user, calls POST /measures on the Saphere API with your key, and relays the identifier. The API’s answer carries the id field, so it can be relayed as it is.

handle — your code makes the call

fetch receives the same object the delegate body carries, { userData, desiredVariables, tags }, and resolves to the measure.

createMeasure: {
    strategy: "handle",
    fetch: async ({ userData, desiredVariables }) => {
        const response = await fetch("/api/saphere-measure", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ userData, desiredVariables })
        })
        return await response.json()      // must be { id: "…" }
    }
}

fetch must resolve to an object with an id

Returning the identifier as a bare string fails the creation, and the measurement stops with CREATE_MEASURE_ERROR. The contract is { id: string } — an object.

This is worth checking first when a v1 integration fails at the very start: some published examples returned json["token"], which is a string, and does not satisfy it.

When the measure is created

The widget asks for a measure at each attempt, when the face is accepted — right after the start event — and in parallel with the countdown and the capture. The creation fails when your delegate endpoint answers a non-2xx status, when your fetch rejects, when the answer carries no string id, or when no answer arrives within 25 seconds. The widget then stops the measurement: onEvent receives aborted with CREATE_MEASURE_ERROR, and the user sees the error screen. Nothing is thrown to your code.

Return a new measure on every call. A measure serves a single measurement, and reusing an identifier does not produce a second one. When the measurement server refuses an identifier, the module retries the connection six times — seven handshakes, in about six seconds — then stops the measurement: onEvent receives aborted with WS_CONNECTION_ERROR. Once a connection has been established, reconnection after a drop is no longer limited. Opening a measurement is also bounded per account — see rate limiting; an opening refused for that reason is retried automatically.

onEvent

onEvent: async event => {
    console.log(event.type, event)
}

Called for every event below. The return value is meaningful: returning literally false cancels the transition the event announces. Anything else allows it, including undefined, and including an exception thrown by your own code, which is logged and ignored.

The handler is awaited.

A slow handler slows the widget

Because the return value can veto a transition, v1 waits for your handler before proceeding. A handler that performs a network call on every event delays the user journey by that call.

This is the behaviour v2 deliberately dropped: there, onEvent is never awaited, and vetoing moved to a separate hooks API, narrowed to two points and bounded by a timeout.

The event union

typePayloadWhen
video-stream-loading{ status: "start" }The camera is being requested
video-stream-loading{ status: "ready" }The stream is open
video-stream-loading{ status: "error", reason }The camera could not be opened
start—The face is accepted and framing is frozen
record—Capture begins
end—All frames are buffered and the end marker is queued
result{ id, userData?, variables }The measurement completed
aborted{ reasons }The measurement stopped
leave—The user asked to quit (requires allowLeave); the widget does nothing else — unmount it with Handler.destroy()
transition{ from, to }Declared, but never emitted

video-stream-loading reason is one of "denied", "no-device", "not-supported", "already-used". A camera error that the browser files under none of the names the module knows (impossible constraints, a refused context…) arrives as "not-supported", and the module shows its “not supported” screen.

If the browser exposes no camera API at all — an insecure origin, a WebView that does not provide one — the module shows its “not supported” screen straight away and emits no video-stream-loading error: the only video-stream-loading event you receive is the one with status: "start".

aborted reasons is a single code, despite its name. It is one of:

  • the user cancelled: CANCELED_WHILE_COUNTDOWN, CANCELED_WHILE_CAPTURING, CANCELED_WHILE_SENDING, CANCELED_WHILE_PROCESSING;
  • the capture was interrupted: WIDGET_RESIZED, FOCUS_LOST, VIDEO_SOURCE_ENDED;
  • the checks the module runs during capture: CONFORMITY_POOR_LIGHT, CONFORMITY_MUCH_VARIATIONS, CONFORMITY_LOW_FPS;
  • the exchange with the servers: CREATE_MEASURE_ERROR, WS_CONNECTION_ERROR, UNEXPECTED_WS_RESULT.

The codes the server computes — CONFORMITY_FACE_PRESENCE, CREDIT_EXCEEDED, MISSING_USER_DATA_* and the others — never come through aborted. They arrive in the result event, as a variable’s error. CONFORMITY_POOR_LIGHT, CONFORMITY_MUCH_VARIATIONS and CONFORMITY_LOW_FPS also exist on the server side: when it is the server’s check that refuses a measure, they arrive in result, as a variable’s error, and not through aborted.

transition never fires

transition appears in the table above because the module’s own event type declares it. Nothing in the module constructs one. Do not build navigation tracking on it.

In a result event, each variable is { value, error: null } on success, or { value: null, error } on failure; the result describes the shape of each value. userData is present only when an external identifier was given, and then carries { externalId } alone.

The closing form

After the results screen, the widget can show a closing form: a rating, a remark and — when bp is among the variables returned, whatever its value — the reference readings, blood pressure among them, that the calibration of bp needs for a person identified by an externalId. Without bp, pages.finalForm decides: { version: "1" } shows the readings, { version: "2" } the rating and the remark only, and without it there is no form. The widget sends the form to Saphere itself, once per measurement: a second submission, or one made more than a day after the measurement ended, is refused. The result event is emitted before this screen, so a page that unmounts the widget on result never shows it.

Appearance: screens and colours

The widget’s appearance is best not written in your code. It is prepared in the ops console, in the customisation workshop, and attached to the widget by its identifier.

Each customisation is listed under Scan tools → Scan customization, with the identifier you will use. When you create one, set Widget version to v1: the default is v2, and the identifier of a v2 customisation applies nothing to this module.

The customisation list in the ops console
The customisations of an account. The identifier in the first column is what you put in the widget address.

Opening one gives the workshop. A live widget sits beside the settings, so what you approve is what your users will see.

Colours — the palette the widget applies to itself.

The Colors tab of the customisation workshop, with a live widget preview
Each colour is a field, and the preview redraws as you change it.

Pages — which screens the journey includes, and which are left out, plus the logo shown at the top.

The Pages tab of the customisation workshop
Removing a guidance screen shortens the journey and lowers the share of measurements that produce a usable signal.

Once the customisation is saved, add its identifier to the address you load the module from:

<script src="https://cdn.saphere.ai/saphere-scan/v1/js/main.min.js?customizationId=8f1c2d34-5a6b-4c7d-8e9f-0a1b2c3d4e5f"></script>

The module arrives already carrying it. Nothing changes in your code, and editing the customisation later takes effect at the next load, with no deployment on your side. What you pass in colors, pages or texts still takes precedence over it.

Prepare it in the same environment you load from

A customisation saved on Test is not the same record as one saved on Production, so its identifier does not carry across. Prepare it where you will use it.