Embed Widget using Web SDK

The Web Widget SDK simplifies Connect Widget integrations.

After completing this guide, your application will display the Connect Widget using the Web Widget SDK, available on GitHub.

Prerequisites

Sign up for a developer account on the Client Dashboard.

Step 1

Install the Web Widget SDK

Install the SDK at the root of your project using your preferred package manager.

npm

_10

npm install --save @mxenabled/web-widget-sdk

yarn

_10

yarn add @mxenabled/web-widget-sdk

Step 2

Incorporate the SDK

The Web Widget SDK provides multiple modules that you can import and use in your application, depending on your build process.

CommonJS

A CommonJS module is exported by this package and available by requiring @mxenabled/web-widget-sdk. Require this module and build your project with a build tool that supports CommonJS modules (such as browserify).

CommonJS

Language:js

_10

const widgetSdk = require("@mxenabled/web-widget-sdk")

_10

const widget = new widgetSdk.ConnectWidget({

_10

container: "<CONTAINER SELECTOR>",

_10

url: "<Widget URL>"

_10

// additional widget options

_10

})

ES

An ES module is exported by this package and available by importing @mxenabled/web-widget-sdk. Import this module and build your project with a build tool that supports ES modules (such as webpack).

ES

Language:js

_10

import * as widgetSdk from "@mxenabled/web-widget-sdk"

_10

const widget = new widgetSdk.ConnectWidget({

_10

container: "<CONTAINER SELECTOR>",

_10

url: "<Widget URL>"

_10

// additional widget options

_10

})

AMD

The AMD module can be found in node_modules/@mxenabled/web-widget-sdk/dist/amd/index.js. To serve this file in your application, you will have to host it yourself. Transfer this file into any location where it can be made publicly available. Once the file is available, you can import and use it.

AMD

Language:html

_12

<div id="container"></div>

_12

_12

<script src="https://requirejs.org/docs/release/2.3.6/minified/require.js"></script>

_12

<script>

_12

requirejs(["node_modules/@mxenabled/web-widget-sdk/dist/amd/index.js"], function (widgetSdk) {

_12

const widget = new widgetSdk.ConnectWidget({

_12

container: "#container",

_12

url: "<Widget URL>"

_12

// additional widget options

_12

})

_12

})

_12

</script>

UMD

The UMD module can be found in node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js. To serve this file in your application, you will have to host it yourself. Transfer this file into any location where it can be made publicly available. Once the file is available, you can import and use it.

UMD

Language:html

_10

<div id="container"></div>

_10

_10

<script src="node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js"></script>

_10

<script>

_10

const widget = new widgetSdk.ConnectWidget({

_10

container: "#container",

_10

url: "<Widget URL>"

_10

// additional widget options

_10

})

_10

</script>

Step 3

Generate the Widget URL

There are two options to generate the widget URL:

• Option A: Using a Platform API endpoint
• Option B: Using a proxy server

a. Platform API

Use the Request Widget URL endpoint to get a URL. Note that this url expires after ten minutes or upon first use, so you may need to request it again while following this guide.

Request

Response

Language:shell

_10

curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \

_10

-H 'Content-Type: application/json' \

_10

-H 'Accept: application/json' \

_10

-H 'Accept-Version: v20250224' \

_10

-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \

_10

--data-raw '{

_10

"widget_url": {

_10

"widget_type":"connect_widget"

_10

}

_10

}'

Then set the URL from the API response in the url Widget class option. See Class Options for a complete list.

_10

const options = {

_10

container: "#widget",

_10

url: "https://int-widgets.moneydesktop.com/md/connect/..."

_10

}

b. Proxy Server

The SDK can make requests on your behalf to your backend service that calls the Platform API.

Pass the proxy URL to a widget component via the proxy option. See Class Options for a complete list.

When using a proxy server, pass the widget's configurations directly to the widget component.

Configurations list

Configuration option	Description
colorScheme	Load the widget with the specified color_scheme; options are light and dark. Defaults to light.
currentInstitutionCode	Load the widget into the credential view for the specified institution.
currentInstitutionGuid	Load the widget into the credential view for the specified institution.
currentMemberGuid	Load the widget into a specific member that contains an error or requires multifactor authentication. The widget will determine the best view to load based on the member's current state. current_member_guid takes precedence over current_institution_code and current_institution_guid.
disableInstitutionSearch	This determines whether the institution search is skipped within the Connect Widget. This option must be used with current_institution_code, current_instituion_guid, or current_member_guid. You must listen to the backToSearch postMessages to intercept the user navigating back to search during the flow. Defaults to false.
includeTransactions	This determines whether transaction data are retrieved. Defaults to true in aggregation mode and false in verification mode. This can be set in either aggregation or verification mode. This option does not affect future foreground or background aggregations.
language	Load the widget in the specified language. Defaults to en-US. For more info, Language Support.
uiMessageWebviewUrlScheme	This is a client-defined scheme used in OAuth redirects in WebViews; also used in URL updates when these replace postMessages in WebViews. Defaults to mx.
updateCredentials	Load the widget into a view that allows them to update the current member. Optionally used with current_member_guid. This option should be used sparingly. The best practice is to use current_member_guid and let the widget resolve the issue.

_10

const options = {

_10

container: "#widget",

_10

proxy: "https://server.com/mx-sso-proxy",

_10

colorScheme: "dark",

_10

disableInstitutionSearch: true

_10

}

Step 4

Mount and Unmount the Widget

When you instantiate a widget with options, it mounts itself in the DOM and sets up event listeners. Call the unmount method when closing the widget and before creating a new instance.

_10

const options = {

_10

container: "#widget",

_10

url: "https://int-widgets.moneydesktop.com/md/connect/...."

_10

}

_10

_10

// Instantiating `new sdk.ConnectWidget(...)` mounts the widget in the DOM

_10

const widget = new widgetSdk.ConnectWidget(options)

_10

_10

// Call `unmount` to remove the element and event listeners

_10

widget.unmount()

success

You've set up the SDK and embedded the Connect Widget!

Class Options

You can configure the state and behavior of the widget with the following class options.

Options	Description
container	CSS selector or node reference to the element where the widget iframe should be mounted.
iframeTitle	Sets the title attribute of the iframe.
proxy	Proxy server URL.
style	Styles applied to the view containing the widget. Default styles: border: "none", height: "550px", width: "320px"
url	URL returned in the Request Widget URL response. This prop is required.

Troubleshooting

If widget events aren't triggered, check the following:

• Ensure your widget URL request is correctly configured for the Web SDK:
  • ui_message_version is set to 4
  • is_mobile_webview is set to false
• Ensure you use the corresponding widget class for the widget_type in the widget URL request. For example, if you set widget_type to connect_widget, use the ConnectWidget class.

Next Steps

Now that the widget can display in your application, you'll build some additional flows, specify the data you want to retrieve when a user connects to their financial institution, handle events the widget sends, and more.

See Integrate using MX's Connect Widget.