Widget Events

When certain events trigger 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 widget events is required. See Events in Mobile WebViews for more information. It’s your responsibility to add a listener to capture the properties of these triggered events and handle what happens next.

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.

Here’s 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

MX has developed a URL-based updating mechanism to replace event messages that are available to other desktop implementations. You can capture this URL and use the information provided in it to build the necessary logic for coordinating application events. When requesting a widget URL, you must include the is_mobile_webview field with a value of true in your request to access WebView event messages. If you don’t want to handle these events, either set the is_mobile_webview value to false or don’t include this flag. For the Micro Insights Widget, this URL is delivered via a window.location = "mx://pulse/micro-carousel/cta?metadata=<metadata as an encodedURI JSON string>" call within the iFrame. You must capture this URL, parse out the path and query string, then JSON decode the metadata field. When decoded, the metadata contains the beat_guid, beat_template, and user_guid fields.

Not capturing this URL can cause the app to break.

Application Events

This event triggers when the widget loads.

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

This event keeps 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"  
  }  
}  

When displayed in the Insights Widget, some insights contain a call to action (CTA) that directs the user to the appropriate location by default, but others require you to send the user somewhere else to complete an action. Here’s the process:

We detect that a user has selected a CTA on one of our insights that requires you to send the user somewhere outside of our widget.
We send you a UI event to let you know that a user has selected this CTA. Each event contains base metadata fields, and some events contain fields specific to individual insight templates. Refer to Table 1 for details about these fields.
The listener you create for this event sends the user to the appropriate location within your mobile app or website based on the details we sent through the UI event.

Table 1. Event fields

Field	Type	Definition
`account_guid`	String	The unique identifier for the account. Defined by MX.
`account_name`	String	The human-readable name of the account.
`accounts`	Array	An array of account objects, each of which contains the `account_guid` and `account_name` described in this table.
`action`	String	The base metadata field that represents the scenario number within an insight. Most insights have only one scenario. For insights that require you to configure events for two or more possible scenarios, use the value `op_1` to indicate the first scenario, `op_2` to indicate the second scenario, and `op_3` to indicate the third scenario. For example, `"action": 'op_1'` indicates the first scenario of a multi-scenario insight.
`amount`	Integer	The amount the user would like to transfer to savings.
`beat_guid`	String	The base metadata field that represents the unique identifier for the insight. Defined by MX.
`beat_template`	String	The base metadata field that represents a short label for the insight being delivered. For example, `DesignateEmergencySavingsAccount`.
`destination_account_ids`	Array	The identifiers you define for the accounts eligible to transfer funds to.
`goal_guid`	String	The unique identifier for the goal. Defined by MX. This field returns an empty string for the Start Saving for Emergencies call to action.
`projected_overdraft_amount`	Integer	The projected amount the account will be overdrawn.
`source_account_ids`	Array	The identifiers you define for the accounts eligible to transfer funds from.
`total_amount_withdrawn`	Integer	The total amount withdrawn from all included accounts.
`user_guid`	String	The unique identifier for the user. Defined by MX.

You must create listeners for each of the insight templates described in Table 2 that MX has enabled for you.

Table 2. Templates and associated actions

Insight Template	When MX Sends This Event	What You Must Do	Base Metadata Fields
`DesignateEmergencySavingsAccount`	When the user selects the Open Savings Account CTA in the scenario where the user doesn’t have a savings account.	Send the user to open a savings account.	`"action": 'op_1'`
`EmergencyFundWithdrawal`	When the user selects the View my emergency savings CTA or the Transfer funds CTA. The CTA that appears depends on if you have transfers for funds enabled.	When MX sends you this event, you must either send the user to view their emergency savings or create a transfer, depending on whether you have transfers for funds enabled or disabled.	`"action": 'op_1'`
`LowAccountBalance`	When the user selects the Transfer funds CTA.	Send the user to transfer funds to their low balance account.	`"action": 'op_1' account_guid`
`MonthlyEmergencyFundReview` (scenario 1)	When the user selects the View my emergency savings CTA.	Send the user to where they can view their emergency savings amount.	`"action": 'op_1'`
`MonthlyEmergencyFundReview` (scenario 2)	When the user selects the Create new goal CTA.	Send the user to the Goals Widget.	`"action": 'op_2'`
`MonthlyEmergencyFundReview` (scenario 3)	When the user selects the Create transfer CTA.	Send the user somewhere where they can transfer money.	`"action": 'op_3'`
`MonthlyObligationsStatus`	When the user selects the Make a transfer CTA.	Send the user somewhere where they can transfer money.	`"action": 'op_1'`
`MonthlySpendingPlanCelebration`	When the user selects the Visit spending plan CTA.	Send the user to the Spending Plan Widget.	`"action": 'op_1'`
`ReplenishSavings`	When the user selects the Create Transfer CTA.	Send the user to create a transfer to their savings account.	`"action": 'op_1' account_guid account_name accounts total_amount_withdrawn`
`SaveAnExtra100Dollars`	When the user selects the Make A Transfer CTA.	Send the user to where they can make a transfer.	`"action": 'op_1'`
`SavingsAccountDeposit`	When the user selects either the View my emergency savings or Start saving for emergencies CTA.	Send the user to the Goals Widget. From there the user can see their emergency savings goal or start an emergency savings goal.	`"action": 'op_1' account_guid goal_guid` (if available) `user_guid`
`SavingsMilestoneEmergencyFund`	When the user selects the View my emergency savings CTA.	Send the user to where they can view the Goals Widget.	`"action": 'op_1' account_guid goal_guid` `user_guid`
`SavingsOpportunityV2` (scenario 1)	When the user already has an eligible savings account to transfer money to and selects the Transfer Funds CTA.	Send the user to create a transfer to their savings account.	`"action": 'op_1' amount destination_account_ids` `source_account_ids`
`SavingsOpportunityV2` (scenario 2)	When the user doesn’t have an eligible savings account to transfer money to and selects the Open Savings Account CTA.	Send the user to open a savings account.	`"action": 'op_2' amount` `source_account_ids`
`SetUpDirectDeposit`	When the user selects the Set Up Direct Deposit CTA.	When MX sends you this event, you must activate your direct deposit integration.	None.
`SpendingPlanCreatedCelebration`	When the user selects either the Start Spending Plan or Visit Spending Plan CTA.	Send the user to the Spending Plan Widget.	`"action": 'op_1'`
`SwitchDirectDeposit`	When the user selects the Switch Direct Deposit CTA.	When MX sends you this event, you must activate your direct deposit integration.	None.
`TransparentOverdraft`	When the user selects the Transfer funds CTA.	Send the user to transfer funds to their potentially overdrawn account.	`"action": 'op_1' destination_account_ids projected_overdraft_amount user_guid`
`UnifiedDepositEmergencyFund` (scenario 1)	When the user selects the Start saving for emergencies CTA.	Send the user to the Goals Widget.	`"action": 'op_1' account_guid goal_guid` `user_guid`
`UnifiedDepositEmergencyFund` (scenario 2)	When the user selects the Transfer funds CTA.	Send the user to a location where they can transfer funds to their emergency savings fund.	`"action": 'op_2' account_guid goal_guid` `user_guid`
`UnifiedDepositEmergencyFund` (scenario 3)	When the user selects the View my emergency savings CTA.	Send the user to the Goals Widget.	`"action": 'op_3' account_guid goal_guid` `user_guid`
`WeeklyNoSpendDays`	When the user selects the Visit Spending Plan CTA.	Send the user to the Spending Plan Widget, where they can see the widget as normal or onboard to it.	`"action": 'op_1'`

The Micro Insights Widget has two UI events. One event triggers when the user selects the View all CTA in the Micro Insight Widget’s header. If you have the header enabled, you must add a listener for this event that sends the user to the Insights Widget. Here’s what this event looks like:

Example

{  
  "type": "mx/pulse/micro-carousel/cta",  
  "mx": true,  
  "metadata": {  
    "user_guid": "USR-abcd-1234"  
  }  
}  

Another event is triggered when the user selects the Learn more CTA. You must add a listener for this event that sends the user to the Insights Widget. In this event, the metadata includes a beat_guid. Use this GUID in your widget URL request for the Insights Widget so the specified insight shows at the top of the insights feed. See Move Insight to Top of Feed for more info. Here’s an example of what this event looks like:

Example

{  
  "type": "mx/pulse/micro-carousel/cta",  
  "mx": true,  
  "metadata": {  
    "beat_guid": "BRT-2345-bcda",  
    "beat_template": "MonthlySpendComparison",  
    "user_guid": "USR-abcd-1234"  
  }  
}  

Events in Mobile WebViews

Application Events

Widget Load

Widget Ping

Widget focusTrap

Insights Widget Events

Micro Insights Widget Events

​Events in Mobile WebViews

​Application Events

​Widget Load

​Widget Ping

​Widget focusTrap

​Insights Widget Events

​Micro Insights Widget Events

Events in Mobile WebViews

Application Events

Widget Load

Widget Ping

Widget focusTrap

Insights Widget Events

Micro Insights Widget Events