Integrating Insights Widgets - MX Documentation

Once you’ve decided how best to engage your audience, you need to integrate your Insights Widget. This guide explains how to integrate the Insights Widget, Mini Insights Widget, and Micro Insights Widget either on a website using an iFrame or on a mobile app. The examples in this guide use fields that apply only to the Platform API. If you’re using the Nexus API, use the SSO API fields instead.

If you integrated using the Widget Loader, please reference the legacy Widget Loader Configurations guide.

To learn more about each widget, see Insights Widgets.

Integrate using an iFrame

Follow these steps to integrate a widget on a website using an iFrame.

Request a Widget URL

Create a backend endpoint that calls the Platform API to generate a widget URL. Set the value of widget_type to your desired widget:

Insights Widget: pulse_widget
Mini Insights Widget: mini_pulse_carousel_widget
Micro Insights Widget: micro_pulse_carousel_widget

See Example API Requests for different configurations.

Create an iFrame

Create an iFrame using the widget’s recommended dimensions:

Widget	Optimal Dimensions (Height ✕ Width)
Insights Widget	550 px ✕ 320 px
Mini Insights Widget	400 px ✕ 320 px
Micro Insights Widget	224 px ✕ 320 px

Reference the endpoint you created in Step 1 as the src. If you use sandbox, the following attributes must be whitelisted for the widget to work: sandbox="allow-forms allow-same-origin allow-scripts".

Example

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

Create Application Event Listeners

Create listeners for the widget load and widget ping application events.

Example

<html>  
  <head>  
  </head>  
  <body>  
    <iframe width="100%" height="550px" src=requestURL()></iframe>  
    <script>  
        // an example for handling events.  
        window.addEventListener('message', (event) => {  
            if (event.data.mx) {  
                if (event.data.type === "mx/load") {  
                  // This event is triggered when the widget is loaded.  
                }  

                if (event.data.type === "mx/ping") {  
                  // This event is triggered when the user interacts with the UI.  
                  // For example, when the user swipes through the feed.  
                }  
            }  
        });  
    </script>  
  </body>  
</html>  

Configure Widget Event Listeners

Configure event listeners for your widget events.Capture and parse the URLs necessary for your widget version:

Insights Widget: Refer to the Insights Widget events table to determine which of your enabled insight templates create events that you need to handle.
Mini Insights Widget: Capture and parse a URL for when the end user interacts with the View more call to action inside the widget. You must add a listener for this UI event to know when to navigate the end user to the Insights Widget.
Micro Insights Widget: Capture and parse two URLs relating to the Micro Insights Widget events:
- A URL for when the user selects the View all call to action. When the user selects this, you 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 selects the Learn more call to action. When the user selects this, you consume additional information from the URL. This lets you send the user to the Insights Widget with the insight the user selected at the top of the feed.

Example

<html>  
  <head>  
  </head>  
  <body>  
    <iframe width="100%" height="550px" src=requestURL()></iframe>  
    <script>  
        // an example for handling events.  
        window.addEventListener('message', (event) => {  
            if (event.data.mx) {  
                if (event.data.type === "mx/load") {  
                  // This event is triggered when the widget is loaded.  
                }  

                if (event.data.type === "mx/ping") {  
                  // This event is triggered when the user interacts with the UI.  
                  // For example, when the user swipes through the carousel.  
                }

                // Example of handling one Insights Widget event.  
                if (event.data.metadata.beat_template === "ReplenishSavings") {  
                  // Use the metadata to send the user to create a transfer for their savings account.  
                }

            }  
        });  
    </script>  
  </body>  
</html>  

Optional: Filter Insights

You can filter which insights show in a specific Mini Widget instance. See Filter Insights for more information.

Congrats! You’ve integrated your Insights Widget!

Integrate on a Mobile App

To integrate the Insights Widget on a mobile app, follow these steps.

Request a Widget URL

Create a backend endpoint that calls the Platform API to generate a widget URL. Set the value of widget_type to your desired widget:

Insights Widget: pulse_widget
Mini Insights Widget: mini_pulse_carousel_widget
Micro Insights Widget: micro_pulse_carousel_widget

Include the is_mobile_webview field with a value of true in your request to access WebView event messages.See Example API Requests for different configurations.

Load the URL

Load the URL received from the previous request into a WebView.

Build Event Logic

Capture the URLs delivered via window.location = "someurl" calls within the WebView and use the information provided in those calls to build the necessary logic for coordinating events.

All MX URL message events have the mx:// prefix and appear in the format mx://<entity|widget>/<event>?metadata=<metadata as an encodedURI JSON string>. For example: 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.

Handle Widget Load and Widget Ping Events

Capture and parse a URL for the widget load and widget ping application events.

Handle Other Widget Events

Capture and parse the URLs necessary for your widget version:Insights Widget: Refer to the Insights Widget events table to determine which of your enabled insight templates create events that you need to handle.Mini Insights Widget: Capture and parse a URL for when the end user interacts with the View more call to action inside the widget. You must add a listener for this UI event to know when to navigate the end user to the Insights Widget.Micro Insights Widget: Capture and parse two URLs relating to the Micro Insights Widget events:

A URL for when the user selects the View all call to action. When the user selects this, you 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 selects the Learn more call to action. When the user selects this, you consume additional information from the URL. This lets you send the user to the Insights Widget with the insight the user selected at the top of the feed.

Optional: Filter Insights

You can filter which insights show in a specific Mini Widget instance. See Filter Insights for more information.

Congrats! You’ve integrated your Insights Widget!

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)

By default, iOS adds additional padding to its WebViews, which sometimes causes 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 correctly, 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

<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=no">

Move Insight to Top of Feed

If you embedded the Mini or Micro Insights Widget, you must configure the View More call to action to send users to the Insights Widget. For a seamless experience, we recommend moving the insight they selected to the top of the Insights Widget. To request the Insights Widget with a specified insight displayed at the top:

Request a Widget URL

Request the Insights Widget with the insight_guid configuration. Set the value for the insight_guid to the value of the beat_guid you received from the Mini or Micro Insights Widget event.

Platform API Example

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

Use the URL

The response from this Insights Widget request contains the URL for an Insights Widget that has the specified insight at the top of the feed.

(Optional) Filter Insights

To filter which insights appear in your Mini Insights Widget, request mini_pulse_carousel_widget as the widget_type, then append a query string to the widget URL using the following format. Include at least one insight template name (no maximum limit). For compatible templates, see the Insights Library.

Widget URL with query string

https://int-widgets.moneydesktop.com/md/mini_pulse_carousel/ncAg2m36dv4dhb1n1wqghcqqk2Zbv3A8dznvlwvlw2d65bbwqwttpkpxhx2l53vmk4w8hqhvtlthsds4dwktjxbw01127q6blsrnxwlfsx01jc5xzA2vvvAyy3tlsdy06f8gqwt4bn3mm93k8bsxf5j5jfdd37qqdb8q8Arnj1kf9hwc3c64pmrslp36x9cmkphA5y7z5tcxztkzxvdyyckmpnjhh6c227xb7rfvspt6n90rp7Atb3dpytp2kjsjt1jjgdhjbjk91cfj4xAglbhq3034slvwbfA24ftwdkw97yygc4fhn7v9j56snx7zqw12jcqt88yt8jq4mfbc01q16mlqn5cn74rvkv0A/eyJ1aV9tZXNzYWdlX3ZlcnNpb24iOjQsInVpX21lc3NhZ2Vfd2Vidmlld191cmxfc2NoZW1lIjoibXgiLCJsb2NhbGUiOiJlbi1VUyJ9?enabled_templates[]=WeeklyNoSpendDays&enabled_templates[]=AmericanFederalBankHolidays&enabled_templates[]=TaxDeposit&enabled_templates[]=CashBack&enabled_templates[]=CheckDeposit  

Insights display in their original generation order, not the order you append them. Since templates can appear multiple times and the carousel caps at five insights, repeated templates may prevent other insights from displaying. If a user lacks transaction history for a template, it won’t populate; if no templates can populate, two no-state cards appear instead.

Example API Requests

The following examples are for requesting a Widget URL in the Platform API. Add a Spanish-language widget to a website:

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

Request a Mini Insights Widget to embed on a mobile app through a WebView.

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

You can embed multiple instances of the Micro Insights Widget on a website, for example, a widget on the Accounts page and a widget on the Transactions page.

Accounts Page

curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls'   
-H 'Content-Type: application/json'   
-H 'Accept: application/vnd.mx.api.v20250224+json'   
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}'   
--data '{  
  "widget_url": {  
    "widget_type": "micro_pulse_carousel_widget",
    "microwidget_instance_id": "accounts_page",
  }  
}'  

Transactions Page

curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.mx.api.v20250224+json' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
--data '{
  "widget_url": {
    "widget_type": "micro_pulse_carousel_widget",
    "microwidget_instance_id": "transactions_page"
  }
}'

​Integrate using an iFrame

​Integrate on a Mobile App

​Common Problems

​Move Insight to Top of Feed

​(Optional) Filter Insights

​Example API Requests

Integrate using an iFrame

Integrate on a Mobile App

Common Problems

Move Insight to Top of Feed

(Optional) Filter Insights

Example API Requests