> ## 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 > A list of Connect Widget events, how to handle them, and best practices When key actions occur in the Connect Widget, widget events are sent to you with the details that you need to respond to the event in your codebase. **WARNING** **Don't** use widget events for keeping data in sync between platforms. [Webhooks](/resources/webhooks) are more reliable when coordinating events between your servers and MX servers. ## How to Handle Events The way you'll handle widget events depends on your integration method. If you're using the Web Widget SDK, you'll listen for widget events by passing a `callbacks.onEvent` handler to the `ConnectWidget` constructor. The handler receives an `event` object with `type` and `metadata` fields. All payloads include the `user_guid` (string) and `session_guid` (string) fields. The following is an example integration that lets you listen to the events we send. ```js theme={null} import { ConnectWidget } from '@mxenabled/web-widget-sdk' const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { switch (event.type) { case 'mx/connect/connected/backToSearch': console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Context:', event.metadata.context) break } } } }) ``` **NOTE** If you're using our legacy React Native SDK, see the [legacy documentation](/other/legacy-connectivity-guides/react-native-legacy-sdk). The Event callback function (type: `(event: Event) => void`) is called whenever an event occurs within the widget. It will always contain a `type` and `metadata` field. ```js theme={null} type Event = { type: string // Event type identifier (for example, "mx/connect/oauthRequested") metadata: Record // Event-specific data and context } ``` Here's an example that handles the OAuth Requested event: ```js theme={null} const handleEvent = (event: Event) => { switch (event.type) { case "mx/connect/oauthRequested": console.log("OAuth requested with URL:", event.metadata) break default: console.log("Received event:", event.type, event.metadata) } } ``` When using the JavaScript Loader, events have the following properties: * The `mx` field (boolean) lets you filter out events coming from MX. * The `type` field (string) identifies what the event represents. * Schema: `mx//` * Example: `mx/connect/institutionSelected` * The `metadata` object contains: * `user_guid` (string) * `session_guid` (string) * `x_callback_payload` (returns if the `X-CALLBACK-PAYLOAD` header was defined in the Platform API [widget URL request](/api-reference/platform-api/reference/widgets)) The following is an example integration that lets you listen to the events we send. ```js theme={null} function handleEvent(event) { if (event.data.mx) { // handle the mx widget event using event.data.type and event.data.metadata. } } window.addEventListener('message', handleEvent) ``` When embedding the widget in a WebView, events have the following properties: * The `mx` field (boolean) lets you filter out events coming from MX. * The `type` field (string) identifies what the event represents. * Schema: `mx//` * Example: `mx/connect/institutionSelected` * The `metadata` object contains: * `user_guid` (string) * `session_guid` (string) * `x_callback_payload` (returns if the `X-CALLBACK-PAYLOAD` header was defined in the Platform API [widget URL request](/api-reference/platform-api/reference/widgets)) Ensure `is_mobile_webview` is set to `true` when requesting a widget URL, which affects the following: * Sends events with `window.location = {scheme}://{event path}?metadata={json encoded metadata}` instead of `window.postMessage(message)`. You must capture the URLs delivered via `window.location = "someurl"` calls within the iFrame, parse out the path and query string, then JSON-decode the `metadata` field. These events will all have the `mx://` prefix and the following format: `mx:///?metadata=`. * Sets `oauth_referral_source` to `APP` so the OAuth flow will redirect back to a native application instead of sending an event to the opening window. * Prevents the widget from automatically trying to open an OAuth window; instead it will send the [OAuth requested event](#oauth-requested) so your app can correctly open the OAuth window in the user agent. By default, the `ui_message_webview_url_scheme` will be `mx`. This can be configured when requesting a widget URL by setting the value to whatever custom string you prefer, for example `yourAppScheme`. **WARNING** Your app **must** capture all navigation events to `mx://` and custom schemes like `yourAppScheme://` so the WebView doesn't lose the Connect Widget session and the app doesn't break. **Example Navigation Event Schema** ``` Schema: {ui_message_webview_url_scheme}://{some/path}?metadata={jsonString} Default: mx://connect/loaded?metadata={jsonString} Custom: yourAppScheme://connect/institutionSearch?metadata={jsonString} ``` **Suggested Configuration for WebViews** ```shell Request theme={null} curl -i -X POST https://int-api.mx.com/users/USR-29eab3cf-6a87-fe97-6279-563b63e75a53/widget_urls \ -H 'Accept: application/vnd.mx.api.v1+json' \ -u 'client_id:api_key' \ -H 'Content-type: application/json' \ -d '{ "widget_url": { "widget_type": "connect_widget", "is_mobile_webview": true, "ui_message_version": 4, "ui_message_webview_url_scheme": "{app_scheme}" } }' # Possible navigation events based on the config above: # `mx://load` # `yourAppScheme://connect/institutionSearch?metadata={...json...} ``` ```json Response theme={null} { "widget_url": { "type": "connect_widget", "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5", "user_id": "partner-2345" } } ``` **Code Examples** ```java Java theme={null} public class MainActivity extends AppCompatActivity { private WebView webView = null; @Override protected void onCreate(Bundle savedInstanceState) { webView = (WebView) findViewById(R.id.webview); webView.setWebViewClient(new ConnectWebviewClient()); webView.getSettings().setDomStorageEnabled(true); webView.getSettings().setJavaScriptEnabled(true); } private class ConnectWebviewClient extends WebViewClient { @Override public boolean shouldOverrideUrlLoading(WebView view, String url) { if (url.startsWith("mx://")) { return true; } return false; } } } ``` ```swift Swift theme={null} class ViewController: UIViewController, WKUIDelegate { override func viewDidLoad() { super.viewDidLoad() webView.delegate = self ... } func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Swift.Void) { // Intercept custom URI let surl = navigationAction.url?.absoluteString if (surl?.hasPrefix("mx://"))! { // Take action here // Cancel request decisionHandler(.cancel) return } // Allow request decisionHandler(.allow) } } ``` *** ## Notable Widget Events The section details important widget events and what to do when you receive them. | Widget Event | What To Do | | :------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Back to Search](#back-to-search) | If you disabled the search institution step by setting `disable_institution_search: true`, listen to this event to know when your user will be navigated to the search step so you can close the widget. | | [Connect Loaded](#connect-loaded) | Track the start of the user's journey. You can also use this if you intend on hiding the widget from the user until you know it's loaded. | | [Institution Search](#institution-search) and [Institution Selected](#institution-selected) | Use these events to track trends in institutions your users want to connect to. If you identify a trend, you can customize the top 10 institutions in the default institutions list. You could also create UI that calls out and loads your users to connect to that institution directly. | | [Member Connected, Primary Action Selected](#member-connected-primary-action-selected) | If you don't want the end user to return to connect more accounts after they connected to one, close the widget. | | [OAuth Requested](#oauth-requested) | This event only applies if you embedded the widget inside a mobile app using a WebView, or using an iFrame inside a WebView. Send the user to the OAuth provider's site, opening the URL (contained in the event's `metadata`) in the device’s default browser. | | [Widget Ping](#widget-ping) | Used to keep the widget session alive. See [Handling Session Timeouts](/connect#handling-session-timeouts) for more info. | *** ## Back to Search Sent when the user selects a button that navigates to the `search` step, as defined in the [Step Change](#step-change) event. Used in relation with `disable_institution_search` widget configuration option. **Recommended use:** If you disabled the search institution step by setting `disable_institution_search: true`, listen to this event to know when your user will be navigated to the `search` step so you can close the widget. Fields: * `user_guid` (string) * `session_guid` (string) **WARNING** If you listen for this event, don't listen for any of the Primary Action events. You'll receive a double payload. ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/connected/backToSearch') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/connected/backToSearch") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Context:", event.metadata.context) } } ``` ```json theme={null} { "type": "mx/connect/connected/backToSearch", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123" } } ``` ## Connect Loaded Sent when the Connect Widget loads. It's often useful to know what “step” or view the user started on. **Recommended use:** Track the start of the user's journey. You can also use this if you intend on hiding the widget from the user until you know it's loaded. Fields: * `user_guid` (string) * `session_guid` (string) * `initial_step` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/loaded') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Initial step:', event.metadata.initial_step) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/loaded") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Initial step:", event.metadata.initial_step) } } ``` ```json theme={null} { "type": "mx/connect/loaded", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "initial_step": "search" } } ``` The `initial_step` can be: | Value | Definition | | :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- | | `connected` | The initial step when configured with `current_member_guid` and the member is in a connected state. | | `disclosure` | The initial step when configured to display the disclosure screen that shows the MX privacy policy first. This is optional and is turned off by default. | | `enterCreds` | The initial step when configured with `current_institution_guid` or `current_member_guid`, and `updated_credentials` set to `true`. | | `loginError` | The initial step when configured with `current_member_guid` and the member is in an error state. | | `mfa` | The initial step when configured with `current_member_guid` and the member has encountered multi-factor authentication. | | `search` | The default initial step. | | `verifyExistingMember` | The initial step when configured with `data_request.products` set to `account_verification`. | ## Enter Credentials Sent when a user submits credentials for a given institution for the first time. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `user_guid` (string) * `session_guid` (string) * `institution` (object) * `code` (string) * `guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/enterCredentials') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Institution:', event.metadata.institution) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/enterCredentials") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Institution:", event.metadata.institution) } } ``` ```json theme={null} { "type": "mx/connect/enterCredentials", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "institution": { "code": "mxbank", "guid": "INS-123" } } } ``` ## Initial Data Ready **DEPRECATED** This event is deprecated and should not be used in new implementations. **NOTE** This event only applies if you're using Platform API version 20250224. Triggered when some initial data you requested has aggregated and is ready for retrieval. When you receive this event, you can close the widget and retrieve some initial data to avoid making the user wait until every requested product finishes aggregating. For more details, including what initial data is sent based on the products you set, see [Accessing Priority Data](/products/connectivity/overview/intro-to-unified-product-ordering#accessing-priority-data). ```json theme={null} { "type": "mx/connect/initialDataReady", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member_guid": "MBR-123" } } ``` ## Institution Search Sent when the end user searches for an institution. This is useful in determining what users are searching for. **Recommended use:** Track this to find trends in institutions your users want to connect to. If you identify a trend, you can customize the top 10 institutions in the default institutions list. You could also create UI that calls out the FI directly and loads your users to connect to that institution directly. Fields: * `user_guid` (string) * `session_guid` (string) * `query` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/institutionSearch') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Query:', event.metadata.query) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/institutionSearch") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Query:", event.metadata.query) } } ``` ```json theme={null} { "type": "mx/connect/institutionSearch", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "query": "MX Bank" } } ``` ## Institution Selected Sent when an end user selects an institution from the institution list. **Recommended use:** Similar to the Institution Search event. Track this to find trends in institutions your users want to connect to. If you identify a trend, you can customize the top 10 institutions in the default institutions list. You could also create UI that calls out the FI directly and loads your users to connect to that institution directly. Fields: * `user_guid` (string) * `session_guid` (string) * `code` (string) * `guid` (string) * `name` (string) * `url` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/selectedInstitution') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Code:', event.metadata.code) console.log('Guid:', event.metadata.guid) console.log('Name:', event.metadata.name) console.log('Url:', event.metadata.url) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/selectedInstitution") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Code:", event.metadata.code) console.log("Guid:", event.metadata.guid) console.log("Name:", event.metadata.name) console.log("Url:", event.metadata.url) } } ``` ```json theme={null} { "type": "mx/connect/selectedInstitution", "mx": true, "metadata": { "code": "mxbank", "guid": "INS-123", "name": "MX Bank", "session_guid": "ANS-123", "url": "www.example.com", "user_guid": "USR-123" } } ``` ## Invalid Data Sent when there are no valid demand deposit (DDA) accounts on the member. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `code` (string) * `member_guid` (string) * `session_guid` (string) * `user_guid` (string) **Conditions** * `"mode": "verification"` * The member receives an error as one of the codes below. The `code` can be: | Value | Definition | | :----- | :----------------------------------------------------- | | `1000` | No demand deposit (DDA) accounts for verification job. | ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/invalidData') { console.log('Code:', event.metadata.code) console.log('Member guid:', event.metadata.member_guid) console.log('Session guid:', event.metadata.session_guid) console.log('User guid:', event.metadata.user_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/invalidData") { console.log("Code:", event.metadata.code) console.log("Member guid:", event.metadata.member_guid) console.log("Session guid:", event.metadata.session_guid) console.log("User guid:", event.metadata.user_guid) } } ``` ```json theme={null} { "type": "mx/connect/invalidData", "mx": true, "metadata": { "code": "1000", "member_guid": "MBR-123", "session_guid": "ANS-123", "user_guid": "USR-123" } } ``` ## Invalid Data, Primary Action Selected Sent when there are no valid demand deposit (DDA) accounts on the member and the end user selects **Try again** on the associated error screen. When the end user selects **Try again**, the widget will send them to the institution search screen. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `member_guid` (string) * `session_guid` (string) * `user_guid` (string) **Conditions** * `data_request.products` includes `account_verification`. * `disable_institution_search` is set to `true`. * The member doesn't have any valid DDA accounts. * The user selects **Try again** on the error screen. ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/invalidData/primaryAction') { console.log('Member guid:', event.metadata.member_guid) console.log('Session guid:', event.metadata.session_guid) console.log('User guid:', event.metadata.user_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/invalidData/primaryAction") { console.log("Member guid:", event.metadata.member_guid) console.log("Session guid:", event.metadata.session_guid) console.log("User guid:", event.metadata.user_guid) } } ``` ```json theme={null} { "type": "mx/connect/invalidData/primaryAction", "mx": true, "metadata": { "member_guid": "MBR-123", "session_guid": "ANS-123", "user_guid": "USR-123" } } ``` ## Member Connected Sent when a member has successfully connected and the data you requested in your Widget URL request has finished aggregating. **Recommended use:** Retrieve the data you requested in your Widget URL request, which has finished aggregating. If you don't want the user to acknowledge they connected to a member in our UI, you could close the widget after receiving this event and present your own success screen. Fields: * `user_guid` (string) * `session_guid` (string) * `member_guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/memberConnected') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Member guid:', event.metadata.member_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/memberConnected") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Member guid:", event.metadata.member_guid) } } ``` ```json theme={null} { "type": "mx/connect/memberConnected", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member_guid": "MBR-123" } } ``` ## Member Connected, Primary Action Selected Sent when the user selects the primary button on the connected step. **Recommended use:** If you don't want the end user to return to connect more accounts, close the widget. Fields: * `user_guid` (string) * `session_guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/connected/primaryAction') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/connected/primaryAction") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) } } ``` ```json theme={null} { "type": "mx/connect/connected/primaryAction", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123" } } ``` ## Member Connection Error Sent when a member has encountered an error state. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `user_guid` (string) * `session_guid` (string) * `member` (object) * `guid` (string) * `connection_status` (number) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/memberError') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Member guid:', event.metadata.member.guid) console.log('Connection status:', event.metadata.member.connection_status) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/memberError") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Member guid:", event.metadata.member.guid) console.log("Connection status:", event.metadata.member.connection_status) } } ``` ```json theme={null} { "type": "mx/connect/memberError", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member": { "guid": "MBR-123", "connection_status": 6 } } } ``` ## Member Create Error Sent when a member failed to get created when credentials were entered. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `user_guid` (string) * `session_guid` (string) * `institution_guid` (string) * `institution_code` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/createMemberError') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Institution guid:', event.metadata.institution_guid) console.log('Institution code:', event.metadata.institution_code) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/createMemberError") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Institution guid:", event.metadata.institution_guid) console.log("Institution code:", event.metadata.institution_code) } } ``` ```json theme={null} { "type": "mx/connect/createMemberError", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "institution_guid": "INS-123", "institution_code": "mxbank" } } ``` ## Member Deleted Sent when a member has been deleted in the widget. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `user_guid` (string) * `session_guid` (string) * `member_guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/memberDeleted') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Member guid:', event.metadata.member_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/memberDeleted") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Member guid:", event.metadata.member_guid) } } ``` ```json theme={null} { "type": "mx/connect/memberDeleted", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member_guid": "MBR-123" } } ``` ## Member Status Update Sent when a member’s connection status has changed while connecting. **Recommended use:** Useful for determining the current connection status of the member. If the status is `CONNECTED`, you can start polling to ensure that data is ready for retrieval. If the status is related to an error, you can begin a resolution flow depending on the error. Fields: * `user_guid` (string) * `session_guid` (string) * `member_guid` (string) * `connection_status` (number) **INFO** A `connection_status` of `6` (CONNECTED) doesn't mean data is available yet. To ensure that data is available, refer to the [member connected](#member-connected) event instead. ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/memberStatusUpdate') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Member guid:', event.metadata.member_guid) console.log('Connection status:', event.metadata.connection_status) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/memberStatusUpdate") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Member guid:", event.metadata.member_guid) console.log("Connection status:", event.metadata.connection_status) } } ``` ```json theme={null} { "type": "mx/connect/memberStatusUpdate", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member_guid": "MBR-123", "connection_status": 6 } } ``` ## Microdeposit Account Details Submitted Sent when the end user submits account details for a given institution for the first time and a `microdeposit` object is created on the MX system. For guidance, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). Fields: * `user_guid` (string) * `session_guid` (string) * `microdeposit_guid` (string) ```json theme={null} { "type": "mx/connect/microdeposits/detailsSubmitted", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "microdeposit_guid": "MIC-123" } } ``` ## Microdeposit Blocked Routing Number Sent when the end user submits a blocked routing number on the **Enter Details** step. For guidance, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). Fields: * `user_guid` (string) * `session_guid` (string) * `routing_number` (string) * `reason` (string). Possible values are: * `BLOCKED`: MX has blocked this routing number. Microdeposit verification can't proceed. * `CLIENT_BLOCKED`: An MX client has requested that this routing number be blocked. Microdeposit verification can't proceed. * `IAV_PREFERRED`: The institution associated with the routing number has an Instant Account Verification (IAV) connection that is preferred over microdeposit verification. The IAV flow will be suggested to the end user. ```json theme={null} { "type": "mx/connect/microdeposits/blockedRoutingNumber", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "routing_number": "123456789", # This is the user-entered routing number "reason": "BLOCKED", } } ``` ## Microdeposit Come Back, Primary Action Selected Sent when the end user selects the primary button on the **Come Back** step. This step is visible while the microdeposit is in the `REQUESTED` status. For guidance, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). Fields: * `user_guid` (string) * `session_guid` (string) * `microdeposit_guid` (string) ```json theme={null} { "type": "mx/connect/microdeposits/comeBack/primaryAction", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "microdeposit_guid": "MIC-123" } } ``` ## Microdeposit Error, Primary Action Selected Sent when the end user selects the primary button on the **Error** step. This page is visible after entering deposits and getting a `PREVENTED` status. For guidance, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). Fields: * `user_guid` (string) * `session_guid` (string) * `microdeposit_guid` (string) * `microdeposit_status` (string) ```json theme={null} { "type": "mx/connect/microdeposits/error/primaryAction", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "microdeposit_guid": "MIC-123", "microdeposit_status": "PREVENTED" } } ``` ## Microdeposit Flow Loaded Sent when the microdeposit flow is loaded in the Connect Widget. For guidance, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). Fields: * `user_guid` (string) * `session_guid` (string) * `initial_step` (string) ```json theme={null} { "type": "mx/connect/microdeposits/loaded", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "initial_step": "enterDetails" } } ``` ## Microdeposit Verified Sent when an end user successfully verifies the microdeposit amounts. For guidance, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). Fields: * `user_guid` (string) * `session_guid` (string) * `microdeposit_guid` (string) ```json theme={null} { "type": "mx/connect/microdeposits/verified", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "microdeposit_guid": "MIC-123" } } ``` ## Microdeposit Verified, Primary Action Selected Sent when the end user selects the primary button on **Verified** step. This step is visible after entering the correct deposit amounts. For guidance, see [Microdeposits Workflow in the Connect Widget](/products/connectivity/microdeposits/connect-widget). Fields: * `user_guid` (string) * `session_guid` (string) ```json theme={null} { "type": "mx/connect/microdeposits/verified/primaryAction", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123" } } ``` ## OAuth Error Sent when the user lands on the OAuth error page. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `user_guid` (string) * `session_guid` (string) * `member_guid` (optional) (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/oauthError') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Member guid:', event.metadata.member_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/oauthError") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Member guid:", event.metadata.member_guid) } } ``` ```json theme={null} { "type": "mx/connect/oauthError", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member_guid": "MBR-123" } } ``` ## OAuth Requested **NOTE** This event only applies if you embedded the widget inside a mobile app using a WebView, or using an iFrame inside a WebView. Sent when the user navigates to the OAuth provider's site. Note that the redirect doesn't happen in WebViews. The native app will need to use this event to send the user to the URL contained in the metadata. The URL given in the payload will always be an MX URL. The user will be routed to us first (for example, `mx://connect/oauthRequested?metadata={...JSON encoded payload ...}`), then to the provider. **Recommended use:** Only use if you embedded the widget inside a mobile app using a WebView, or using an iFrame inside a WebView. Fields: * `user_guid` (string) * `session_guid` (string) * `url` (string) * `member_guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/oauthRequested') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Url:', event.metadata.url) console.log('Member guid:', event.metadata.member_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/oauthRequested") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Url:", event.metadata.url) console.log("Member guid:", event.metadata.member_guid) } } ``` ```json theme={null} { "type": "mx/connect/oauthRequested", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "url": "https://something.com", "member_guid": "MBR-123" } } ``` ## Step Change **WARNING** Connect flows and steps are constantly being evaluated, updated, and optimized. The steps listed below are subject to change without notice. Sent when the end user changes from one “step” to another. **Recommended use:** Intended for analytics tracking purposes only, and not for controlling or altering the user's experience. Fields: * `user_guid` (string) * `session_guid` (string) * `previous` (string) * `current` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/stepChange') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Previous:', event.metadata.previous) console.log('Current:', event.metadata.current) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/stepChange") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Previous:", event.metadata.previous) console.log("Current:", event.metadata.current) } } ``` ```json theme={null} { "type": "mx/connect/stepChange", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "previous": "search", "current": "enterCreds" } } ``` Possible step values for `previous` and `current` can be: | Current/Previous Value | Definition | | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | `addManualAccount` | Where the user creates manual accounts. Manual accounts are not currently offered in the Platform API; partners should not expect to see this value. | | `connected` | Where the user lands when they have successfully connected. | | `connecting` | Where the user goes while the connection is being attempted. | | `disclosure` | Where the user reads the MX privacy policy and agrees by selecting Continue. This is optional and is turned off by default. | | `enterCreds` | Where the user enters credentials for a particular institution. | | `error` | Where the user lands when the member create was unsuccessful due to user or system error. | | `existingMember` | Where the user lands if they are trying to add a member they have previously added. | | `loginError` | Where the user lands when they have unsuccessfully connected due to user or system error. | | `mfa` | Where the user enters in MFA responses. | | `oauth` | Where the user goes instead of enter credentials if the institution and client supports oauth. | | `search` | Where the user searches for institutions. | | `timeOut` | When the user has been connecting for more than 60 seconds without any updates to the member, if the member's `connection_status` isn't `PENDING`. | | `verifyExistingMember` | Where the user can verify existing members when `data_request.products` includes `account_verification`. | ## Submit MFA Sent when a user submits an MFA answer. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `user_guid` (string) * `session_guid` (string) * `member_guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/submitMFA') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Member guid:', event.metadata.member_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/submitMFA") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Member guid:", event.metadata.member_guid) } } ``` ```json theme={null} { "type": "mx/connect/submitMFA", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member_guid": "MBR-123" } } ``` ## Update Credentials Sent when a user submits credentials while trying to update their existing credentials. **Recommended use:** Use as needed for your implementation, or for informational and tracking purposes. Fields: * `user_guid` (string) * `session_guid` (string) * `member_guid` (string) * `institution` (object) * `code` (string) * `guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/connect/updateCredentials') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) console.log('Member guid:', event.metadata.member_guid) console.log('Institution:', event.metadata.institution) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/connect/updateCredentials") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) console.log("Member guid:", event.metadata.member_guid) console.log("Institution:", event.metadata.institution) } } ``` ```json theme={null} { "type": "mx/connect/updateCredentials", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123", "member_guid": "MBR-123", "institution": { "code": "mxbank", "guid": "INS-123" } } } ``` ## Widget Load Sent when the app is loaded. **INFO** This event applies to **all** MX widgets. For the Connect Widget specifically, there is a separate event—Connect Loaded—that's sent when the widget loads and also includes the initial view the user started on. For more details, see [Connect Loaded](#connect-loaded). Only contains `type` (string) and `mx` (boolean). ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/load') { console.log('Type:', event.type) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/load") { console.log("Type:", event.type) } } ``` ```js theme={null} { "type": "mx/load", "mx": true } ``` ## Widget Ping Used to keep the widget session alive. See [Handling Session Timeouts](/connect#handling-session-timeouts) for more info. Fields: * `user_guid` (string) * `session_guid` (string) ```js theme={null} const widget = new ConnectWidget({ containerSelector: '#mx-widget-container', url: widgetUrl, callbacks: { onEvent: (event) => { if (event.type === 'mx/ping') { console.log('User guid:', event.metadata.user_guid) console.log('Session guid:', event.metadata.session_guid) } } } }) ``` ```js theme={null} import { ConnectWidget, Event } from "@mxenabled/react-native-connect-widget-sdk" const handleEvent = (event: Event) => { if (event.type === "mx/ping") { console.log("User guid:", event.metadata.user_guid) console.log("Session guid:", event.metadata.session_guid) } } ``` ```js theme={null} { "type": "mx/ping", "mx": true, "metadata": { "user_guid": "USR-123", "session_guid": "ANS-123" } } ```