SDK/API integration guidelines
This section of the customer portal explains how to integrate IntelliProve into your platform using an SDK or the API to perform health checks and obtain health insights. It is a good place to get started as a developer, but can also be useful information if you are a UI designer. We cover:
- Throughout the article a demo application is used, which can serve as an example for the user interface.
- The importance of the different steps in the process is clarified, and links to relevant API or SDK's are mentioned.
- Actions and UI elements that can facilitate the process for the end user and improve the UX are discussed.
The first step in the process is to inform the user about the measurement. It is good practice to explain to the user what the health scan does and how they should correctly perform it. Refer to the Usage instructions for a comprehensive overview. When integrating our product into your own platform or app, we recommend also showing these instructions to the user, in order to increase the chance of them passing the check for conditions. We come back to this in the next step.
After going through the information screen, the health scan screen becomes visible. Here, the user can start the health scan by e.g. pressing a start button.
When pressing the start button, the recording setup should first be reviewed. This check, also referred to as 'quality check', ensures that the recording setup meets a few requirements for a qualitative measurement. This includes, for example, checking if there is sufficient lighting, checking the face-camera distance or analyzing the user's motion. The check is performed based on a single frame of the user's face.
The response of the request can be used to show relevant instructions to the user when the conditions are not met. In that case, the UI element that outlines the face - the indicatory brackets - will change color in our demo app, as shown in the figure below. You can use a similar visual clue in your own platform or app. Below, you can also find a few guidelines with regards to the indicatory brackets.
UI guidelines for indicatory brackets
The quality check is blocking, in other words, the actual measurement can only be started when the check is positive, i.e. the quality conditions are met.
Below is a comprehensive list of possible outcomes of the quality check and corresponding suggested messages towards the user.
List of quality check responses
You’re in position! Ready to start / Press start!
You're too close, move further away from the camera.
You’re too far, move closer to the camera.
Positioning not good
Align and center your face with the indication frame.
Chest visibility insufficient
Your upper chest is not visible enough, make sure it’s in the indicated frame.
Head pose not good
Look straight to the camera.
Lighting not good
Good lightning is important. Make sure your face is well lit and the light is evenly spread on your face. Use the flash function if needed.
Forehead out of frame
Make sure your forehead is within the indicated frame.
Face not detected
Sorry, we could not detect a face. Make sure you are in the indication frame and lighting is good.
It seems like your forehead is covered. Make sure to clear your hair or take off hats.
When the quality check succeeds, the UI element outlining the face turns green and the app automatically starts recording. The recommended recording time is 30 seconds (also see the Video input requirements). A timer indicates the remaining recording time to the user. During the measurement, the user should keep their face still and look straight into the camera. More information on how to perform the measurement correctly can be found in the Product instructions.
We recommend adding an indication frame to guide the user to keep their face centered, as well as a countdown timer to inform the user when the health check will end.
Once the recording has been finished, the video needs to be processed.
For the user, this should be a seamless process. The app shows a loading sign while uploading the video and waiting for the results. As soon as the processing is done, the app shows the results, which is outlined in the next section.
Behind the scenes, the SDK will handle the necessary steps to process the video for you.
Process the video
If you're using the API directly without SDK, this part will require three requests:
Request a URL to upload the video
In order to register a new measurement with the cloud and have the video processed, it first needs to be uploaded to our cloud. Keep in mind that you need to have a signature from the previous step (check conditions to be able to request an upload URL). The Get Upload URL endpoint can be used to request an upload URL. The response of this request includes the URL, which will be used to upload the video; the unique identifier (UUID) for this measurement, which will be needed for the consecutive requests; and authentication information needed in the next step.
With the obtained URL and authentication info, the video can now be uploaded using the Upload video endpoint.
With the video now uploaded, a request can be sent to start the actual processing of the video. To specify which video to process, the UUID obtained before is sent as a path parameter with the request. Refer to the Process video endpoint in the API docs for more detailed information.
With the processing now finished, the results can be fetched and displayed in the app. The SDK will automatically return these. If you're using the API, use the Get results endpoint and pass the UUID in the request path parameter. The results are returned in json format. The demo app displays the results as shown below. You can find information about the values that are returned in the response in the Insights & biomarkers page.
IntelliProve provides you with the freedom to customize your results to suit your specific requirements. You can connect it to a data model, conduct training verification, or use it to offer advice on therapy or products. The possibilities for customization are endless, but it's important to keep in mind some key considerations.
- When the video recording does not meet the minimal video input requirements, IntelliProve may be unable to provide qualitative results. As a commitment to maintaining a quality-first approach, we refrain from delivering results when accuracy cannot be guaranteed. In these cases we advice our customer to not abruptly stop the user flow but implement a graceful backup-flow.
- If a measurement fails and there is no option to redirect the user to an alternative next step, it is imperative to present a clear message to the end user. This message should not only explain why the measurement failed but also outline the available options for achieving success. The SDK or API response will return an error code in the response, which you can use to provide an explanation to the user. The table below gives an overview of the possible error codes.
Table of error codes with explanation
If the measurement was successfully processed, you will receive the biomarkers in json format.
However, in case the video recording did not meet the minimum input requirements, one of the below error codes will be returned, explaining why the video could not be processed.
The device or camera lacks the necessary performance for conducting a high-quality health scan. We recommend using another device with a better quality camera
The video is not long enough
The video does not meet the minimal FPS threshold.
The video codec is not in the list of supported codecs.
The video bitrate does not meeting our minimal bitrate threshold.
A face could not be accurately detected in the video.
Insufficient skin is visible, e.g. due to the face being partially covered, making an accurate health scan unfeasible.
The subject's face (partially) moved out of frame during the recording.
Something unexpected happened. We will look into this.