1. Get a Widget URL

This guide will take you through embedding Connect 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 Connect URL using the request widget URL endpoint in the Platform API. There are all sorts of ways to configure Connect using this endpoint, but for now, we’re going to just 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. Just for fun, we’re also including the color_scheme parameter as well.

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-jeff-201709221210"
  }
}

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.

1
<script type="text/javascript" src="https://atrium.mx.com/connect.js"></script>

Once you have added it to your webapp. You can use the MXConnect constructor to setup the widget instance.

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
25
26
27
<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);
  },
  config: {
    ui_message_version: 4
  },
  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 happening. This postMessage does not necessarily mean that aggregation has completed and all data has been gathered.

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.

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

Handlings 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 },
  // ...
})

4. Next steps

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

However, Connect 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.

Soon, we’ll have guides covering these situations, but for now, take a look at our reference documentation for configuration options.