IntelliWidgets.js SDK

Introduction

This reference documents the available methods in IntelliProve's browser-side JavaScript SDK, IntelliWidgets.js. This guide applies to IntelliWidgets version 2.

Note: While we are slowly transitioning to IntelliWidgets, which use web components, the V2 widgets are still supported and some widgets are not available in the web component variant yet.

Including IntelliWidgets.js

Using our CDN - recommended

Include the IntelliWidgets.js script on the page of your site where you want to use the widgets. It should always be loaded directly from https://cdn.intelliprove.com, rather than included in a bundle or hosted yourself. This ensures you and your customers get the latest updates and improvements live without needing an intervention from your end.

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

Using a package install

If preferred or required, we also provide support for the installation of our SDK as a package. This can be installed using the npm command into your front-end project. Please note that this approach requires you to manually update the version of our SDK every now and then to make sure you have the latest improvements.

npm install "https://cdn.intelliprove.com/packages/intelli-widgets/v2/<version>.tgz"

Create an SDK instance

IntelliProveWidgets(action_token)

Use IntelliProveWidgets(action_token) to create an instance of the IntelliProveWidgets object. The IntelliProveWidgets object is the entrypoint to the rest of the IntelliWidgets.js SDK.

A valid user action token is required when calling this constructor, as it identifies the user to IntelliProve.

Replace the placeholder action token in the example with a valid user action token, created with your API key.

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

Authentication

-> Learn how to create user action tokens with the API

Property	Description
action_token string	Valid user-authenticated JWT action token

Verify status

IntelliProveWidgets.loaded()

Use IntelliProveWidgets.loaded() to verify that IntelliWidgets.js loaded successfully.

If the loading of IntelliWidgets.js failed, this will result in an error when creating widgets.

const loaded = IntelliProveWidgets.loaded();

intelli.mountWidget(selector, name, config, variation="", themeOverrides={}, version=null)

The intelli.mountWidget method creates a new widget and attaches it to the DOM.

First you need to create a container DOM element on your platforms website. intelli.mountWidget accepts a CSS selector (e.g., #biomarker-tile).

Check out the widget overview for a full list of the available widgets.

Adjust the appearance of the widget by overriding the theming variables.

Optionally specify the widget version to mount (e.g., 1 or 2). If not set, the default widget version is used.

intelli.mountWidget(
   "#biomarker-tile",
   "biomarker",
   {
      face_scan_id: "3db0ca36ba714354bfc2c2c215aba2a9",
      parameter: "respiratory_rate"
   },
   "default"
);

Property	Description
selector string	The CSS selector where your widget will be mounted.
name string	The name from one of the available widget types.
config object	Configurations for creating the widget.
variation optional string	Widget variation, if applicable.
themeOverrides optional object	Custom styling variables applied to the widget. Refer to Widget Appearance for more information.
version optional number	Widget version to mount.

Exceptions

IntelliActionTokenError, IntelliWidgetNotFoundError, IntelliInvalidParameterError, IntelliUnexpectedError, IntelliSdkLoadingError

intelli.setDefaultWidgetVersion(version)

Sets the default widget version (i.e. 1 or 2) to be used across all widgets.

The current default widget version is 2. To ensure consistent behavior, we recommend explicitly setting the desired widget version using this method or pass the version directly in mountWidget.

intelli.setDefaultWidgetVersion(1);

Change locale

intelli.changeLanguage(locale)

The intelli.changeLanguage(locale) method allows you change the locale for all active widgets.

Newly created widgets will have the new locale by default.

intelli.changeLanguage('en');

Property	Description
locale string enum	Two-letter language code for preferred user language Values: "en", "nl", "fr"

Errors

The IntelliWidgets.js SDK may raise exceptions for a few reasons, such as authentication errors, invalid parameters or loading errors. We recommend writing code that gracefully handles all possible API exceptions. Check the error message for more information.

Below you find an overview of the various errors that are defined.

Error	Description	Fix
IntelliActionTokenError	The provided action token is invalid	Request a new action token.
IntelliWidgetNotFoundError	The widget or variation of the widget is not found	Verify the method input values. Check the error message for more information.
IntelliInvalidParameterError	The parameter or value that was provided is invalid	Verify the method input values. Check the error message for more information.
IntelliUnexpectedError	An unexpected error occurred	Check the error message for more information. If the problem persists, please contact the support team.
IntelliSdkLoadingError	The SDK failed to load properly	Reload the page. If the problem persists, please contact the support team.

Custom use cases

Forking the SDK

Our SDK is designed to be widely compatible across browsers, devices, and frameworks. We also recognize that some use cases require additional flexibility. That’s why the SDK is available as a public Git repository on GitHub.

You can fork the repository if your application needs a change or feature we don’t currently support. Pull requests are welcome if you believe your addition would benefit other users. However, we only merge changes that maintain compatibility with major platforms and frameworks. If your changes don’t meet this requirement, you’ll need to build, host, or bundle your own version of the SDK. In such cases, IntelliProve cannot provide support for your custom code.

-> Open GitHub repository