Integrate Any PFM Widget

This guide shows you how to integrate any PFM Widget on a website using an iframe (recommended) or using the Widget Loader. You can also integrate on a mobile app.

info

Before you can integrate the widget, you must have worked with MX to enable your access to our PFM product.

For this guide, you'll either use the Platform API or SSO API. The API you use depends on what you have purchased and have enabled. If you have the Nexus API enabled, you'll use the SSO API.

Integrate on a Website (iframe)

Recommended

This shows how to integrate the widget on a website using an iframe.

Step 1

Create an iframe. If you're integrating the Money Dashboard Widget, see IFrame Integration for a code example to help maintain proper display.

Set the width and height to 100%, or use the widget's supported dimensions.

Language:shell


_10<html>
_10  <body>
_10    <iframe width="100%" height="100%" src=""></iframe>
_10  </body>
_10</html>

Step 2

In the iframe's src, you'll need to request a widget URL by specifying the widget_type, using the Platform API or the SSO API.

For a list of acceptable values, see:

Widget Types for Platform API
Widget Types for SSO API

The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered.

Language:shell


_10<html>
_10  <body>
_10    <iframe width="100%" height="100%" src=requestURL()></iframe>
_10  </body>
_10</html>

Step 3

Optionally create listeners for the application events.

See Postmessage UI Events for more info.

Language:shell


_23<html>
_23  <head>
_23  </head>
_23  <body>
_23    <iframe id="widgetIframe" width="100%" height="100%" src=requestURL()></iframe>
_23    <script>
_23        // an example for handling events.
_23        window.addEventListener('message', (event) => {
_23            if (event.data.mx) {
_23                // example of handling an application event.
_23                if (event.data.type === "mx/load") {
_23                  // This event is triggered when the widget is loaded.
_23                }
_23                
_23                // example of handling an application event.
_23                if (event.data.type === "mx/ping") {
_23                  // This event is triggered when the user interacts with the UI.
_23                }
_23            }
_23        });
_23    </script>
_23  </body>
_23</html>

Step 4

Depending on the widget you're integrating, you may have to create additional event listeners:

If integrating the Connections Widget, you must create listeners for all the Connections Widget events, which includes all the Connect Widget's postMessage events.
If integrating the Mini Finstrong Widget, you must create listeners for all the Mini Finstrong Widget's events.

Language:shell


_22<html>
_22  <head>
_22  </head>
_22  <body>
_22    <iframe id="widgetIframe" width="100%" height="100%" src=requestURL()></iframe>
_22    <script>
_22        // an example for handling events.
_22        window.addEventListener('message', (event) => {
_22            if (event.data.mx) {
_22                if (event.data.type === "mx/load") {
_22                  // This event is triggered when the widget is loaded.
_22                }
_22                
_22                if (event.data.type === "mx/ping") {
_22                  // This event is triggered when the user interacts with the UI.
_22                  // For example, when the user swipes through the carousel.
_22                }
_22            }
_22        });
_22    </script>
_22  </body>
_22</html>

Step 1

Create an iframe. If you're integrating the Money Dashboard Widget, see IFrame Integration for a code example to help maintain proper display.

Set the width and height to 100%, or use the widget's supported dimensions.

Step 2

In the iframe's src, you'll need to request a widget URL by specifying the widget_type, using the Platform API or the SSO API.

For a list of acceptable values, see:

Widget Types for Platform API
Widget Types for SSO API

The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered.

Step 3

Optionally create listeners for the application events.

See Postmessage UI Events for more info.

Step 4

Depending on the widget you're integrating, you may have to create additional event listeners:

If integrating the Connections Widget, you must create listeners for all the Connections Widget events, which includes all the Connect Widget's postMessage events.
If integrating the Mini Finstrong Widget, you must create listeners for all the Mini Finstrong Widget's events.

Language:html


_10<html>
_10  <body>
_10    <iframe width="100%" height="100%" src=""></iframe>
_10  </body>
_10</html>

This shows how to integrate the widget on a website using the widget loader.

Step 1

Request a widget URL by specifying the widget_type, using the Platform API or the SSO API.

For a list of acceptable values, see:

Widget Types for Platform API
Widget Types for SSO API

The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered.

Set the height and width to 100%. If you don't, it will default to 600px height and 100% width.

Language:shell


_16<html>
_16  <head>
_16    <title>My Web Page</title>
_16    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_16    <script type="text/javascript">
_16      var myWidget = new MoneyDesktopWidgetLoader({
_16        url: 'https://widgets.moneydesktop.com/md/accounts/XXXXX',
_16        width: "100%",
_16        height: "100%"
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 2

Add the widget loader script to the page. Place this file before any other code related to the widgets. This custom script loads the widgets onto the page.

You can load the widget loader from the MX production server or download and store it in your local environment. We update the widget loader when needed, so if you're caching it on your server, refresh your cached version monthly.

Language:shell


_16<html>
_16  <head>
_16    <title>My Web Page</title>
_16    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_16    <script type="text/javascript">
_16      var myWidget = new MoneyDesktopWidgetLoader({
_16        url: 'https://widgets.moneydesktop.com/md/accounts/XXXXX',
_16        width: "100%",
_16        height: "100%"
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 3

Add a widget placeholder element. Our widget loader will use this placeholder element to embed an iframe containing the widget. The element must have an id of md-widget.

Language:shell


_16<html>
_16  <head>
_16    <title>My Web Page</title>
_16    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_16    <script type="text/javascript">
_16      var myWidget = new MoneyDesktopWidgetLoader({
_16        url: 'https://widgets.moneydesktop.com/md/accounts/XXXXX',
_16        width: "100%",
_16        height: "100%"
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 4

Load the widget into the placeholder element.

Create a new instance of the MoneyDesktopWidgetLoader class, which is defined in the widget loader script. When you instantiate MoneyDesktopWidgetLoader, you must pass in an object with at least the required URL parameter, and possibly one or more optional parameters.

The widget loader will wait until the page has been loaded, and then load the widget into the placeholder element.

Make sure the widget uses its [supported dimensions](/products/experience/pfm#supported-dimensions.

Language:shell


_16<html>
_16  <head>
_16    <title>My Web Page</title>
_16    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_16    <script type="text/javascript">
_16      var myWidget = new MoneyDesktopWidgetLoader({
_16        url: 'https://widgets.moneydesktop.com/md/accounts/XXXXX',
_16        width: "100%",
_16        height: "100%"
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 1

Request a widget URL by specifying the widget_type, using the Platform API or the SSO API.

For a list of acceptable values, see:

Widget Types for Platform API
Widget Types for SSO API

The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered.

Set the height and width to 100%. If you don't, it will default to 600px height and 100% width.

Step 2

Add the widget loader script to the page. Place this file before any other code related to the widgets. This custom script loads the widgets onto the page.

Step 3

Add a widget placeholder element. Our widget loader will use this placeholder element to embed an iframe containing the widget. The element must have an id of md-widget.

Step 4

Load the widget into the placeholder element.

The widget loader will wait until the page has been loaded, and then load the widget into the placeholder element.

Make sure the widget uses its [supported dimensions](/products/experience/pfm#supported-dimensions.

Language:html


_16<html>
_16  <head>
_16    <title>My Web Page</title>
_16    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_16    <script type="text/javascript">
_16      var myWidget = new MoneyDesktopWidgetLoader({
_16        url: 'https://widgets.moneydesktop.com/md/accounts/XXXXX',
_16        width: "100%",
_16        height: "100%"
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Integrate on a Mobile App

To integrate the widget on a mobile app:

Request a PFM widget URL by specifying the widget_type, using the Platform API or SSO API. The URL you'll receive is single-use and expires after 10 minutes. You must request a new URL every time the page is rendered. For a list of acceptable values, see:
- Widget Types for Platform API
- Widget Types for SSO API
Load the URL received from the previous request into a WebView.
See Events in Mobile WebViews.
Capture and parse URLs for application events.
If you're integrating the Connections Widget or Mini Finstrong Widget, you'll need to capture and parse URLs for additional events. See PostMessage UI Events for more information.

Common Problems

This section covers some common problems with loading a widget URL into a WebView.

Minimum Size

To embed our mobile widgets into a WebView, we require a device width of at least 320 pixels. Depending on the implementation of the WebView, smaller devices may not be provided the full width, leading to display issues.

Money Dashboard integration

In order to have the benefit of the full responsive nature of our application, please don't restrict the available browser width by adding margins or padding.

WKWebView vs. UIWebView (iOS)

In apps that run in iOS 8 and later, MX only supports WKWebView. If you previously implemented UIWebView, update your implementation to use WKWebView.

Apple recommends this. For more information, see Apple's developer documentation for UIWebView and WKWebView.

Default Padding (iOS)

iOS adds additional padding to its WebViews by default, which sometimes causes problems.

To fix this:

Select the WebView providing the widgets in your application and navigate to the size inspector.
Change the layout margins from "Default" to "Explicit".
Update the left and right margins to "0".
Ensure the Width is at least 320 pixels.

Default Margin (iOS and Android)

Whether using WebViews on Android or iOS, most browsers will have a default margin (set in the user agent stylesheet) on the body element when rendering the HTML page responsible for loading a widget. This margin is deducted from the total available width of the containing element, which will cause a problem.

To fix this:

Determine the computed width available on the body element.
- The width available to the iframe can be confirmed by inspecting the iframe injected by MX and typing window.innerWidth in the JavaScript console. The width available to the iframe must be at least 320 pixels.
Confirm the body and HTML elements have their padding and margin set to "0."

Viewport (iOS and Android)

For mobile widgets to render correctly, the viewport must be set in a meta tag on the HTML page used to load the widget URL.

The viewport is the size of the window through which a page is seen. It can be smaller or larger than the actual size of a page or device screen.

On most mobile devices, the virtual viewport is larger than the actual screen size; web pages are rendered according to the viewport size, then shrunk down to the actual screen size. This helps when viewing pages that aren't optimized for mobile, but for pages that are optimized for mobile (like the mobile widgets), the viewport meta tag is used to guarantee that the page is rendered properly.

Set a meta tag within the <head> element as follows.

Example

Language:html


_10<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">

This section is for integrating a widget on desktop using the Widget Loader.

It shows the parameters you'll use to set things like the widget's height and width, additional configurations that let you set configurations for specific widgets, and also has the following sections to further help your integration:

Create a Loading Message
Keeping a Session Alive and Logging Out
Loading Multiple Widgets
Loading Widgets at Different Times
Master Widget Deep Linking

When you instantiate MoneyDesktopWidgetLoader, you must pass in an object with at least the required URL parameter, and any of the following optional parameters.

Parameter	Required?	Default Value	Description
`autoload`	No	`true`	Determines if the widget loads automatically. See Loading Widgets at Different Times.
`config`	No		This contains an object in which you can pass several configuration options specific to a given widget type. See Config Parameter for all options.
`deepLink`	No	`accounts`	Only use this for the Master Widget. This lets you set which widget loads in the Master Widget by default. See Master Widget Deep Linking for more information.
`height`	No	`600`	The widget's height, in pixels or a percentage.
`id`	No	`'md-widget'`	Tells the widget loader what element to place the widget in. See Loading Multiple Widgets.
`width`	No	`'100%'`	The widget's width, in pixels or a percentage.
`url`	Yes		The widget's URL, received through an SSO API or Platform API request.

Config Parameter

The config object, as shown in the following example, contains configurations options.

Example

Language:html


_11var myWidget = new MoneyDesktopWidgetLoader({
_11  url: getUrl(url),
_11  width: "100%",
_11  height: "100%",
_11  config: {
_11    transactions: {
_11      selected_account_guid: "ACT-bb749d65-7a86-bece-7138-9690b4e8a212"
_11    }
_11  },
_11  postMessageOrigin: "*"
_11});

Specific options are nested under the name of the widget being configured. You can use one of the following widget names for that name:

accounts
budgets
connections
debts
goals
help
master
mini_budgets
mini_spending
mini_spending_plan
settings
spending
spending_plan
transactions
trends

You can set the following configuration options. Boolean fields default to false unless otherwise specified.

Configuration Option	Data Type	Widget	Description
`is_mobile_webview`	Boolean	All	Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages.
`language`	String	All	Deprecated. See Supported Languages. Defaults to `en-us`.
`ui_message_version`	Integer	All	Determines which version of postMessage events are triggered. All new implementations must include this option when getting any widget URL and must set it to version `4`. Prior versions are deprecated and supported only for existing integrations.
`hide_mark_as_duplicate`	Boolean	Connections	Hides the "mark as duplicate" feature option in the widget.
`hide_partner_managed_members`	Boolean	Connections	Hides any "home" members that are managed by the partner.
`selected_institution_guid`	String	Connections	Loads the widget to a specific selected institution.
`selected_member_guid`	String	Connections	Loads the widget to a selected member.
`update_credentials`	Boolean	Connections	Loads to the update credential feature for a current member. Optionally used with `selected_member_guid`.
`hide_account_filter`	Boolean	Transactions	Hides the account filter feature within the widget.
`selected_account_guid`	String	Transactions	Loads the widget to a selected account.

Create a Loading Message

Any HTML placed inside of the widget placeholder element will be replaced once the widget iframe has loaded. This means you can use the placeholder element's inner HTML to display a loading message. Because this is just HTML, it can be text, images, or anything you want.

The following example adds some loading text that will appear until the widget has loaded.

Example

Language:html


_21<html>
_21  <head>
_21    <title>My Web Page</title>
_21    <script
_21      type="text/javascript"
_21      src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"
_21    ></script>
_21    <script type="text/javascript">
_21      var myWidget = new MoneyDesktopWidgetLoader({
_21        url: "https://widgets.moneydesktop.com/md/accounts/XXXXX",
_21        width: "100%",
_21        height: "100%"
_21      });
_21    </script>
_21  </head>
_21  <body>
_21    <div id="md-widget">
_21      Loading...
_21    </div>
_21  </body>
_21</html>

Keeping a Session Alive and Logging Out

MX provides two important functions for the widget loader: ping and logout.

The ping function resets the session timer, allowing you to keep the session open as long as needed. The default timeout period is 900 seconds, and ping can be used anywhere in that period to restart the timer. A custom timeout period can be set by contacting MX, but MX recommends using the ping method rather than setting a longer timeout.


_10<script type="text/javascript">
_10  var myWidget = new MoneyDesktopWidgetLoader({
_10    url: "https://widgets.moneydesktop.com/md/accounts/XXXXX",
_10    width: "100%",
_10    height: "100%"
_10  });
_10
_10  myWidget.ping();
_10</script>

The logout function ends the session and redirects to the session timeout URL defined in your client profile. If no URL is defined, there is no redirect.

Contact MX if you wish to set a specific session timeout URL.

Loading Multiple Widgets

To load multiple widgets on a single page:

Define multiple placeholder elements, each with a unique CSS id.
In your JavaScript, create an instance of MoneyDesktopWidgetLoader for each widget.
Connect each loader instance to a placeholder element by setting the id property value as the CSS id.

After the page has loaded, all widgets will load in their respective elements.

Here’s an example of loading 3 separate widgets onto a single page.

Example

Language:html


_36<html>
_36  <head>
_36    <title>My Web Page</title>
_36    <script
_36      type="text/javascript"
_36      src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"
_36    ></script>
_36    <script type="text/javascript">
_36      var myAccountsWidget = new MoneyDesktopWidgetLoader({
_36        url: "https://widgets.moneydesktop.com/md/accounts/XXXXX",
_36        width: "100%",
_36        height: "100%",
_36        id: "my-accounts-widget"
_36      });
_36
_36      var myTransactionsWidget = new MoneyDesktopWidgetLoader({
_36        url: "https://widgets.moneydesktop.com/md/transactions/XXXXX",
_36        width: "100%",
_36        height: "100%",
_36        id: "my-transactions-widget"
_36      });
_36
_36      var myBudgetsWidget = new MoneyDesktopWidgetLoader({
_36        url: "https://widgets.moneydesktop.com/md/budgets/XXXXX",
_36        width: "100%",
_36        height: "100%",
_36        id: "my-budgets-widget"
_36      });
_36    </script>
_36  </head>
_36  <body>
_36    <div id="my-accounts-widget"></div>
_36    <div id="my-transactions-widget"></div>
_36    <div id="my-budgets-widget"></div>
_36  </body>
_36</html>

Loading Widgets at Different Times

By default, widgets load automatically once the web page has loaded. If you'd like to load your widgets manually you can use the autoload option by setting autoload to false when instantiating MoneyDesktopWidgetLoader.

When you're ready to load a widget, call the load method on the instance of MoneyDesktopWidgetLoader with the URL.

Here’s an example of loading the Accounts Widget on page load, then loading the Transactions Widget when a button is selected.

Example

Language:html


_38<html>
_38  <head>
_38    <title>My Web Page</title>
_38    <script
_38      type="text/javascript"
_38      src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"
_38    ></script>
_38    <script type="text/javascript">
_38      var myAccountsWidget = new MoneyDesktopWidgetLoader({
_38        url: "https://widgets.moneydesktop.com/md/accounts/XXXXX",
_38        width: "100%",
_38        height: "100%",
_38        id: "my-accounts-widget"
_38      });
_38
_38      var myTransactionsWidget = new MoneyDesktopWidgetLoader({
_38        url: "https://widgets.moneydesktop.com/md/transactions/XXXXX",
_38        width: "100%",
_38        height: "100%",
_38        id: "my-transactions-widget",
_38        autoload: false
_38      });
_38
_38      var loadTransactionsButton = document.getElementById('load-transactions');
_38
_38      loadTransactionsButton.addEventListener('click', function(ev) {
_38        getTransactionWidgetURL().then(widgetURL => {
_38          myTransactionsWidget.load(widgetURL);
_38        });
_38      });
_38    </script>
_38  </head>
_38  <body>
_38    <div id="my-accounts-widget"></div>
_38    <button id="load-transactions">Load Transactions</button>
_38    <div id="my-transactions-widget"></div>
_38  </body>
_38</html>

By default, the Master Widget displays the Accounts Widget on initial load. If you want to display a different widget on initial load, set the deepLink attribute in MoneyDesktopWidgetLoader to one of the following values:

Widget	`deepLink` Value
Accounts Widget	`accounts`
Budgets Widget	`budgets`
Debts Widget	`debts`
Goals Widget	`goals`
Investments Widget	`investments`
Net Worth Widget	`net-worth`
Spending Widget	`spending`
Spending Plan Widget	`spending_plan`
Transactions Widget	`transactions`
Trends Widget	`trends`

If you want your Master Widget to load the Spending Plan Widget by default, you can set deepLink to spending_plan as follows.

Example

Language:html


_10<script>
_10  var myMasterWidget = new MoneyDesktopWidgetLoader({
_10    url: "https://int-widgets.moneydesktop.com/md/master/XXXX",
_10      width: "100%",
_10      height: "100%",
_10      deepLink: "spending_plan"
_10    });
_10</script>

Example scenario: you want to run an email campaign to increase user engagement with the Spending Widget. By default your Master Widget displays the Accounts Widget on initial load, but in this case you want to display the Spending Widget on initial load.

In your email, you might have a link that looks like: <a href="http://yourinstitutiondomain.com/#spending">Click Here</a>. When a user clicks that link, they would be taken to the page that contains your implementation of the Master Widget. On that page you'd need logic that parses the URL to determine if a deepLink value should be set. This can be done with some simple JavaScript.

Your code might look like the following example.

Example

Language:html


_28<a href="http://yourinstitutiondomain.com/#spending">Click Here</a>
_28
_28<html>
_28  <head>
_28    <title>My Web Page</title>
_28    <script
_28      type="text/javascript"
_28      src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"
_28    ></script>
_28    <script type="text/javascript">
_28      var widgetOptions = {
_28        url: "https://widgets.moneydesktop.com/md/master/XXXXX",
_28        width: "100%",
_28        height: "100%",
_28        id: "my-master-widget"
_28      };
_28
_28      if (window.location.hash) {
_28        widgetOptions.deepLink = window.location.hash.replace("#", "");
_28      }
_28
_28      var myMasterWidget = new MoneyDesktopWidgetLoader(widgetOptions);
_28    </script>
_28  </head>
_28  <body>
_28    <div id="my-master-widget"></div>
_28  </body>
_28</html>

PostMessage UI Events

When certain events are triggered in our UI, we send you a postMessage UI event. These events have the information you need to take action in your codebase in response to the event.

If integrating on mobile through a WebView, an alternative to standard postMessage UI events is required. See Events in Mobile WebViews for more information.

warning

Don't use postMessage UI events for keeping data in sync between platforms. Webhooks are a more reliable way of coordinating events between your servers and MX servers.

PostMessage UI events from MX have the following properties:

The mx field that lets you filter out postMessage UI events coming from MX.
The type field that identifies what the event represents at a high level.
The metadata object field that has information related to the type.

The following is an example integration that lets you listen to the events we send.

Example

Language:js


_10
_10function handleEvent(event) {
_10  if (event.data.mx) {
_10    // handle the mx post message using event.data.type and event.data.metadata.
_10  }
_10}
_10
_10window.addEventListener('message', handleEvent)

Events in Mobile WebViews

note

This section only applies if you are embedding the widget in a WebView.

Because of the technical limitations of WebView-based widget integrations, an alternative to standard postMessage UI events is required if embedding the widget into a WebView.

When requesting widget URLs using the Platform API or SSO API, you must include the is_mobile_webview field with a value of true in your request to access WebView event messages.

In WebView integrations, you must capture the URLs delivered via window.location = "someurl" calls within the iframe and use the information provided in those calls to build the necessary logic for coordinating events.

All MX URL message events will have the mx:// prefix as well as the following format: mx://<entity|widget>/<event>?metadata=<metadata as an encodedURI JSON string>.

The following is an example URL message: mx://account/created?metadata="{'guid':'ACT-1'}".

You must capture the URL, parse out the path and query string, then JSON-decode the metadata field.

Application Events

You must create listeners for our postMessage UI application events.

This event is triggered when the widget is loaded.


_10{
_10  "type": "mx/load",
_10  "mx": true
_10}

This event is used to keep the widget session alive.


_10{
_10  "type": "mx/ping",
_10  "mx": true,
_10  "metadata": {
_10    "user_guid": "USR-123",
_10    "session_guid": "ANS-123"
_10  }
_10}

This event is triggered when popover content which traps the focus onto a particular element is opened or closed, but only in the case that no other popover content is already open. This event is triggered by some drawers, menu buttons, and modals.


_10{
_10  "type": "mx/focusTrap",
_10  "mx": true,
_10  "metadata": {
_10    "trapped": "true"
_10  }
_10}

You must create a listener for one event specific to the Connections Widget: the Member Deleted event.

All postMessage UI events that apply to the Connect Widget also apply to the Connections Widget.

Member Deleted

This event is triggered when a member has been deleted in the widget.

Example

Language:json


_10{
_10  "type": "mx/connections/memberDeleted",
_10  "mx": true,
_10  "metadata": {
_10    "user_guid": "USR-123",
_10    "session_guid": "ANS-123",
_10    "member_guid": "MBR-123"
_10  }
_10}

The following events are for the Finstrong Mini Widget.

Sufficient Data, Primary Action Selected

This event is triggered when the user has enough data to generate a Finstrong health score and the primary action is selected.

Example

Language:json


_10{
_10  "type": "mx/miniFinstrong/sufficientData/primaryAction",
_10  "mx": true,
_10  "metadata": {
_10    "user_guid": "USR-123",
_10    "session_guid": "ANS-123",
_10  }
_10}

Insufficient Data, Primary Action Selected

This event is triggered when the user doesn't have enough data to generate a Finstrong health score and the primary action is selected.

Example

Language:json


_10{
_10  "type": "mx/miniFinstrong/insufficientData/primaryAction",
_10  "mx": true,
_10  "metadata": {
_10    "user_guid": "USR-123",
_10    "session_guid": "ANS-123",
_10  }
_10}

Deprecated PostMessage Events

info

These events are deprecated and are only supported for existing integrations.

A postMessage is an event-based protocol that allows you to take action in your own codebase in response to events triggered within a widget's user interface. They're intended specifically to allow your code and a widget's user interface to work in concert, not to give a full picture of events happening on MX servers. PostMessage events shouldn't be used for analytics or for keeping data in sync between platforms.

Webhooks are a more reliable way of coordinating events between your servers and MX servers, rather than the UI-oriented postMessages.

Maintaining Sessions

Because our widgets are embedded through iframes, the parent frame (usually window) isn't aware of any activity going on within the iframe. This can cause the online banking session to time out even though the user is actively using a widget. To prevent this, each of our widgets will periodically send a postMessage to the parent frame. The postMessage will contain a JSON-formatted string as follows.

The most common way to take advantage of these postMessages is to implement an event listener function that will capture any postMessages. When a postMessage is captured, you can then tell your application to maintain its session. An example also follows.


_10{
_10  "moneyDesktop": true,
_10  "payload": {},
_10  "timeStamp": 123435234,
_10  "type": "ping"
_10}


_10var onPostMessage = function(evt) {
_10  var postMessageData = JSON.parse(evt.data);
_10
_10  // Check to see if the post message is from MoneyDesktop
_10  if (postMessageData.moneyDesktop) {
_10    // Do something to keep my app's session alive
_10  }
_10};
_10
_10window.addEventListener("message", onPostMessage);

Sometimes, your application may want to know about specific events that have occurred within the widget iframe. To account for this, we send postMessages for specific widget events.

All widget event postMessages will contain a JSON-formatted string with the structure shown to the right.

info

PostMessage events related to members — such as member updated — will contain the connection_status field. This field indicates the current status of the member's aggregation.


_10{
_10  "type": "event_name",
_10  "moneyDesktop": true,
_10  "timeStamp": 1426627364010,
_10  "payload": {
_10    "type": "indicates the type of payload object"
_10    ... (additional payload fields)
_10  }
_10}

Account Created
Account Updated
Account Deleted

This event triggers when any account is created. The is_manual field can be used to distinguish manual accounts from other accounts.


_19{
_19  "moneyDesktop": true,
_19  "payload": {
_19    "account_subtype": "",
_19    "account_type": "PROPERTY",
_19    "balance": 25000,
_19    "guid": "MBR-12345",
_19    "id": "A-12345",
_19    "is_closed": "false",
_19    "is_hidden": "false",
_19    "is_manual": "true",
_19    "member_guid": "MBR-12345",
_19    "name": "Delorean",
_19    "property_type": "VEHICLE",
_19    "type": "account"
_19  },
_19  "timeStamp": 1426627364010,
_19  "type": "created"
_19}

Triggered when an existing account is updated.


_19{
_19  "moneyDesktop": true,
_19  "payload": {
_19    "account_subtype": "",
_19    "account_type": "CHECKING",
_19    "balance": 2500,
_19    "guid": "ACT-12345",
_19    "id": "A-12345",
_19    "is_closed": "false",
_19    "is_hidden": "false",
_19    "is_manual": "false",
_19    "member_guid": "MBR-12345",
_19    "name": "Zen Checking",
_19    "property_type": "",
_19    "type": "account"
_19  },
_19  "timeStamp": 1426627364010,
_19  "type": "updated"
_19}

Triggered when an existing account is deleted.


_19{
_19  "moneyDesktop": true,
_19  "payload": {
_19    "account_subtype": "",
_19    "account_type": "SAVINGS",
_19    "balance": 5000,
_19    "guid": "ACT-12345",
_19    "id": "A-12345",
_19    "is_closed": "false",
_19    "is_hidden": "false",
_19    "is_manual": "false",
_19    "member_guid": "MBR-12345",
_19    "name": "Zen Savings",
_19    "property_type": "",
_19    "type": "account"
_19  },
_19  "timeStamp": 1426627364010,
_19  "type": "deleted"
_19}

Member Created
Member Updated
Member Deleted

Triggered when a member is created. This event is triggered on the creation of the member before any aggregation is initiated. The aggregation-related fields, such as most_recent_job_guid, may be null.


_14  {
_14    "moneyDesktop": true,
_14    "payload": {
_14      "connection_status": "CREATED",
_14      "guid": "MBR-45678",
_14      "institution_guid": "INS-12345",
_14      "is_manual": false,
_14      "most_recent_job_guid": null,
_14      "name": "Zen Bank",
_14      "type": "member"
_14    },
_14    "timeStamp": 1566425077001,
_14    "type": "created"
_14  }

Triggered when an existing member is updated.


_17{
_17  "moneyDesktop": true,
_17  "payload": {
_17    "accounts_count": 3,
_17    "connection_status": "CONNECTED",
_17    "guid": "MBR-12345",
_17    "id": "M-12345",
_17    "institution_guid": "INS-12345",
_17    "is_manual": "false",
_17    "is_user_created": "false",
_17    "most_recent_job_guid": "JOB-12345",
_17    "name": "Zen Bank",
_17    "type": "member"
_17  },
_17  "timeStamp": 1426627364010,
_17  "type": "updated"
_17}

Triggered when an existing member is deleted.


_17{
_17  "moneyDesktop": true,
_17  "payload": {
_17    "accounts_count": 3,
_17    "connection_status": "CONNECTED",
_17    "guid": "MBR-12345",
_17    "id": "M-12345",
_17    "institution_guid": "INS-12345",
_17    "is_manual": "false",
_17    "is_user_created": "false",
_17    "most_recent_job_guid": "JOB-12345",
_17    "name": "Zen Bank",
_17    "type": "member"
_17  },
_17  "timeStamp": 1426627364010,
_17  "type": "deleted"
_17}

Transaction Created
Transaction Updated
Transaction Deleted

Triggered when a new transaction is created. This includes the creation of child transactions when the parent transaction is split.


_18{
_18  "moneyDesktop": true,
_18  "payload": {
_18    "account_guid": "ACT-12345",
_18    "amount": 4.25,
_18    "category_guid": "CAT-12345",
_18    "date": 1425384000,
_18    "description": "Transaction Description",
_18    "guid": "TRN-12345",
_18    "has_been_split": false,
_18    "memo": "Transaction Memo",
_18    "parent_guid": "TRN-45678",
_18    "transaction_type": 2,
_18    "type": "transaction"
_18  },
_18  "timeStamp": 1426627364010,
_18  "type": "created"
_18}

Triggered when a transaction amount, account_guid, category_guid, date, memo, transaction_type, or description is changed by the User, or when a split has been added or removed.


_18{
_18  "moneyDesktop": true,
_18  "payload": {
_18    "account_guid": "ACT-12345",
_18    "amount": 4.25,
_18    "category_guid": "CAT-12345",
_18    "date": 1425384000,
_18    "description": "Transaction Description",
_18    "guid": "TRN-12345",
_18    "has_been_split": true,
_18    "memo": "Transaction Memo",
_18    "parent_guid": null,
_18    "transaction_type": 2,
_18    "type": "transaction"
_18  },
_18  "timeStamp": 1426627364010,
_18  "type": "updated"
_18}

Triggered when a transaction is deleted.


_18{
_18  "moneyDesktop": true,
_18  "payload": {
_18    "account_guid": "ACT-12345",
_18    "amount": 100,
_18    "category_guid": "CAT-12345",
_18    "date": 1501113600,
_18    "description": "Transaction Description",
_18    "guid": "TRN-12345",
_18    "has_been_split": false,
_18    "memo": null,
_18    "parent_guid": null,
_18    "transaction_type": 1,
_18    "type": "transaction"
_18  },
_18  "timeStamp": 1426627364010,
_18  "type": "deleted"
_18}

Focus Trap: trapped: true
Focus Trap: trapped: false

This event is triggered when popover content is opened which traps the focus onto a particular element, but only in the case that no other popover content is already open. This event is triggered by drawers, menu buttons, and modals.


_10{
_10  "moneyDesktop": true,
_10  "payload": {
_10    "trapped": true
_10  },
_10  "timeStamp": 1426627364010,
_10  "type": "focusTrap"
_10}

This event is triggered when popover content that has trapped focus onto a particular element is closed, but only in the case that no other popover content is open. This event is triggered by closing drawers, menu buttons, and modals.


_10{
_10  "moneyDesktop": true,
_10  "payload": {
_10    "trapped": false
_10  },
_10  "timeStamp": 1426627364010,
_10  "type": "focusTrap"
_10}

PostMessage UI Events in Mobile WebViews

Because of the technical limitations of WebView-based widget implementations, an alternative to standard postMessages is required. MX has developed a simple URL-based updating mechanism to replace event messages that are available to other implementations. Capture these URLs and use the information provided in them to build the necessary logic for coordinating application events. URL event messages are available for the widget events outlined in the following sections.

When requesting widget URLs using the SSO API, you must include the is_mobile_webview field with a value of true in your request to access WebView event messages.

info

PostMessage events related to members — such as member updated — will contain the connection_status field. This field indicates the current status of the member's aggregation.

Sample Capture Scripts

The following are example capture scripts in the Java and Swift languages.

Java

Language:java


_20public class MainActivity extends AppCompatActivity {
_20    private WebView webView = null;
_20    @Override
_20    protected void onCreate(Bundle savedInstanceState) {
_20      webView = (WebView) findViewById(R.id.webview);
_20      webView.setWebViewClient(new MxWebViewClient());
_20      webView.getSettings().setDomStorageEnabled(true);
_20      webView.getSettings().setJavaScriptEnabled(true);
_20    }
_20    private class MxWebViewClient extends WebViewClient {
_20        @Override
_20        public boolean shouldOverrideUrlLoading(WebView view, String url) {
_20            if (url.startsWith("mx://")) {
_20                //Take action here.
_20                return true;
_20            } else
_20            return false;
_20        }
_20    }
_20}

Swift

Language:swift


_25class ViewController: UIViewController, WKUIDelegate {
_25  override func viewDidLoad() {
_25      super.viewDidLoad()
_25      webView.delegate = self
_25      ...
_25  }
_25
_25  func webView(_ webView: WKWebView, decidePolicyFor
_25    navigationAction: WKNavigationAction,
_25               decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {
_25
_25    // Intercept custom URI
_25    let surl = webView.url?.absoluteString
_25    if  (surl?.hasPrefix("mx://"))! {
_25      // Take action here
_25
_25      // Cancel request
_25      decisionHandler(.cancel)
_25      return
_25    }
_25
_25    // Allow request
_25    decisionHandler(.allow)
_25  }
_25}

Account Created URL
Account Updated URL
Account Deleted URL

This event message triggers when any account is created. The is_manual field can be used to distinguish manual accounts from other accounts.

Base URL: mx://accountCreated
Example payload: mx://accountCreated?account_subtype=""?account_type="PROPERTY"?balance=25000?guid="ACT-12345"?id="A-12345"?is_closed="false"?is_hidden="false"?is_manual="true"?member_guid="MBR-12345"?name="Delorean"?property_type="VEHICLE"?type="account"

Base URL: mx://accountUpdated
Example payload: mx://accountUpdated?account_subtype=""?account_type="PROPERTY"?balance=25000?guid="ACT-12345"?id="A-12345"?is_closed="false"?is_hidden="false"?is_manual="true"?member_guid="MBR-12345"?name="Delorean"?property_type="VEHICLE"?type="account"

Base URL: mx://accountDeleted
Example payload: mx://accountDeleted?account_subtype=""?account_type="PROPERTY"?balance=25000?guid="ACT-12345"?id="A-12345"?is_closed="false"?is_hidden="false"?is_manual="true"?member_guid="MBR-12345"?name="Delorean"?property_type="VEHICLE"?type="account"

Member Created URL
Member Updated URL
Member Deleted URL

Base URL: mx://memberCreated
Example payload: mx://memberCreated?accounts_count=0?connection_status="CREATED"?guid="MBR-12345"?id=""?institution_guid?"INS-12345"?is_manual="false"?is_user_created="false"?most_recent_job_guid?""?name="Zen Bank"?type="member"

Base URL: mx://memberUpdated
Example payload: mx://memberUpdated?accounts_count=3?connection_status="CONNECTED"?guid="MBR-12345"?id="M-12345"?institution_guid?"INS-12345"?is_manual="false"?is_user_created="false"?most_recent_job_guid?"JOB-12345"?name="Zen Bank"?type="member"

Base URL: mx://memberDeleted
Example payload: mx://memberDeleted?accounts_count=3?connection_status="CONNECTED"?guid="MBR-12345"?id="M-12345"?institution_guid?"INS-12345"?is_manual="false"?is_user_created="false"?most_recent_job_guid?"JOB-12345"?name="Zen Bank"?type="member"

Transaction Created URL
Transaction Updated URL
Transaction Deleted URL

Base URL: mx://transactionCreated
Example payload: mx://transactionCreated?account_guid="ACT-12345"?amount=4.25?category_guid="CAT-12345"?date=1425384000?description="Transaction Description"?guid="TRN-12345"?has_been_split=false?memo="Transaction Memo"?parent_guid="TRN-45678"?transaction_type=2?type="transaction"

Base URL: mx://transactionUpdated
Example payload: mx://transactionUpdated?account_guid="ACT-12345"?amount=4.25?category_guid="CAT-12345"?date=1425384000?description="Transaction Description"?guid="TRN-12345"?has_been_split=false?memo="Transaction Memo"?parent_guid="TRN-45678"?transaction_type=2?type="transaction"

Base URL: mx://transactionDeleted
Example payload: mx://transactionDeleted?account_guid="ACT-12345"?amount=4.25?category_guid="CAT-12345"?date=1425384000?description="Transaction Description"?guid="TRN-12345"?has_been_split=false?memo="Transaction Memo"?parent_guid="TRN-45678"?transaction_type=2?type="transaction"

Integrate Any PFM Widget

Integrate on a Website (iframe)​

Step 1​

Step 2​

Step 3​

Step 4​

Step 1​

Step 2​

Step 3​

Step 4​

Integrate on a Website (Widget Loader)​

Step 1​

Step 2​

Step 3​

Step 4​

Step 1​

Step 2​

Step 3​

Step 4​

Integrate on a Mobile App​

Common Problems​

Minimum Size​

WKWebView vs. UIWebView (iOS)​

Default Padding (iOS)​

Default Margin (iOS and Android)​

Viewport (iOS and Android)​

Widget Loader Configurations​

Widget Loader Parameters​

Config Parameter​

Create a Loading Message​

Keeping a Session Alive and Logging Out​

Loading Multiple Widgets​

Loading Widgets at Different Times​

Master Widget Deep Linking​

PostMessage UI Events​

Events in Mobile WebViews​

Application Events​

Widget Load​

Widget Ping​

Widget focusTrap​

Connections Widget Event​

Member Deleted​

Mini Finstrong Widget Events​

Sufficient Data, Primary Action Selected​

Insufficient Data, Primary Action Selected​

Deprecated PostMessage Events​

Maintaining Sessions​

Widget Events​

PostMessage UI Events in Mobile WebViews​

Sample Capture Scripts​

Integrate on a Website (iframe)

Step 1

Step 2

Step 3

Step 4

Step 1

Step 2

Step 3

Step 4

Integrate on a Website (Widget Loader)

Step 1

Step 2

Step 3

Step 4

Step 1

Step 2

Step 3

Step 4

Integrate on a Mobile App

Common Problems

Minimum Size

WKWebView vs. UIWebView (iOS)

Default Padding (iOS)

Default Margin (iOS and Android)

Viewport (iOS and Android)

Widget Loader Configurations

Widget Loader Parameters

Config Parameter

Create a Loading Message

Keeping a Session Alive and Logging Out

Loading Multiple Widgets

Loading Widgets at Different Times

Master Widget Deep Linking

PostMessage UI Events

Events in Mobile WebViews

Application Events

Widget Load

Widget Ping

Widget focusTrap

Connections Widget Event

Member Deleted

Mini Finstrong Widget Events

Sufficient Data, Primary Action Selected

Insufficient Data, Primary Action Selected

Deprecated PostMessage Events

Maintaining Sessions

Widget Events

PostMessage UI Events in Mobile WebViews

Sample Capture Scripts