Cordova Guide

Human Connect can also be run in embedded mode, which is useful for some mobile applications and other non-standard environments where browser features are limited in some way. This includes applications built with PhoneGap/Cordova libraries.

The main difference of embedded mode is that all callbacks are implemented as simple redirects. The result is that users will not be directed outside of your application during authentication, but you will need to supply Human Connect with URLs for the finish and close functions.

In order to start the authentication process you can redirect your user to https://connect.humanapi.co/embed and add the following parameters into your query string:

📘

Create and Edit Mode

For new users, open the popup in Create Mode by supplying both client_id and client_user_id parameters.

For existing users, open the popup in Edit Mode by supplying client_id, client_user_id, and public_token as parameters.

See Human Connect Overview for more details.

Next, ensure that you monitor the connect popup web view for the close callbacks you passed in on launch. When you detect these urls, implement methods appropriate for finish or close.

Here's an example of what this might look like:

var baseURL = 'https://connect.humanapi.co/embed?';
var clientID = '0589b8a68485746bd737a7a58f5c8e02aeac445f';
var clientUserId = '[email protected]';
var publicToken = null; //Set to publicToken value if previously retrieved or 'null' for new users
var finishURL = 'https://connect.humanapi.co/blank/hc-finish';
var closeURL = 'https://connect.humanapi.co/blank/hc-close';

//construct URL to launch Connect
var url = baseURL + 'client_id=' + clientID + '&client_user_id=' + clientUserId + '&finish_url=' + finishURL + '&close_url='+ closeURL + (publicToken != null ? "&public_token="+ publicToken : '');

var ref = window.open(url, '_blank', 'toolbar=no, location=no');

ref.addEventListener('loadstart', function(event) {
	if (event.url.indexOf('https://connect.humanapi.co/blank/') === 0) {
      if (event.url.indexOf('hc-finish') !== -1) {       
        
        //Create sessionTokenObject from finish url parameters
        var paramString = event.url.replace(finishURL+"?","");
        var match = "";
        var params = {};
        var regex = /([^&=]+)=?([^&]*)/g;

        while (match = regex.exec(paramString))
          params[match[1]] = match[2];

        var sessionTokenObject = {
          "humanId": params["human_id"],
          "clientId": params["client_id"],
          "sessionToken": params["session_token"]
        }

				//Post `sessionTokenObject` to your server to finish
        //the authentication process (see link below for guide)
        ref.close();
        
      } else if (event.url.indexOf('hc-close') !== -1) {
        alert('Close callback called');
        //Do something on close
        ref.close();
      }
   }
});

🚧

Keep in mind that the eventListener for callbacks will only work in the Cordova inAppBrowser. Therefore, you will need to test in the platform emulators (Xcode/AndroidStudio) instead of via the raw HTML files. In a desktop browser, you will see {"statusCode"=200} instead of a callback.

As soon as user is redirected to the finish_url you can finalize the authentication process on your server by exchanging the sessionTokenObject and retrieving a user's accessToken.

The server-side token exchange process is the same for all platforms. See the guide on Finalizing User Authentication guide to finish the process.