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

# Embed Widget Using React Native SDK

> Install and configure the React Native Widget SDK to load the Connect Widget in your mobile application

The React Native SDK simplifies Connect Widget integrations.

<Warning>
  **LEGACY SDK**

  This page documents the legacy React Native SDK. For new integrations, see [React Native SDK](/connect/guides/react-native-sdk).
</Warning>

After completing this guide, your application will display the Connect Widget using the React Native SDK, available on [GitHub](https://github.com/mxenabled/react-native-sdk).

<Note>
  **PREREQUISITES**

  Sign up for a developer account on the [Client Dashboard](https://dashboard.mx.com/sign_in).
</Note>

## 1. Install the SDK

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

<Tabs>
  <Tab title="npm">
    ```shell theme={null}
    npm install --save @mxenabled/react-native-widget-sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```shell theme={null}
    yarn add @mxenabled/react-native-widget-sdk
    ```
  </Tab>
</Tabs>

## 2. Generate the Widget URL

There are two options to generate the widget URL:

* Option A: [Using a Platform API endpoint](#platform-api)
* Option B: [Using a proxy server](#proxy-server)

### a. Platform API

Use the [Request Widget URL](/api-reference/platform-api/reference/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.

<Tabs>
  <Tab title="Request">
    ```shell theme={null}
    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"
        }
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "widget_url": {
        "type": "connect_widget",
        "url": "https://int-widgets.moneydesktop.com/md/connect/yxcdk7f1nb99jwApp34lA24m0AZ8rzprgmw17gm8z8h2AzjyAnd1rj42qfv42r3xnn07Amfwlg3j09hwp8bkq8tc5z21j33xjggmp2qtlpkz2v4gywfhfn31l44tx2w91bfc2thc58j4syqp0hgxcyvA4g7754hk7gjc56kt7tc36s45mmkdz2jqqqydspytmtr3dAb9jh6fkb24f3zkfpdjj0v77f0vmrtzvzxkmxz7dklsq8gd0gstkbhlw5bgpgc3m9mAtpAcr2w15gwy5xc4blgxppl42Avnm63291z3cyp0wm3lqgmvgzdAddct423gAdqxdlfx5d4mvc0ck2gt7ktqgks4vxq1pAy5",
        "user_id": "u-2345"
      }
    }
    ```
  </Tab>
</Tabs>

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

<Accordion title="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](/connect/widget-events#back-to-search) 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](/connect/#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.                                                                                                                                |
</Accordion>

```jsx Proxy theme={null}
<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.

```jsx theme={null}
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/..."
    />
  )
}
```

<Check>
  **SUCCESS**

  You've set up the SDK and embedded the Connect Widget!
</Check>

## 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](https://reactnative.dev/docs/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](https://reactnative.dev/docs/linking) for instructions.
2. Ensure your application has a scheme. You can install and use the [URI scheme](https://www.npmjs.com/package/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).

```jsx Scheme theme={null}
<ConnectWidget uiMessageWebviewUrlScheme="sampleScheme" />
```

<Warning>
  **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.

  ```jsx theme={null}
  <ConnectWidget clientRedirectUrl={Linking.createURL("/oauth_complete")} />
  ```
</Warning>

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

```js theme={null}
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](/products/connectivity/overview/connectivity-integration-guides/connect-widget-flow).