Embed Widget Using React Native SDK

The React Native SDK simplifies Connect Widget integrations.

LEGACY SDKThis page documents the legacy React Native SDK. For new integrations, see React Native SDK.

After completing this guide, your application will display the Connect Widget using the React Native SDK, available on GitHub.

PREREQUISITESSign up for a developer account on the Client Dashboard.

1. Install the SDK

Install the SDK at the root of your project using your preferred package manager.

npm
yarn

npm install --save @mxenabled/react-native-widget-sdk

yarn add @mxenabled/react-native-widget-sdk

There are two options to generate the widget URL:

Option A: Using a Platform API endpoint
Option B: Using a proxy server

a. Platform API

Use the Request Widget URL endpoint to get a URL. Note that this url expires after ten minutes or upon first use, so you may need to request it again while following this guide.

Request
Response

curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Accept-Version: v20250224' \
-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \
--data-raw '{
  "widget_url": {
    "widget_type":"connect_widget"
    }
  }'

{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
    "user_id": "u-2345"
  }
}

b. Proxy Server

The SDK can make requests on your behalf to your backend service that calls the Platform API. Pass the proxy URL to a widget component via the proxy prop. When using a proxy server, pass the widget’s configurations directly to the widget component.

Configurations List

Configuration option	Description
`colorScheme`	Load the widget with the specified `color_scheme`; options are `light` and `dark`. Defaults to `light`.
`currentInstitutionCode`	Load the widget into the credential view for the specified institution.
`currentInstitutionGuid`	Load the widget into the credential view for the specified institution.
`currentMemberGuid`	Load the widget into a specific member that contains an error or requires multifactor authentication. The widget will determine the best view to load based on the member’s current state. `current_member_guid` takes precedence over `current_institution_code` and `current_institution_guid`.
`disableInstitutionSearch`	This determines whether the institution search is skipped within the Connect Widget. This option must be used with `current_institution_code`, `current_instituion_guid`, or `current_member_guid`. You must listen to the backToSearch postMessages to intercept the user navigating back to search during the flow. Defaults to `false`.
`includeTransactions`	This determines whether transaction data are retrieved. Defaults to `true` in aggregation mode and `false` in verification mode. This can be set in either `aggregation` or `verification` mode. This option does not affect future foreground or background aggregations.
`language`	Load the widget in the specified language. Defaults to `en-US`. For more info, Language Support.
`uiMessageWebviewUrlScheme`	This is a client-defined scheme used in OAuth redirects in WebViews; also used in URL updates when these replace postMessages in WebViews. Defaults to `mx`.
`updateCredentials`	Load the widget into a view that allows them to update the current member. Optionally used with `current_member_guid`. This option should be used sparingly. The best practice is to use `current_member_guid` and let the widget resolve the issue.

Proxy

<ConnectWidget
  proxy={"https://server.com/mx-sso-proxy"}
  colorScheme={"dark"}
  disableInstitutionSearch={true}
/>

Now that you can generate a widget URL, import components from @mxenabled/react-native-widget-sdk and render them in your application.

import React from "react"

import { ConnectWidget } from "@mxenabled/react-native-widget-sdk"

export default function App() {
  return (
    <ConnectWidget
      onLoaded={() => console.log("Connect Widget Loaded")}
      url="https://widgets.moneydesktop.com/md/connect/..."
    />
  )
}

SUCCESSYou’ve set up the SDK and embedded the Connect Widget!

Props

You can configure the state and behavior of a widget with the following component props:

Component prop	Description
`proxy`	Proxy server URL.
`style`	Styles applied to the view containing the widget. See React Native’s style documentation.
`url`	Widget URL. This prop is required.

OAuth Redirects

To properly handle OAuth redirects from the Connect Widget back to your application when using the React Native SDK, you need to:

Update your application and enable deeplinking from native code into the React Native layer. See Linking for instructions.
Ensure your application has a scheme. You can install and use the URI scheme package to manage your application’s schemes.
Provide your application’s scheme to the widget component with the uiMessageWebviewUrlScheme prop. Expo applications that are not deployed as standalone applications should use clientRedirectUrl instead (see note below).

Scheme

<ConnectWidget uiMessageWebviewUrlScheme="sampleScheme" />

WARNINGExpo applications: Expo applications rely on Expo’s own application scheme. Expo users need to use the clientRedirectUrl prop instead of uiMessageWebviewUrlScheme. Note that this does not apply to standalone Expo applications. If your application is standalone, continue to use the uiMessageWebviewUrlScheme prop.clientRedirectUrl works similarly to uiMessageWebviewUrlScheme, except you need to pass in the full URL to your Expo application and include /oauth_complete at the end of the URL path for the Widget SDK to properly detect the linking event. You can use Expo’s Linking.createURL method to create the URL.

<ConnectWidget clientRedirectUrl={Linking.createURL("/oauth_complete")} />

Handling Events

If you’re using the React Native SDK, you’ll listen for widget events by passing callback props in the widget component. The prop names follow the naming scheme below.

Event	Prop
Widget	`on<event name>`
Entity	`on<entity><action>`

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.

import { ConnectWidget } from "@mxenabled/react-native-widget-sdk"

<ConnectWidget
  url="https://widgets.moneydesktop.com/md/connect/..."

  onBackToSearch={(payload) => {
    console.log(`User guid: ${payload.user_guid}`)
    console.log(`Session guid: ${payload.session_guid}`)
    console.log(`Context: ${payload.context}`)
  }
/>

Troubleshooting

If widget events aren’t triggered, check the following:

Ensure your widget URL request is correctly configured for the React Native SDK:
- ui_message_version is set to 4
- is_mobile_webview is set to true
Ensure you use the corresponding widget component for the widget_type in the widget URL request. For example, if you set widget_type to connect_widget, use the ConnectWidget component.

Next Steps

Now that the widget displays in your application, you’ll build additional flows, specify the data you want to retrieve when a user connects to their financial institution, handle events the widget sends, and more. See Integrate using MX’s Connect Widget.

Legacy Connectivity Guides

Embed Widget Using React Native SDK

1. Install the SDK

2. Generate the Widget URL

a. Platform API

b. Proxy Server

3. Import the SDK and Render the Widget

Props

OAuth Redirects

Handling Events

Troubleshooting

Next Steps

​1. Install the SDK

​2. Generate the Widget URL

​a. Platform API

​b. Proxy Server

​3. Import the SDK and Render the Widget

​Props

​OAuth Redirects

​Handling Events

​Troubleshooting

​Next Steps

1. Install the SDK

2. Generate the Widget URL

a. Platform API

b. Proxy Server

3. Import the SDK and Render the Widget

Props

OAuth Redirects

Handling Events

Troubleshooting

Next Steps