Skip to main content

The Connect Widget

Connect is a ready-made and embeddable application that allows you to quickly add members to Atrium and navigate the complex aggregation process. It searches for institutions, creates new members, gathers credentials, prompts for MFA, resolves errors, and can start verification and aggregation jobs.

You can use Connect by embedding it in a website with an iframe or a mobile application with a WebView.

Get a Connect Widget URL​

To get started with the Connect Widget, you will first need to create a user and then get a widget URL by making a POST request to /users/{user_guid}/connect_widget_url. You can also use one of our wrapper libraries to make this request.

Configuration and Integration​

For complete information on correctly configuring and integrating the Connect Widget into your website or app, please see our comprehensive Connect reference. Examples in this reference use the Platform API, but all configuration options and details in the integration guides apply to Connect in the Atrium API as well.

Embedding in Webviews​

Because of the technical limitations of WebView-based implementations, an alternative to standard postMessages is required. If Connect is configured with is_mobile_webview set to true, we will use navigation events with window.location = url instead of window.postMessage(message)

ui_message_webview_url_scheme will be atrium:// by default.

warning

Your app will need to prevent all navigation events to ui_message_webview_url_scheme:// and atrium:// so the WebView doesn't lose the Connect session.

Example navigation event schema

{ui_message_webview_url_scheme}://{some/path}?metadata={jsonString}

Request
Language:shell

_14
# Suggested base configuration for WebViews.
_14
curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
_14
-H 'Accept: application/vnd.mx.atrium.v1+json' \
_14
-H 'Content-Type: application/json' \
_14
-H 'MX-API-Key: {mx_api_key}' \
_14
-H 'MX-Client-ID: {mx_client_id}' \
_14
-d '{
_14
"is_mobile_webview": true,
_14
"ui_message_version": 4,
_14
"ui_message_webview_url_scheme": "yourAppScheme"
_14
}'
_14
# Possible navigation events based on the config above:
_14
# `atrium://load`
_14
# `yourAppScheme://connect/institutionSearch?metadata={...json...}

Example URL capture

Language:java

_23
public class MainActivity extends AppCompatActivity {
_23
private WebView webView = null;
_23
@Override
_23
protected void onCreate(Bundle savedInstanceState) {
_23
webView = (WebView) findViewById(R.id.webview);
_23
webView.setWebViewClient(new AtriumWebViewClient());
_23
webView.getSettings().setDomStorageEnabled(true);
_23
webView.getSettings().setJavaScriptEnabled(true);
_23
}
_23
private class AtriumWebViewClient extends WebViewClient {
_23
@Override
_23
public boolean shouldOverrideUrlLoading(WebView view, String url) {
_23
if (url.equals("atrium://mxConnectLoaded")) {
_23
//Take action here.
_23
return true;
_23
} else if (url.startsWith("atrium://memberAdded")) {
_23
//Grab member guid and take action here.
_23
return true;
_23
}
_23
return false;
_23
}
_23
}
_23
}

Using OAuth in Connect with WebViews​

info

All new clients making use of WebViews will need to use the OAuth methods described here. Existing clients will need to adjust their implementations.

There are three configuration options WebViews will need in order to have the optimal OAuth flow:

  • is_mobile_webview: true — Allows the widget to know if it is in a WebView context.
  • ui_message_version: 4 — Allows the widget to send new postMessage events.
  • ui_message_webview_url_scheme: <your app> — Determines message scheme; this is is used by MX to redirect the user back to the client app in mobile contexts.

Example request

Request
Language:shell

_10
curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/connect_widget_url' \
_10
-H 'Accept: application/vnd.mx.atrium.v1+json' \
_10
-H 'Content-Type: application/json' \
_10
-H 'MX-API-Key: {mx_api_key}' \
_10
-H 'MX-Client-ID: {mx_client_id}'
_10
-d '{ "is_mobile_webview": true, "ui_message_version": 4, "ui_message_webview_url_scheme": "{app scheme}" }'

Redirecting the User​

Since the MX WebView can't reliably send the user from the app to the OAuth provider's site in a native browser, the containing iOS or Android app will need to. To facilitate this, your app will need to react to the connect/oauthRequested postMessage request:

<ui_message_webview_url_scheme>://connect/oauthRequested?metadata=...

The OAuth URL is inside of the metadata query parameter under the url key.

Example redirect

Language:java

_39
/**
_39
* This Client will capture urls from MX and cancel them. It will specifically
_39
* handle the oauthRequested URL. You will want to set this client as your
_39
* WebView's client or add this functionality to your own.
_39
*/
_39
public class MXWebViewClient extends WebViewClient {
_39
private Activity activity;
_39
_39
public MXWebViewClient(Activity mainActivity) {
_39
activity = mainActivity;
_39
}
_39
_39
@Override
_39
public boolean shouldOverrideUrlLoading(WebView view, String url) {
_39
// Ensure you are looking for schemes from both 'mx', 'atrium' and whatever you configured
_39
// ui_message_webview_url_scheme to be. In this example, it was 'appscheme'.
_39
boolean isFromMX = url.startsWith("mx://") || url.startsWith("atrium://") || url.startsWith("appscheme://");
_39
_39
if (isFromMX) {
_39
try {
_39
Uri mxURI = Uri.parse(url);
_39
_39
// Handle the oauth url redirect. Send the user to the URL given.
_39
if (mxURI.getPath().equals("/oauthRequested")) {
_39
JSONObject mxMetaData = new JSONObject(mxURI.getQueryParameter("metadata"));
_39
String oauthURL = mxMetaData.getString("url");
_39
Uri oauthPage = Uri.parse(oauthURL);
_39
Intent intent = new Intent(Intent.ACTION_VIEW, oauthPage);
_39
activity.startActivity(intent);
_39
}
_39
} catch (Exception err) {
_39
Log.e("sb: Error creating URI", err.getMessage());
_39
}
_39
return true;
_39
}
_39
_39
return false;
_39
}
_39
}

Getting Back To Your App​

Once the user completes the OAuth process, MX will send the user back to the client app via a URL scheme like so:

<ui_message_webview_url_scheme>://oauth_complete?status=<success|error>&member_guid=<guid>

This part is optional for OAuth, but highly recommended. If this is not set, the user will end on an MX page with a success or error message and will have to navigate back to your app manually. Make sure to pick a scheme that your app can respond to.

On this page