Skip to main content
This guide covers embedding the Connect Widget in a native app via a WebView. 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.
NOTEIf you’re embedding the Connect Widget in a webapp that is itself embedded in a WebView, see Hybrid Mobile Webapps.
While working through this guide, 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.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.
INFOThere are other less commonly used options that provide further customization to OAuth flows. For more info, see Hybrid Mobile Apps.
Request
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}"
      }
    }'
Response
{
  "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 undesirable 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 event. 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.
INFOFailure to appropriately handle navigation events in a WebView can lead to broken behavior, like replacing the Connect Widget with the bank’s website with no way for the user to get back.
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.An workflow that explains the Oauth webview and redirect
WARNINGIt’s required to use the device’s browser, not another WebView or iframe, to authenticate the user. Not only does this approach result in better security, it also can leverage saved passwords and password managers that the user has installed. It is also worth noting that many OAuth providers explicitly block loading their web apps in an iframe or webview.
INFOThe URL given in the payload will always be an MX URL; the user will be routed to us first, then to the provider.
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. 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. Example URL Request 
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",
        "ui_message_version": 4,
        "client_redirect_url": "{your_url_here}",
        "oauth_referral_source": "APP"
      }
    }'
Example URL Response 
{
  "widget_url": {
    "type": "connect_widget",
    "url": "https://int-widgets.moneydesktop.com/md/connect/yxc...snip...Ay5",
    "user_id": "u-abc-789"
  }
}
From here, you would still want to listen for the OAuth requested postMessage in your webapp, then message the URL to your mobile app, so it can redirect them via the mobile device’s browser. Once OAuth is completed, MX will redirect the user back to your client_redirect_url. A workflow explaining how OAuth redirects