Eliminate the use of alert() to improve User Experience and uniformize how information is displayed

Issue

AR.js requires certain browser functionalities (e.g. webrtc) and permissions (e.g. permission to access camera) to be available for an AR.js application to work properly. When these functionalities are not available in a browser or when the user does not grant the required permissions, AR.js provides an error message. The error messages provided via AR.js do not have a consistent interface: some are displayed using the browser alert() function and others using HTML elements. This lack of consistency hinders user experience. Furthermore, AR.js frequently displays multiple error messages at the same time (for example, when permissions to access camera and location are not provided, two error messages are displayed), which results in multiple alert dialogs to be displayed consecutively. It is known that such practice is not recommended for user experience reasons and the use of alert() should be avoided. Finally, by using the alert() function, application developers are not able to customize the design of how errors messages should be displayed to suit each application needs.

Requirements

• As a user, I want to be warned about errors of the application in a consistence manner that follows web usability best practices.
• As an application developer, I want errors from the AR.js library to be available in a format that allows me to customize the design of the error messages in a format that suits my custom application.

Source code files

The source code affected by this improvement are the following:

• aframe/src/location-based/arjs-webcam-texture.js
• aframe/src/location-based/gps-camera.js
• aframe/src/location-based/gps-projected-camera.js
• three.js/src/threex/threex-artoolkitsource.js

These correspond to the files that make use of the javacript alert() function.

Design of the fix

Current Implementation of errors

AR.js has two implementations for errors: 1) appending a HTML div to the document body with the error information; 2) using the alert() function.

Figure 1 - Example of error triggered by appending a HTML div to the document body with the error information

Figure 2 - Example of error triggered using alert()

The implementation 1 is more appropriate since it does not rely on the alert() function and allows for element style customization via the Id attribute. The fix we propose will use a logic similar to this implementation.

Types of errors

AR.js provides two types of errors: permanent and temporary. Permanent errors correspond to situations where AR.js cannot function and in most situations will require some action by the user (e.g. to allow camera access permissions). Temporary errors correspond to situations where the performance of a AR.js may be compromised (e.g. when GPS reception is poor the application continues to function but will have lower precision). Temporary errors may self-resolve. For example, if GPS reception improves, AR.js element positioning accuracy will return to baseline. Because of the temporary nature of these errors, they should be dynamically displayed and removed. An example of such situation is described in Figure 3:

Figure 3 – Code that dynamically adds and removes temporary errors based on whether the error condition is present or not.

Number of permanent errors displayed

AR.js may trigger more than one permanent error in a given moment. We believe that errors messages should be displayed in a single element instead of in multiple elements that would pop-up on the application – for better usability.
Considering this, we evaluated two options:

1. Adding multiple error messages in a single element: this would result in multiple errors messages (if existent) to be displayed the error element.
2. Only displaying the first error message: this would result in only the first error message to be displayed in the error element and all other messages to be ignored. We opted for option 2 because of two reasons: adding multiple errors messages to the error element could result in too much information for the user to process and because permanent error messages require some action by the user, thus we believe it is more appropriate for the user to receive one message at a time and perform the action the may be required, instead of receiving several messages and having to perform several actions. From the above, we define the following technical requirements:

• Errors shall be displayed by creating a HTML div and appending it to the document body and shall include a Id attribute to enable manipulation of the element
• Two types of errors shall be support: permanent errors and temporary errors.
• A maximum of 1 error message for permanent errors and temporary errors is displayed.

Figure 4 - State diagram of how errors are displayed.

Fix Source code

Figure 5 - Example of application showing permanent error message with custom styling, after this improvement.

Submit the fix

Pull request was submitted on the project Github page. It can be found at https://github.com/AR-js-org/AR.js/pull/270