{"_id":"564d1afb4567342100ad96c1","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"},"user":"551375a3d04af219007ddc50","__v":11,"project":"551375e1d04af219007ddc52","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"},"updates":["55f03993e507711900e58c6e","595f99577fe8510029e41197"],"next":{"pages":[],"description":""},"createdAt":"2015-03-27T03:00:42.765Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Integrating Human Connect on the web is easy. We have provided the code necessary to launch the popup and manage user interaction thereafter. For the integration, you will need to add the Connect Health Data button and manage callbacks from the popup.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Add the \\\"Connect Health Data\\\" Button\"\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/UGsCZBxSUisR5XyUZ8mJ_blue.png\",\n        \"blue.png\",\n        \"259\",\n        \"49\",\n        \"#4c8ec6\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n#1. Add our javascript library\nThis will create a global `HumanConnect` JS object.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script src='https://connect.humanapi.co/connect.js'></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n#2. Add the button in the appropriate place on your page.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<img id='connect-health-data-btn' src='https://connect.humanapi.co/assets/button/blue.png'/>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Render the Connect Popup\"\n}\n[/block]\nWhen a user first connects, a user for your Human API app will be created with your specified `clientUserId` and you will be issued a `publicToken` as part of the auth process.\n\nWhen a user returns to connect more sources or disconnect existing ones, simply include the `publicToken` to let them edit their connections.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Public Tokens\",\n  \"body\": \"Make sure to hold on to that `publicToken`!  You'll need it in order to render the Connect popup for returning users.  Additionally, the publicToken changes each time the user connects a new source, so be sure to update it accordingly.\\n\\nIf the token goes missing, you can always get a new one with the publicTokens endpoint as detailed at the bottom of [this page](doc:finalizing-user-authentication).\"\n}\n[/block]\n# Launching the Human Connect Popup For New Users (Create Mode)\nTo launch Human Connect popup in create mode (when a user clicks on the connect health data button for the first time) you need to call the `HumanConnect.open()` function like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var options = {\\n  clientUserId: encodeURIComponent('UNIQUE_ID_FOR_YOUR_USER'), \\n  clientId: 'CLIENT_ID', // grab it from app settings page \\n  publicToken: '',  // Leave blank for new users\\n\\n  finish: function(err, sessionTokenObject) {\\n      /* Called after user finishes connecting their health data\\n       You need to post `sessionTokenObject` to your server to then:\\n       1. Append your `clientSecret` to it\\n       2. Send send it to our server for user credentials\\n\\n       Sending a POST request with jQuery might look like this\\n      (it's not necessary to use jQuery):\\n      */\\n      $.post('/your-servers-endpoint', sessionTokenObject, function(res){\\n\\n      });\\n\\n      // Include code here to refresh the page.\\n\\n  },\\n  close: function() {\\n      /* Optional callback called when a user closes the popup \\n         without connecting any data sources */\\n  },\\n  error: function(err) {\\n      /* Optional callback called if an error occurs when loading\\n         the popup. */\\n\\n      // `err` has fields: `code`, `message`, `detailedMessage`\\n  }  \\n}\\n\\nHumanConnect.open(options);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n The best practice for doing this is to call `HumanConnect.open()` inside the `onClick` handler for the `connect-health-data-btn` button we added earlier.\n\nThe specified `options.finish` callback will need to POST the `sessionTokenObject` to your server. To finalize the user authentication flow you will POST the `sessionTokenObject` signed with your `clientSecret` to our servers. Read more about this process below.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"After you POST the `sessionTokenObject` to your server, you must redirect the user or refresh the current page with the `publicToken` data so that the Human Connect button will open in Edit Mode described below.\\n\\nHuman Connect will continue polling our servers after it is closed until you refresh the page. This is correct behavior and necessary for security reasons, despite a 412 response that may be seen in the javascript console.\",\n  \"title\": \"Refresh/Redirect on finish()\"\n}\n[/block]\n# Launching the Human Connect Popup For a Returning User (Edit Mode)\nWhen an existing user clicks on the Connect Health Data button again, you will want to show them the sources they have already connected. To do this, you must pass the user's `publicToken` to `HumanConnect.open` in the `options` variable, along with the `clientUserId` and `clientId` like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var options = {\\n  clientUserId: encodeURIComponent('UNIQUE_ID_FOR_YOUR_USER'), \\n  clientId: 'CLIENT_ID', // grab it from app settings page\\n  publicToken: 'PUBLIC_TOKEN_FOR_THE_USER', // you should have this from the successful authentication flow\\n \\n  // Include the same code as launching Human Connect for a new user here \\n  // (see above) \\n}\\nHumanConnect.open(options);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThe remainder of the Human Connect authorization process remains the same. If the user adds or removes a source in edit mode, the `finish()` callback will be called and you will need to go through the same finalization process as detailed below in order to retrieve an updated `accessToken` and `publicToken` for the user.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"User Already Exists Error\",\n  \"body\": \"If you do not pass a `publicToken` upon launching Human Connect for an existing user, the user will see an User Already Exists Error and Human Connect will not launch properly.\"\n}\n[/block]\n#Finalizing User Authentication\n\nAlmost there! The next step is to finalize the user's authentication and retrieve API credentials on your server. See [Finalizing User Authentication](doc:finalizing-user-authentication) for next steps.","excerpt":"","slug":"connect-web-guide","type":"basic","title":"Web Guide"}
Integrating Human Connect on the web is easy. We have provided the code necessary to launch the popup and manage user interaction thereafter. For the integration, you will need to add the Connect Health Data button and manage callbacks from the popup. [block:api-header] { "type": "basic", "title": "Add the \"Connect Health Data\" Button" } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/UGsCZBxSUisR5XyUZ8mJ_blue.png", "blue.png", "259", "49", "#4c8ec6", "" ] } ] } [/block] #1. Add our javascript library This will create a global `HumanConnect` JS object. [block:code] { "codes": [ { "code": "<script src='https://connect.humanapi.co/connect.js'></script>", "language": "html" } ] } [/block] #2. Add the button in the appropriate place on your page. [block:code] { "codes": [ { "code": "<img id='connect-health-data-btn' src='https://connect.humanapi.co/assets/button/blue.png'/>", "language": "html" } ] } [/block] [block:api-header] { "type": "basic", "title": "Render the Connect Popup" } [/block] When a user first connects, a user for your Human API app will be created with your specified `clientUserId` and you will be issued a `publicToken` as part of the auth process. When a user returns to connect more sources or disconnect existing ones, simply include the `publicToken` to let them edit their connections. [block:callout] { "type": "warning", "title": "Public Tokens", "body": "Make sure to hold on to that `publicToken`! You'll need it in order to render the Connect popup for returning users. Additionally, the publicToken changes each time the user connects a new source, so be sure to update it accordingly.\n\nIf the token goes missing, you can always get a new one with the publicTokens endpoint as detailed at the bottom of [this page](doc:finalizing-user-authentication)." } [/block] # Launching the Human Connect Popup For New Users (Create Mode) To launch Human Connect popup in create mode (when a user clicks on the connect health data button for the first time) you need to call the `HumanConnect.open()` function like so: [block:code] { "codes": [ { "code": "var options = {\n clientUserId: encodeURIComponent('UNIQUE_ID_FOR_YOUR_USER'), \n clientId: 'CLIENT_ID', // grab it from app settings page \n publicToken: '', // Leave blank for new users\n\n finish: function(err, sessionTokenObject) {\n /* Called after user finishes connecting their health data\n You need to post `sessionTokenObject` to your server to then:\n 1. Append your `clientSecret` to it\n 2. Send send it to our server for user credentials\n\n Sending a POST request with jQuery might look like this\n (it's not necessary to use jQuery):\n */\n $.post('/your-servers-endpoint', sessionTokenObject, function(res){\n\n });\n\n // Include code here to refresh the page.\n\n },\n close: function() {\n /* Optional callback called when a user closes the popup \n without connecting any data sources */\n },\n error: function(err) {\n /* Optional callback called if an error occurs when loading\n the popup. */\n\n // `err` has fields: `code`, `message`, `detailedMessage`\n } \n}\n\nHumanConnect.open(options);", "language": "javascript" } ] } [/block] The best practice for doing this is to call `HumanConnect.open()` inside the `onClick` handler for the `connect-health-data-btn` button we added earlier. The specified `options.finish` callback will need to POST the `sessionTokenObject` to your server. To finalize the user authentication flow you will POST the `sessionTokenObject` signed with your `clientSecret` to our servers. Read more about this process below. [block:callout] { "type": "warning", "body": "After you POST the `sessionTokenObject` to your server, you must redirect the user or refresh the current page with the `publicToken` data so that the Human Connect button will open in Edit Mode described below.\n\nHuman Connect will continue polling our servers after it is closed until you refresh the page. This is correct behavior and necessary for security reasons, despite a 412 response that may be seen in the javascript console.", "title": "Refresh/Redirect on finish()" } [/block] # Launching the Human Connect Popup For a Returning User (Edit Mode) When an existing user clicks on the Connect Health Data button again, you will want to show them the sources they have already connected. To do this, you must pass the user's `publicToken` to `HumanConnect.open` in the `options` variable, along with the `clientUserId` and `clientId` like so: [block:code] { "codes": [ { "code": "var options = {\n clientUserId: encodeURIComponent('UNIQUE_ID_FOR_YOUR_USER'), \n clientId: 'CLIENT_ID', // grab it from app settings page\n publicToken: 'PUBLIC_TOKEN_FOR_THE_USER', // you should have this from the successful authentication flow\n \n // Include the same code as launching Human Connect for a new user here \n // (see above) \n}\nHumanConnect.open(options);", "language": "javascript" } ] } [/block] The remainder of the Human Connect authorization process remains the same. If the user adds or removes a source in edit mode, the `finish()` callback will be called and you will need to go through the same finalization process as detailed below in order to retrieve an updated `accessToken` and `publicToken` for the user. [block:callout] { "type": "danger", "title": "User Already Exists Error", "body": "If you do not pass a `publicToken` upon launching Human Connect for an existing user, the user will see an User Already Exists Error and Human Connect will not launch properly." } [/block] #Finalizing User Authentication Almost there! The next step is to finalize the user's authentication and retrieve API credentials on your server. See [Finalizing User Authentication](doc:finalizing-user-authentication) for next steps.