> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget Events

> Handle widget events triggered by PFM widgets in your integration.

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](#events-in-mobile-webviews) for more information.

<Warning>
  Don't use widget events for keeping data in sync between platforms. [Webhooks](/resources/webhooks) are a more reliable way of coordinating events between your servers and MX servers.
</Warning>

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:

```js Example Integration theme={null}

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

<Note>
  This section only applies if you are embedding the widget in a WebView.
</Note>

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.

### Widget Load

This event is triggered when the widget is loaded.

```json theme={null}
{
  "type": "mx/load",
  "mx": true
}
```

### Widget Ping

This event is used to keep the widget session alive.

```json theme={null}
{
  "type": "mx/ping",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}
```

### Widget `focusTrap`

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.

```json theme={null}
{
  "type": "mx/focusTrap",
  "mx": true,
  "metadata": {
    "trapped": "true"
  }
}
```

## Money Dashboard Widget Events

All Connect Widget events also apply to the Money Dashboard Widget.

The following events are for the Money Dashboard Widget.

### Mini Widget Selected

This event is triggered when a user selects a primary CTA, like **View Details**.

```json Example theme={null}
{
  "type": "mx/moneyDashboard/miniWidgetClicked",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}
```

### Mini Widget Call to Action Selected

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

```json Example theme={null}
{
  "type": "mx/moneyDashboard/miniWidgetSecondaryClicked",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}
```

## Connections Widget Events

You must create a listener for one event specific to the Connections Widget: the Member Deleted event.

All [widget events](/connect/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.

```json Example theme={null}
{
  "type": "mx/connections/memberDeleted",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123",
    "member_guid": "MBR-123"
  }
}
```

## Mini Finstrong Widget Events

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.

```json Example theme={null}
{
  "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.

```json Example theme={null}
{
  "type": "mx/miniFinstrong/insufficientData/primaryAction",
  "mx": true,
  "metadata": {
    "user_guid": "USR-123",
    "session_guid": "ANS-123"
  }
}
```