Partner Resources
This document will guide you step-by-step in the creation of a simple client-side HTML page to host Curai Health’s (“Curai”) patient experience using our Web SDK to provide care to your patients. This guide also covers the basics of using the Curai API to implement the Curai patient experience in your mobile application(s).
Glossary
clientID
A unique string that Curai uses to identify your organization. You will also receive this from your Curai Customer Success representative.
Access token
An access token is a string that is used to make API requests on behalf of a patient. The access token represents the authorization to access the Curai application and specific parts of the patient’s data.
WebView
A way of displaying a web application inside a native mobile application. Similar to an iFrame.
Patient
The individual customer of your organization — the end user of the Curai patient experience.
NPM
NPM is an online repository for the publishing of open source JavaScript projects as well as a command-line utility for interacting with said project that aids in package installation, and version/dependency management.
Authenticating with Curai Health
The Curai Web SDK requires an access token. You will need to call the register-patient endpoint to generate this access token.
You will need to supply your API Key as an HTTP header with your request to the register-patient endpoint. Please speak to your Curai Customer Success partner if you do not have this key.
unique_id is the unique id for how you identify this user in your system.
primary_account_holder_unique_id is the unique id in your system for the parent of this user. This is used to indicate that the specified user is a dependent of another user. If the user being registered is not a dependent of another, simply use the unique_id of the user in this field.
Note: All of the remaining demographic fields in this example are required, as they are necessary for us to create a new patient record in Curai for your user.
Curl example
curl -X 'POST' \
'https://gateway.staging.curaihealth.com/partner/register-patient' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <YOUR_API_KEY>' \
-d '{
"patient": {
"unique_id": "8d979517-fa9e-48bf-a210-e632a83ab043",
"first_name": "Ryan",
"last_name": "Ward",
"date_of_birth": "1986-10-12",
"sex": "male",
"state": "CA",
"email": "rward@example.com",
"phone": "5555551212"
},
"primary_account_holder_unique_id": "8d979517-fa9e-48bf-a210-e632a83ab043"
}'
Curl Response
{
"access_token":"ac70fd41bddcc6f1390e63ef46e4ffd158b92b97ba73a13913990969cc43e202"
}
Installing the SDK
By way of example, we are going to create a simple HTML page to host the SDK:
<html>
<head>
<title>Curai Health SDK Quick Start</title>
</head>
<body>
<h1>Curai Health SDK Quick Start</h1>
<div id="”embedded-chat”" />
</body>
</html>
Installing the SDK into the HTML page
Using an HTML <script> tag
Next, we need to embed the Curai patient experience into the page. Right after the title tag, insert the following code, which will make the patient experience available for use:
<script crossorigin type=“text/javascript” src=”https://unpkg.com/curai-js"></script>
Using the Curai NPM package for JavaScript applications
For your convenience, Curai provides a public NPM package that contains everything you need to embed the Curai patient experience in your JavaScript application.
Adding a placeholder element for the patient experience
After installing the SDK, you’ll need an HTML element to attach the patient experience to. In our example code above, you can see a simple HTML <div> element with an id of embedded-chat. You can give your element any identifier you choose, but make sure to alter your initialization script in the step below to take that into account.
Initialization
Once the Web SDK has been properly implemented and you have a placeholder for the patient experience, we can initialize the Curai service immediately.
To proceed, add a new script tag to the HTML page with the following content (don’t forget to replace the clientId and accessToken variable values with your clientID and previously-generated access token):
<script type="text/javascript">
Curai.startChatSession(
clientId,
accessToken,
{parentElement: document.getElementById(“embedded-chat”)}
)
.then(frame => {
// A valid session has started and the frame element is returned
})
.catch(err => {
// An error has occurred
});
</script>
The Curai.startChatSession method will be executed once the Web SDK has successfully loaded, creating an instance of the service, and receiving the following optional parameters:
The boolean `testMode` which directs to staging if true. The default is false, pointing to production. This allows you to specifically target the staging environment for integration and testing purposes.
The `parentElement` which, if provided, will be the HTML/DOM element that the Curai patient application instance is appended to. Otherwise, the new application instance will simply be appended as a child of document.body. Use this to specify a “container” or “placeholder” in your application/page layout that will be replaced by the Curai patient application.
Event Listeners
If you want access to events generated from the embedded client there are a number of provided listener helpers.
One such helper is Curai.onError, this will be called when an error occurs in the embedded client and passed along to the SDK. This could be used to inject errors into any custom logging solution you might employ.
Curai.onError((msg) => {
// Pass onto custom logging solution
});
Complete Web Application Example Source Code
For your convenience, below is the full source code for the web example:
<html>
<head>
<script crossorigin type="text/javascript" src="https://unpkg.com/curai-js"></script>
<title>Curai Health SDK Quick Start</title>
</head>
<body>
<h1>Curai Health SDK Quick Start</h1>
<div id="”embedded-chat”" />
</body>
<script type="text/javascript">
Curai.startChatSession(clientId, accessToken, { parentElement: document.getElementById("embedded-chat") })
.then((frame) => {
// A valid session has started and the frame element is returned
})
.catch((err) => {
// An error has occurred
});
</script>
</html>
Mobile-specific Instructions
The use of the Curai SDK to embed the Curai patient application into your native mobile applications for iOS and Android is quite similar to how it is used with web applications.
Regardless of the development platform you use for your mobile application, you will need the ability to call our register-patient endpoint to retrieve an access token using your API key.
We do not provide platform-specific SDKs at this time. Please use our convenient Postman documentation for instructions on how to use the Curai API.
You will then need to use a WebView or similar construct (similar to an iFrame) to seamlessly embed the web-based Curai patient experience into your mobile application.
You will pass the clientId and the access token returned by the register-patient endpoint into the patient experience by including them as querystring values. This allows us to bootstrap the Curai application with information about your customer, registering them if they are new to Curai, or signing them in if they are a returning customer.
https://customer.curaihealth.com?clientId=MY_ID&accessToken=MY_TOKEN
You should now see the Curai application embedded in your mobile application as though it were part of your native application.
