Introduction

The MX Widget Software Development Kit (SDK) simplifies and streamlines the integration process to set up and use MX widgets. The SDK provides an improved interface to post messages and OAuth. The Widget SDK is the new preferred method to implement and load MX’s widgets in the relevant mode and configuration. Widget SDKs are currently available for installation in React Native and Web.

Refer to Github for more details on MX’s repositories.

React Native Widget SDK

The React Native Widget SDK simplifies and streamlines the integration process to set up and use MX widgets. Follow the instructions below to import and load MX widgets in the React Native application and configure them to your specific needs.

To access the React Native Widget SDK in GitHub, click the React Native Widget SDK button.

React Native Widget Components

The React Native SDK exposes the following available components:

• AccountsWidget
• BudgetsWidget
• ConnectVerificationWidget
• ConnectWidget
• ConnectionsWidget
• DebtsWidget
• FinstrongWidget
• GoalsWidget
• HelpWidget
• MasterWidget
• MiniBudgetsWidget
• MiniFinstrongWidget
• MiniPulseCarouselWidget
• MiniSpendingWidget
• PulseWidget
• SettingsWidget
• SpendingWidget
• TransactionsWidget
• TrendsWidget

React Native Widget SDK Getting Started Guide

The following guide provides instructions to import and load MX widgets in a React Native application by including the react-native-widget-sdk into your development project.

Prerequisites

Sign up for a developer account at the developer portal. A developer account can be obtained by signing up at the Client Dashboard.

Outline of Steps

1. Install and setup the SDK with npm or yarn.

2. Generate an authenticated widget URL.

3. Import the widget into your project, providing it with the needed configuration object.

4. Interact with the widget through PostMessage events.

1. Install the React Native Widget SDK

Steps:

1. Open a terminal.
2. Run the commands below at the root of your project to install and setup the SDK.

Using npm:

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

Using yarn:

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

3. Once installed, run the command below to finish setting up the SDK’s required dependencies:

1
npx mx-widget-sdk-setup

2. Generate the Widget URL

There are two methods to generate the widget URL: using the request a widget URL endpoint or using a proxy server.

2a. Configure the Widget using the Widget URL Request

Refer to our authentication and Widget URL documentation for instructions and information related to making a URL request. If loading the Connect Widget, follow the instructions located in Connect Widget URL documentation. The URL should be passed to a Widget component via the url prop.

2b. Configure the Widget using a Proxy Server

The SDK also has the option of making the request on your behalf to your backend service that can make requests to the MX API. If used, the proxy URL should be passed to a Widget component via the proxy prop.

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

Connect Widget Configuration

When you are not using the proxy setting, you must pass the widget configuration in the request that generates the URL. However, when using the proxy setting with the Connect Widget, those configuration settings may be passed directly to the widget component.

The following are configuration options that can be passed to the MX endpoint.

3. Import the SDK and Render a Widget

Once the steps above have been completed, import components from the @mxenabled/react-native-widget-sdk package and render them in your application.

1
2
3
4
5
6
7
8
9
10
11
12
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/..."
    />
  )
}

4. Interact with the Widget

You can listen to PostMessage events by passing callback props in the widget component. The prop names follow the below naming scheme.

For example, the mx/connect/selectInstitution event is made available via onSelectInstitution in the ConnectWidget component. Refer to this document for a list of events and their payloads.

1
2
3
4
<ConnectWidget
  onMessage={(request) => console.log(`Message: ${request.url}`)}
  onSelectedInstitution={(payload) => console.log(`Selecting ${payload.name}`)}
/>

React Native Widget Props

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

OAuth Redirects in Connect

To properly handle OAuth redirects from the Connect Widget back to your application, you will need to do three things:

1. Update your application and enable deeplinking from native code into the React Native layer. See Linking for instructions on how to do that.

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

1
<ConnectWidget uiMessageWebviewUrlScheme="sampleScheme" />

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

React Native Troubleshooting

PostMessages not working

Check the following items if widget PostMessage callbacks are not being triggered in your application.

• Ensure your URL request is correctly configured for the React Native SDK:

  • ui_message_version should be set to 4.
  • is_mobile_webview should be set to true.

• Ensure you are using the corresponding widget component for the widget_type used in the URL request. For example, if you set widget_type to connect_widget, then you should use the ConnectWidget component.

Web Widget SDK

The Web Widget SDK simplifies and streamlines the integration process to set up and use MX widgets. Follow the instructions below to import and load MX widgets in web applications and configure them to your specific needs.

To access the Web Widget SDK in GitHub, click the Web Widget SDK button.

Web Widget Classes

The Web Widget SDK exposes the following available classes:

• AccountsWidget
• BudgetsWidget
• ConnectAggregationWidget
• ConnectVerificationWidget
• ConnectWidget
• ConnectionsWidget
• DebtsWidget
• FinstrongWidget
• GoalsWidget
• HelpWidget
• MasterWidget
• MiniBudgetsWidget
• MiniFinstrongWidget
• MiniPulseCarouselWidget
• MiniSpendingWidget
• PulseWidget
• SettingsWidget
• SpendingWidget
• TransactionsWidget
• TrendsWidget

Web Widget SDK Getting Started Guide

The following guide provides instructions to import and load MX widgets in the web application by including the web-widget-sdk into your development project.

Prerequisites

Sign up for a developer account at the developer portal. A developer account can be obtained by signing up at the Client Dashboard.

Outline of Steps

1. Install and setup the SDK with npm or yarn.

2. Incorporate the SDK into your application.

3. Generate an authenticated widget URL.

4. Interact with the widget through PostMessage events.

5. Mount and unmount the widget.

1. Install the Web Widget SDK

Steps:

1. Open a terminal.

2. Run the command below at the root of your project to install and setup the SDK.

Using npm:

1
npm install --save @mxenabled/web-widget-sdk

Using yarn:

1
yarn add @mxenabled/web-widget-sdk

2. Incorporate the Web Widget SDK

The Widget SDK provides multiple modules that you can import and use in your application. There is currently a CommonJS module, an ES module, an AMD module, and a UMD module that you can use depending on your build process.

CommonJS module

A CommonJS module is exported by this package and available by requiring @mxenabled/web-widget-sdk. Require this module and build your project with a build tool that supports CommonJS modules (such as browserify).

1
2
3
4
5
6
const widgetSdk = require("@mxenabled/web-widget-sdk")
const widget = new widgetSdk.ConnectWidget({
  container: "<CONTAINER SELECTOR>",
  url: "<Widget URL>"
  // additional widget options
})

ES module

An ES module is exported by this package and available by importing @mxenabled/web-widget-sdk. Import this module and build your project with a build tool that supports ES modules (such as webpack).

1
2
3
4
5
6
import * as widgetSdk from "@mxenabled/web-widget-sdk"
const widget = new widgetSdk.ConnectWidget({
  container: "<CONTAINER SELECTOR>",
  url: "<Widget URL>"
  // additional widget options
})

AMD module

The AMD module can be found in node_modules/@mxenabled/web-widget-sdk/dist/amd/index.js. To serve this file in your application, you will have to host it yourself. Transfer this file into any location where it can be made publicly available. Once the file is available, you can import and use it.

1
2
3
4
5
6
7
8
9
10
11
12
<div id="container"></div>

<script src="https://requirejs.org/docs/release/2.3.6/minified/require.js"></script>
<script>
requirejs(["node_modules/@mxenabled/web-widget-sdk/dist/amd/index.js"], function (widgetSdk) {
  const widget = new widgetSdk.ConnectWidget({
    container: "#container",
    url: "<Widget URL>"
    // additional widget options
  })
})
</script>

UMD module

The UMD module can be found in node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js. To serve this file in your application, you will have to host it yourself. Transfer this file into any location where it can be made publicly available. Once the file is available, you can import and use it.

1
2
3
4
5
6
7
8
9
10
<div id="container"></div>

<script src="node_modules/@mxenabled/web-widget-sdk/dist/umd/index.js"></script>
<script>
const widget = new widgetSdk.ConnectWidget({
  container: "#container",
  url: "<Widget URL>"
  // additional widget options
})
</script>

3. Generate the Widget URL

There are two methods to generate the widget URL: using the request a widget URL endpoint or using a proxy server.

3a. Configure the Widget using the Widget URL Request

Refer to our authentication and Widget URL documentation for instructions and information related to making a URL request. If loading the Connect Widget, follow the instructions located in the Connect Widget URL documentation. The URL should be passed to a Widget class via the url option.

1
2
3
4
const options = {
  container: "#widget",
  url: "https://int-widgets.moneydesktop.com/md/connect/..."
}

3b. Configure the Widget using a Proxy Server

The SDK also has the option of making the widget URL request on your behalf to your backend service that can make requests to the MX API. If used, the proxy URL should be passed to a widget class via the proxy option.

1
2
3
4
5
6
const options = {
  container: "#widget",
  proxy: "https://server.com/mx-sso-proxy",
  colorScheme: "dark",
  disableInstitutionSearch: true
}

Connect Widget Configuration

When you are not using the proxy setting, you must pass the widget configuration in the widget URL request that generates the widget URL. However, when using the proxy setting with the Connect Widget, those configuration settings may be passed directly to the widget class.

4. Interact with the Widget

You can listen to PostMessage events by passing callback functions in the widget options object to the class. The option names follow this naming scheme.

For example, the mx/connect/selectInstitution event is made available via onSelectInstitution in the ConnectWidget class. Refer to this document for a list of events and their payloads.

5. Mount and Unmount the Widget

When you instantiate a widget with options, it will mount itself in the DOM and set up various event listeners. You’ll need to call the unmount method when closing the widget and before creating a new instance.

1
2
3
4
5
6
7
8
9
10
11
const options = {
  container: "#widget",
  url: "https://int-widgets.moneydesktop.com/md/connect/...."
}

// Calling `new sdk.ConnectWidget(...)` here will mount the widget in the DOM
const widget = new widgetSdk.ConnectWidget(options)

// When you are ready to close the widget, you'll want to call `unmount`. This
// will remove the element and any event listeners added.
widget.unmount()

Widget Options

You can configure the state and behavior of the widget with the following class options.

Web Troubleshooting

PostMessages not working

Check the following items if widget PostMessage callbacks are not being triggered in your application.

• Ensure your widget URL request is correctly configured for the Web SDK:
  • ui_message_version should be set to 4.
  • is_mobile_webview should be set to false.
• Ensure you are using the corresponding widget class for the widget_type used in the widget URL request. For example, if you set widget_type to connect_widget, then you should use the ConnectWidget class.
• Ensure you are serving your application’s HTML from a web server and not loading it from your file system.
• Ensure your application’s Referrer-Policy is one that allows origin information to be passed to the widget. We recommend using the default, which is strict-origin-when-cross-origin.