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

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

NameDescriptionCan Restart
'Failed'Generic failure page. Map detailed codes via params.props.type value.Whenever an application can perform an automatic restart using the same URL parameters depends on the sub-states.
{  
    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:

ValueDescriptionCan Restart
'invalidStartup'Invalid or missing transaction initialization parameters in the URLno
'requestFailed' or 'requestTimeout'Network error or backend temporary malfunctionyes
'transactionNotValid'The transaction ID is not valid anymore or expiredno
'transactionMaxAttempts'Maximum retry attempts limit achievedno
'sessionExpired'Timeout waiting for camera feed inputyes

Camera Problems

{  
    type: 'authid:control:page',  
    params: {  
        name: 'CameraUnavailable'  
    }  
  }
NameDescriptionCan Restart
'CameraUnavailable'Problem acquiring camera feedCheck if the camera is available on the device. Tip: The user to confirm the camera access request and allow retry.
'CameraBlurry'Specific phone models are detected with problematic camera macro photo capabilities that cause problems for document scanning.Tip user to update phone firmware and allow to continue.
'DocScanResolutionTooLow'The device camera resolution is below the minimum configured document or selfie resolution.no

Document Scanning Problems

NameDescriptionCan Restart
'DocumentFailed'Document scanning failed. Additional information is included in notification properties.yes (tip user based on specific codes below)
`{
    type: 'authid:control:page',
    params: {
        name: 'DocumentFailed',
        docInfo: {
            description: 'US Driver License',
            type: 'Document'
        }
        side: 'back',
        reason: 'WRONG_SIDE',
        additionalReasons: [  
            'BAD_FOCUS'  
        ]
    }
  }`

DocumentFailed 'reason' values

ValueDescription
'INVALID'Unable to process, rescan the document.
'INVALID_IMAGE_QA'Document photo quality is below the acceptable threshold.
'WRONG_SIDE'The user submitted the wrong document side (front when asked for back etc.).
'NOT_FOUND'Unable to recognize the document in the captured photo. Perhaps the user scanned an unknown document type.
'WRONG_COUNTRY'The document's country of origin does not match the requested document's origin.
'EXPIRED'Documents have expired and expired documents are not allowed per configuration.
'BAD_FRONT'After scanning the back image the front document image was detected to be of low quality, re-capture of the front image was required.

DocumentFailed 'additionalReasons' values

ValueDescription
'BAD_FOCUS'The image is too blurry, try again.
'BOUNDS'Image outside of capture border.
'GLARE'Bad lighting, try again.
'PERSPECTIVE'Adjust document angle.

Selfie Capture Problems

`{
    type: 'authid:control:page',
    params: {
        name: 'VerifyMatchFail'
    }
  }`
NameDescriptionCan Restart
'VerifyMatchFail'Something went wrong with user identity verification.Tip user to improve lightning conditions and retry
'VerifyFinalFail'Unable to verify user biometrics.no
'FLWAError'FaceLok engine encountered a problem.yes
`{
    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.