1. Get a widget URL

This guide will take you through embedding the Connect Widget in a typical website using our widget loader. There are other ways to do this, but we recommend the integration discussed here; it’s by far the most common approach. We’ll also go over some best practices.

While working through this guide, it’s also a good idea to use our demo application to follow along.

The first thing you’ll need to do is request a widget URL. There are all sorts of ways to configure the Connect Widget using this endpoint, but for now, we’re going to use a plain old URL with the default options. This means the only thing we need to include in the request body is the widget_type, which we’ll set to connect_widget. For fun, we’re also including the color_scheme parameter as well. To see all the configuration options, navigate to the request widget URL endpoint in the Platform API documentation.

Endpoint:

POST /users/{user_guid}/widget_urls

Example request

1
2
3
4
5
6
7
8
9
10
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-u '{client_id}:{api_key}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "color_scheme": "dark"
      }
    }'

Example response

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "u-abc-789"
  }
}

2. Use the widget loader

Now that you’ve got a URL, you can actually work on embedding it in a website. The simplest way to do this is to use the widget loader provided by MX. The widget loader is a simple script that primarily sets up the iframe, offers an onEvent callback, and allows you to configure the widget.

Setting up the widget loader

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<script src="https://atrium.mx.com/connect.js"></script>
/**
 * The reference to "atrium" is a holdover from a legacy API.
 * Nevertheless, this is still the correct source for the widget loader
 * even in the context of the Platform API.
 */

<script>
var mxConnect = new window.MXConnect({
  id: "connect-widget",
  iframeTitle: "Connect",
  /**
   * Callback that for handling all events within Connect.
   * Only called in  ui_message_version 4 or higher.
   *
   * The events called here are the same events that come through post
   * messages.
   */
  onEvent: function (type, payload) {
    console.log("onEvent", type, payload);
  },
  targetOrigin: "*",
})
</script>

Now that we have the widget loader set up and a URL ready, we can load the Connect widget in our application by simply calling mxConnect.load({url}).

3. Handle events

Now that the widget is loaded, you can start working on what to do when certain events happen.

Perhaps the most important event is the mx/connect/memberConnected event, which indicates that the member has been successfully authenticated and the aggregation (or verification) process is complete.

Generally, you’ll want to use this event as the cue to close the widget and move on with your app. However, the end user can loop back and add another connection as well. Just be conscious of the exact state and flow that your app needs.

Handling specific events

1
2
3
4
5
6
7
8
9
10
var mxConnect = new window.MXConnect({
  //...
  onEvent: function (type, payload) {
    if (type === "mx/connect/memberConnected") {
      myApp.handleSuccessfulConnection(payload)
    }
  },
  config: { ui_message_version: 4 },
  // ...
})

While there are many events to listen to, it is best to let the widget do its thing until a connection is successful. The Connect Widget knows how to recover from user and connection errors.

4. Next steps

We’ve now loaded the Connect Widget with the simplest default configuration, and the end user has added a brand new connection with it. We’ve also listened for the most important postMessage indicating that a new member has been successfully connected.

However, the Connect Widget can be loaded with a number of different configuration options for different situations. These could be loading a specific institution, resolving MFA and connection errors, starting instant account verification, and more.