Embedding MyDataHelps in Custom Apps

With MyDataHelps Embeddables, you can leverage the power of the MyDataHelps platform in your custom web or mobile application without your participants ever creating a MyDataHelps account or using a MyDataHelps app directly.

Introduction to Embeddables

What makes Embeddables different from the other MyDataHelps experiences like Views or Web View steps is that they operate outside of MyDataHelps. Embeddables are ideal when you have your own web page or native app, but want to incorporate specific MyDataHelps SDK functionality such as:

• Surveys
• Device Data Collection
• Electronic Health Record Integration

For some examples of how you can use MyDataHelps Embeddables, see the following case studies:

• Patient-Mediated Electronic Health Record (EHR) Integration

Prerequisites

Before using MyDataHelps in a custom application, you will still need to have a MyDataHelps Designer account and project. See the Getting Started guide if you do not already have one. You will also need to set up a service account for your project to access the MyDataHelps REST API and generate access tokens for your participants.

Getting Started

Integrating the MyDataHelps Embeddables with your own custom application involves three steps:

1. Managing participant mapping between your application and MyDataHelps using the MyDataHelps REST API.
2. Managing participant access tokens using the MyDataHelps REST API.
3. Embedding MyDataHelps SDK features within the custom application.

Managing Participants

Custom applications using MyDataHelps Embeddables will often have their own user accounts independent of MyDataHelps. For example, you might embed MyDataHelps within a web application that has a pre-existing account system.

However, to use the MyDataHelps SDK outside the MyDataHelps application, you will need to create MyDataHelps participant entities to mirror the users in your application. The MyDataHelps participant entity will then be the surrogate for your application user for all related activities. When your application client wants to initiate a feature that uses the MyDataHelps SDK, it should communicate with your application server, which then uses the MyDataHelps REST API to create or locate the corresponding MyDataHelps participant. Once the participant is obtained, you can then generate a participant access token that grants the appropriate permissions for the application client.

You are responsible for maintaining the mapping between the users in your application and the MyDataHelps participants you create for them. The recommended way to do this is to set the MyDataHelps participantIdentifier to a unique identifier from your system. (Internal identifiers like database IDs or your own synthetic participant identifier are recommended over business identifiers like MRNs/SSNs to maximize participant privacy.) Another option is to store the MyDataHelps participantID field associated with the user in your application. This is an auto-generated, stable, unique, internal ID for the participant. Either way, you’ll be able to determine whether a participant entity already exists for a given user, and create a new one when needed.

Managing Participant Access Tokens

To guard against unauthorized use, MyDataHelps requires an access token. When using MyDataHelps within your own application (outside of MyDataHelps), you will need to manage the participant’s access token yourself.

To retrieve a participant’s access token, your application server will first identify the appropriate MyDataHelps participant using the participant identification mapping described in Managing Participants. If the participant is authorized, the server will request a participant access token from the MyDataHelps REST API, specifying the required scope of access of features and actions that the participant can take. Once the participant access token is obtained, the application server will pass it on to the application client to authenticate to the MyDataHelps SDK for the participant.

See Participant Access Tokens for details.

Using SDK Features

Your custom application can be a web page or native app. To leverage MyDataHelps features, you will need to embed the MyDataHelps SDK within your application. The SDK is available on several platforms:

• JavaScript SDK for web applications.
• iOS SDK for native iOS mobile apps (including iPhone and iPad).
• Android SDK for native Android mobile apps is planned for a future release.

Follow the platform-specific installation instructions to include the SDK within your application.

Once you have a participant access token, you can utilize MyDataHelps SDK features within your application. The specific features will vary by platform, so consult the platform-specific SDK documentation for details. Examples of things you can do include:

• Get participant demographics and device data.
• Launch surveys.
• Connect external accounts, such as FitBit or Electronic Health Records.