Version 2.13.6.
Back

URL scheme documentation

URL scheme documentation for Qvido version 2.13.6.

Overview

To start the Qvido app from another application of the iPad an URL with following scheme must be opened:
vzs://start-measurement?ref-id=abc123&callback-uri=https%3A%2F%2Fcustom.erp.com%2Fapi%2Fmeasurements

Optional parameters are:

  • locale, a language to override the default language of the system:
    vzs://start-measurement?ref-id=abc123&callback-uri=https%3A%2F%2Fcustom.erp.com%2Fapi%2Fmeasurements&locale=de-DE

  • dispatch-uri, it is a URI which will be opened upon successful completion of a measurement:
    vzs://start-measurement?ref-id=abc123&callback-uri=https%3A%2F%2Fcustom.erp.com%2Fapi%2Fmeasurements&locale=de-DE&dispatch-uri=app-scheme%3A%2F%2F

Regarding the callback-uri and dispatch-uri, the url encoding (percent encoding) must be applied and that is why in this example https://custom.erp.com/api/measurements results in https%3A%2F%2Fcustom.erp.com%2Fapi%2Fmeasurements.

Scheme

The scheme is vzs://.

Hostname

For creating a new measurement the hostname must be start-measurement.

Required query parameters

ref-id

ref-id stands for reference ID and is not used by the application. It is provided so that the ERP system can identify the context of the measurement (e.g. order number). The value provided must be an alphanumerical string of up to 128 characters; additionally, the hyphen “-” characters is also allowed. If these requirements are not met, the application will prompt an error message on startup, and the application will only be available without data transmission until another invocation is made.

callback-uri

This callback-uri must be an URL which points to a server reachable in an intranet or the internet, and the url encoding (percent encoding) must be applied for this parameter. The provided URL must be a resource that is reachable via HTTPS. Other protocols, for example, HTTP, will prompt an error message on startup, and the application will only be available without data transmission until another invocation is made.

After completing the measurement a HTTPS PUT request containing a JSON object will be sent to this callback-uri, specified as a parameter when invoking the app. The JSON object of the measurement result also contains the ref-id specified when invoking the app. If the status code returned by the HTTPS PUT request is not matching 2xx (e.g. invalid callback-uri) then an error banner will occur in the application. The transmission can be retried manually as often as desired until the app is closed manually.

HTTPS PUT request

HTTP Headers:

  • Content-Type: application/json
  • charset=utf-8

Optional query parameters

dispatch-uri

This dispatch-uri is optional and is opened after the measurement data is sent to the callback-uri successful. This parameter must, like the callback-uri, be url encoded (percent encoding). This way an app or a website can be opened upon completion. If this parameter is not provided the app will return to the home screen after completing a measurement.

E.g.

  • To open application: &dispatch-uri=app-scheme%3A%2F%2F
  • To open website: &dispatch-uri=https%3A%2F%2Fwww.oak.tt

locale

As a default the system settings will be used. If you want to override this language it can be done with this parameter. Following languages are currently supported:

  • en: English
  • de: German
  • fr: French
  • es: Spanish
  • it: Italian
  • pl: Polish
  • cs: Czech

ISO language codes (e.g. en-UK, en-US, it-CH, es-SV) are also supported for the languages mentioned above.

Measurement result JSON object

Structure

  • Optometry: Container for measurement results
    • LeftEye: Container for results related to the left eye (perspective from patient’s point of view)
      • PupillaryDistance(float): Measurement in millimeters of the distance monocular pupillary distance for the left eye.
      • PupilHeight(float): Measurement of the distance from the projection of the visual axis onto the lens, to the bottom of the lens.
    • RightEye: Container for results related to the right eye (perspective from patient’s point of view)
      • PupillaryDistance(float): Measurement in millimeters of the distance monocular pupillary distance for the right eye.
      • PupilHeight(float): Measurement in millimeters of the distance from the projection of the visual axis onto the lens, to the bottom of the lens.
    • Glass: Container for results related to measurements of the lens
      • Width(float): Measurement in millimeters of the width of the lens. Also known as A in the Boxing system.
      • Height(float): Measurement in millimeters of the height of the lens. Also known as B in the Boxing system.
      • Diameter(float): Measurement in millimeters of the effective diameter of the lens. Also known as ED in the Boxing system.
      • BridgeWidth(float): Measurement in millimeters of the bridge size, or distance between lens. Also known as DBL in the Boxing system.
    • PantoscopicTilt(float): Measurement in degrees of the pantoscopic tilt, which considers posture of the patient.
    • WrapAngle(float, nullable): Measurement in degrees of the frame wrap angle, also known as the panoramic angle. Can contain null as a value.
    • VertexDistance(float): Measurement in millimetres of the vertex distance.
    • FrameType(string): String denoting type of spectacles. This is the direct output of what has been selected during the usage of the application. Its possible values are: “Metal”, “Plastic”, “Nylor” and “Frameless”.
    • IsPrincipalVisualDirection(bool): If true, it denotes that during usage of the application, the toggle for Principal Visual Direction has been selected, which affects the calculation of pupil height.
  • RefId(string): String containing the value for ref-id provided as an input parameter when invoking the application.
  • AppVersion(string): String containing a major,minor,revision representation of the version of the application.
  • CreatedAt(string): String representation of a Date object with Timezone. Represents the date and time at the end of the measurement, i.e. when the data transmission to another system has begun.

Example

{
  "Optometry": {
      "LeftEye": {
          "PupillaryDistance": 31.550530328920487,
          "PupilHeight": 20.122261813275188
      },
      "RightEye": {
          "PupillaryDistance": 30.421606482735026,
          "PupilHeight": 20.739992759000067
      },
      "Glass": {
          "Width": 53.754006632024542,
          "Height": 36.750644671179835,
          "Diameter": 75.0,
          "BridgeWidth": 18.391899493087173
      },
      "PantoscopicTilt": 4.5383661409211964,
      "WrapAngle": 3.0,
      "VertexDistance": 10.230324418583375,
      "FrameType": "Nylor",
      "IsPrincipalVisualDirection": false
  },
  "RefId": "abc123",
  "AppVersion": "2.11.0",
  "CreatedAt": "2020-09-21T14:00:47.818256+02:00"
}