Introduction

There are several ways to embed the Connect widget in your native app. This guide will take you through embedding Connect in a webapp that is itself embedded in a WebView. This approach has the same caveats as directly embedding Connect into a WebView, but requires a slightly different integration.

For the most part, you’ll want to follow the same steps in our web guide. However, there are still some additional things you’ll need to do or change — specifically when it comes to getting OAuth to work properly:

  • Add additional configuration options for OAuth flows.
  • Redirect the user out to the OAuth provider.
  • Get the user back to your app once OAuth completes.

Configuration

Here’s a request to get a Connect URL with the minimum configuration for OAuth flows.

Example request

1
2
3
4
5
6
7
8
9
10
11
12
curl -L -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,
        "ui_message_webview_url_scheme": "<your app scheme>",
        "oauth_referral_source": "APP"
      }
    }'
  • ui_message_version: 4 ensures that you get the right messages.
  • ui_message_webview_url_scheme defaults to mx, which is not what we want for this flow. So, we must override that by giving it a value that your app can respond to, e.g. "<your app scheme>". This ensures that the user gets sent back to your app — along with some metadata about what happened.
  • oauth_referral_source: "APP" tells MX to redirect to the the ui_message_webview_url_scheme you provided.

Handling OAuth

OAuth flows in WebViews always require you to both facilitate the redirect to the OAuth provider and let MX know how to get back to your native app.

To facilitate the redirect out, your webapp will need to capture the OAuth requested message, pass the URL from the payload to your native app, and send the user to that URL.

To get back to your app, you’ll want to make sure you set the ui_message_webview_url_scheme to a scheme that your app can respond to when linked from a browser. Once OAuth is complete, the MX page that the user is sent to will try to link back to your app via a URI.

Example URI back to your app

appscheme://oauth_complete?status=<success|error>&member_guid=...

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 Connect finish doing it’s 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, just plan on making a generic error page to use as a catch all for now and the future.