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 |
Please note that PROFILE_DATA, DFX_AUTH_TOKEN and DFX_REFRESH_TOKEN
need to be encoded using encodeURIComponent() while constructing the call-in URL.
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"
}
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. |
| 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. 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]",
"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 and
SESSION_ID keys which correspond to the PartnerID, MeasurementID and SessionID
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.Retrieveendpoint- 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
SNRkey, 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.
- The signal quality is too low. In this case, the
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 invalid or out of range values. |
| 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. |
For acceptable value ranges for age, height, weight, and BMI please refer to the Measurement Questionnaire section.
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
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