Embed Widget using React Native SDK

The React Native SDK simplifies Connect Widget integrations.

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

Prerequisites

Sign up for a developer account on the Client Dashboard.

Step 1

Install the SDK

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

npm

_10

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

yarn

_10

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

Step 2

Generate the Widget URL

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

Language:shell

_10

curl -L -X POST 'https://int-api.mx.com/users/{user_guid}/widget_urls' \

_10

-H 'Content-Type: application/json' \

_10

-H 'Accept: application/json' \

_10

-H 'Accept-Version: v20250224' \

_10

-H 'Authorization: Basic BASE_64_ENCODING_OF{client_id:api_key}' \

_10

--data-raw '{

_10

"widget_url": {

_10

"widget_type":"connect_widget"

_10

}

_10

}'

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

Language:jsx

_10

<ConnectWidget

_10

proxy={"https://server.com/mx-sso-proxy"}

_10

colorScheme={"dark"}

_10

disableInstitutionSearch={true}

_10

/>

Step 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.

_12

import React from "react"

_12

_12

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

_12

_12

export default function App() {

_12

return (

_12

<ConnectWidget

_12

onLoaded={() => console.log("Connect Widget Loaded")}

_12

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

_12

/>

_12

)

_12

}

success

You'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:

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

Language:jsx

_10

<ConnectWidget uiMessageWebviewUrlScheme="sampleScheme" />

warning

Expo 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.

_10

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

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 false
• 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.