Widget Loader Configurations

This guide covers the configuration settings that are available to you if you integrated your PFM Widget onto a website using the Widget Loader.

The Widget Loader is no longer the recommended method of integrating the PFM Widgets onto a website. To learn about the recommended method, refer to How to Integrate PFM Widgets.

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. When you instantiate MoneyDesktopWidgetLoader, you must pass in an object with at least the required url parameter along with any optional parameters you wish to use:

Parameter	Requirement	Default Value	Description
`autoload`	Optional	`true`	Determines if the widget loads automatically. See Loading Widgets at Different Times.
`config`	Optional		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`	Optional	`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`	Optional	`600`	The widget’s height, in pixels or a percentage.
`id`	Optional	`'md-widget'`	Tells the Widget Loader what element to place the widget in. See Loading Multiple Widgets.
`width`	Optional	`'100%'`	The widget’s width, in pixels or a percentage.
`url`	Required		The widget’s URL. This is received through an SSO API or Platform API request.

Config Parameter

The config object contains the following configuration options:

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

Here’s an example of what the config object using the transactions option looks like:

Example

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

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 `postMessage` event.
`language`	String	All	Deprecated. See Supported Languages. Defaults to `en-us`.
`ui_message_version`	Integer	All	Determines which version of the `postMessage` event is triggered. All new implementations must include this option when getting any widget URL and must set `ui_message_version` to `4`. Prior versions are deprecated and supported only for existing integrations.
`hide_mark_as_duplicate`	Boolean	Connections	Hides the option to mark transactions as duplicates in the widget.
`hide_partner_managed_members`	Boolean	Connections	Hides any 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

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

Resetting the Session Timer 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.

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

  myWidget.ping();
</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 three separate widgets onto a single page.

Example

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

      var myTransactionsWidget = new MoneyDesktopWidgetLoader({
        url: "https://widgets.moneydesktop.com/md/transactions/XXXXX",
        width: "100%",
        height: "100%",
        id: "my-transactions-widget"
      });

      var myBudgetsWidget = new MoneyDesktopWidgetLoader({
        url: "https://widgets.moneydesktop.com/md/budgets/XXXXX",
        width: "100%",
        height: "100%",
        id: "my-budgets-widget"
      });
    </script>
  </head>
  <body>
    <div id="my-accounts-widget"></div>
    <div id="my-transactions-widget"></div>
    <div id="my-budgets-widget"></div>
  </body>
</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 instead, 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

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

      var myTransactionsWidget = new MoneyDesktopWidgetLoader({
        url: "https://widgets.moneydesktop.com/md/transactions/XXXXX",
        width: "100%",
        height: "100%",
        id: "my-transactions-widget",
        autoload: false
      });

      var loadTransactionsButton = document.getElementById('load-transactions');

      loadTransactionsButton.addEventListener('click', function(ev) {
        getTransactionWidgetURL().then(widgetURL => {
          myTransactionsWidget.load(widgetURL);
        });
      });
    </script>
  </head>
  <body>
    <div id="my-accounts-widget"></div>
    <button id="load-transactions">Load Transactions</button>
    <div id="my-transactions-widget"></div>
  </body>
</html>

Master Widget deep linking has been deprecated and is only supported for existing integrations.

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`

For example, if you want your Master Widget to load the Spending Plan Widget by default, you can set deepLink to spending_plan as follows:

Example

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

(Deprecated) PostMessage Events

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. A postMessage event 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. To learn more, read our Webhooks guide.

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:

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

The most common way to take advantage of a postMessage event is to implement an event listener function that will capture any postMessage. Once captured, you can tell your application to maintain its session. Here’s an example of how to do this:

var onPostMessage = function(evt) {
  var postMessageData = JSON.parse(evt.data);

  // Check to see if the post message is from MoneyDesktop
  if (postMessageData.moneyDesktop) {
    // Do something to keep my app's session alive
  }
};

window.addEventListener("message", onPostMessage);

We send postMessage events when your application wants to know about specific events that have occurred within the widget iFrame. All widget postMessage events contain a JSON-formatted string with the following structure:

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

Event Triggers

View the widget event triggers associated with account, member, and transaction changes.

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.

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

This event triggers when an existing account is updated.

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

This event triggers when an existing account is deleted.

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

Member Created
Member Updated
Member Deleted

This event triggers when a member is created and before any aggregation is initiated. The aggregation-related fields, such as most_recent_job_guid, may be null.

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

This event triggers when an existing member is updated.

{
  "moneyDesktop": true,
  "payload": {
    "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"
  },
  "timeStamp": 1426627364010,
  "type": "updated"
}

This event triggers when an existing member is deleted.

{
  "moneyDesktop": true,
  "payload": {
    "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"
  },
  "timeStamp": 1426627364010,
  "type": "deleted"
}

Transaction Created
Transaction Updated
Transaction Deleted

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

{
  "moneyDesktop": true,
  "payload": {
    "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"
  },
  "timeStamp": 1426627364010,
  "type": "created"
}

This event triggers 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.

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

This event triggers when a transaction is deleted.

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

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

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

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

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.

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

PostMessage UI Events in Mobile WebViews

Because of the technical limitations of WebView-based widget implementations, an alternative to the standard postMessage 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. 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. URL event messages are availalbe for the widget events outlined in the following sections.

PostMessage events related to members, such as when a member is 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

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

Swift

class ViewController: UIViewController, WKUIDelegate {
  override func viewDidLoad() {
      super.viewDidLoad()
      webView.delegate = self
      ...
  }

  func webView(_ webView: WKWebView, decidePolicyFor
    navigationAction: WKNavigationAction,
               decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) {

    // Intercept custom URI
    let surl = webView.url?.absoluteString
    if  (surl?.hasPrefix("mx://"))! {
      // Take action here

      // Cancel request
      decisionHandler(.cancel)
      return
    }

    // Allow request
    decisionHandler(.allow)
  }
}

Event Message Triggers

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"

This event message triggers when any account is updated.

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"

This event message triggers when any account is deleted.

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

This event message triggers when any member is created.

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"

This event message triggers when any member is updated.

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"

This event message triggers when any member is deleted.

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

This event message triggers when any transaction is created.

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"

This event message triggers when any transaction is updated.

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"

This event message triggers when any transaction is deleted.

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"

Widget Loader Configurations

Widget Loader Parameters

Config Parameter

Create a Loading Message

Resetting the Session Timer and Logging Out

Loading Multiple Widgets

Loading Widgets at Different Times

(Deprecated) Master Widget Deep Linking

(Deprecated) PostMessage Events

Maintaining Sessions

Widget Events

Event Triggers

PostMessage UI Events in Mobile WebViews

Sample Capture Scripts

Event Message Triggers

​Widget Loader Parameters

​Config Parameter

​Create a Loading Message

​Resetting the Session Timer and Logging Out

​Loading Multiple Widgets

​Loading Widgets at Different Times

​(Deprecated) Master Widget Deep Linking

​(Deprecated) PostMessage Events

​Maintaining Sessions

​Widget Events

​Event Triggers

​PostMessage UI Events in Mobile WebViews

​Sample Capture Scripts

​Event Message Triggers

Widget Loader Parameters

Config Parameter

Create a Loading Message

Resetting the Session Timer and Logging Out

Loading Multiple Widgets

Loading Widgets at Different Times

(Deprecated) Master Widget Deep Linking

(Deprecated) PostMessage Events

Maintaining Sessions

Widget Events

Event Triggers

PostMessage UI Events in Mobile WebViews

Sample Capture Scripts

Event Message Triggers