Using Web SDK

Introduction

Integrate the IDWise Web SDK into your web application to run ID verification journeys with a configurable IDWise user interface.

The IDWise JavaScript Document Capture SDK guides users through the ID documents and/or biometrics required by your configured journey flow in the IDWise backend system. When the user completes the journey, your app receives a callback with the journey information so your backend can securely retrieve the results.

Compared with the Native SDK, the Web SDK does not currently support advanced Smart Capture features, such as automatic document capture and automatic selfie capture. The Dynamic SDK feature is also not available in the web version.

Requirements

Install the IDWise Web SDK by following the WebSDK Installation guide.

AI integration prompt

You are an expert JavaScript SDK integration engineer.

I am integrating the IDWise Web SDK into the project this prompt is pasted in.
Detect the frontend framework and routing model from the project (plain HTML / React / Next.js / Vue / Angular / other). If signals are mixed or ambiguous, ask before continuing.

## Source-of-truth docs (use these exact pages — don't substitute)
- Web SDK runtime: https://docs.idwise.com/docs/web-sdk-usage
- Web SDK installation: https://docs.idwise.com/docs/websdk-installation
- Latest version: https://docs.idwise.com/docs/web-sdk-release-notes — use the latest stable version from the release notes, not a `<VERSION>` placeholder.
- SDK error codes: https://docs.idwise.com/docs/sdk-error-codes
- Journey Finished webhook: https://docs.idwise.com/docs/finished-journey-webhook

## Hard rules

1. **Do not invent methods.** Use only Web SDK methods shown in the docs: `IDWise.initialize`, the session instance's `startJourney`, `resumeJourney`, and `cleanup`. If the installed/runtime SDK exposes something different, say so explicitly and stop — do not fabricate a signature.
2. **Keep the initialized session instance.** Store the result returned by `IDWise.initialize` and call journey methods on that instance.
3. **Clean up before reuse.** If starting or resuming another journey in the same page session, call `cleanup()` before launching the next journey.
4. **Do not treat frontend completion as the final verification result.** `onJourneyFinished` means the user finished the Web SDK flow; my backend must wait for the Journey Finished webhook or fetch results securely server-side.
5. **Not done until it runs.** Run the app's build/test command or a local smoke test, fix errors, and paste the final command + last ~10 lines of output as proof.

## Ask before guessing

If any of the following are unclear from the project, ask me — do not assume:
- Which page / route / component should host the IDWise mount element.
- Which button or user action should trigger `startJourney`.
- Whether to wire `resumeJourney`, or only `startJourney`.
- Where `journeyId` should be stored on the frontend before sending it to my backend.
- Which backend endpoint should receive `journeyId`, `referenceNo`, and event payloads.
- Whether the app already has an existing Content Security Policy that must be merged instead of replaced.
- Whether the Web SDK is loaded from the IDWise CDN or self-hosted.
- Any applicant-details fields I should populate beyond the SDK-required minimum.

Group related questions into one round.

## What to deliver

### A. Web SDK setup
- Add the Web SDK script using the actual latest stable version from the release-notes page.
- Add a mount element with the selector `#idwise-mount` on the correct page / component.
- Initialize the SDK with `<YOUR_CLIENT_KEY>`, locale, and theme.
- Store the initialized session instance in a scope that the journey actions can access.
- Add or merge the minimum Content Security Policy directives required by the Web SDK:
  - `script-src` allows `releases.idwise.com`
  - `style-src` allows `releases.idwise.com` and `resources.idwise.com`
  - `img-src` allows `data:`, `blob:`, `resources.idwise.com`, and `www.res.idwise.com`
  - `connect-src` allows `releases.idwise.com` and `api.idwise.com`
  - `font-src` allows `fonts.gstatic.com`

### B. Runtime integration
1. Initialize the Web SDK once and handle initialization success and failure.
2. Start a new journey with `<FLOW_ID>`, mount selector `#idwise-mount`, `<REFERENCE_NUMBER>`, applicant details, and event handlers.
3. Implement every documented event handler:
   - `onJourneyStarted`: store `details.journeyId`, send it to my backend if an endpoint exists, and hide any loading UI.
   - `onJourneyResumed`: confirm the resumed journey and hide any loading UI.
   - `onJourneyFinished`: store/log `details.journeyId`, show a submitted/pending state, and trigger or document backend result retrieval after the Journey Finished webhook.
   - `onJourneyCancelled`: show a resumable interrupted state and keep the journey ID if available.
   - `onError`: log the full payload, including `code`, `message`, and `requestId` when present.
4. Resume an unfinished journey if requested, using `<FLOW_ID>`, `#idwise-mount`, stored `journeyId`, and the same event handlers.
5. Add a cancel / cleanup path that calls `cleanup()` on the session instance.
6. Before starting or resuming another journey in the same page session, call `cleanup()` and wait for it to complete.
7. If the app has backend integration points, send `journeyId`, `referenceNo`, and relevant event payloads to the backend without exposing any server-side API keys in the browser.

### C. Placeholders to keep verbatim
- `<YOUR_CLIENT_KEY>` — in `IDWise.initialize` only
- `<FLOW_ID>` — as a constant
- `<REFERENCE_NUMBER>` — as a constant
- `<JOURNEY_ID>` — fallback when no stored id exists
- `#idwise-mount` — mount selector unless the existing app requires a different selector

### D. Execution & report
Apply the changes directly to the project — edit the actual files, do not just print snippets. At minimum:
- HTML template / app shell / framework component — SDK script and mount element added.
- Frontend page / component — initialization, start, resume, event handlers, and cleanup wired up.
- CSP configuration — minimum IDWise directives merged into the existing policy.
- Backend integration point, if present — receives `journeyId` or documents the exact missing endpoint needed.

After applying changes, report:
- Short integration checklist of what was done.
- List of files created / modified, with a one-line note on each.
- One sentence per event handler explaining where it connects in the frontend and backend lifecycle.
- Final build/test/smoke-test command and last ~10 lines of its output, as proof of a working integration.

Full integration sequence diagram

This sequence diagram shows the steps performed after integrating the Web SDK with your web application.

SDK usage

Use these methods to interact with the IDWise Web SDK from your web application.

Initialize the SDK

Initialize the IDWise SDK library using the initialize function. This function requires the following parameters:

• clientKey (Mandatory): A string that identifies your business and is used for authentication. Provided by the IDWise team.
• locale (Optional): A two-letter ISO language identifier (e.g., "en") to determine the language of the UI. The default is "en". For a list of available languages, adding additional languages, please contact IDWise Support or you can add additional languages via IDWise Theme Designer.
• theme (Optional): The theme of UI elements, which can be either light or dark. Alternatively, use system_default for the system default theme.

The initialize function returns a promise that resolves to a session instance. This session instance is used to access the functionality of the IDWise system in the subsequent steps.

Example code for initialization:

 <script>
     let idwise;
     IDWise.initialize({
        //replace xxxx with client key that you have generated from API Keys section in admin panel 
        clientKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        locale: "en",
        theme: "system_default", // Optional: Can be 'light', 'dark', or 'system_default' (default).
     })
     .then(result => {
        idwise = result
     })
     .catch(error => {
        alert(error);
     });
  </script>

Starting a new Journey

Use the IDWise session instance obtained from the initialize function to start a new journey by calling the startJourney function. This function requires the following parameters:

• flowId (Mandatory): A string that identifies the journey flow to be started. Provided by the IDWise team based on your requirements.

• mount (Mandatory): A string with a CSS selector representing a single element. This specifies the HTML DOM element where IDWise UI elements should be added.

• referenceNo (Optional but recommended): A string used to uniquely identify the user undergoing the journey in your system. This identifier will be attached to the journey and can be used to link the journey back to your system when fetching the journey data.

• applicantDetails (Optional) This parameter allows you to pass applicant details which is Information about the person doing the verification. This is usually the information that the user fills in your registration form before doing the KYC process. If you don't want to pass any applicant details then you can just pass null. Here are the currently supported keys for applicant details:

  Field	Description
  full_name	The full name of the applicant.
  birth_date	The birth date of the applicant apture SDK p (e.g. 2022-02-01)
  sex	The sex of the applicant. Possible values: male or female
  address	The address of the applicant. Format follows what is printed on Proof of Address document or as follows: Apartment Number, Building Name, Building Number, Street Name, Suburb, City, District, Postal Code, State, Country
  nationality_code	The applicant’s nationality, represented using the ISO 3166-1 alpha-3 standard (3-letter country code). For example: GBR

• eventHandlers (Optional but recommended): An object containing call-backs to handle different events fired by the IDWise SDK. The supported call-backs include:

  1. onJourneyStarted: Triggered when the user starts the journey.

     Field	Type	Description
     journeyId	String	The value of the field

  2. onJourneyResumed: Triggered when the user resumes the journey.

     Field	Type	Description
     journeyId	String	The value of the field

  3. onJourneyFinished: Triggered when the user completes all the steps of the journey.

     Field	Type	Description
     journeyId	String	The value of the field

  4. onJourneyCancelled: Triggered when the user cancels the journey.

     Field	Type	Description
     journeyId	String	The value of the field

  5. onError : Triggered when the user is not able to continue the journey due to a breaking error.

     Field	Type	Description
     code	String	Error code specifying the type of error that occurred. Please refer to this page for details on possible error codes <https://docs.idwise.com/docs/sdk-error-codes>
     message	String	Message explaining the error
     requestId	String	Unique identifier for this request. Please keep track of this identifier as it is useful to share with IDWise Support when making any support requests

Example code for start journey:

 let applicantDetails = {
   "full_name": "John Doe",
   "birth_date": "1995-05-06",
   "sex": "male",
   "address":"221 Sample Road, Placeholder House, Testford, London, T35 7AB, United Kingdom",
	 "nationality_code": "GBR"
 };

idwise.startJourney({
   flowId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 
   mount: '#idwise-mount',
   applicantDetails: applicantDetails,
   referenceNo: "842098029309823", 
   eventHandlers: {
   		onJourneyStarted: function(details) {
     		// You should keep track of details.journeyId and store it in your DB for this applicant
   		},
   		onJourneyFinished: function(details) {
     		// By this point UI control is back to your app and IDWise UI is now removed
     		// No further steps are required from your user for KYC at this point
     		// The journey processing will continue in the background
     		// You can inform your user that their submission was received and that you will get back to them with the outcome
     		// Your backend can listen to IDWise Webhooks or poll IDWise backend to know when the results are ready
     		// When the journey processing is done you can inform the user of next steps you require from them based on the journey decision
   		},
   		onJourneyCancelled: function(details) {
     		// By this point UI control is back to your app and IDWise UI is now removed
     		// You can inform your user that their KYC was interrupted and not finished yet
     		// and that they need to come back to finish it
   		},
   		onError: function(details) {
     		// Check the details.code to identify the reason of the error
     		// Read details.message for further details explaining the error
    		// Log any errors in your system logs and ensure you log all the elements in details object    
   		},
 	}
});

The journeyId identifier can be used to retrieve the data associated with the journey from the IDWise Data Fetch API once you receive the Journey Finished webhook in your backend.

Note that the IDWise SDK automatically removes the IDWise UI and cleans up the used resources when a journey completes.

That's it! You have successfully completed the core integration and enabled streamlined user onboarding journeys using the IDWise Web SDK. You can find here a sample HTML file that demonstrates the integration steps described above.

WebSDK Desktop Transitioning Options

When embedding the WebSDK into a web application accessed from a desktop, you can configure the transitioning behavior using the Flow Builder with one of the following options:

• Switch to mobile web to complete the verification (Recommended):
  Redirects users to the mobile web by displaying a QR code on the desktop for scanning. This is the recommended option for ensuring optimal performance and capturing high-quality images.
• Continue on desktop:
  Allows users to complete the process on the desktop by uploading files or using the desktop camera. Note: Desktop cameras often have lower resolution, which could impact verification quality.
• Let the user choose desktop or mobile web:
  Offers users the choice to either remain on the desktop or transition to the mobile web for verification, accommodating individual preferences.

Resuming a Journey

To resume a journey, call the resumeJourney function on the IDWise session instance. This function requires the following parameters:

• flowId (Mandatory): A string that identifies the journey flow to be started. Provided by the IDWise team based on your requirements.
• mount (Mandatory): A string with a CSS selector representing a single element. This specifies the HTML DOM element where IDWise UI elements should be added.
• journeyId (Mandatory): An id string that is received after starting a journey on one of the eventHandlers in startJourney function.
• eventHandlers (Optional but recommended): An object containing call-backs to handle different events fired by the IDWise SDK. These are explained in Starting a new Journey section above.

This is an example code snippet of how your invocation of resumeJourney will look like:

idwise.resumeJourney({
   flowId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 
   mount: '#idwise-mount',
   journeyId: "xxxxxxxxxxxxxxxx", 
   eventHandlers: {
   onJourneyResumed: function(details) {
     // This confirms the journey was resumed successfully and UI control is with IDWise SDK
     // IDWise will guide the user to complete the progress on this existing journey
   },
   onJourneyFinished: function(details) {
     // By this point UI control is back to your app and IDWise UI is now removed
     // No further steps are required from your user for KYC at this point
     // The journey processing will continue in the background
     // You can inform your user that their submission was received and that you will get back to them with the outcome
     // Your backend can listen to IDWise Webhooks or poll IDWise backend to know when the results are ready
     // When the journey processing is done you can inform the user of next steps you require from them based on the journey decision
   },
   onJourneyCancelled: function(details) {
     // By this point UI control is back to your app and IDWise UI is now removed
     // You can inform your user that their KYC was interrupted and not finished yet
     // and that they need to come back to finish it
   },
   onError: function(details) {
     // Check the details.code to identify the reason of the error
     // Read details.message for further details explaining the error
     // Log any errors in your system logs and ensure you log all the elements in details object    
   }
 }
});

Cancelling the Journey

To cancel a journey, call the cleanup function on the IDWise session instance. This function takes no parameters and returns a promise. The promise is resolved when the journey is cancelled and the UI elements are removed

<script>
 let idwise;
 IDWise.initialize({
    //replace xxxx with client key that you have generated from API Keys section in admin panel 
    clientKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    locale: "en",
 })
 .then(result => {
    idwise = result
  	// Starts the journey
  	idwise.startJourney({ ... });
 })
 .catch(error => {
   	// Handle initialization error
  });

  .
  .
  .
  
  // To cancel IDWise process at any moment and hide IDWise UI you can invoke this method
  idwise.cleanup();
</script>

Triggering IDWise SDK Again

If the IDWise SDK has an active journey (initiated by calling startJourney or resumeJourney) and you wish to switch to a different journey within the same script without reloading the web page, it is essential to clean up the current active journey. This ensures that the IDWise SDK can properly handle the new journey.

To do this clean up you can call cleanup method on the IDWise session instance. The following code shows an example:

<script>
 let idwise;
 IDWise.initialize({
    //replace xxxx with client key that you have generated from API Keys section in admin panel 
    clientKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    locale: "en",
 })
 .then(result => {
    idwise = result
    // Starts the journey first time in this session
    idwise.startJourney({ ... });
 })
 .catch(error => {
   	// Handle initialization error
  });

  .
  .
  .
  
  // Use this method to trigger another journey in same session
  // cleanup is necessary to clean the state of the current journey and ensure IDWise SDK is ready to handle another journey
  idwise.cleanup();
  idwise.startJourney({ ... });
</script>

Advanced Usage

Content Security Policy (CSP)

If your web application enforces a Content Security Policy, add the following minimum CSP directives to allow the IDWise Web SDK to operate correctly:

<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self';
      script-src 'self' releases.idwise.com;
      style-src 'self' releases.idwise.com resources.idwise.com;
      img-src 'self' data: blob: resources.idwise.com www.res.idwise.com;
      connect-src 'self' releases.idwise.com api.idwise.com;
      font-src 'self' fonts.gstatic.com;
      object-src 'none';
      base-uri 'self';
      form-action 'self';" />

Each directive serves a specific purpose:

⚠️

These are the minimum required origins. If your application already has a CSP, merge these directives with your existing policy rather than replacing it.

Self-Hosting the Web SDK

If your security or infrastructure requirements prevent loading the SDK from the IDWise CDN, you can self-host the Web SDK assets on your own servers. Refer to the Advanced WebSDK Usage guide for detailed self-hosting instructions.

ℹ️

Even when self-hosting, certain static assets such as icons and UI resources will still be served from IDWise servers (resources.idwise.com). Ensure your CSP and network policies allow requests to these origins.