> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK

The Web Widget SDK simplifies Connect Widget integrations.

<Warning>
  **LEGACY SDK**

  This page documents the legacy Web SDK. For new integrations, see [Web SDK](/connect/guides/web-sdk).
</Warning>

After completing this guide, your application will display the Connect Widget using the Web Widget SDK, available on [GitHub](https://github.com/mxenabled/web-widget-sdk).

<Note>
  **PREREQUISITES**

  Sign up for a developer account on the [Client Dashboard](https://dashboard.mx.com/sign_in).
</Note>

## 1. Install the Web Widget SDK

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

<Tabs>
  <Tab title="npm">
    ```shell theme={null}
    npm install --save @mxenabled/web-widget-sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```shell theme={null}
    yarn add @mxenabled/web-widget-sdk
    ```
  </Tab>
</Tabs>

## 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.

<Tabs>
  <Tab title="CommonJS">
    A [CommonJS module](https://nodejs.org/api/modules.html) 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](https://browserify.org/)).

    ```js CommonJS theme={null}
    const widgetSdk = require("@mxenabled/web-widget-sdk")
    const widget = new widgetSdk.ConnectWidget({
        container: "<CONTAINER SELECTOR>",
        url: "<Widget URL>"
        // additional widget options
    })
    ```
  </Tab>

  <Tab title="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).

    ```js ES theme={null}
    import * as widgetSdk from "@mxenabled/web-widget-sdk"
    const widget = new widgetSdk.ConnectWidget({
        container: "<CONTAINER SELECTOR>",
        url: "<Widget URL>"
        // additional widget options
    })
    ```
  </Tab>

  <Tab title="AMD">
    The [AMD module](https://requirejs.org/docs/whyamd.html) 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.

    ```html AMD theme={null}
    <div id="container"></div>

    <script src="https://requirejs.org/docs/release/2.3.6/minified/require.js"></script>
    <script>
    requirejs(["node_modules/@mxenabled/web-widget-sdk/dist/amd/index.js"], function (widgetSdk) {
    const widget = new widgetSdk.ConnectWidget({
        container: "#container",
        url: "<Widget URL>"
        // additional widget options
        })
    })
    </script>
    ```
  </Tab>

  <Tab title="UMD">
    The [UMD module](https://github.com/umdjs/umd) 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.

    ```html UMD theme={null}
    <div id="container"></div>

    <script src="node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js"></script>
    <script>
    const widget = new widgetSdk.ConnectWidget({
        container: "#container",
        url: "<Widget URL>"
        // additional widget options
    })
    </script>
    ```
  </Tab>
</Tabs>

## 3. Generate the Widget URL

There are two options to generate the widget URL:

* Option A: [Using a Platform API endpoint](#platform-api)
* Option B: [Using a proxy server](#proxy-server)

### a. Platform API

Use the [Request Widget URL](/api-reference/platform-api/reference/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.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Accept-Version: v20250224' \
    -H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
    --data-raw '{
      "widget_url": {
        "widget_type":"connect_widget"
        }
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "widget_url": {
        "type": "connect_widget",
        "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
        "user_id": "u-2345"
      }
    }
    ```
  </Tab>
</Tabs>

Then set the URL from the API response in the `url` Widget class option. See [Class Options](#class-options) for a complete list.

```js theme={null}
const options = {
  container: "#widget",
  url: "https://int-widgets.moneydesktop.com/md/connect/..."
}
```

### 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](#class-options) for a complete list.

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

<Accordion title="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](/connect/widget-events#back-to-search) 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](/connect/#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.                                                                                                                                |
</Accordion>

```js theme={null}
const options = {
  container: "#widget",
  proxy: "https://server.com/mx-sso-proxy",
  colorScheme: "dark",
  disableInstitutionSearch: true
}
```

## 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.

```js theme={null}
const options = {
  container: "#widget",
  url: "https://int-widgets.moneydesktop.com/md/connect/...."
}

// Instantiating `new sdk.ConnectWidget(...)` mounts the widget in the DOM
const widget = new widgetSdk.ConnectWidget(options)

// Call `unmount` to remove the element and event listeners
widget.unmount()
```

<Check>
  **SUCCESS**

  You've set up the SDK and embedded the Connect Widget!
</Check>

## 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](/api-reference/platform-api/reference/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](/products/connectivity/overview/connectivity-integration-guides/connect-widget-flow).