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
- 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
- Enter the
Operation ID
from the Proof Transaction API response, for example, 113e838b-be34-53e9-c52f-3cc45b2d10ce. - 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
Web Component: Proof TransactionsOpen Recipe
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
- 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
- Enter the
Transaction ID
from the Authentication Transaction API response, for example, 57a72266-c515-9771-bf16-4177c22332a8. - 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: Verification TransactionsOpen Recipe
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:
Value | Description |
---|---|
success | true 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. |
pageName | This 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
|
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:
- 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>
- 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>
Updated 3 months ago