Upgrading from v1

Version 2 is a separate module rather than an update of version 1. An integration does not migrate itself: you replace the script, rename a handful of options, and adapt the way you obtain a credential.

Nothing on the server changes. The same account, the same measurements, the same variables. What changes is the code in your page.

The five changes, in order

1. The script and the mounting

<!-- v1 -->
<script src="https://cdn.saphere.ai/saphere-scan/v1/js/main.min.js"></script>
<script>
    Handler.load("#scan", options)
</script>

<!-- v2 -->
<script type="module">
    import SaphereScan from "https://cdn.saphere.ai/saphere-scan/v2/main.js"

    const instance = SaphereScan.create("#scan", options)
    await instance.bootstrap()
</script>

Two differences behind that. create() returns an instance rather than acting on a global, so several widgets can coexist on one page. And mounting is now in two steps: create() validates your options straight away and throws if something is wrong, bootstrap() puts the widget on screen.

The container contract is the same: you give a div with a height, the widget fills it, and it keeps its styles to itself.

2. The credential

This is the change that needs your server, and the reason v2 exists.

In v1, your endpoint created a measure and returned its identifier. That identifier opened the measurement session.

In v2, your endpoint issues an access token: valid for a short time, usable once, and carrying only the permission to run one measurement. Your API key stays on your server in both versions, but a token that leaks is worth almost nothing, where a measure identifier was worth a whole measurement.

// v1
createMeasure: { strategy: "delegate", url: "/api/saphere-measure" }

// v2
proxy: { retrieveAccessToken: { strategy: "delegate", url: "/api/saphere-token" } }

What your endpoint no longer carries is the measurement itself. In v1 you described it in the body of the call that created it; in v2 it is an option of the widget, createMeasureOptions, where the patient data you already hold goes. The token authorises; the option describes.

The strategies keep their names and their meaning: delegate for the widget to call your endpoint, handle for your own code to obtain the value. Access tokens covers what your endpoint has to call.

3. The events

v1 reported six events; v2 reports forty-one, and none of the old names survives. The naming is now domain:event, so ready became widget:ready, result became measure:result, and so on. The full list, with a v1-to-v2 table, is in Events.

One behaviour moved rather than being renamed. In v1, your onEvent handler was awaited, and returning false cancelled a screen change — which meant a slow handler could hold the interface. In v2, onEvent is never awaited, and the power to refuse moved to hooks, where it is bounded by a guard delay.

4. The options that changed name

5. What does not change

The measurement itself. The same thirty seconds, the same conditions, the same variables, the same result shape. A user comparing the two versions sees a different interface, not a different measurement.

Your customisation, too: screens, colours and wording are prepared in the same console workshop for both versions.