Widget Events

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

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

​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

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