Integrate the Micro Widget

This guide shows you how to integrate the Micro Widget on a website using an iFrame, on a website using the Widget Loader, or on a 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 recommended dimensions.

Language:shell


_10<html>
_10  <body>
_10    <iframe width="300px" height="200px" src=""></iframe>
_10  </body>
_10</html>

Step 2

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

Language:shell


_10<html>
_10  <body>
_10    <iframe width="300px" height="200px" src=requestURL()></iframe>
_10  </body>
_10</html>

Step 3

Optionally create listeners for these two application events:

Widget Load – triggered when the widget is loaded.
Widget Ping – used to keep the widget session alive.

See Postmessage UI Events for more info.

Language:shell


_22<html>
_22  <head>
_22  </head>
_22  <body>
_22    <iframe width="300px" height="200px" 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 4

Configure event listeners for:

An event for when the user clicks the View all > CTA. When the user clicks this, you'll consume the info we send to you in the postMessage event and then send the user to the Insights Widget.
An event for when the user clicks the Learn more CTA. When the user clicks this, you'll consume additional information from the postMessage event. This will let you send the user to the Insights Widget with the insight the user clicked on at the top of the feed.

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

Language:shell


_27<html>
_27  <head>
_27  </head>
_27  <body>
_27    <iframe width="300px" height="200px" src=requestURL()></iframe>
_27    <script>
_27        // an example for handling events.
_27        window.addEventListener('message', (event) => {
_27            if (event.data.mx) {
_27                if (event.data.type === "mx/load") {
_27                  // This event is triggered when the widget is loaded.
_27                }
_27                
_27                if (event.data.type === "mx/ping") {
_27                  // This event is triggered when the user interacts with the UI.
_27                  // For example, when the user swipes through the carousel.
_27                }
_27
_27                if (event.data.type === "mx/pulse/micro-carousel/cta") {
_27                  // Send the user to the Insights Widget.
_27                  // If a beat_guid exists, send the user to the Insights Widget with the specified insight at the top of the feed.
_27                }
_27            }
_27        });
_27    </script>
_27  </body>
_27</html>

Step 1

Create an iFrame.

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

Step 2

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

Step 3

Optionally create listeners for these two application events:

Widget Load – triggered when the widget is loaded.
Widget Ping – used to keep the widget session alive.

See Postmessage UI Events for more info.

Step 4

Configure event listeners for:

An event for when the user clicks the View all > CTA. When the user clicks this, you'll consume the info we send to you in the postMessage event and then send the user to the Insights Widget.
An event for when the user clicks the Learn more CTA. When the user clicks this, you'll consume additional information from the postMessage event. This will let you send the user to the Insights Widget with the insight the user clicked on at the top of the feed.

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

Language:html


_10<html>
_10  <body>
_10    <iframe width="300px" height="200px" src=""></iframe>
_10  </body>
_10</html>

success

Congrats! You've integrated the Micro 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/micro_pulse_carousel/XXXXX',
_16        width: 300,
_16        height: 200
_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/micro_pulse_carousel/XXXXX',
_16        width: 300,
_16        height: 200
_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 recommended 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/micro_pulse_carousel/XXXXX',
_16        width: 300,
_16        height: 200
_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 example is hardcoded).

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 Micro Widget by specifying micro_pulse_carousel_widget as the widget_type, using the Platform API or SSO API.

See Example API Requests for different configurations.

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

Step 5

Optionally create listeners for these two application events:

Widget Load – triggered when the widget is loaded.
Widget Ping – is used to keep the widget session alive.

See Postmessage UI Events for more info.

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/micro_pulse_carousel/XXXXX',
_31        width: 300,
_31        height: 200
_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 Micro Widget events:

An event for when the user clicks the View all > CTA. When the user clicks this, you'll consume the info we send to you in the postMessage event and then send the user to the Insights Widget.
An event for when the user clicks the Learn more CTA. When the user clicks this, you'll consume additional information from the postMessage event. This will let you send the user to the Insights Widget with the insight the user clicked on at the top of the feed.

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

Language:shell


_36<html>
_36  <head>
_36    <title>My Web Page</title>
_36    <script type="text/javascript" src="https://widgets.moneydesktop.com/assets/mx-widgetloader.js"></script>
_36    <script type="text/javascript">
_36      var myWidget = new MoneyDesktopWidgetLoader({
_36        url: 'https://widgets.moneydesktop.com/md/micro_pulse_carousel/XXXXX',
_36        width: 300,
_36        height: 200
_36      });
_36    </script>
_36  </head>
_36  <body>
_36    <div id="md-widget"></div>
_36    <script>
_36        // an example for handling events.
_36        window.addEventListener('message', (event) => {
_36            if (event.data.mx) {
_36                if (event.data.type === "mx/load") {
_36                  // This event is triggered when the widget is loaded.
_36                }
_36                
_36                if (event.data.type === "mx/ping") {
_36                  // This event is triggered when the user interacts with the UI.
_36                  // For example, when the user swipes through the carousel.
_36                }
_36
_36                if (event.data.type === "mx/pulse/micro-carousel/cta") {
_36                  // Send the user to the Insights Widget.
_36                  // If a beat_guid exists, send the user to the Insights Widget with the specified insight at the top of the feed.
_36                }
_36            }
_36        });
_36    </script>
_36  </body>
_36</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 recommended 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 example is hardcoded).

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 Micro Widget by specifying micro_pulse_carousel_widget as the widget_type, using the Platform API or SSO API.

See Example API Requests for different configurations.

Step 5

Optionally create listeners for these two application events:

Widget Load – triggered when the widget is loaded.
Widget Ping – is used to keep the widget session alive.

See Postmessage UI Events for more info.

Step 6

Configure event listeners for the Micro Widget events:

An event for when the user clicks the View all > CTA. When the user clicks this, you'll consume the info we send to you in the postMessage event and then send the user to the Insights Widget.
An event for when the user clicks the Learn more CTA. When the user clicks this, you'll consume additional information from the postMessage event. This will let you send the user to the Insights Widget with the insight the user clicked on at the top of the feed.

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

success

Congrats! You've integrated the Micro Widget!

Integrate on a Mobile App

To integrate the widget on a mobile app:

Request micro_pulse_carousel_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.
Load the URL received from the previous request into a WebView.
See Events in Mobile WebViews.
Capture and parse a URL for the widget load and widget ping application events.
Capture and parse two URLs, relating to the Micro Widget events:
- A URL for when the user clicks the View all > CTA. When the user clicks this, you'll consume the info we send to you in the URL and then send the user to the Insights Widget.
- A URL for when the user clicks the Learn more CTA. When the user clicks this, you'll consume additional information from the URL. This will let you send the user to the Insights Widget with the insight the user clicked on at the top of the feed.

success

Congrats! You've integrated the Micro Widget!

Move Insight to Top of Feed

This guide shows you how to move an insight to the top of the feed in the Insights Widget.

You'll want to use this if you're also using the Mini or Micro Widget. This is so users can select View More above an insight in the Mini Widget, which sends them to the full feed, then see that insight at the top.

To request an Insights Widget with a specified insight displayed at the top:

Request the Insights Widget with the insight_guid configuration, as shown in the examples. Set the value for the insight_guid to the vale of the beat_guid you received from the Mini Widget postmessage UI event.
The response from this Insights Widget request will contain the URL for an Insights Widget that has the specified insight at the top of the feed.

SSO

Language:shell


_10curl -i -X POST https://int-sso.moneydesktop.com/{client_id}/users/{id}/urls.json  \
_10  -H 'Content-Type: application/vnd.moneydesktop.sso.v3+json' \
_10  -H 'Accept: application/vnd.moneydesktop.sso.v3+json' \
_10  -H 'MD-API-KEY: {api_key}' \
_10  -d '{
_10        "url": {
_10          "type": "pulse_widget",
_10          "insight_guid": "BET-123"
_10        }
_10      }'

Platform

Language:shell


_10curl -i -X POST 'https://int-api.mx.com/users/{user_id}/widget_urls' \
_10-u '{client_id}:{api_key}' \
_10-H 'Accept: application/vnd.mx.api.v1+json' \
_10-H 'Content-Type: application/json' \
_10-d '{
_10      "widget_url": {
_10        "widget_type": "pulse_widget",
_10        "insight_guid": "BET-123"
_10      }
_10    }'

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)

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

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": "micro_pulse_carousel_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": "micro_pulse_carousel_widget"
_10  }
_10}'

If embedding multiple instances of the Micro Widget, you'll want to set microwidget_instance_id to a unique string value for every instance. This lets us collect data for each instance of the widget. For example, one instance that displays on the accounts page could be set as follows...


_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    "microwidget_instance_id": "accounts_page",
_10    "widget_type": "micro_pulse_carousel_widget"
_10  }
_10}'

While another instance of the Micro Widget that appears on the transactions page could be set as...


_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    "microwidget_instance_id": "transactions_page",
_10    "widget_type": "micro_pulse_carousel_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": "micro_pulse_carousel_widget"
_10  }
_10}'

PostMessage UI Events

When certain events trigger 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.

It's your responsibility to add a listener to capture the properties of these triggered events and also handle what happens next.

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, as seen in the previous example, 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

Because of the technical limitations of WebView-based widget implementations, an alternative to standard postMessages is required. MX has developed a URL-based updating mechanism to replace event messages that are available to other desktop implementations. You can capture this URL and use the information provided in them to build the necessary logic for coordinating application events.

When requesting a widget URL using the SSO API or Platform API, you must include the is_mobile_webview field with a value of true in your request to access WebView event messages. If you don't want to handle these events, don't set the is_mobile_webview flag, or set it to false.

For the Micro Widget, this URL is delivered via a window.location = "mx://pulse/micro-carousel/cta?metadata=<metadata as an encodedURI JSON string>" call within the iFrame.

danger

Not capturing this URL can cause the app to break.

You must capture this URL, parse out the path and query string, then JSON-decode the metadata field. When decoded, the metadata will contain the beat_guid, beat_template, and user_guid.

Application Events

This event triggers when the widget loads.


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

This event keeps 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}

The Micro Widget has two postMessage events.

One postMessage event triggers when the end user clicks the View all CTA in the Micro Widget's header. If you have the header enabled, you must add a listener for this postMessage that sends the user to the Insights Widget.

This event will look like the following.

Example

Language:json


_10{
_10  "type": "mx/pulse/micro-carousel/cta",
_10  "mx": true,
_10  "metadata": {
_10    "user_guid": "USR-abcd-1234"
_10  }
_10}

Another event is triggered when the end user clicks the Learn more CTA. You must add a listener for this postMessage event that sends the user to the Insights Widget.

In this postMessage event, the metadata includes a beat_guid. You'll use this GUID in your widget URL request for the Insights Widget so the specified insight shows at the top of the insights feed. See Move Insight to Top of Feed for more info.

This event will look like the following.

Example

Language:json


_10{
_10  "type": "mx/pulse/micro-carousel/cta",
_10  "mx": true,
_10  "metadata": {
_10    "beat_guid": "BRT-2345-bcda",
_10    "beat_template": "MonthlySpendComparison",
_10    "user_guid": "USR-abcd-1234"
_10  }
_10}

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 setting these configurations is through the widget URL request. See Config Parameter for more info.
`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: 450,
_11  height: 400,
_11  config: {
_11    micro_pulse_carousel: {
_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.

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/micro_pulse_carousel/XXXXX",
_10    width: 320,
_10    height: 300
_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 Micro 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​

Move Insight to Top of Feed​

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​

Micro Widget Events​

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​

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

Move Insight to Top of Feed

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

Micro Widget Events

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