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. |
| 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 |
Callback
WMS will use the pre-configured CALLBACK_URL to pass back results to your app.
The results are passed as a Base64 encoded JSON object query string, along with
the SESSION_ID that your app passed to WMS at call-in.
Example callback URL:
https://thirdparty.com/example/measurementComplete?ai.nuralogix.nura.results=<<base64encoded>>
If you are using CNAME, then the callback URL should not be a subpath of the CNAME.
For example, if measurement.domain.com is the CNAME, then the callback URL must
not be of the form measurement.domain.com/results. This is required because
the callback URL is hosted at your backend, whereas CNAME points towards the WMS.
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 |
|---|---|
| MISSING_MEASUREMENT_IDENTIFIER | The identifier field is missing in the PROFILE_DATA object |
| INVALID_AGE | The age value is invalid. |
| INVALID_WEIGHT | The weight value is invalid. |
| INVALID_HEIGHT | The height value is invalid. |
| INVALID_BMI | The given values for weight and height represent an invalid BMI value. |
| MEASUREMENT_CANCELED | The measurement is 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 is denied by the user. |
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