Options

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=. Unknown top-level keys are rejected rather than ignored.

Top level

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, and expects { "id": "<measureId>" } back.

Your endpoint authenticates your user, calls POST /measures on the Saphere API with your key, and relays the identifier.

handle — your code makes the call

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: "…" }
    }
}

If the endpoint answers with a non-2xx status, the widget throws Cannot create measure!.

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 — including undefined, and including a thrown exception, which is logged and swallowed — allows it.

The handler is awaited.

The event union

video-stream-loading reason is one of "denied", "no-device", "not-supported", "already-used".

aborted reasons carries either a conformity code (CONFORMITY_POOR_LIGHT, CONFORMITY_MUCH_VARIATIONS, CONFORMITY_FACE_PRESENCE, CONFORMITY_LOW_FPS, CREDIT_EXCEEDED, MISSING_USER_DATA_*, …) or a failure reason (WIDGET_RESIZED, FOCUS_LOST, CANCELED_WHILE_CAPTURING, CREATE_MEASURE_ERROR, WS_CONNECTION_ERROR, VIDEO_SOURCE_ENDED, …).

In a result event, each variable is { value, signals, error: null } on success, or { value: null, error } on failure.

colors

Eleven slots, each a hex string (#RGB or #RRGGBB). All eleven are required once you supply the object.

Only color01 and color02 are used to derive further tints and shades; the rest are applied literally.

pages

Which screens appear, and how.

pages: {
    notice: { ignore: false },
    logo: { ignore: false, data: null },
    staticFacePlacement: { ignore: false },
    result: { ignore: false, titles: { ignore: false } },
    validates: {
        1: { ignore: false }, 2: { ignore: false },
        3: { ignore: true },  4: { ignore: false },
        5: { ignore: false }, 6: { ignore: false },
        7: { ignore: false }, 8: { ignore: false }
    }
}

The eight onboarding screens

All eight are required when you supply validates.

Screen 3 takes a fields object when enabled:

validates: {
    3: {
        ignore: false,
        fields: {
            height: { ignore: false },
            weight: { ignore: false },
            age: { ignore: false },
            sex: { ignore: false },
            smokingStatus: { ignore: false },
            externalId: { ignore: true }
        }
    }
}

All six keys are required, and they cannot all be ignore: true — a form with no fields is refused.

texts

Every user-visible string, overridable per language. The object must carry all ten language keys — ar, de, en, es, fr, it, pl, pt, pt_BR, tr — and each is merged over the built-in strings, so you override only what you name.

texts: {
    ...Handler.defaultModuleOptions.texts,
    en: {
        ...Handler.defaultModuleOptions.texts.en,
        button: { next: "Continue" }
    }
}

Spreading the defaults is the practical way to satisfy the requirement without restating ten languages by hand.