Embedded UI

The authID platform UI can be easily embedded into your front-end user experience through various modern integration options. This will allow you to display a branded UI to capture documents, enroll a user's biometrics, and verify their transactions, without leaving the main application screen.

By hosting the UX within the same screen, a user will never have to interrupt their journey to check for an SMS, open an email, or switch devices, which leads to a more seamless experience.

🚧

Avoid using iframe

While using iframe is technically allowed, the use of web component results in a more consistent user experience across a wide array of device types.


User Interface (UI) Options

Prerequisites

Generate API credentials: In the Identity Portal - go to "settings" -> "My API Keys" and create API Key. This will generate API Key id and secret. Creating an API Key.

Proof Transaction

When the transaction is initiated with "TransportType":0 option, the response contains values for both OperationId and OneTimeSecret allowing you to construct transaction-specific URLs using simple rule.

API Sequence for Creating a Proof Transaction.

Example response body:

json
{  
   "OperationId": "113e838b-be34-53e9-c52f-3cc45b2d10ce",
   "OneTimeSecret": "TbAeETwpOxbvKy7rWCeOcQ=="  
}

Web Component

  1. Install the NPM package to your solution and make sure to note the location of the JS script in the solution.:
npm i @authid/web-component
  1. Enter the Operation ID from the Proof Transaction API response, for example, 113e838b-be34-53e9-c52f-3cc45b2d10ce.
  2. Enter the One-time secret ID from the Proof Transaction API response, for example, TbAeETwpOxbvKy7rWCeOcQ==.
javascript
<script src="path-to/authid-web-component.js"></script>
<authid-component
  data-url="https://id.authid.ai/?i=502b4913-5cb3-d59e-0fc1-27393cfc7f&s=gXumaHzDpaYwxEhn0Q6Bo6da">
</authid-component>

Click below to use the interactive guide

👍

Verification Transaction

🚧

Common Mistake

  • the URL parameters for Proof and Selfie Enrollment transactions start with i=Operation ID
  • the URL parameters for Verification transactions start with t=Transaction ID

When the transaction is initiated with "TransportType":0 option, the response contains values for both TransactionId and OneTimeSecret allowing you to construct transaction-specific URLs using simple rule.

Create an Authentication Transaction

Example response body:

{  
   "TransactionId": "57a72266-c515-9771-bf16-4177c22332a8",
   "OneTimeSecret": "K4QXiEdEB6J009kHbEwYS9hv"  
}

Web Component

  1. Install the NPM package to your solution and make sure to note the location of the JS script in the solution.:
npm i @authid/web-component
  1. Enter the Transaction ID from the Authentication Transaction API response, for example, 57a72266-c515-9771-bf16-4177c22332a8.
  2. Enter the One-time secret ID from the Authentication Transaction API response, for example, K4QXiEdEB6J009kHbEwYS9hv.
<script src="path-to/authid-web-component.js"></script>
<authid-component
  data-url="https://id.authid.ai/?t=57a72266-c515-9771-bf16-4177c22332a8&s=K4QXiEdEB6J009kHbEwYS9hv">
</authid-component>

Click below to use the interactive guide

👍


Web Component Events

To further integrate the UI into the solution, if the user wants to use our Web Component integrations, there is a set of events the user can subscribe to. When the element reaches a end_page, it alerts the parent frame. It returns simple messages to the parent frame via the parent.postMessage method. The pageName and success variables values assigned to them in the message.

Find more information described in the table below:

ValueDescription
successtrue or false
A true value indicates that the transaction finished successfully.
The pageName should always be "verifiedPage". A false value indicates that the transaction either is not finished yet, or finished unsuccessfully.
pageNameThis is the page name that the app has currently reached. Much of the time the page name is quite descriptive enough to ascertain the reason for the message. Note that this doesn't mean that the transaction is finished yet. The only page that will result in success being true will be the verifiedPage.

All transaction types

  • defaultFailedPage: A failure occurred that is not currently handled by other means.
  • livenessErrorPage: An error occurred during the Liveness Test
  • networkErrorPage: Network throughput was insufficient for the Liveness Test to function properly
  • QRCodePage: The user has opted to move this transaction to their phone. Note - This QR Code link will be outside of the IFrame, so it may have to be handled as the QR Code will not include the IFrame URL
  • requestTimeoutPage: A network request took longer than acceptable
  • standardErrorPage: An error occurred. While in debug mode this page will show instead of the other more specific pages in this list
  • transactionNotValidPage: The transaction is no longer valid. Most commonly the transaction has already been finished
  • transactionMaxAttemptsPage: The max attempts count for the transaction has been reached
  • verifiedPage: The transaction has finished successfully
  • verifyDeclinedPage: The customer declined the transaction. Available for all transaction types.
  • videoDeviceNotFoundPage: No camera was detected
Proof Transactions Only
  • docScanResolutionTooLowPage: The camera resolution is too low to complete the Proof transaction
  • docScanWasmTimeoutPage: The barcode scan timed out
  • documentFailedNonMobilePage: The document scan failed and the user is not on a mobile device
  • documentFailedPage: The document scan failed for some reason
Verify transactions only
  • verifiedMatchFailPage: The Verify attempt failed to match the user to their stored biometric credential

Options

Options for FIDO2 Transactions:

If users are using any of these options for FIDO2 transactions, note user must update the HTML to allow features to work. The properties are as follows:

  1. Web Component: Add a property called data-webauth="true". Example below:
<script src="path-to/authid-web-component.js"></script>

 <authid-component
   data-webauth="true"
  data-url="https://id.authid.ai/?t=57a72266-c515-9771-bf16-4177c22332a8&s=K4QXiEdEB6J009kHbEwYS9hv">
</authid-component>
  1. React : Add a property called webauth="true". Example below::
import AuthIDComponent from '@authid/react-component';

const App = () => {
    return <AuthIDComponent 
  	webauth=true
 	url="https://id.authid.ai/?t=57a72266-c515-9771-bf16-4177c22332a8&s=K4QXiEdEB6J009kHbEwYS9hv" />
};

Additional Parameters

By adding the extra parameters listed below to the source URL, the user can further alter the behavior of the user interface:

These parameters can be customized for each transaction. For more details see Transaction URL Parameters.


Sample Code

<!DOCTYPE html>
<html lang="en">

<head>
  <meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no">
  <script src="/authid-web-component.js"></script>
</head>

<body>
    <div>
      <authid-component
        data-url="https://id.authid.ai/?i=502b4913-5cb3-d59e-0fc1-27393cfc7f&s=gXumaHzDpaYwxEhn0Q6Bo6da">
      </authid-component>
	</div>
    <script>
        (function () {
            window.addEventListener("message", (event) => {
                console.log(JSON.stringify(event.data))

                if (event.data.success) {
                    // Pass
                } else {
                    switch (event.data.pageName) {
                        case "documentFailedPage":
                        case "documentFailedNonMobilePage":
                        case "networkErrorPage":
                        case "livenessErrorPage":
                        case "docScanWasmTimeoutPage":
                        case "requestTimeoutPage":
                        //We don't want to stop the BWApp for these pages
                        return
                        case "transactionNotValidPage":
                        case "transactionMaxAttemptsPage":
                        case "QRCodePage":
                            return
                        case "verifiedMatchFailPage":
                        case "verifyDeclinedPage":
                        case "docScanResolutionTooLowPage":
                        case "videoDeviceNotFoundPage":
                        case "standardErrorPage":
                        case "defaultFailedPage":
                        break
                    }
                    //Failed
                }
            }, false);

        })();        
    </script>
</body>

</html>