Human API Connect Client

Table of contents

• Description
• Installation
• Lifecycle Hooks
• Upgrade from 1.x.x

Looking for 1.x documentation?

The documentation below is for humanapi-connect-client@2. We have recently released a new Connect integration client version that replaces the old 1.x.x version that has been deprecated.

It is recommended that you use this new client version which is backwards compatible to make the transition easier.

Click here for [email protected] documentation.

Description

Connect is the authentication widget for your application to allow users to share their health data. After a user has successfully granted you access to their health data using Connect, you'll be able to query their disparate data directly from Human API.

Please refer to the connect guide for full instructions on how to use the Connect client.

Installation

This module can be used by loading the script from our CDN or by installing the npm module.

CDN

To use the library via our CDN you can include the following script source:

<script src="https://cdn.humanapi.co/[email protected]">

NPM module

To install the npm module and use it with e.g. React:

npm install --save humanapi-connect-client

Usage

To use this library regardless of the method used, you first need to acquire a session token and set it as the data-attribute data-hapi-token of an element that supports the onclick event (e.g. a button). Then, you need to add the class hapi__token-container to the parent of the element that has the token value, e.g.:

<div class="hapi__token-container">
    <button data-hapi-token="<your session token>">Open Connect</button>
</div>

Note: Make sure that the element containing the class hapi__token-container is rendered on page load.

The library will then automatically configure all elements with the data-hapi-token attribute under that parent, to allow them to open the Connect window.

Lifecycle hooks

humanapi-connect-client can be configured to respond to the following lifecycle hooks:

• connect: This event will be fired after a source has been successfully connected
• disconnect: This event will be fired after a source has been disconnected
• close: This event will be fired after the Connect window is closed, regardless of whether sources were connected or not
• error: This event fires in case theres an error with the library e.g. a token container element is not found

To add a lifecycle hook to a particular event you have to use the on(eventName, eventListener) method, e.g.:

HumanConnect.on("close", (response) => {console.log("close", response)});
HumanConnect.on("connect", (response) => {console.log("connect", response)});
HumanConnect.on("disconnect", (response) => {console.log("disconnect", response)});
HumanConnect.on("error", (response) => {console.error("error", response)});

Any function listening for lifecycle events defined by Connect will receive a payload with the following schema:

 {
     sessionResults: {
         // List of sources the user connected during this session
         connectedSources: [
             {
                 name: "Starfleet Pharmacy",
                 id: "5b1daf3f079c652eaf41fd23"
             }
         ],
         // List of sources the user disconnected during this session
         disconnectedSources: [],
         // List of sources the user requested during this session
         requestedSources: [
             {
                 address: "742 Evergreen Terrace, OH",
                 healthSystem: "N/A",
                 location: {
                     latitude: 41.3289,
                     longitude: -105.6928
                 },
                 physician: "Dr. John Smith",
                 website: "drjohnsmith.example.com"
             }
         ]
     },
     // List of sources the user currently has connected with your app
     currentConnections: [
         {
             name: "Starfleet Pharmacy",
             id: "5b1daf3f079c652eaf41fd23"
         }
     ],
     // List of sources the user has requested
     requestedProviders: [
             {
                 address: "742 Evergreen Terrace, OH",
                 healthSystem: "N/A",
                 location: {
                     latitude: 41.3289,
                     longitude: -105.6928
                 },
                 physician: "Dr. John Smith",
                 website: "drjohnsmith.example.com"
             }
     ]
 }

Upgrade from 1.x.x

CDN

• If you are using the script via the CDN and the source location is src=https://cdn.humanapi.co/[email protected] you will be upgraded automatically. The new version is backwards compatible so there is no other change needed for the time being.

• If you are using a specific version of the library, e.g. src=https://cdn.humanapi.co/[email protected] you can just use [email protected] or specify a 2.x.x version, e.g. [email protected]

npm

• Install the latest package with npm install humanapi-connect-client

Contributing

Note: This project uses Node 14.

Generate a prerelease version

To generate a new pre-release version, you can run the following command:

npm version prerelease --preid=beta

This will bump the version to the next pre-release version, e.g. from 2.0.0 to 2.0.1-beta.0. After that you can publish the new version with:

npm publish --tag beta

And then push the new tag to the repository:

# Example
git push origin v2.0.1-beta.0

Generate a new version

To generate a new version, you can run the following command:

npm version patch

After that you can publish the new version with:

npm publish

And then push the new tag to the repository:

# Example
git push origin v2.0.1