Message events
To keep your app informed about the user's progress within the plug-in, we transmit data via message events at various stages. This document describes the different types of events, when they are sent, and their data format. The events are in JSON format and contain information about the health check's progress and the final results.
Make sure you've gone through the following documentation:
To learn how to listen for these data messages in web apps, refer to the Listening to message events page.
We currently distinguish the following events:
- RecordingStarted
- RecordingStopped
- Results
- Buckets
- BucketSummaries
- UserFinished
- Dismiss
- Error (informative)
The diagram below illustrates the different stages within the recording screen and the corresponding events triggered.
![Document image Document image](https://images.archbee.com/_0R_DnpmBBLLXmaoWvG2u/SDC6YBPxE-_7kaFj8sMGd_image.png?format=webp)
Upon reaching the recording screen, users encounter the camera stream along with a start button. Pressing the start button initiates the quality-checking process. If the conditions are favourable and the check passes, the actual recording starts and a Recording Started event is sent. The timer begins counting down, and upon reaching zero, the measurement concludes, prompting a Recording Stopped event. The subsequent events depend on the outcome of the measurement.
If the measurement is successful, three events containing the health check results are sent: Results, Buckets and BucketSummaries.
However, there might be instances where the quality deteriorates too much during the health check, rendering an accurate assessment unfeasible. For instance, this could occur if the lighting abruptly dims. In such cases, an 'Error' event is sent and users are presented with two choices: they can restart the health check by selecting the ‘try again’ option, or they can opt to conclude the health check without completing it successfully by clicking the ‘continue’ button. Choosing the 'try again' option brings them back to the start of the health check process. If they select the 'continue' option, no biomarker results will be generated, and a userFinished event will be sent.
The dismiss event is sent whenever the web plugin should be closed.
The event types are further explained in detail below.
Sent when the user clicks the record button and the timer starts.
Event Data
- stage: "recordingStarted"
- uuid: health check UUID
Sent when the recording stopped, i.e. the recording timer ends.
Event Data
- stage: "recordingStopped"
- uuid: health check UUID
The results of the health check in their most basic form, listing the extracted biomarker values.
Sent after the recording is completed. This takes between 1 to a maximum of 20 seconds after the recordingStopped event.
IntelliProve calculates the following biomarkers:
- heart_rate: Heart rate in beats per minute
- respiratory_rate: Respiratory rate in breaths per minute (nullable)
- heart_rate_variability: Heart Rate Variability or HRV in milliseconds
- ans_balance: Balance of autonomous nervous system, dimensionless
- resonant_breathing_score: Resonant Breathing score in percentage
- morning_readiness: Morning Readiness score, dimensionless (only available between morning hours)
- acute_mental_stress_score: Acute Mental Stress Score, dimensionless
- mental_health_risk: Mental Health Risk as enumerator 1 ("low"), 2 ("medium") or 3 ("high")
For more info on how to interpret these values, please refer to our Insights & biomarkers documentation.
Please note that one or more biomarker values may be unavailable if the measurement quality is insufficient or if not relevant for the current time of the day (e.g. morning readiness). Biomarkers of such are set to null.
In addition to the biomarkers we also provide the timestamp and epoch properties representing both an ISO and integer (UTC) representation of the time of the measurement.
Event Data
- stage: "results"
- uuid: health check UUID
- patient: (nullable) Patient reference, initially passed in the web plug-in URL
- performer: (nullable) Performer reference, initially passed in the web plug-in URL
- data: Results data object
The biomarker buckets provide the results in an alternative format, grouping them in logical sets and providing more context to the values in each set (bucket).
Sent after the recording is completed. This takes between 1 to a maximum of 20 seconds after the timer ends.
IntelliProve offers a holistic approach to well-being by organizing information into distinct buckets; i.e. physical health, mental health, sleep and energy, and mindfulness.
Each bucket has the following properties:
- The name distinguishes the specific bucket. A list of the currently available buckets: "physical", "mental", "energy_sleep", "mindfulness".
- The timestamp and timestamp_epoch properties present both an ISO and integer (UTC) representation with the time of the measurement.
- The biomarkers represent a list of selected biomarkers relevant to the specific bucket.
- The status indicates the overall users' health state for the current bucket, based on the biomarker values. We define three different states: "good", "neutral" and "bad".
Each biomarker consists of the following properties:
- The value is the actual numerical value obtained for the biomarker during the health check. It can be an integer or a floating point number.
- The range represents the entire span of possible values for that the biomarker, indicated by minimum and a maximum.
- The zone indicates where the biomarker value falls among three categories "good," "neutral," and "bad", which relates to health condition.
- The optimum defines how the range should be interpreted and visualized. There are three possible values for optimum: "low," "high," and "middle."
- For "low": Lower values are categorized as "good" (green color), while higher values are categorized as "bad" (red color)
- For "high": Higher values are categorized as "good" (green color), while lower values are categorized as "bad" (red color).
- For "middle": The "good" zone (green color) is centered around the middle of the range. Values lower or higher than this midpoint are categorized as "bad" (red color).
![Document image Document image](https://images.archbee.com/_0R_DnpmBBLLXmaoWvG2u/d15PzMYiUOFLIHC4qJEoc_group-123.png?format=webp)
For each bucket, we provide personalised feedback and tips tailored to their specific values. Learn more about this in the next event type.
Event Data
- stage: "buckets"
- uuid: health check UUID
- patient: (nullable) Patient reference, initially passed in the web plug-in URL
- performer: (nullable) Performer reference, initially passed in the web plug-in URL
- data: Buckets data object
For each bucket, we also provide a human-readable representation of the results in the format of personalised feedback (summary) and tips.
Sent after the recording is completed. Since feedback and tips are generated on the fly, it takes some additional time before this event is sent. Expect up to 5 seconds extra.
Event Data
- stage: "bucketSummaries"
- uuid: health check UUID
- patient: (nullable) Patient reference, initially passed in the web plug-in URL
- performer: (nullable) Performer reference, initially passed in the web plug-in URL
- data: (nullable) Buckets summaries data object
Occasionally, the conditions may deteriorate while performing the health check, making an accurate health assessment unfeasible. For instance, this might happen if the lighting suddenly gets very dim. In such instances, users are presented with two choices: they can restart the health check by selecting the ‘try again’ option, or they can opt to conclude the health check without completing it successfully by clicking the ‘continue’ button. If they select the latter option, no biomarker results will be generated. We will notify you of this outcome with a “userFinished” event.
This event is also sent when the user's device does not have a camera or when the necessary permissions to access the camera have not been granted.
Sent in the situation where the user ends the health scan without successfully performing a measurement.
Event Data
- stage: "userFinished"
- data: Reserved for future use
We will notify you with a "dismiss" event when the web plugin can be closed. This can be because of the following reasons:
- The user chose to abort the health check without starting it, i.e. by clicking the "return" button
- The measurement is finished and the results are sent via the "results" event (only sent when not using the built-in results screen)
- The user chose to continue without performing the health scan
Sent when the web plugin should be closed.
Event Data
- stage: "dismiss"
- data: Reserved for future use
If the health check did not complete successfully, we handle the error and retry internally. For full transparency, we forward this error as an event in case your app needs to keep track of this.
Sent to inform the platform that a health check. The actual error handling is managed internally in the web plugin app.
Event Data
- stage: "error"
- uuid: health check UUID
- patient: (nullable) Patient reference, initially passed in the web plug-in URL
- performer: (nullable) Performer reference, initially passed in the web plug-in URL
- data: (nullable) Error data object