Bi-Directional Control

The authID Essential UI has a bi-directional interface, allowing communication between authID and hosting applications or websites.

For website integrations, the control interface can be enabled by customer request for a specific domain. When using the react-native WebView component to render the authID application, there is no domain restriction in place.

When using @authid/web-component the additional "control" attribute must be set on when the <authid-component /> is created. This control interface is available via the window.authidControl`.

<script src="webauthhandler.js"></script> `

`<script src="controlhandler.js"></script> `

\`authidControl.on()

When using @authid/react-component additionally, property "control" must be set to a callback receiving message object and the control interface - this ensures proper handling of race conditions.

For manual <iframe> integration, the control interface is also available via window.authidControl after including https://id.authid.ai/controlhandler.js.

For react-native WebView integration, the control interface is automatically loaded into the WebView context and can be called via JS injection.

🚧

controlhandler.js

Never copy the controlhandler.js to your project because it must match the current version of authID software. Therefore, it should be included by appending additional query string parameter with the transaction or operation ID to it.

Messaging

Receiving messages from authID iframe can be done using events of eventemitter3 API, like .on(), .off(), and others.

For more information, refer to

• EventEmitter3
• Node.js v21.6.0 Documentation

The 'message' is a catch-all event that receives a raw message object consisting of the type and params fields. This type is a fully distinguished event name, starting from authid:control: prefix.

It is also possible to listen for a specific message type without a full prefix, like,handler = (params) => {}; authidControlFace.on('feedback', handler); .

📘

React Component

If event handlers are rapidly added, e.g. via React component, then they must be also removed via authidControl.off(type, handler) to avoid exhausting resources and other unwanted side effects.

Available Messages

1. loaded - once authID iframe is ready for processing;

2. page - on page change with specific parameters:

   1. 'name' - page code,
   2. 'props'` - page-specific properties;

3. 'transition'` - rapidly appearing event in various cases when the screen shows or hides transition messages like "Please wait" with optional parameters:

   1. 'waiting' - Boolean  to indicate if enabled or disabled,
   2. 'reason'` - arbitrary reason code which is subject to changes,
   3. 'waitTitle'` - additional reason code;

4. 'lang'` - upon language change with specific parameter:

   1. \- 'lang' - one of the supported language codes;

5. 'flng' - raw event data from the former FaceLok SDK which is discontinued as a standalone product;

6. 'guides' - hints for drawing a custom overlay with specific parameters:

   1. 'w' and 'h' - width and height of the camera search rectangle,
   2. 'ow' and 'oh' - width and height of the overall container,
   3. 'mt' - top margin for 'h',
   4. 'ml' - side margins for 'w';

7. 'feedback'` - user feedback for video capture process with specific parameters:

   1. 'reason' - reason code,
   2. 'type' - classification group of the reason code, and useful for color coding;

8. 'cameras' - detected camera list during video capture with specific parameters:

   1. 'current' - current camera label (not deviceId),
   2. 'devices' - the result of MediaDevices.enumerateDevices().

Control Commands

1. Control commands are methods of the control interface:
   1. 'setup(config)' - alter runtime configuration (at any time) with specific options:
      1. 'customOverlay=true/false' - when enabled, authID overlays on video capture get disabled;
2. 'next()' - Certain screens force to the next action without recording any user consent and other side effects;
3. 'back()' - Certain screens force back or cancel action;
4. 'restart()' - restart processing, e.g. to recover from error screens, but it is not always safe to force restart during interactive activities like video capture;
5. 'setCamera(deviceId)' - switch capture to the specific one, null for the default selection;
6. 'setFlash(enable)' - turn on flash overlay for Selfie, and torch light is not supported;
7. 'setLanguage(lang)' - switch to a different language by one of the supported i18n language codes.

Feedback Reason Codes

1. Feedback Reason Codes:
   1. Selfie Capture:
      1. 'wait' - waiting for the user's face,
      2. 'motion' - excessive device motion is detected,
      3. 'processing' - captured, completing the recognition
      4. FaceLok SDK error codes:
      5. 'FaceCloseToBorder' - user's face is too close to the edges, 
      6. 'FaceBadAngle' - user's face is at a bad angle,
      7. 'FaceTooBig' - user's face is too close,
      8. 'FaceTooSmall' - user's face is too far,
      9. 'TooDark' - too dark environment,
      10. 'TooBright' - too bright environment,
      11. 'HotSpot' - glare detected,
      12. 'NoFace' - user face not found or multiple faces,
      13. 'FaceNotCentered' - center user face;
2. Document Capture:
   1. 'Loading' - initializing,
   2. 'Wait' - waiting for the document to get presented,
   3. 'AdjustAngle' - bad position, document angle
   4. 'MoveCloser' - bad position, document too far,
   5. 'MoveFarther' - bad position, document too close,
   6. 'AlignToFrame' - bad position, not aligned to guides,
   7. 'BarcodeFocusing' - camera focus is not sufficient, gently move the document further and closer,
   8. 'Hold' - hold document/camera in place to finalize capture,
   9. 'Processing' - captured, completing recognition;

More details of specific page codes, reason codes, etc. can be observed through the message log when running transactions using the FEEDBACK  tool.

Errors

Error states can be detected by checking the 'authid:control:page'` notification message type and comparing 'params.name' to the specific error page below.

Generic Failure

{
    "type": "authid:control:page",
    "params": {
        "name": "Failed",
        "props": {
            "type": "invalidStartup"
        }
    }
}

When 'Failed' state occurs detailed error condition can be found in params.props.type notification value:

Camera Problems

{
    "type": "authid:control:page",
    "params": {
        "name": "CameraUnavailable"
    }
}

Document Scanning Problems

Example:

{
    "type": "authid:control:page",
    "params": {
        "name": "DocumentFailed",
        "props": {
            "docInfo": {
                "front": {
                    "enabled": true
                },
                "back": {
                    "enabled": false
                },
                "description": "Passport"
            },
            "side": "front",
            "reason": "NOT_FOUND",
            "additionalReasons": [
                "BAD_FOCUS",
                "GLARE"
            ]
        }
    }
}

There can be more information provided 'docInfo' node, however the user feedback must be based on a combination of 'reason' and 'additionalReasons' value.

DocumentFailed 'reason' values

DocumentFailed 'additionalReasons' values

Selfie Capture Problems

{
    "type": "authid:control:page",
    "params": {
        "name": "VerifyMatchFail"
    }
}

{
    "type": "authid:control:page",
    "params": {
        "name": "FLWAError",
        "heading": "Something went wrong with your identity verification",
        "info": "Please try again."
    }
}

The following best practice guidelines outline how error messages must be displayed to users at various stages of the Proof transaction event that a ProofTM or Biometric Verification transaction is unsuccessful.

No specific information must be shared with the user regarding why a transaction failed, as malicious actors could exploit this to compromise the system's integrity.

Instead, environmental problems could lead to false positives must be the priority for error notifications.