Integrate the Mini Widget
This guide shows you how to integrate the Mini 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.
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.
Step 2
In the iFrame's src, you'll need to request a widget URL and specify mini_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.
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 an event listener for the Mini Widget event.
See Postmessage UI Events for more information.
Step 2
In the iFrame's src, you'll need to request a widget URL and specify mini_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.
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 an event listener for the Mini Widget event.
See Postmessage UI Events for more information.
Congrats! You've integrated the Micro Widget!
Integrate on a Website (Widget Loader)
This shows how to integrate the widget on a website using an iFrame.
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.
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.
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.
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 mini_pulse_carousel_widget as the widget_type, using the Platform API or SSO API.
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.
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.
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.
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 mini_pulse_carousel_widget as the widget_type, using the Platform API or SSO API.
Integrate on a Mobile App
To integrate the widget on a mobile app:
- Request
mini_pulse_carousel_widgetas thewidget_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 a URL for when the end user interacts with the View more CTA inside the widget. You must add a listener for this postMessage UI event to know when to navigate the end user to the Insights Widget. See Mini Widget event for more information.
Congrats! You've integrated the Mini 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_guidconfiguration, as shown in the examples. Set the value for theinsight_guidto the vale of thebeat_guidyou 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.
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 API Requests
The following examples are for requesting a Mini 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": "mini_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": "mini_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": "mini_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. In this example, it would be your responsibility to direct the user to the full insights feed.
If integrating on mobile through a WebView, an alternative to standard postMessage UI events is required. See Events in Mobile WebViews for more information.
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
mxfield that lets you filter out postMessage UI events coming from MX. - The
typefield that identifies what the event represents at a high level. - The
metadataobject field that has information related to thetype.
The following is an example integration that lets you listen to the events we send.
Application Events
Widget Load
This event triggers when the widget loads.
_10{_10 "type": "mx/load",_10 "mx": true_10}
Widget Ping
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}
Mini Widget Event
Insights were previously called beats. You’ll see field names and other values that still reference beats.
A postMessage UI event is triggered when the end user interacts with the View more CTA inside the widget. You must add a listener for this postMessage UI event to know when to navigate the end user to the Insights Widget.
Widget Loader Configurations
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
Widget Loader Parameters
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. | |
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.
You can set the following configuration options.
| Configuration Option | Data Type | Description |
|---|---|---|
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. |
is_mobile_webview | Boolean | Renders the widget in a mobile WebView. Executes URL updates in place of the JavaScript postMessage UI events. |
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.
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
MoneyDesktopWidgetLoaderfor each widget. - Connect each loader instance to a placeholder element by setting the
idproperty value as the CSSid.
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.
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.
(Optional) Filter Insights
By default, the Mini Widget displays up to 5 insight cards, which are the user's most recent insight cards that are mini-carousel enabled.
To filter which insight cards can appear in your Mini Widget, you must:
- Request
mini_pulse_carousel_widgetas thewidget_type. - Append a query string to the widget URL you receive from the previous step. Use the format shown in the examples to add every insight card template name you want to filter for and include in the Mini Widget. For a list insights that are Mini Widget compatible, see the Insights Library.
Insight cards display in the order they were originally generated, and not in the order you appended their template names. While you must append a minimum of 1 insight card template name to change the default behavior, there is no maximum number of template names you can append.
One insight card template can appear multiple times. Since the carousel displays a maximum of 5 insight cards, this may prevent additional cards from displaying. For example, if you filter the carousel to show the AmericanFederalBankHolidays, FeeDetected, and SaveEnoughToLiveOn templates, the FeeDetected template could display in the carousel's first three slides and the AmericanFederalBankHolidays could display in the carousel's last two slides. As a result, the SaveEnoughToLiveOn wouldn't display in the carousel.
If the user doesn't have enough history for an insight card to populate from one of the appended templates, and you appended another card which can populate, the original card will not display. If none of the insight card templates you appended can populate, then two no state cards will appear in the carousel.