Skip to main content
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 install --save @mxenabled/react-native-widget-sdk

​
2. Generate the Widget URL

There are two options to generate the widget URL:

​
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. 
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"
    }
  }'

​
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.
Configuration optionDescription
colorSchemeLoad the widget with the specified color_scheme; options are light and dark. Defaults to light.
currentInstitutionCodeLoad the widget into the credential view for the specified institution.
currentInstitutionGuidLoad the widget into the credential view for the specified institution.
currentMemberGuidLoad 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.
disableInstitutionSearchThis 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.
includeTransactionsThis 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.
languageLoad the widget in the specified language. Defaults to en-US. For more info, Language Support.
uiMessageWebviewUrlSchemeThis 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.
updateCredentialsLoad 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}
/>

​
3. Import the SDK and Render the Widget

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 propDescription
proxyProxy server URL.
styleStyles applied to the view containing the widget. See React Native’s style documentation.
urlWidget 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:
  1. Update your application and enable deeplinking from native code into the React Native layer. See Linking for instructions.
  2. Ensure your application has a scheme. You can install and use the URI scheme package to manage your application’s schemes.
  3. 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.
EventProp
Widgeton<event name>
Entityon<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.