Vitals™ SDK Documentation

Appearance

Quick Start Guide for JavaScript ​

The quickest and simplest way to kickstart your journey with the JavaScript SDK is by downloading and experimenting with our sample code. Additionally, you should follow this quick start guide to swiftly create your first vital sign app with JavaScript.

After you've completed this guide, we strongly recommend you to follow our Software Development Guide to guarantee accurate and reliable health reports generated by the Vitals™ SDK.

SDK Installation ​

Please follow the instructions in the Downloads page to install and integrate the JavaScript SDK into your project.

Camera Setup ​

As outlined in Integrating Vitals™ Health Assessment (VHA), the first step is to setup the camera. To begin, create a new project and follow the instructions below.

Vital Sign Camera ​

As described in Vital Sign Camera, in Vitals™ SDK, we provide a tailor-made camera component, named Vital Sign Camera. To set it up, in the index.html file, declare the video HTML element. For example:

html
<video id="video" autoplay="true" playsinline></video>

If you are using the vital-sign-camera.umd-X.X.X.js script for SDK installation (as mentioned in Downloads), in your JavaScript or TypeScript file, import the module components using the following code:

js
const { createVitalSignCamera, ServerId, Gender, GetHealthStage } = VitalSignCameraUMD;

Else, use the following code to import the module, make sure the package name is the same as what is described in the package.json file:

typescript
import { createVitalSignCamera, VitalSignEngineConfig, UserInfo, Gender, ServerId, VideoFrameProcessedEvent, GetHealthStage } from "ts-vital-sign-camera";
js
import { createVitalSignCamera, Gender, ServerId, GetHealthStage } from "ts-vital-sign-camera";

Create the Vital Sign Camera component and bind it to the video element:

typescript
/* Vitals™ Cloud Service Config */
const config : VitalSignEngineConfig = {
    serverId: ServerId.AwsProdEnterprise,
    apiKey: "__YOUR_API_KEY__",
}

window.onload = () => {
    /* Create and initialize Vital Sign Camera */
    const video = document.querySelector("video")!;
    const cam = createVitalSignCamera({ isActive: true, config })
    cam.bind(video)
}
js
/* Vitals™ Cloud Service Config */
const config = {
    serverId: ServerId.AwsProdEnterprise,
    apiKey: "__YOUR_API_KEY__",
}

window.onload = () => {
    /* Create and initialize Vital Sign Camera */
    const video = document.querySelector("video");
    const cam = createVitalSignCamera({ isActive: true, config })
    cam.bind(video)
}

Resize the camera preview in the CSS file in case it is too large for you:

css
#video {
	width: 640px;
	height: 480px;
}

TIP

In the above example, the string __YOUR_API_KEY__ should be replaced by your own API Key. Please contact us to obtain your API Key, which is the credential for accessing the Vitals™ Cloud Service.

Run the app, you should be able to see the camera preview now. For more details on system and camera setup, please refer to Camera Setup.

Acquire Health Profile ​

As outlined in Integrating Vitals™ Health Assessment (VHA), user data and medical history data have to be gathered to obtain personalized health insights and enhance the accuracies of measurements.

In the JavaScript or TypeScript file, you can provide the user information gathered by supplying them to the userInfo property in the createVitalSignCamera function.

typescript
const userInfo : UserInfo = {
    age: 30,
    gender: Gender.Male,
    userId: '__YOUR_USER_ID__',
}

// ...

/* Update this line to provide the user info to Vitals™ SDK */
const cam = createVitalSignCamera({ isActive: true, config, userInfo })
js
const userInfo = {
    age: 30,
    gender: Gender.Male,
    userId: '__YOUR_USER_ID__',
}

// ...

/* Update this line to provide the user info to Vitals™ SDK */
const cam = createVitalSignCamera({ isActive: true, config, userInfo })

TIP

In the above example, the string __YOUR_USER_ID__ should be replaced by your own User ID. Please contact us to obtain your User ID, which specifies the subscription plan for the Vitals™ Cloud Service. The set of vital signs obtained from a scan varies depending on the licensed subscription plan, with each plan offering a unique set of vital signs.

For more details, please refer to the Acquire Health Profile page.

Scan Vital Signs ​

To start a scan, you can simply call the startScanning() API of the Vital Sign Camera component.

First, create a start button in your HTML file to initiate a scan:

html
<button id="startButton">Start Scanning</button>

In your JavaScript or TypeScript file, setup the click event listener, and call the startScanning() API:

typescript
/* Update the onload event handler function */
window.onload = () => {
    // ...

    /* Start scanning if start button is pressed */
    const startButton = document.querySelector('#startButton')!;
    startButton.addEventListener('click', () => {
        cam.startScanning()
    })
}
js
/* Update the onload event handler function */
window.onload = () => {
    // ...

    /* Start scanning if start button is pressed */
    const startButton = document.querySelector('#startButton');
    startButton.addEventListener('click', () => {
        cam.startScanning()
    })
}

After calling the API, the component will start scanning the face from the camera for about 30 seconds. And vital signs will be returned upon successful scan. You can log the scanning progress and observe any error by the onVideoFrameProcessed callback function. This callback function delivers processing results at a rate of 30Hz per second (The rate depends on the frame rate of the camera).

typescript
/* Update the onload event handler function */
window.onload = () => {
    // ...

    /* Handles the Vital Sign Camera events */
    cam.onVideoFrameProcessed = (event : VideoFrameProcessedEvent) => {
        const healthResult = event.healthResult;
    
        /* Print the scanning stage & remaining seconds if the scan is in progress. */
        if (healthResult?.stage != GetHealthStage.Idle) {
            console.log(`Scanning Stage=${healthResult?.stage}, Remaining Seconds=${healthResult?.remainingTime}`)
        }
        /* Print error if any */
        if (healthResult?.error) {
            console.log(healthResult.error)
        }
    }
}
js
/* Update the onload event handler function */
window.onload = () => {
    // ...

    /* Handles the Vital Sign Camera events */
    cam.onVideoFrameProcessed = (event) => {
        const healthResult = event.healthResult;
    
        /* Print the scanning stage & remaining seconds if the scan is in progress. */
        if (healthResult?.stage != GetHealthStage.Idle) {
            console.log(`Scanning Stage=${healthResult?.stage}, Remaining Seconds=${healthResult?.remainingTime}`)
        }
        /* Print error if any */
        if (healthResult?.error) {
            console.log(healthResult.error)
        }
    }
}

Run the app, with your face centered in the camera frame, click the "Start Scanning" button. Move your face out of the camera frame to simulate a "face lost" error. You should see something similar to this in your console:

Scanning Stage=1, Remaining Seconds=22.115000000000002
Scanning Stage=1, Remaining Seconds=22.079
Error: face lost

For more details on handling the scanning process, please refer to the Scan Vital Signs page.

Get & Display Health Results ​

The Vital Sign Camera component returns the health results by the onVideoFrameProcessed callback function. In the example code below, it checks if the heart rate is ready, and display it in the console if it is ready.

typescript
/* Update the onload event handler function */
window.onload = () => {
    // ...

    /* Update the onVideoFrameProcessed callback function */
    cam.onVideoFrameProcessed = (event : VideoFrameProcessedEvent) => {
        const healthResult = event.healthResult;
    
        // ...

        /* Obtain the heart rate result */
        if (healthResult?.health?.vitalSigns.heartRate) {
            console.log(`Heart Rate=${healthResult?.health?.vitalSigns.heartRate}`)
        }
    }
}
js
/* Update the onload event handler function */
window.onload = () => {
    // ...

    /* Update the onVideoFrameProcessed callback function */
    cam.onVideoFrameProcessed = (event) => {
        const healthResult = event.healthResult;
    
        // ...

        /* Obtain the heart rate result */
        if (healthResult?.health?.vitalSigns.heartRate) {
            console.log(`Heart Rate=${healthResult?.health?.vitalSigns.heartRate}`)
        }
    }
}

Run the app and perform the scan, after 30 seconds, you will be able to see the heart rate result like this:

Scanning Stage=2, Remaining Seconds=0.49899999999999967
Heart Rate=78.83117164786404
Scanning Stage=2, Remaining Seconds=0.46799999999999997
Heart Rate=78.83117164786404

There are more vital signs available in the Vitals™ SDK and we also provide health result interpretation guides. For more information, please refer to the Get & Display Health Result page.


🎉🎉🎉 Congratulations! 🎉🎉🎉

You have completed your first Vitals™ application!


WARNING

This guide only provides you the minimum viable product (MVP) using our JavaScript SDK, there are still more features and more things to do to ensure an accurate and reliable measurements by our Vitals™ Cloud Service. For example: performing Conditions Check, using the Signal Quality metric, and more. Please refer to the Software Development Guide page, the sample code, or the API reference for further details.

Copyright © 2021-present PanopticAl Ltd. All Rights Reserved.