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.

Add the "Connect Health Data" Button

1. Add our javascript library

This will create a global HumanConnect JS object.

<script src='https://connect.humanapi.co/connect.js'></script>

2. Add the button in the appropriate place on your page.

<img id='connect-health-data-btn' src='https://connect.humanapi.co/assets/button/blue.png'/>

Render the Connect Popup

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.

🚧

Public Tokens

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.

If the token goes missing, you can always get a new one with the publicTokens endpoint as detailed at the bottom of this page.

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:

var options = {
  clientUserId: encodeURIComponent('UNIQUE_ID_FOR_YOUR_USER'), 
  clientId: 'CLIENT_ID', // grab it from app settings page 
  publicToken: '',  // Leave blank for new users

  finish: function(err, sessionTokenObject) {
      /* Called after user finishes connecting their health data
       You need to post `sessionTokenObject` to your server to then:
       1. Append your `clientSecret` to it
       2. Send send it to our server for user credentials

       Sending a POST request with jQuery might look like this
      (it's not necessary to use jQuery):
      */
      $.post('/your-servers-endpoint', sessionTokenObject, function(res){

      });

      // Include code here to refresh the page.

  },
  close: function() {
      /* Optional callback called when a user closes the popup 
         without connecting any data sources */
  },
  error: function(err) {
      /* Optional callback called if an error occurs when loading
         the popup. */

      // `err` has fields: `code`, `message`, `detailedMessage`
  }  
}

HumanConnect.open(options);

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.

🚧

Refresh/Redirect on finish()

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.

Human 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.

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:

var options = {
  clientUserId: encodeURIComponent('UNIQUE_ID_FOR_YOUR_USER'), 
  clientId: 'CLIENT_ID', // grab it from app settings page
  publicToken: 'PUBLIC_TOKEN_FOR_THE_USER', // you should have this from the successful authentication flow
 
  // Include the same code as launching Human Connect for a new user here 
  // (see above) 
}
HumanConnect.open(options);

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.

❗️

User Already Exists Error

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.

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 for next steps.