@mxenabled/web-widget-sdk

MX Web Widget SDK

Introduction

The purpose of this project is to help simplify your integration experience. Giving you as few steps as possible to get up and running with an MX React Native widget.

After following the Getting Started instructions below, you will be able to import and load MX widgets in your React Native application, and configure them for your specific needs.

Getting Started

Please refer to the offical MX Docs for an in-depth explanation of the MX platform. The general outline for incorporating the web-widget-sdk into your project is as follow:

• Signup for a developer account at the developer portal.
• Install and setup the SDK via npm or yarn.
• Generate an authenticated SSO widget url.
• Import the widget into your project providing it with the needed configuration object.

Aquire your developer account

A developer account can be obtained by signing up on our Client Portal site.

Installing the SDK

TODO: Install via es6 module system instructions. TODO: Install via AMD module system instructions.

Generating your Widget SSO URL

See SSO Widget URL documentation for instructions. If loading the Connect Widget, follow the instructions located in Connect SSO Widget URL documentation. The SSO URL should be passed to a Widget class via the url option.

Proxy server

The SDK also has the option of making the SSO request on your behalf to your backend service that is able to make requests to our API. If used, the proxy URL should passed to a Widget class via the proxy option.

Importing the SDK into your project and rendering a widget using modules with Asynchronous Module Definition (AMD)

Once the steps above have been completed, you will be able to import the @mxenabled/web-widget-sdk package and render them in your application:

<script src="mx-web-widget-sdk-amd.js"></script>

<script>
  requirejs(["@mxenabled/web-widget-sdk"], function (sdk) {
    const options = {
      widgetContainer: "#widget",
      proxy: "http://localhost:8089/{widget_type}/{user_guid}",
      onMessage: (event) => {
        logEvent(event.data)
      },
    }

    const widget = new sdk.ConnectWidget(options)
  })
</script>

Interacting with the widget

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

• For widget events: on<event name>,
• For entity events: on<entity><action>

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.

Widget options

You can configure the state and behaviour of the widget with the following class options:

• language: Load the widget in the specified language. Defaults to en-US. See language options for additional information.
• proxy: SSO proxy server URL.
• style: Styles applied to the view containing the widget.
• iframeTitle: Allows for the title attribute of the iframe to be set.
• url: Widget SSO URL. See Generating your Widget SSO URL for additional information. This prop is required.

Connect specific options

• colorScheme: Load the widget in the specified colorScheme; 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 to a specific member that contains an error or requires MFA from the most recent job. currentMemberGuid takes precedence over currentInstitutionCode.
• disableInstitutionSearch: When set to true, the institution search feature will be disabled and end users will not be able to navigate to it. Must be used with currentInstitutionCode, currentInstituionGuid, or currentMemberGuid.
• includeTransactions: When set to false while creating or updating a member, transaction data will not be automatically aggregated. Future manual or background aggregations will not be affected. Defaults to true.
• uiMessageWebviewUrlScheme: Used as the scheme that MX will redirect to at the end of OAuth. This must be a scheme that your application responds to. See OAuth redirects for additional information.
• updateCredentials: Loads widget to the update credential view of a current member. Optionally used with currentMemberGuid. This option should be used sparingly. The best practice is to use currentMemberGuid and let the widget resolve the issue.
• waitForFullAggregation: Loads Connect, but forces the widget to wait until any aggregation-type process is complete in order to fire a member connected postMessage. This allows clients to have transactional data by the time the widget is closed.

Available widget classes

This SDK exposes the following classes:

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

---