Introduction

This guide covers embedding the Connect Widget in a native app via a WebView using our demo apps.

There may be other ways to do this, but we recommend the integrations discussed here; they are the most common approaches. We’ll also go over some best practices.

While working through these guides, it’s also a good idea to follow along using the demos apps:

1. Get a widget URL

The first thing you’ll need to do is request a widget URL. There are all sorts of ways to configure the Connect Widget using this endpoint, but with WebViews, it is particularly important to get the right options. You’ll need to use is_mobile_webview, ui_message_version, and client_redirect_url. To see all the configuration options look at the request widget URL endpoint in the Platform API.

is_mobile_webview determines how the widget communicates. If set to true the widget will send messages via window.location = '...' instead of window.postMessage(...).

ui_message_version ensures you get the right messages.

client_redirect_url allows you to define the URL that the user redirected to at the end of OAuth. This URL should be something your mobile app can respond to.

Example URL request

1
2
3
4
5
6
7
8
9
10
11
12
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/widget_urls' \
-u '{client_id}:{api_key}' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "widget_url": {
        "widget_type": "connect_widget",
        "is_mobile_webview": true,
        "ui_message_version": 4,
        "client_redirect_url": "{your_url_here}"
      }
    }'

Example URL response

1
2
3
4
5
6
7
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxc...snip...Ay5",
    "user_id": "u-abc-789"
  }
}

2. Handle navigation events

WebViews bring some undesireable baggage for integrations, particularly:

How does the widget ‘talk’ to my mobile app?
What happens when the user tries to visit a link in the widget to an external site?

The answer to both of these questions is navigation events. Your native app will need to intercept all events and decide to either ‘block’ the event — if that event is actually a message from the widget — or allow the event and send the user to the browser — like when a user is trying to visit a bank’s site or trying to authenticate via OAuth.

For a good example of handling events, see the iOS and Android demo apps.

3. OAuth: Redirect out to the OAuth provider

OAuth flows in WebViews will require you to facilitate the redirect to the OAuth Provider, as well as let MX know how to get back to your native App.

To facilitate the redirect out, you will need to capture the oauth requested message, get the URL from the payload, and send the user to that URL.

See a good example of handling OAuth in the iOS or Android demo apps.

Example WebView Message

mx://connect/oauthRequested?metadata={...JSON encoded payload ...}

Example Redirect URL

https://widgets.moneydesktop.com/oauth/predirect_to/MBR-f1e7a927-924f-4b31-a8da-61de02954d74/4wa...snip...02?referral_source=BROWSER&skip_aggregation=false&

4. OAuth: Get the user back to your app

To get back to your app, you’ll want to make sure you set the client_redirect_url to a url that your app can respond to when linked from a browser. Once OAuth is complete, MX send the user to the client_redirect_url with some additional query parameters that have information on what happened.

Example URL back to your app

// client_redirect_url: "https://mx.com"

https://mx.com?status=success&member_guid=MBR-123

If the status field is success, you can simply continue showing the Connect Widget. It will continue as usual. A success message at this point means we were able to successfully get an OAuth token and have started a job. You’ll want to let the Connect Widget finish doing its thing before moving on.

If the status field is error, you will want to close the widget and show a generic error view that is appropriate for your application. An error at this point can mean anything from a user rejecting OAuth terms to an internal server error. We are working on adding better error messaging, but for now, plan on making a generic error page to use as a catchall.

Alternate redirect option

MX can also redirect to a custom URI scheme instead of a custom URL. If you use ui_message_webview_url: "appscheme", for instance, The widget will redirect the user to that scheme with a path.

ui_message_webview_url_scheme also influences the scheme used in post messages when is_mobile_webview: true is used. You can see an example of that in the iOS and Android demo apps.

Example URI back to your app

// Demo app uses a `ui_message_webview_url_scheme: "appscheme"

appscheme://oauth_complete?status=success&member_guid=MBR-123

You’ll want to make sure your app can respond to these schemes. See examples with the iOS and Android demo apps.

Hybrid mobile webapps

If you are embedding the Connect Widget in a webapp that is itself embedded in a WebView, there are some additional options for you. While you can implement what is described in this mobile guide, you may prefer to follow our web guide and make a few adjustments.

The first change you may want to make is_mobile_webview: false (or omit entirely). This would allow your webapp and the Connect Widget to communicate via postMessages just like they would in a browser setting.

Then you would want to use oauth_referral_source: "APP". This tells MX that you want us to redirect the user at the end of OAuth, instead of using postMessages in a browser.