Integration guidelines
Last updated
Last updated
This section of the customer portal explains how to integrate IntelliProve's Engine into your platform 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. Throughout the article a demo application is used as an example for the user interface. The importance of the different steps in the process is clarified. Actions and UI elements that can facilitate the process for the end user and improve the user experience are also discussed, these can serve as a guide for integration.
The IntelliProve Engine is built to be integrated into any existing platform and is thus offered through a compatible SDK or through its API. The mobile application mentioned further on only serves as an example of how you can integrate the solution into your own mobile app, web app or software. If you've been in touch with us before and want to easily test out our product before starting an actual integration, you can get temporary access to the mobile app. Don't hesitate to reach out to your point-of-contact to request access.
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 SDK's automatically perform this step for you. If you're using the API, the check conditions endpoint can be used.
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.
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.
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.
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.
Upload video
With the obtained URL and authentication info, the video can now be uploaded using the Upload video endpoint.
Process video
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.
When the processing is done, the results are securly stored in a database and the video file is removed. For more information about how we treat privacy and how we handle your data, refer to the Privacy policy
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.
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.
