Service Details

Some additional technical details about Web Measurement Service follow.

Call-in URL Structure

The user is redirected to WMS via the following URL structure:

https://awe.na-east.nuralogix.ai/c/[CONFIG_ID]/[PROFILE_DATA]/[DFX_AUTH_TOKEN]/[DFX_REFRESH_TOKEN]/[SESSION_ID]

URL Parameter	Description
`CONFIG_ID`	The assigned configuration ID
`PROFILE_DATA`	Base64 encoded value of the encrypted profile information
`DFX_AUTH_TOKEN`	The authorization token (`Token`) obtained by calling the registerLicense endpoint with the assigned license key
`DFX_REFRESH_TOKEN`	The refresh token (`RefreshToken`) obtained by calling the registerLicense endpoint with the assigned license key
`SESSION_ID`	ID assigned by you to this measurement session

Note

Please note that PROFILE_DATA, DFX_AUTH_TOKEN and DFX_REFRESH_TOKEN need to be encoded using encodeURIComponent() while constructing the call-in URL.
All the parameters in the call-in URL are mandatory.

`PROFILE_DATA` object structure

Example PROFILE_DATA JSON object:

{
  "identifier": "B748FD3B-DF16-4963-A654-48A9574C1059", // [Partner ID (a 2 to 148 characters long string) used by you to tag this measurement]
  "age": 44,
  "height": 175,
  "weight": 89,
  "gender": "male",
  "smoking": "0",
  "bloodpressuremedication": "0",
  "diabetes": "type2"
}

Note

Both keys and values used in the PROFILE_DATA JSON object must be lowercase. Also, please make sure that the keys are exactly the same as shown in the example above.

For more information about the questions that are included as part of the measurement questionnaire and their impact on the measurement, please refer to the Measurement Questionnaire section.

For more details about identifier/Partner ID, please refer to this page in the DeepAffex Developer Guide.

The PROFILE_DATA object will be encrypted using a public key to protect the privacy of the user. The corresponding private key will be used by WMS to decrypt it.

Config ID

The CONFIG_ID provided by NuraLogix to you will contain app specific information such as:

Config element	Description
DeepAffex Study ID	ID for the DeepAffex Study to be used during the measurement. You can get it from the DeepAffex Dashboard. Under the Studies, select Details. Study Index is the Study ID.
Organization logo URL	Publicly hosted URL for the logo to be displayed on WMS. The recommended format is a 150 x 55-pixel PNG with a transparent background. Only PNG and JPEG formats are supported.
Header image URL	Publicly hosted URL for the header image to be displayed on the measurement screen on desktops. The image needs to be hosted on a publicly accessible URL. Only PNG and JPEG formats are supported. The minimum image width is 640px, and height is applied dynamically, but it is recommended not to have an image with too much height to avoid scrolling on the measurement screen. Please refer to End User Walkthrough for an example of how header image looks like.
CALLBACK URL	URL where WMS will send the results after the measurement is complete. The callback URL is hosted by you.
CSS file URL	Publicly hosted URL for the stylesheet to customize the styling of the measurement screen.
Default language	Default language from the supported languages list to be used for WMS. If not set, then the browser's active language is used if it is one of the supported languages.
Camera Auto start	If enabled, camera will start automatically. User won't see the start camera button.
Measurement auto start	If enabled, measurement will start automatically. User won't see the start measurement button.
Default camera on mobile	Allows rear camera to be selected as default camera on mobile devices.
Expire token after measurement	If enabled, the token will expire after the measurement is completed. By default, it is disabled.
Region for data processing	Allows to process the data in a specific region. Please refer to the regions chapter for more details.
Webhook URL	URL where the WMS will send the Webhook events.
Settings URL	An endpoint at your end to override the Config settings. It will allow you to enable results encryption and share your public key with us.
Page title	This string is displayed in the browser’s title bar or the page’s tab.
Hide histograms	If enabled, the histogrms will not be visible on the measurement page during the scan.
Show logs	If enabled, a browser tools widget is visible on the measurement screen to allow users to view and capture browser logs easily. It is mostly useful for debugging purposes only.

Results

The results are also encoded using JSON. A snippet is shown below.

{
    "identifier": "B748FD3B-DF16-4963-A654-48A9574C1059", // [Partner ID sent in PROFILE_DATA object],
    "MEASUREMENT_ID": "[DeepAffex Measurement ID that uniquely identifies this measurement]",
    "SESSION_ID": "[Session ID passed in via call-in URL]",
    "statusId":"COMPLETE",
    "HR_BPM": 76,
    "SNR": 5.6,
    "BR_BPM": 20,
    "BP_DIASTOLIC": 120,
    "BP_SYSTOLIC": 80,
    ...  // Other signals in the study
}

It will always contain the identifier, MEASUREMENT_ID, SESSION_ID and statusId keys which correspond to the PartnerID, MeasurementID, SessionID and StatusID respectively. The results themselves will be returned with keys corresponding to the Signal IDs present in your DeepAffex Study. To check the results:

Get a list of Signal IDs for your app using the Studies.Retrieve endpoint
- If you are always going to use the same study, you can embed this list in your app
- If you intend to change studies at runtime, you can call that endpoint in your app (usually right after switching studies)
Use these Signal IDs as keys to look for results. If a key is not present in the results, then that result could not be computed by the DeepAffex Cloud. This can happen if:
- The signal quality is too low. In this case, the SNR key, will be present and it will be negative.
- Some demographic information wasn't sent to the Cloud or
- Some other issue was encountered during computation - you can investigate using the DeepAffex Dashboard etc.

Note

Detailed measurement results can also be retrieved later by using our API if your legal agreement with Nuralogix allows saving results. Please refer to the results section here for more details. Please note that the authorization token gets expired in a certain amount of time (10 mins is the default value in the sample app). If your token has expired then you must call Auths.Renew endpoint to get a fresh pair of tokens before trying to retrieve the results from the API. If you lose the authorization token, then the only way to retrieve the measurement results through API is by calling the Organizations.RetrieveMeasurement endpoint. In addition to this, you may also directly see the results from the dashboard.

⚠️ Deprecated keys ⚠️

The following keys are currently returned in the results object but are deprecated. Please do not rely on them as they will be removed in future versions of WMS.

Deprecated Key	Signal ID to use instead
`absi`	`ABSI`
`age`	`AGE`
`bmi`	`BMI_CALC`
`breathing`	`BR_BPM`
`cardiacWorkload`	`BP_RPP`
`cvdRisk`	`BP_CVD`
`DiabetesRisk`	`DBT_RISK_PROB`
`diastolic`	`BP_DIASTOLIC`
`healthScore`	`HEALTH_SCORE`
`heartAttackRisk`	`BP_HEART_ATTACK`
`heartRateVariability`	`HRV_SDNN`
`HypercholesterolemiaRisk`	`HDLTC_RISK_PROB`
`HypertensionRisk`	`HPT_RISK_PROB`
`HypertriglyceridemiaRisk`	`TG_RISK_PROB`
`irregularHeartBeats`	`IHB_COUNT`
`msi`	`MSI`
`ppm`	`HR_BPM`
`snr`	`SNR`
`strokeRisk`	`BP_STROKE`
`systolic`	`BP_SYSTOLIC`
`waistToHeight`	`WAIST_TO_HEIGHT`

Handling Errors

In case the Web Measurement Service faces an issue, or if there are any validation errors in the profile data, the measurement will fail and the user will be redirected to the CALLBACK_URL with an error parameter in the query string that contains the error code.

Error Code	Description / Cause
THIRD_PARTY_SETTINGS_FETCH_ERROR	The Settings URL endpoint did not respond, or provided invalid values.
PROFILE_DECRYPTION_ERROR	There was an error while decrypting the `PROFILE_DATA` object.
TOKEN_RENEWAL_FAILED	Token couldn't be renewed due to invalid or expired token provided.
ORG_DETAILS_FETCH_ERROR	There was an error in fetching `ORG` details.
PROFILE_VALIDATION_FAILED	The profile data validation failed due to out of range values provided for age, height or weight. Also occurs if provided height and weight lead to an out of range Calculated BMI.
MEASUREMENT_CANCELED	The measurement was cancelled by the user.
TOKEN_EXPIRED	The authorization token has expired.
WORKER_ERROR	An error occurred in the DeepAffex Cloud while processing a payload.
MEASUREMENT_TIMED_OUT	If, after sending a chunk or while waiting for the final results, no response is received from the API for 60 seconds due to network issues, this error is returned.
CAMERA_PERMISSION_NOT_GRANTED	Camera permission was denied by the user.
NETWORK_ERROR	Network related error occurred while communicating with the DeepAffex Cloud.
UNEXPECTED_ERROR	An unexpected error occurred while fetching or parsing `Config` object.
FAILED_INIT_BLOOD_FLOW	Facial blood-flow collector failed to initialize.

For acceptable value ranges for age, height, weight, and BMI please refer to the Measurement Questionnaire section.

Error Details

In case of an error, the CALLBACK_URL will also include a details parameter containing more information related to the error. The error details are Base64 encoded. An example of a decoded error details is as follows:

{
  "measurementId":"c5131e45-423f-41e2-bfaa-1c8ca162e32c",
  "starRating":1,
  "errorTimeSeconds":30.11
}

In the above example:

The starRating means the star rating at or just before the error.
The errorTimeSeconds means the number of seconds passed after starting the scan before the error is encountered.

Note

Please note that more keys may be added to results JSON and additional error codes may also be introduced in the future as we keep improving our service. It is important to handle the response in the CALLBACK_URL with these potential changes in mind to ensure your integration remains robust and reliable. We recommend regularly reviewing the documentation and testing your integration to stay up-to-date with any changes.

Supported Languages

Following languages are currently supported by WMS:

English
Simplified Chinese
Italian
French
Spanish
Portuguese
Brazilian Portuguese
Japanese
German

It is possible to fix a language to be used for WMS through the CONFIG_ID. Please reach out to us if you want to exercise this option. WMS follows the following order to decide the language to be used for the service :

Language selected through CONFIG_ID
Browser's active language if it is one of the supported languages given above
English

NuraLogix Web Measurement Service