--- title: IntelliWidgets.js SDK slug: technical-docs/dEkc-intelliwidgetsjs-sdk docTags: createdAt: 2024-10-08T12:23:20.243Z --- # Introduction This reference documents the available methods in IntelliProve's browser-side JavaScript SDK, **IntelliWidgets.js**. # 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. :::CodeblockTabs Including Intelli.js ```html ``` ::: ### 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. :::CodeblockTabs Including Intelli.js ```bash npm install "https://cdn.intelliprove.com/packages/intelli-widgets/v1/.tgz" ``` ::: # Create an SDK instance `IntelliProveWidgets(action_token)` :::::VerticalSplit{layout="middle"} :::VerticalSplitItem 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](docId\:BiuPVixvHltbukKLR2ATI) 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](docId\:BiuPVixvHltbukKLR2ATI). ::: ::::VerticalSplitItem :::CodeblockTabs Initialise Intelli.js ```javascript const intelli = IntelliProveWidgets(""); ``` ::: ### Authentication :::hint{type="success"} [ -> Learn how to create user action tokens with the API](docId\:BiuPVixvHltbukKLR2ATI) ::: :::: ::::: | **Property** | **Description** | | ---------------------------- | ----------------------------------------- | | `action_token`
*string* | Valid user-authenticated JWT action token | # Verify status `IntelliProveWidgets.loaded()` :::::VerticalSplit{layout="middle"} :::VerticalSplitItem Use `IntelliProveWidgets.loaded()` to verify that IntelliWidgets.js loaded successfully. If the loading of IntelliWidgets.js failed, this will result in an [error](docId\:dEkcuoAPHRmcZXe_caJ5v) when creating widgets. ::: ::::VerticalSplitItem :::CodeblockTabs Intelli.js loaded ```javascript const loaded = IntelliProveWidgets.loaded(); ``` ::: :::: ::::: # Mount a widget `intelli.mountWidget(selector, name, config, variation="", themeOverrides={}, version=null)` :::::VerticalSplit{layout="middle"} :::VerticalSplitItem 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](docId\:oORapCkooI6-89xrAfduV) for a full list of the available widgets. Adjust the [appearance](docId:2kL5Bnrb-6uIcQrFAqsiG) 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. ::: ::::VerticalSplitItem :::CodeblockTabs Mount a widget ```javascript intelli.mountWidget( "#biomarker-tile", "biomarker", { face_scan_id: "3db0ca36ba714354bfc2c2c215aba2a9", biomarker: "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](docId\:sXVSW2jFSOhr7XbXEYZ_J). | | `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](docId:2kL5Bnrb-6uIcQrFAqsiG) for more information. | | `version`
*optional number* | Widget version to mount. | **Exceptions** `IntelliActionTokenError`, `IntelliWidgetNotFoundError`, `IntelliInvalidParameterError`, `IntelliUnexpectedError`, `IntelliSdkLoadingError` # Set default widget version `intelli.setDefaultWidgetVersion(version)` ::::VerticalSplit{layout="middle"} :::VerticalSplitItem Sets the default widget version (i.e. `1` or `2`) to be used across all widgets. The **current default** widget version is `1`, maintained for** backward compatibility**. This default may change to `2` in a future SDK version. To ensure consistent behavior, we recommend **explicitly setting the desired widget version** using this method or pass the version directly in `mountWidget`. ::: :::VerticalSplitItem ```javascript intelli.setDefaultWidgetVersion(1); ``` ::: :::: # Change locale `intelli.changeLanguage(locale)` ::::VerticalSplit{layout="middle"} :::VerticalSplitItem The `intelli.changeLanguage(locale)` method allows you change the locale for **all active widgets**. Newly created widgets will have the new locale by default. ::: :::VerticalSplitItem ```javascript 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](mailto\:support@intelliprove.com). | | `IntelliSdkLoadingError` | The SDK failed to load properly | Reload the page. If the problem persists, please contact the [support team](mailto\:support@intelliprove.com). |