Migration from V2 to V3

Overview

This guide explains how to migrate from IntelliWidgets V2 (JavaScript SDK) to IntelliWidgets V3, which is based on web components.

IntelliWidgets V3 introduces a simpler and more modern integration approach, reducing the amount of setup and JavaScript required to render widgets on your platform.

Core concept

The main change in V3 is how widgets are integrated.

V2 (SDK) uses a JavaScript API to create and mount widgets imperatively
V3 (Web Components) uses native HTML elements to render widgets declaratively

In practice, this means:

You no longer need to initialize an SDK instance
You no longer mount widgets using selectors
Widgets are placed directly in your HTML
A shared <ip-session> component replaces the SDK instance and provides global configuration (such as authentication and language)

This shift makes integrations easier to maintain and avoids common issues such as CSS or script conflicts across different frameworks.

Step-by-step migration

1. Replace the SDK script

Remove the V2 SDK script:

<script src="https://cdn.intelliprove.com/packages/intelli-widgets/v2/latest.js"></script>

Add the V3 script:

<script type="module" src="https://cdn.intelliprove.com/packages/intelli-widgets/v3/latest.js"></script>

2. Remove SDK initalization

In V2, you initialize the SDK:

const intelli = IntelliProveWidgets("<USER_ACTION_TOKEN>");

In V3, this is replaced by the <ip-session> component:

<ip-session action-token="<USER_ACTION_TOKEN>">
  <!-- widgets go here -->
</ip-session>

The session component provides global configuration such as authentication and language.

3. Replace mountWidget with components

In V2:

intelli.mountWidget("#biomarker", "biomarker", {
  face_scan_id: "...",
  parameter: "respiratory_rate"
});

In V3:

<ip-biomarker
  face-scan-id="..."
  parameter="respiratory_rate">
</ip-biomarker>

Widgets are now rendered declaratively using HTML.

4. Wrap all widgets in session

All IntelliProve web components must be placed within an <ip-session>:

<ip-session action-token="<USER_ACTION_TOKEN>">
  <ip-biomarker parameter="respiratory-rate"></ip-biomarker>
</ip-session>

This replaces the SDK instance and ensures all widgets share the same configuration.

5. Language handling

In V2:

intelli.changeLanguage("en");

In V3:

<ip-session action-token="<USER_ACTION_TOKEN>" language="en">

6. Theming

V3 widgets are built as web components, making them more flexible and customizable than in V2. Customization options are continuously being expanded.

If your V2 integration uses custom styling, you may need to adjust how these are applied in V3.