How to Integrate PFM Widgets

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 Legacy Widget Integration Guide for troubleshooting.

Integrate on a Website

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

Step 1

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

Line focusing example

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

Step 2

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.

Line focusing example

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

Step 3

Create listeners for the 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’s events.

Line focusing example

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

Money Dashboard Deep Linking

Configure the Money Dashboard Widget 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.
Create the necessary event listeners for the Money Dashboard Widget events.

Integrate on a Mobile App

To integrate the widget on a mobile app:

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 received from the previous request into a WebView.
Capture and parse URLs delivered via window.location = "someurl" calls for the application events. See Events in Mobile WebViews for more details.
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 the list of 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.

In order to have the benefit of the full responsive nature of our application, please 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">

When certain events are triggered in our UI, we send you a widget 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 widget events is required. See Events in Mobile WebViews for more information.

Don’t use widget events for keeping data in sync between platforms. Webhooks are a more reliable way of coordinating events between your servers and MX servers.

Widget events from MX have the following properties:

The mx field that lets you filter out widget 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 Integration

function handleEvent(event) {
  if (event.data.mx) {
    // handle the mx post message using event.data.type and event.data.metadata.
  }
}

window.addEventListener('message', handleEvent)

Events in Mobile WebViews

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 widget 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.

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

This event is used to keep the widget session alive.

{
  "type": "mx/ping",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

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.

{
  "type": "mx/focusTrap",
  "mx": true,
  "metadata": {
    "trapped": "true"
  }
}

All Connect Widget events also apply to the Money Dashboard Widget. The following events are for the Money Dashboard Widget. This event is triggered when a user selects a primary CTA, like View Details.

Example

{
  "type": "mx/moneyDashboard/miniWidgetClicked",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

This event is triggered when a user selects a secondary CTA.

Example

{
  "type": "mx/moneyDashboard/miniWidgetSecondaryClicked",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

You must create a listener for one event specific to the Connections Widget: the Member Deleted event. All widget events that apply to the Connect Widget also apply to the Connections Widget.

Member Deleted

This event is triggered when a member has been deleted in the widget.

Example

{
  "type": "mx/connections/memberDeleted",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}

The following events are for the Finstrong Mini Widget.

Sufficient Data, Primary Action Selected

This event is triggered when the user has enough data to generate a Finstrong health score and the primary action is selected.

Example

{
  "type": "mx/miniFinstrong/sufficientData/primaryAction",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Insufficient Data, Primary Action Selected

This event is triggered when the user doesn’t have enough data to generate a Finstrong health score and the primary action is selected.

Example

{
  "type": "mx/miniFinstrong/insufficientData/primaryAction",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}

Integrate on a Website

Money Dashboard Deep Linking

Integrate on a Mobile App

Common Problems

Widget Events

Events in Mobile WebViews

Application Events

Widget Load

Widget Ping

Widget focusTrap

Money Dashboard Widget Events

Mini Widget Selected

Mini Widget Call to Action Selected

Connections Widget Events

Member Deleted

Mini Finstrong Widget Events

Sufficient Data, Primary Action Selected

Insufficient Data, Primary Action Selected

​Integrate on a Website

​Money Dashboard Deep Linking

​Integrate on a Mobile App

​Common Problems

​Widget Events

​Events in Mobile WebViews

​Application Events

​Widget Load

​Widget Ping

​Widget focusTrap

​Money Dashboard Widget Events

​Mini Widget Selected

​Mini Widget Call to Action Selected

​Connections Widget Events

​Member Deleted

​Mini Finstrong Widget Events

​Sufficient Data, Primary Action Selected

​Insufficient Data, Primary Action Selected

Integrate on a Website

Money Dashboard Deep Linking

Integrate on a Mobile App

Common Problems

Widget Events

Events in Mobile WebViews

Application Events

Widget Load

Widget Ping

Widget focusTrap

Money Dashboard Widget Events

Mini Widget Selected

Mini Widget Call to Action Selected

Connections Widget Events

Member Deleted

Mini Finstrong Widget Events

Sufficient Data, Primary Action Selected

Insufficient Data, Primary Action Selected