CommonHealth connects users to their historical healthcare data, gives them complete control of how, when, and with whom to share, and focuses on consent management. The concepts related to taking control over personal data and deciding how and with whom to share those data are highly complex. The best policy and approach will be ineffective if the implementation does not work for all users of the platform. To that end, we are employing a participatory, iterative design process working with diverse groups of patients first to gain a better understanding of patients' conceptual views and beliefs about their health data and how it might be shared, then to design and assess user experiences that support people making informed personal decisions.

To foster innovation, we are inviting other healthcare apps and services in the digital health ecosystem so that we can strengthen our data sharing and privacy protection standards. Our objective is to fully support patient autonomy via personal data rights, level the developer playing field via interoperability standards, and support a vibrant and accountable developer community.  We acknowledge that to do so will require finding a middle ground in the false dichotomy of recklessly sharing all data on one hand and paternalistic data blocking on the other. 

The digital health app ecosystem will be invaluable to our design and development of data and privacy models. As you adopt our common standards, best practices, and code of conduct, we will solicit your input on how CommonHealth can further support your work. Combined with our participatory design process, your feedback will help CommonHealth to design new features and functions so that the app developer community can also benefit from our knowledge-base. 

The Commons Project is a strong believer in open source. The CommonHealth Developer Toolkit is open source and made available according to the Apache 2.0 license. We will release all code for the core functioning of the developer tools and health data interoperability. We may choose to hold back certain in-development code as well as code related to operations such as storage and deployment. We also may rely on certain third-party modules that are not open source. We do not require developers we work with or anyone leveraging our platform or code to be open-source, but we encourage them to do so.

CommonHealth generally follows the CARIN Alliance Code of Conduct, which in summary consists of: Asserting transparency in practice and use of data, not transacting data without explicit, informed consent, minimizing use and disclosure of data, providing individual access to data, using security best practices, maintaining data provenance, being accountable for our actions, taking the opportunity to educate users, and being an advocate for greater availability of standards-compliant health data.

We look forward to working with like-minded developers who put the interests, safety, and privacy of people first. Please refer to our Terms and Conditions agreement for more information.

The CommonHealth SDK provides an interface to accessing medical data residing in the CommonHealth app. Once CommonHealth is set up and a user onboarded with an active link to their healthcare provider(s), applications can leverage the SDK to request authorization to read subsets of their clinical data records. 

The SDK provides a simple CommonHealth Store interface that encapsulates the back-and-forth authorization handshakes, presenting the authorization interface itself, the inter-app querying of CommonHealth, and query results serialization. The SDK artifact itself is distributed through JFrog Bintray, and a Sample Client application demonstrating integration with the CommonHealth SDK is provided.  

You will first need to install the CommonHealth Developer Edition application. We are currently distributing this via a closed track on Google Play, so we will need to invite specific people via the Gmail/g suite account that is tied to the Android device/emulator that will be used for development. Please send your Gmail/g suite addresses to your CommonHealth contact or email them to developers@commonhealth.org.  

After you send your email information, you may download the SDK onto your device by clicking on this link: CommonHealth SDK download link

After you have installed the CommonHealth Developer Edition application, launch the application and start onboarding. You will first need to create a profile (name, dob, gender), and then connect to a SMART on FHIR data source. The CommonHealth Developer Edition application contains a single data source that points to the SMART Health IT Sandbox. Selecting this provider will redirect you to the SMART Health IT Sandbox authorization server, where you will need to enter a patient identifier and password. You can find the patient listing here. The ID field in the patient listing is the patient identifier that you need to enter in the authorization screen. Once you have successfully authorized, you should see the patient resource appear on the next screen. Continue on to complete onboarding, and you should be redirected to the dashboard. The application is downloading the sample patient’s data in the background and it should begin to appear momentarily.

Once you have the CommonHealth Developer Edition application in a good state, you can now test out the inter-application data sharing functionality of CommonHealth. To do so, clone the CommonHealth Client Sample application and open the project in Android Studio. Build and run this application on the same device that you have installed the CommonHealth Developer Edition application. When the sample application loads, select the “Authorize" button to begin the authorization flow. You will be redirected to the CommonHealth application where you can select which resources you would like to share with the sample application. Once you consent to share, you will be redirected back to the sample application, where you can view the shared resources.

If you have the sample application working with the CommonHealth Developer Edition, you can start looking at what is required to integrate and use the CommonHealth Client Application SDK within your application. You can find that information here. 

If you have any technical issues or questions getting things set up, please reach out to your CommonHealth contact, or email us at developers@commonhealth.org. We are constantly looking to improve the SDK to support a variety of use cases. If you or others have feedback or questions, we would be happy to evaluate or hop on a call to discuss.

The CommonHealth Client SDK provides applications access to FHIR resources stored in the CommonHealth application.  CommonHealth uses standard FHIR APIs defined by the Argonaut Project. 

CommonHealth supports data on allergies, conditions, immunizations, lab results, medications, procedures, and vitals.  Users’ data are secured by PIN or biometric sign-in and data is encrypted such that access is only possible with explicit user-directed consent.

Integrating with the CommonHealth SDK is required for Android applications that wish to access clinical and other health data through CommonHealth. 

We provide a CommonHealth Developer Edition application with test data to support a smooth integration and software development workflow. 

Clinical data access is scoped down to the record-level. This means that patients have the ability to choose exactly which records are shared with each application they link to their CommonHealth account. 

Apps wishing to connect to CommonHealth for production purposes will request approval from a review team managed by The Commons Project (details of this team and process will be available Q2 2020). As part of the approval request, developers will work with the review team to minimize the scope of data access to the minimum functional level. For example, an allergy tracking app that needs only access to allergies and meds will not be granted access to other categories of data.

Once authorized, accessing data is simple. The client application specifies the types of data it is looking for (e.g., Lab Results), and optional date range. The SDK fetches approved resources matching the query and returns them to the client application.

We leverage the existing Android inter-application communication components, but we add an extra layer of security to ensure patient data privacy.

See more in the open source sample app repository: https://github.com/the-commons-project/CommonHealthClientSample

In order to help ensure patient data privacy, CommonHealth maintains a registry of applications that have been verified and approved to connect to CommonHealth. By default, only approved applications will be allowed to request data from CommonHealth.

The CommonHealth SDK was designed with ease-of-use in mind, recognizing that many application developers would be integrating with Apple’s HealthKit in parallel. The interface for interacting with CommonHealth is very similar to HealthKit and the first set of data types and queries that are supported are essentially equivalent to HealthKit’s sample queries for clinical data. Developers can manage authorization, scoping, querying, and processing the query results using many of the same patterns as they have established for HealthKit. 

However, there are some key differences from HealthKit:

• CommonHealth maintains a registry of approved applications, whereas Apple gates access through their App Store approval process.

• Apple Health comes pre-installed and integrated on Apple devices, so users do not need to install or sign in to Apple Health separately. With CommonHealth, users will need to install the app from the Google Play Store and create a profile within the app.

The CommonHealth Enterprise Implementation team will work closely with your organization to determine an appropriate launch date for the app. The definition of a launch date is when a user can find and connect to your organization through the CommonHealth app.

This date will be dependent on your organization providing the minimum required information.  A launch is not dependent on optional project tasks such as training and user distribution work.

Overview and Requirements

The Add to CommonHealth button gives users a visual cue that they can securely download and store their COVID-19 test or vaccination information in the CommonHealth app.

Basic requirements

• The Add to CommonHealth buttons shown in these guidelines should appear only in association with your health records using the SMART® Health Cards framework.

• Always use artwork provided by CommonHealth without modification.

Getting Started

Follow these steps to begin the process:

• Verify that your organization’s patient record system is capable of generating SMART Health Cards according to the SMART Health Cards framework. To learn more about SMART Health Cards and implementing the SMART Health Cards framework, please refer to the SMART Health Cards website.

• Be sure you have at least one test patient account, populated with synthetic data, that can be used to validate your implementation of the Add to CommonHealth button.

• When adding the Add to CommonHealth button to an Android app, web page, or email, make sure that the device is an Android device or tablet, either in an Android app or web browser.

  • Android app: if you integrate the CommonHealth SDK, you can use the getCommonHealthAvailability (link) to determine if CommonHealth is installed. If not, you can include language to guide the user to first install CommonHealth before pressing on the link.

  • Web page: Check the browser user agent to exclude user-agents indicating iOS or Windows devices (for example, excluding strings like “iPhone”, “AppleWebKit” or “Windows”).

  • Email: Near the Add to CommonHealth button, let the user know that the button will only work on devices with Android 6+.

Note that if the user does not have CommonHealth installed, clicking on the deeplink will redirect them to the Google Play listing for CommonHealth where they can install the app.

Prepare the SMART Health Card

Deeplink

To implement the Add to CommonHealth button in an app, web page, or in an email, you will need to take the numeric value of each SMART Health Card QR code and embed it in a CommonHealth deeplink as the URL backing the Add to CommonHealth button.

Specifically, take the numeric value and attach it to the CommonHealth deeplink as a url fragment (specifically, as #shc_numeric=shc:/123). The CommonHealth deeplink is:

https://app.commonhealth.org/m/phr/main?source=add_shc_to_ch

Putting it together with the QR code contents, and assuming that the value “shc:/123”, would be:

https://app.commonhealth.org/m/phr/main?source=add_shc_to_ch#shc_numeric=shc:/123

Note that this exact structure must be used, and the QR code contents (the “shc:/123”) must not be modified in any fashion, otherwise the SMART Health Card will be unreadable. Use this full URL as the link from the Add to CommonHealth button.

For example, using the sample SMART Health Card here, the fully-formed deeplink URL would be:

https://app.commonhealth.org/m/phr/main?source=add_shc_to_ch#shc_numeric=shc:/567629095243206034602924374044603122295953265460346029254077280433602870286471674522280928613331456437653141590640220306450459085643550341424541364037063665417137241236380304375622046737407532323925433443326057360106452933611232742428535076646807676662393862717766034360387620367604083623090777534477112457626152636563737733057205292172067360372609396443651173681212221229105230243544572171415762213756620455092527696229572272070943002637090326596905580966663222772607355353054431126131080975594539057322755825713154363958332200500306110550547006327538744259276700394262546157502858694363764033593755734030715840285975055228316509266554504028366252551231550735342903073111083103246050124340573930407477236905333972210463580043376526752011286837533877246169206554586162523338060876605853731263712720435724200023354566570540285555075965207125572758635224450850324521776460383964007106056804764170297730076205390033360029415212560423334277756626030436116830450042700510357635055844576670120403073627392144045422266374441071322431523908672225000832356822507359050964411173387262344162680511102266752758625811604403532065395560675872243836085677376640655210605528360452280927286964530542006675667064264253252540560070037354566259447158434029050358003008776143640970065233217555574342006224266960586622632745112265684341662563695009033638535077312145734273240476642166402839655303110034270300534431075525502430334374016828756711610605247737287165105927692857253043040906686376443232360603576244613474630322587608707037123476675270003030000620402576587210642369366421263260740707745840687258

Add to CommonHealth Button

Following the guidelines, place the Add to CommonHealth button in the appropriate location in your app, web page, or email that allows users to import a SMART Health Card into CommonHealth.

Validate

Using the new SMART Health Card redirect URL you generated for your test patient, validate that you can tap the Add to CommonHealth button in the appropriate app, web page, or email interface. Tapping the Add to CommonHealth button will prompt the user to add the vaccination record to Health and create a vaccination card in Wallet.

Add to CommonHealth Button

The Add to CommonHealth artwork is designed to be used as a button in apps, web pages, and email, or included as a badge with a QR code on printed material. The button should appear only in association with compatible SMART Health Cards, currently for COVID-19 testing and vaccination records.

Adding the Add to CommonHealth button in an app, web page, or email will enable users to add a SMART Health Card directly to the CommonHealth app on an Android device with Android 6 or higher.

Background Color

Place the button on a clear, uncluttered background. Use a white, black, or very dark gray background for maximum legibility.

Using the Digital Button

Apps, Web Pages, and Email

Use the scalable SVG artwork provided by CommonHealth for buttons on your apps, web pages, and email. Place the button directly below the SMART Health Card QR code and other information related to the user’s vaccination record.

Clear Space for Onscreen Use

The minimum clear space for onscreen layouts is .1X where X is the height of the button. Always use the button at a size that is clearly legible in the media resolution of your communication.

Printed SMART Health Card

When you provide a printed version of the SMART Health Card, use the Works with CommonHealth button. It should appear only in association with a SMART Health Card and must be accompanied by a QR code or download link. Users can access the Camera app to scan a QR code included on a web page, in an email, or in printed material. Users can scan the QR code within CommonHealth to add it.

Artwork

Use the scalable EPS artwork provided by CommonHealth in your printed SMART Health Card.

Clear Space and Size Requirements

On printed SMART Health Cards, the minimum button size for the Add to CommonHealth button is 8 mm in height and the maximum size is 25 mm in height. Do not reduce or enlarge the button beyond these sizes. Minimum clear space is one-quarter the height of the button.

QR Codes

A recommended minimum QR code size for optimum scanning is 40 mm wide.

Button and QR Code Alignment

It is recommended that the QR code and Add to CommonHealth button be aligned to equal width. It is also acceptable to have the QR codes left or center aligned.

White Space

Allow minimum clear space around the Add to CommonHealth button. Make sure you also comply with the requirements for a surrounding “quiet zone” for the QR code. QR codes must be printed on a white or light background. If your layout includes a dark background, do not extend the QR code’s required surrounding white space to include the Add to CommonHealth button. The white space should surround only the QR code. On dark backgrounds, the Add to CommonHealth button should not touch the QR code’s required surrounding white space.

Messaging Guidelines

Messaging that describes CommonHealth can be used in communications promoting SMART Health Cards. Messaging can be placed near the Add to CommonHealth button that accompanies the SMART Health Card, or it can be used in general product communications to describe compatibility with CommonHealth.

Recommended Messaging

You can use the suggested messaging below to describe the Add to CommonHealth feature, or you can develop your own. Always follow the guidelines described below:

Adding your verifiable SMART Health Card to CommonHealth allows you to securely store your health records and enables you to quickly present your records by saving them to Samsung Pay or Google Pay.

Non-Disclosure Agreement

CommonHealth does not need a Mutual Non-Disclosure Agreement (MNDA) before providing SDK access, as we are open-source.

If your institution requires a MNDA before you can participate in SDK testing, please send a copy of your standard MNDA to ops@thecommonsproject.org. 

Timeframe

We will continue to develop CommonHealth with feedback from our developer community. However, we request that you share your crucial feedback with us within thirty (30) days after starting your testing.

Disclaimer

Participation in SDK testing is voluntary. The Commons Project Foundation will not provide you with office space, specific hardware, software, or other licenses for this SOW. You are expected to test our SDK from your location and on your device. 

CommonHealth Support and Contact Information

Technical Support: developers@commonhealth.org

Business Support: ops@thecommonsproject.org