Integrate the Insights Widget

This guide shows you how to integrate the Insights Widget on a website using an iFrame, on a website using the Widget Loader, or on the mobile app.

For information on widget behavior, reference the Widget Overview.

info

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

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)

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

Step 1

Create an iFrame.

Make sure the width and height uses the widget's supported dimensions.

If you use sandbox, some attributes must be whitelisted for the widget to work: sandbox="allow-forms allow-same-origin allow-scripts".

Language:shell


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

Step 2

In the iFrame's src, you'll need to request a widget URL and specify pulse_widget as 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.

See Example API Requests for different configurations.

Language:shell


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

Step 3

Optionally create listeners for application events.

See Postmessage UI Events for more info.

Language:shell


_22<html>
_22  <head>
_22  </head>
_22  <body>
_22    <iframe width="100%" height="550px" 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 feed.
_22                }
_22            }
_22        });
_22    </script>
_22  </body>
_22</html>

Step 4

Configure event listeners for each Insights Widget event.

See Postmessage UI Events for general info on our postMessage events.

Language:shell


_28<html>
_28  <head>
_28  </head>
_28  <body>
_28    <iframe width="100%" height="550px" src=requestURL()></iframe>
_28    <script>
_28        // an example for handling events.
_28        window.addEventListener('message', (event) => {
_28            if (event.data.mx) {
_28                if (event.data.type === "mx/load") {
_28                  // This event is triggered when the widget is loaded.
_28                }
_28                
_28                if (event.data.type === "mx/ping") {
_28                  // This event is triggered when the user interacts with the UI.
_28                  // For example, when the user swipes through the carousel.
_28                }
_28
_28                // Example of handling one Insights Widget event.
_28                if (event.data.metadata.beat_template === "ReplenishSavings") {
_28                  // Use the metadata to send the user to create a transfer for their savings account.
_28                }
_28
_28            }
_28        });
_28    </script>
_28  </body>
_28</html>

Step 1

Create an iFrame.

Make sure the width and height uses the widget's supported dimensions.

If you use sandbox, some attributes must be whitelisted for the widget to work: sandbox="allow-forms allow-same-origin allow-scripts".

Step 2

In the iFrame's src, you'll need to request a widget URL and specify pulse_widget as 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.

See Example API Requests for different configurations.

Step 3

Optionally create listeners for application events.

See Postmessage UI Events for more info.

Step 4

Configure event listeners for each Insights Widget event.

See Postmessage UI Events for general info on our postMessage events.

Language:html


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

success

Congrats! You've integrated the Insights Widget!

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

Step 1

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/pulse/XXXXX',
_16        width: 850,
_16        height: 550
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 2

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/pulse/XXXXX',
_16        width: 850,
_16        height: 550
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 3

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 (see step 4), 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.

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/pulse/XXXXX',
_16        width: 850,
_16        height: 550
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 4

You'll need to request a widget URL through the Platform API or SSO API and set it in the URL parameter.

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.

You can request a widget URL for the Insights Widget by specifying pulse_widget as the widget_type, using the Platform API or SSO API.

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/pulse/XXXXX',
_16        width: 850,
_16        height: 550
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

Step 5

Optionally create listeners for application events.

See Postmessage UI Events for more information.

Language:shell


_31<html>
_31  <head>
_31    <title>My Web Page</title>
_31    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_31    <script type="text/javascript">
_31      var myWidget = new MoneyDesktopWidgetLoader({
_31        url: 'https://widgets.moneydesktop.com/md/pulse/XXXXX',
_31        width: 850,
_31        height: 550
_31      });
_31    </script>
_31  </head>
_31  <body>
_31    <div id="md-widget"></div>
_31    <script>
_31        // an example for handling events.
_31        window.addEventListener('message', (event) => {
_31            if (event.data.mx) {
_31                if (event.data.type === "mx/load") {
_31                  // This event is triggered when the widget is loaded.
_31                }
_31                
_31                if (event.data.type === "mx/ping") {
_31                  // This event is triggered when the user interacts with the UI.
_31                  // For example, when the user swipes through the carousel.
_31                }
_31            }
_31        });
_31    </script>
_31  </body>
_31</html>

Step 6

Configure event listeners for the Insights Widget events.

See Postmessage UI Events for general info on our postMessage events.

Language:shell


_38<html>
_38  <head>
_38    <title>My Web Page</title>
_38    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_38    <script type="text/javascript">
_38      var myWidget = new MoneyDesktopWidgetLoader({
_38        url: 'https://widgets.moneydesktop.com/md/pulse/XXXXX',
_38        width: 850,
_38        height: 550
_38      });
_38    </script>
_38  </head>
_38  <body>
_38    <div id="md-widget"></div>
_38    <script>
_38        // an example for handling events.
_38        window.addEventListener('message', (event) => {
_38            if (event.data.mx) {
_38                if (event.data.type === "mx/load") {
_38                  // This event is triggered when the widget is loaded.
_38                }
_38                
_38                if (event.data.type === "mx/ping") {
_38                  // This event is triggered when the user interacts with the UI.
_38                  // For example, when the user swipes through the carousel.
_38                }
_38
_38                // Example of handling one Insights Widget event.
_38                if (event.data.metadata.beat_template === "ReplenishSavings") {
_38                  // Send the user to create a transfer for their savings account.
_38                  // Use the event.data.metadata.
_38                }
_38
_38            }
_38        });
_38    </script>
_38  </body>
_38</html>

Step 1

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 2

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 3

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.

Step 4

You'll need to request a widget URL through the Platform API or SSO API and set it in the URL parameter.

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.

You can request a widget URL for the Insights Widget by specifying pulse_widget as the widget_type, using the Platform API or SSO API.

Step 5

Optionally create listeners for application events.

See Postmessage UI Events for more information.

Step 6

Configure event listeners for the Insights Widget events.

See Postmessage UI Events for general info on our postMessage events.

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/pulse/XXXXX',
_16        width: 850,
_16        height: 550
_16      });
_16    </script>
_16  </head>
_16  <body>
_16    <div id="md-widget"></div>
_16  </body>
_16</html>

success

Congrats! You've integrated the Insights Widget!

Integrate on a Mobile App

To integrate the widget on a mobile application:

Request pulse_widget as 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.
Load the URL received from the previous request into a WebView.
See Events in Mobile WebViews.
Capture and parse URLs for application events.
Capture and parse URLs for Insights Widget events.

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.

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 padding to its WebViews by default, which can cause 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)

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 properly, 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 render 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 renders correctly.

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">

Example API Requests

The following examples are for requesting a Micro Widget URL in the Platform API.

Request a widget to embed on a website.


_10curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
_10-H 'Content-Type: application/json' \
_10-H 'Accept: application/vnd.mx.api.v20231004+json' \
_10-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
_10--data '{
_10  "widget_url": {
_10    "widget_type": "pulse_widget"
_10  }
_10}'

Request a widget to embed on a mobile app through a WebView.


_10curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
_10-H 'Content-Type: application/json' \
_10-H 'Accept: application/vnd.mx.api.v20231004+json' \
_10-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
_10--data '{
_10  "widget_url": {
_10    "is_mobile_webview": true,
_10    "widget_type": "pulse_widget"
_10  }
_10}'

Request the widget in Spanish by adding the Accept-Language header and setting it to es.


_10curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
_10-H 'Content-Type: application/json' \
_10-H 'Accept: application/vnd.mx.api.v20231004+json' \
_10-H 'Accept-Language: es' \
_10-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
_10--data '{
_10  "widget_url": {
_10    "widget_type": "pulse_widget"
_10  }
_10}'

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}

When displayed in the Insights Widget, some insights contain a call-to-action (CTA). Some CTAs will direct the user to the appropriate location by default, but others will require you to send the user somewhere to complete an action.

This process is as follows:

We detect that a user has clicked a call-to-action (CTA) on one of our insights that require you to send the user somewhere outside of our widget.
We send you a postMessage UI event to let you know a user has clicked this CTA. Depending on the CTA and associated insight that the user clicked, we'll send you additional information about the event inside the postMessage UI event.
The listener you create for this event sends the user to the appropriate location within your mobile app or website based on the details we sent through the postMessage.

You must create listeners for each of the following insight templates (only create listeners for the templates MX has enabled for you).

Insight Template	When MX Sends This Event	What You Must Do
`DesignateEmergencySavingsAccount`	When the user clicks the Open Savings Account CTA in the scenario where the user doesn't have a savings account.	Send the user to open a savings account.
`EmergencyFundWithdrawal`	When the user clicks the View my emergency savings CTA or the Transfer funds CTA. The CTA that appears depends on if you have transfers for funds enabled.	When MX sends you this event, you must either send the user to view their emergency savings or create a transfer, depending on whether you have transfers for funds enabled or disabled.
`LowAccountBalance`	When the user clicks the Transfer funds CTA.	Send the user to transfer funds to their low balance account.
`MonthlyEmergencyFundReview` (scenario 1)	When the user clicks the View my emergency savings CTA.	Send the user to where they can view their emergency savings amount.
`MonthlyEmergencyFundReview` (scenario 2)	When the user clicks the Create new goal CTA.	Send the user to the Goals Widget.
`MonthlyEmergencyFundReview` (scenario 3)	When the user clicks the Create transfer CTA.	Send the user somewhere where they can transfer money.
`MonthlyObligationsStatus`	When the user clicks the Make a transfer CTA.	Send the user somewhere where they can transfer money.
`MonthlySpendingPlanCelebration`	When the user clicks the Visit spending plan CTA.	Send the user to the Spending Plan Widget.
`ReplenishSavings`	When the user selects the Create Transfer CTA.	Send the user to create a transfer to their savings account.
`SaveAnExtra100Dollars`	When the user selects the Make A Transfer CTA.	Send the user to where they can make a transfer.
`SavingsAccountDeposit`	When the user selects either the View my emergency savings or Start saving for emergencies CTA.	Send the user to the Goals Widget. From there the user can see their emergency savings goal or start an emergency savings goal.
`SavingsMilestoneEmergencyFund`	When the user selects the View my emergency savings CTA.	Send the user to where they can view the Goals Widget.
`SavingsOpportunityV2` (scenario 1)	This insight template has two scenarios. This covers scenario 1, where `"action": 'op_1'`. We'll send you a postMessage for this scenario when the user already has an eligible savings account to transfer money to and selects the Transfer Funds CTA.	Send the user to create a transfer to their savings account.
`SavingsOpportunityV2` (scenario 2)	This insight template has two scenarios. This covers scenario 2, where `"action": 'op_2'`. We'll send you a postMessage for this scenario when the user doesn't have an eligible savings account to transfer money to and selects the Open Savings Account CTA.	Send the user to open a savings account.
`SpendingPlanCreatedCelebration`	When the user clicks either the Start Spending Plan or Visit Spending Plan CTA.	Send the user to the Spending Plan Widget.
`SwitchDirectDeposit`	When the user clicks the Switch Direct Deposit CTA.	When MX sends you this event, you must activate your direct deposit integration.
`TransparentOverdraft`	When the user clicks the Transfer funds CTA.	Send the user to transfer funds to their potentially overdrawn account.
`UnifiedDepositEmergencyFund` (scenario 1)	When the user clicks the Start saving for emergencies CTA.	Send the user to the Goals Widget.
`UnifiedDepositEmergencyFund` (scenario 2)	When the user clicks the Transfer funds CTA.	Send the user to a location where they can transfer funds to their emergency savings fund.
`UnifiedDepositEmergencyFund` (scenario 3)	When the user clicks the View my emergency savings CTA.	Send the user to the Goals Widget.
`WeeklyNoSpendDays`	When the user clicks the Visit Spending Plan CTA.	Send the user to the Spending Plan Widget, where they can see the widget as normal or onboard to it.

These are the base metadata fields for each event we send. Fields specific to certain insight templates appear in the sections that follow.

Field	Type	Definition
`action`	String	Represents the scenarios within the insight. This value, and additional fields relating to this value, are listed in the sections that follow. Most insights only have one scenario. The `SavingsOpportunityV2` insight will require you to configure events for two possible scenarios within that insight.
`beat_guid`	String	Insights were previously called "beats." This is the unique identifier for the insight. Defined by MX.
`beat_template`	String	Insights were previously called "beats." This is a short label for the insight being delivered. For example, `DesignateEmergencySavingsAccount`.

Example

Language:json


_10{
_10  "type": "mx/pulse/beat/cta",
_10  "mx": true,
_10  "metadata": {
_10    "action": "op_1",
_10    "beat_guid": "BET-123",
_10    "beat_template": "DesignateEmergencySavingsAccount"
_10  }
_10}

DesignateEmergencySavingsAccount Action

"action": 'op_1'.

EmergencyFundWithdrawal Action

"action": 'op_1'

LowAccountBalance Action

"action": 'op_1'.

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.

MonthlyEmergencyFundReview Actions

The following values for used for different scenarios in the insight and don't have any fields beyond the base metadata fields.

"action": 'op_1'.
"action": 'op_2'.
"action": 'op_3'.

MonthlyObligationsStatus Action

"action": 'op_1'.

MonthlySpendingPlanCelebration Action

"action": 'op_1'.

ReplenishSavings Action

"action": 'op_1'.

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.
`account_name`	String	The human-readable name of the account.
`accounts`	Array	An array of account objects, each of which contains the `account_guid` and `account_name` described in this table.
`total_amount_withdrawn`	Integer	The total amount withdrawn from all included accounts.

SaveAnExtra100Dollars Action

"action": 'op_1'.

SavingsAccountDeposit Action

"action": 'op_1'.

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.
`goal_guid` (if available)	String	The unique identifier for the goal. Defined by MX. This field will return an empty string for the "start saving for emergencies" scenario.
`user_guid`	String	The unique identifier for the user. Defined by MX.

SavingsMilestoneEmergencyFund Action

"action": 'op_1'.

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.
`goal_guid`	String	The unique identifier for the goal. Defined by MX.
`user_guid`	String	The unique identifier for the user. Defined by MX.

SavingsOpportunityV2 Actions

"action": 'op_1'.

Field	Type	Definition
`amount`	Integer	The amount the user would like to transfer to savings.
`destination_account_ids`	Array	The partner-defined identifiers for the accounts eligible to transfer funds to.
`source_account_ids`	Array	The partner-defined identifiers for the accounts eligible to transfer funds from.

"action": 'op_2'.

Field	Type	Definition
`amount`	Integer	The amount the user would like to transfer to savings.
`source_account_ids`	Array	The partner-defined identifiers for the accounts eligible to transfer funds from.

SpendingPlanCreatedCelebration Action

"action": 'op_1'.

TransparentOverdraft Action

"action": 'op_1'.

Field	Type	Definition
`destination_account_ids`	Array	Array of potentially overdrawn account numbers.
`projected_overdraft_amount`	Integer	The projected amount the account will be overdrawn.
`user_guid`	String	The unique identifier for the user. Defined by MX.

UnifiedDepositEmergencyFund Actions

"action": 'op_1'.

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.
`goal_guid`	String	The unique identifier for the goal. Defined by MX. For this action, the `goal_guid` will be an empty string `''`.
`user_guid`	String	The unique identifier for the user. Defined by MX.

"action": 'op_2'.

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.
`goal_guid`	String	The unique identifier for the goal. Defined by MX.
`user_guid`	String	The unique identifier for the user. Defined by MX.

"action": 'op_3'.

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.
`goal_guid`	String	The unique identifier for the goal. Defined by MX.
`user_guid`	String	The unique identifier for the user. Defined by MX.

WeeklyNoSpendDays Action

"action": 'op_1'.

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 set configurations. Some of these configurations are for specific widgets. While setting configurations this way is supported, the most current way of settings these configurations is through the widget URL request. See Configuration Options 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 example, contains configurations options.

Example

Language:html


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

You can set the following configuration options.

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.
`language`	String	Deprecated. See Localize Insights Widgets.
`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

You can set the following deep-linking options.

Deep Link Option	Data Type	Description
`launch_integration`	String	Must be `direct-deposit`. This lets the widget know to “deep link” to a specific integration. If the `account_guids` are provided under the `deep_link_params`, the direct-deposit session will be initiated with those accounts as potential deposit destinations.

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

Integrate the Insights 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 5​

Step 6​

Step 1​

Step 2​

Step 3​

Step 4​

Step 5​

Step 6​

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)​

Example API Requests​

PostMessage UI Events​

Events in Mobile WebViews​

Application Events​

Widget Load​

Widget Ping​

Widget focusTrap​

Insights Widget Events​

DesignateEmergencySavingsAccount Action​

EmergencyFundWithdrawal Action​

LowAccountBalance Action​

MonthlyEmergencyFundReview Actions​

MonthlyObligationsStatus Action​

MonthlySpendingPlanCelebration Action​

ReplenishSavings Action​

SaveAnExtra100Dollars Action​

SavingsAccountDeposit Action​

SavingsMilestoneEmergencyFund Action​

SavingsOpportunityV2 Actions​

SpendingPlanCreatedCelebration Action​

TransparentOverdraft Action​

UnifiedDepositEmergencyFund Actions​

WeeklyNoSpendDays Action​

Widget Loader Configurations​

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​

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 5

Step 6

Step 1

Step 2

Step 3

Step 4

Step 5

Step 6

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)

Example API Requests

PostMessage UI Events

Events in Mobile WebViews

Application Events

Widget Load

Widget Ping

Widget focusTrap

Insights Widget Events

DesignateEmergencySavingsAccount Action

EmergencyFundWithdrawal Action

LowAccountBalance Action

MonthlyEmergencyFundReview Actions

MonthlyObligationsStatus Action

MonthlySpendingPlanCelebration Action

ReplenishSavings Action

SaveAnExtra100Dollars Action

SavingsAccountDeposit Action

SavingsMilestoneEmergencyFund Action

SavingsOpportunityV2 Actions

SpendingPlanCreatedCelebration Action

TransparentOverdraft Action

UnifiedDepositEmergencyFund Actions

WeeklyNoSpendDays Action

Widget Loader Configurations

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