Integrating PFM Widgets - MX Documentation

This guide shows you how to integrate any PFM Widget on a website or mobile app using the Platform API. If you have the Nexus API enabled, use the SSO API to implement your widgets.

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

Integrate PFM Widgets on a Website

To integrate the widget on a website using an iframe:

Create an iFrame

Create an iframe. Set the width and height to 100%.For more information about widget sizing, reference the widget’s supported dimensions.

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

Generate a Widget URL

Create a backend endpoint that calls the Platform API to generate a widget URL. Set the widget_type to your desired widget; reference the list of widget types for the acceptable values.

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

Create Listeners for Widget Events

Depending on the widget you’re integrating, you may have to create additional event listeners:

If integrating the Money Dashboard Widget, you must create listeners for all the Money Dashboard Widget events, which includes all the Connect Widget’s widget events.
If integrating the Connections Widget, you must create listeners for all the Connections Widget events, which includes all the Connect Widget’s events.
If integrating the Mini Finstrong Widget, you must create listeners for all the Mini Finstrong Widget events.

<html>
  <head>
  </head>
  <body>
    <iframe id="widgetIframe" width="100%" height="100%" src="requestURL()"></iframe>
    <script>
        // an example for handling events.
        window.addEventListener('message', (event) => {
            if (event.data.mx) {
                // example of handling an application event.
                if (event.data.type === "mx/load") {
                  // This event is triggered when the widget is loaded.
                }
                
                // example of handling an application event.
                if (event.data.type === "mx/ping") {
                  // This event is triggered when the user interacts with the UI.
                }
            }
        });
    </script>
  </body>
</html>

Optional: Deep Link Embedded Widgets

If you’re using the Money Dashboard Widget and other Mini Widgets, you can configure it to deep link other embedded Mini Widgets to their full views. For example, selecting the View All button on the Mini Spending Widget should redirect the user to the full Spending Widget within the Money Dashboard. Similarly, clicking the call-to-action (CTA) button on any embedded Mini Widget should take the user to its corresponding full view.To create a deep link, use the Platform API’s request widget URL endpoint and follow these steps:

Set the widget_type field to money_dashboard_widget.
Set the widget field to your desired Mini Widget.

Integrate PFM Widgets on a Mobile App

To integrate the widget on a mobile app:

Generate a Widget URL

Create a backend endpoint that calls the Platform API to generate a widget URL. Set the widget_type to your desired widget; reference the list of widget types for the acceptable values. Include the is_mobile_webview field with a value of true.

Load the URL into a WebView

Load the widget_url.url returned in the Generate a Widget URL step into a WebView.

Capture URLs for Application Events

Capture and parse URLs delivered via window.location = "someurl" calls for the application events. See Events in Mobile WebViews for more details.

Capture URLs for Additional Events

If you’re integrating the Connections Widget or Mini Finstrong Widget, you’ll need to capture and parse URLs for additional events. For more information, see Widget Events.

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.

To experience the full responsive nature of our application, don’t restrict the available browser width by adding margins or padding.

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

​Integrate PFM Widgets on a Website

​Integrate PFM Widgets on a Mobile App

​Common PFM Widget WebView Problems

Integrate PFM Widgets on a Website

Integrate PFM Widgets on a Mobile App

Common PFM Widget WebView Problems