{"_id":"564d1afb4567342100ad96c3","version":{"_id":"564d1af84567342100ad96aa","project":"551375e1d04af219007ddc52","__v":1,"createdAt":"2015-11-19T00:42:32.705Z","releaseDate":"2015-11-19T00:42:32.705Z","categories":["564d1af94567342100ad96ab","564d1af94567342100ad96ac","564d1af94567342100ad96ad","564d1af94567342100ad96ae","564d1af94567342100ad96af","564d1af94567342100ad96b0","564d1af94567342100ad96b1","564d1af94567342100ad96b2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.1.0","version":"1.1"},"category":{"_id":"564d1af94567342100ad96ad","__v":2,"pages":["564d1afb4567342100ad96c0","564d1afb4567342100ad96c1","564d1afb4567342100ad96c2","564d1afb4567342100ad96c3","564d1c209f8c5c0d00245e15"],"project":"551375e1d04af219007ddc52","version":"564d1af84567342100ad96aa","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-27T02:56:41.497Z","from_sync":false,"order":2,"slug":"authenticating-users","title":"Authenticating Users"},"__v":7,"user":"551375a3d04af219007ddc50","project":"551375e1d04af219007ddc52","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-03-27T02:57:43.538Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"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.\n\nThe 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.\n\nIn 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:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`client_id`\",\n    \"0-1\": \"String\",\n    \"1-0\": \"`client_user_id`\",\n    \"1-1\": \"String\",\n    \"2-0\": \"`public_token`\",\n    \"2-1\": \"String\",\n    \"0-2\": \"This is your client's or app's ID, you can get this from the app settings page.\",\n    \"1-2\": \"User ID from your app. It can be email or any other internal id of the user in your system.\",\n    \"2-2\": \"The `publicToken` received from previous user authentication (only for existing users).\",\n    \"3-0\": \"`finish_url`\",\n    \"3-1\": \"String\",\n    \"3-2\": \"User is redirected to this URL when health data connection process is finished. `session_token` and `human_id` will be added as request parameters.\\n\\nThe base of this URL must be: `https://connect.humanapi.co/blank/`\",\n    \"4-0\": \"`close_url`\",\n    \"4-1\": \"String\",\n    \"4-2\": \"User is redirected to this URL if process cancelled or popup closed.\\n\\nThe base of this URL must be: `https://connect.humanapi.co/blank/`\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Create and Edit Mode\",\n  \"body\": \"For **new users**, open the popup in Create Mode by supplying both `client_id` and `client_user_id` parameters.\\n\\nFor **existing users**, open the popup in Edit Mode by supplying `client_id`, `client_user_id`, and `public_token` as parameters.\\n\\nSee [Human Connect Overview](doc:overview-of-human-connect) for more details.\"\n}\n[/block]\n\nNext, 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.\n\nHere's an example of what this might look like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var baseURL = 'https://connect.humanapi.co/embed?';\\nvar clientID = '0589b8a68485746bd737a7a58f5c8e02aeac445f';\\nvar clientUserId = 'someuser:::at:::google.com';\\nvar publicToken = null; //Set to publicToken value if previously retrieved or 'null' for new users\\nvar finishURL = 'https://connect.humanapi.co/blank/hc-finish';\\nvar closeURL = 'https://connect.humanapi.co/blank/hc-close';\\n\\n//construct URL to launch Connect\\nvar url = baseURL + 'client_id=' + clientID + '&client_user_id=' + clientUserId + '&finish_url=' + finishURL + '&close_url='+ closeURL + (publicToken != null ? \\\"&public_token=\\\"+ publicToken : '');\\n\\nvar ref = window.open(url, '_blank', 'toolbar=no, location=no');\\n\\nref.addEventListener('loadstart', function(event) {\\n\\tif (event.url.indexOf('https://connect.humanapi.co/blank/') === 0) {\\n      if (event.url.indexOf('hc-finish') !== -1) {       \\n        \\n        //Create sessionTokenObject from finish url parameters\\n        var paramString = event.url.replace(finishURL+\\\"?\\\",\\\"\\\");\\n        var match = \\\"\\\";\\n        var params = {};\\n        var regex = /([^&=]+)=?([^&]*)/g;\\n\\n        while (match = regex.exec(paramString))\\n          params[match[1]] = match[2];\\n\\n        var sessionTokenObject = {\\n          \\\"humanId\\\": params[\\\"human_id\\\"],\\n          \\\"clientId\\\": params[\\\"client_id\\\"],\\n          \\\"sessionToken\\\": params[\\\"session_token\\\"]\\n        }\\n\\n\\t\\t\\t\\t//Post `sessionTokenObject` to your server to finish\\n        //the authentication process (see link below for guide)\\n        ref.close();\\n        \\n      } else if (event.url.indexOf('hc-close') !== -1) {\\n        alert('Close callback called');\\n        //Do something on close\\n        ref.close();\\n      }\\n   }\\n});\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"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.\"\n}\n[/block]\nAs 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`. \n\nThe server-side token exchange process is the same for all platforms. See the guide on [Finalizing User Authentication](doc:finalizing-user-authentication) guide to finish the process.","excerpt":"","slug":"limited-browser-environments","type":"basic","title":"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: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "0-0": "`client_id`", "0-1": "String", "1-0": "`client_user_id`", "1-1": "String", "2-0": "`public_token`", "2-1": "String", "0-2": "This is your client's or app's ID, you can get this from the app settings page.", "1-2": "User ID from your app. It can be email or any other internal id of the user in your system.", "2-2": "The `publicToken` received from previous user authentication (only for existing users).", "3-0": "`finish_url`", "3-1": "String", "3-2": "User is redirected to this URL when health data connection process is finished. `session_token` and `human_id` will be added as request parameters.\n\nThe base of this URL must be: `https://connect.humanapi.co/blank/`", "4-0": "`close_url`", "4-1": "String", "4-2": "User is redirected to this URL if process cancelled or popup closed.\n\nThe base of this URL must be: `https://connect.humanapi.co/blank/`" }, "cols": 3, "rows": 5 } [/block] [block:callout] { "type": "info", "title": "Create and Edit Mode", "body": "For **new users**, open the popup in Create Mode by supplying both `client_id` and `client_user_id` parameters.\n\nFor **existing users**, open the popup in Edit Mode by supplying `client_id`, `client_user_id`, and `public_token` as parameters.\n\nSee [Human Connect Overview](doc:overview-of-human-connect) for more details." } [/block] 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: [block:code] { "codes": [ { "code": "var baseURL = 'https://connect.humanapi.co/embed?';\nvar clientID = '0589b8a68485746bd737a7a58f5c8e02aeac445f';\nvar clientUserId = 'someuser@google.com';\nvar publicToken = null; //Set to publicToken value if previously retrieved or 'null' for new users\nvar finishURL = 'https://connect.humanapi.co/blank/hc-finish';\nvar closeURL = 'https://connect.humanapi.co/blank/hc-close';\n\n//construct URL to launch Connect\nvar url = baseURL + 'client_id=' + clientID + '&client_user_id=' + clientUserId + '&finish_url=' + finishURL + '&close_url='+ closeURL + (publicToken != null ? \"&public_token=\"+ publicToken : '');\n\nvar ref = window.open(url, '_blank', 'toolbar=no, location=no');\n\nref.addEventListener('loadstart', function(event) {\n\tif (event.url.indexOf('https://connect.humanapi.co/blank/') === 0) {\n if (event.url.indexOf('hc-finish') !== -1) { \n \n //Create sessionTokenObject from finish url parameters\n var paramString = event.url.replace(finishURL+\"?\",\"\");\n var match = \"\";\n var params = {};\n var regex = /([^&=]+)=?([^&]*)/g;\n\n while (match = regex.exec(paramString))\n params[match[1]] = match[2];\n\n var sessionTokenObject = {\n \"humanId\": params[\"human_id\"],\n \"clientId\": params[\"client_id\"],\n \"sessionToken\": params[\"session_token\"]\n }\n\n\t\t\t\t//Post `sessionTokenObject` to your server to finish\n //the authentication process (see link below for guide)\n ref.close();\n \n } else if (event.url.indexOf('hc-close') !== -1) {\n alert('Close callback called');\n //Do something on close\n ref.close();\n }\n }\n});\n", "language": "javascript" } ] } [/block] [block:callout] { "type": "warning", "body": "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." } [/block] 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](doc:finalizing-user-authentication) guide to finish the process.