Widget Loader Configurations - MX Documentation

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

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

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 set configurations. Some of these configurations are for specific widgets. While setting configurations this way is supported, the most current way of setting these configurations is through the widget URL request. See Config Parameter for more info.
`deep_link_params`	No		This allows you to request a widget URL and provide a desired `launch_integration` destination. This requested widget URL will immediately mount the Atomic direct-deposit UX.
`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 examples, contains configuration options.

Insights configuration options

var myWidget = new MoneyDesktopWidgetLoader({  
  url: getUrl(url),  
  width: 850,  
  height: 550,  
  config: {  
    pulse: {  
      ui_message_version: 4  
    }  
  },  
  postMessageOrigin: "*"  
});  

Mini Widget configuration options

var myWidget = new MoneyDesktopWidgetLoader({  
  url: getUrl(url),  
  width: 450,  
  height: 400,  
  config: {  
    mini_pulse_carousel: {  
      ui_message_version: 4  
    }  
  },  
  postMessageOrigin: "*"  
});  

Micro Widget configuration options

var myWidget = new MoneyDesktopWidgetLoader({  
  url: getUrl(url),  
  width: 450,  
  height: 400,  
  config: {  
    micro_pulse_carousel: {  
      ui_message_version: 4  
    }  
  },  
  postMessageOrigin: "*"  
});  

Configuration Option	Data Type	Description
`is_mobile_webview`	Boolean	Defaults to `false`. Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript event postMessages.
`insight_widget_filter_from_date`	Integer	Filters which insights can appear in your widget by date. Insights older than the set date won’t appear. The date must be in Unix format. Example: `1686074427`. This option is only supported in the SSO API.
`insight_widget_filter_templates`	Array	Filters which insights can appear in your widget by template name. Example: `['LargeTransaction', 'UnifiedDeposit']`. See the Insights Library for all supported values. This option is only supported in the SSO API.
`ui_message_version`	Integer	Use this to specify which version of `postMessage` UI 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.

Deep Linking Parameter

The only option for deep linking is launch_integration, and the only available value is direct-deposit. This field is passed as a string. This enables the widget to deep link to a specific integration. If account_guids are provided under deep_link_params, the direct-deposit session is initiated with those accounts as potential deposit destinations.

Create a Loading Message

Any HTML placed inside of the widget placeholder element is replaced once the widget iFrame has loaded. This means you can use the placeholder element’s inner HTML to display a loading message. Since this is HTML, it can be text, images, or anything you want. The following example adds some loading text that appears when the widget loads.

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: 850,  
        height: 550  
      });  
    </script>  
  </head>  
  <body>  
    <div id="md-widget">  
      Loading...  
    </div>  
  </body>  
</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 it 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: 850,  
    height: 550  
  });

  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 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: 850,  
        height: 550,  
        id: "my-accounts-widget"  
      });

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

      var myBudgetsWidget = new MoneyDesktopWidgetLoader({  
        url: "https://widgets.moneydesktop.com/md/budgets/XXXXX",  
        width: 850,  
        height: 550,  
        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 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: 850,  
        height: 550,  
        id: "my-accounts-widget"  
      });

      var myTransactionsWidget = new MoneyDesktopWidgetLoader({  
        url: "https://widgets.moneydesktop.com/md/transactions/XXXXX",  
        width: 850,  
        height: 550,  
        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>  

​Widget Loader Parameters

​Config Parameter

​Deep Linking Parameter

​Create a Loading Message

​Keeping a Session Alive and Logging Out

​Loading Multiple Widgets

​Loading Widgets at Different Times

Widget Loader Parameters

Config Parameter

Deep Linking Parameter

Create a Loading Message

Keeping a Session Alive and Logging Out

Loading Multiple Widgets

Loading Widgets at Different Times