Embedding in iFrame

If you want to embed the Web Client on your web page, place the iFrame tag in your HTML code where you want the client to appear. Use web.href as the value of the iFrame src attribute.

info

Do not add the iFrame element and its attributes with javascript dynamically at runtime. The iFrame must be present when the page loads.

allow Attributes

The following allow attributes must be included to enable the camera for image capture in supported browsers:

• camera
• autoplay
• fullscreen
• clipboard-read
• clipboard-write
• accelerometer
• gyroscope
• magnetometer

Example

<iframe src="https://yourcompany.web.emea-1.jumio.ai/web/client?baseUrl=xxx&authorizationToken=xxx&locale=en-US" width="70%" height="80%" allow="camera;autoplay;fullscreen;clipboard-read;clipboard-write;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>

Width and Height

We recommend adhering to the responsive breaking points in the following table:

Size class	Width	Height
Large	≥ 900 px	≥ 710 px
Medium	640 px	660 px
Small	560 px	600 px
X-Small	≤ 480 px	≤ 535 px

When specifying the width and height of your iFrame, you may prefer to use percentage values so that the iFrame behaves responsively on your page.

Absolute Sizing Example

<iframe src="https://yourcompany.web.emea-1.jumio.ai/web/client?baseUrl=xxx&authorizationToken=xxx&locale=en-US" width="930" height="750" allow="camera;autoplay;fullscreen;clipboard-read;clipboard-write;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>

Responsive Sizing Example

<iframe src="https://yourcompany.web.emea-1.jumio.ai/web/client?baseUrl=xxx&authorizationToken=xxx&locale=en-US" width="70%" height="80%" allow="camera;autoplay;fullscreen;clipboard-read;clipboard-write;accelerometer;gyroscope;magnetometer" allowfullscreen></iframe>

Recommended Approach for Error Handling (Optional iFrame Logging​)

When the Web Client is embedded in an iFrame it will communicate with the containing page using the JavaScript window.postMessage() method to send events containing pre-defined data. This allows the containing page to react to events as they occur (e.g. by directing to a new page once the success event is received).

Events include data that allows the containing page to identify which transaction triggered the event. Events are generated in a stateless way, so that each event contains general contextual information about the transaction (e.g., transaction reference, authorization token, etc.) in addition to data about the specific event that occurred.

Using JavaScript, the containing page can receive the notification and consume the data it contains by listening for the message event on the global window object and reacting to it as needed. The data passed by the Web Client in this notification is represented as JSON in the data string property of the listener method’s event argument. Parsing this JSON string results in an object with the properties described below.

warning

If success or error redirect URLs are configured, the final event will not be delivered because the redirection occurs before the event is sent.
We recommend choosing either event listeners or redirect URLs, but not both.

note

All data is encoded with UTF-8. This functionality is not available for instances of the Web Client running in a standalone window or tab.

Error Handling & Retry Logic

• Redirect to a fallback page on errors.
• Control retries server-side — always generate fresh tokens.
• Log workflowExecutionId, session start, and error codes.

event.data object

Required items appear in bold type.

Property	Type	Description
accountId	string	UUID of the account
authorizationToken	string	Authorization token, valid for a specified duration
workflowExecutionId	string	UUID of the workflow
customerInternalReference	string	Internal reference for a request to link it in the customer backend. It must not contain Personally Identifiable Information (PII) or sensitive data such as e-mail addresses.
eventType	integer	Type of event that has occurred. Possible values: 510 (application state-change)
dateTime	string	UTC timestamp of the event in the browser Format: YYYY-MM-DDThh:mm:ss.SSSZ
payload	JSON object	Information specific to the event generated (refer the table below)

event.data.payload object

Required items appear in bold type.

Name	Type	Description
value	string	Possible values: loaded (Web Client loaded in the user’s browser). success (Images were accepted for verification). error (Verification could not be completed due to an error).
metainfo	JSON object	Additional meta-information for error events. (see event.data.payload.metainfo object)

Example payload info object

{
  "authorizationToken": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XMy2rDQAyF4Vcxs65gLtJcuusy27yBrJEgkDgwcWlD6LvX9htkd_j5OC-nv1-r-3ShUKKQUiglZPfhWOTUt26Vva_BAGNEQKUAdV9NAyH6HKPizg8shbL0lsFySoCdDRq1BqIBzWT2rfoN_5i-w-WstukbL53X-3hO8v1Y7zcd02VZdSx8nYaaDl1Ed358k0ZUowqaegfkmIDnSlDYvFHWgml2f_8yL0I9_wAAAA.E-C7qQu_RgRUuUlw93VWDkzgPGb94ZeAleyZ6RR4MSX6Dmu3m3YqSEIlCQEYzXFtjH1K5uyUsfI65G5y_JF06g",
  "eventType": 510,
  "dateTime": "2025-05-27T07:02:23.747Z",
  "payload": {
    "value": "error",
    "metainfo": {
      "mode": "original",
      "code": 9822,
      "codeExternal": 9822,
      "publicErrorCode": "H000000"
    }
  },
  "workflowExecutionId": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "transactionReference": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "jumioIdScanReference": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "accountId": "c756cd96-f633-4daf-9599-ce14ffcb0980",
  "customerInternalReference": "mandatory customer internal reference"
}

event.data.payload.metainfo object

Required items appear in bold type.

Property	Type	Description
code	integer	Only present if payload.value=error Only present if payload.value=error. Check the table below.

publicErrorCodes

Code Pattern	Message	Description
A[xx][yyyy]	We have encountered a network communication problem	Retry possible, user decided to cancel
B[xx][yyyy]	Authentication failed	Secure connection could not be established, retry impossible
C[xx]0401	Authentication failed	API credentials invalid, retry impossible
H[xx]0000	The camera is currently not available	Camera cannot be initialized, retry impossible
J[xx]0000	Transaction already finished	User did not complete SDK journey within session lifetime
M[xx]0000	Transaction cannot be completed	User did not complete the transaction.
N[xx]0000	Scanning not available at this time, please contact the app vendor	Required images are missing to finalize the acquisition

Example meta info object

{
"value": "error",
  "metainfo": {
    "mode": "original",
    "code": 9801,
    "codeExternal": 9801,
    "publicErrorCode": "M010451",
    "retriable": false
  }
}

note

The "retriable" field indicates whether an error is recoverable.

Example iFrame Logging Code

window.addEventListener("message", (event) => {
  const mandatoryKeys = ['authorizationToken', 'eventType', 'payload'];
  const data = window.JSON.parse(event.data);
  if (mandatoryKeys.every((key) => key in event.data)) {
    console.log('ID Verification Web was loaded in an iframe.');
    console.log('auth-token:', data.authorizationToken);
    console.log('event-type:', data.eventType);
    console.log('date-time:', data.dateTime);
    console.log('workflow-execution-id:', data.workflowExecutionId);
    console.log('account-id:', data.accountId);
    console.log('customer-internal-reference:', data.customerInternalReference);
    console.log('value:', data.payload.value);
    console.log('metainfo:', data.payload.metainfo);
  }
});

iFrame Security

• Configure Content Security Policy (CSP) to allow only *.jumio.ai in frames.
• Restrict which origins can embed the iFrame.
• Use postMessage API for receiving status updates.
• Consider full-page modals for mobile responsiveness.