About

This is a pilot version of the Cleared Verification Client. Current main version is 0; version 1 will be available to the public.

Cleared is a robust KYC verification platform for identity, address, employment, background checks and document forensics. The verification client (this package), can be used to implement verification tools in your apps, using React or vanilla JavaScript.

Configuration

The client library allows you to pass configuration settings for API integration, host URLs, and authentication. These configurations are typically passed as part of the config prop or directly into components if rendering in React.

Example Configuration Object

const config = {
    CLEARED_API_PUBLIC_KEY: "your-cleared-api-public-key",
    CLEARED_API_BASE_URL: "https://cleared.id/api/v1/verification-client",
    CLEARED_FRONT_END_HOST: "https://cleared.id/verification",
    CLEARED_API_PUBLIC_HOST: "https://cleared.id/api/v1/public/verification-client",
};

How to Use Configuration

1. Directly Pass into Components: Some components, such as VerificationSession, accept a config prop directly.

   <VerificationSession
       authToken="your-auth-token"
       services={['identity']}
       customerReferenceId="customer-id"
       customerData={{ emailAddress: '[email protected]' }}
       config={{
           CLEARED_API_PUBLIC_KEY: "your-cleared-api-public-key",
           CLEARED_API_BASE_URL: "https://cleared.id/api/v1/verification-client",
       }}
   />

2. Centralise Configuration: Define the configuration in a centralised file (e.g., config.js) and import it wherever needed:

   config.js:

   export const verificationConfig = {
       CLEARED_API_PUBLIC_KEY: "your-cleared-api-public-key",
       CLEARED_API_BASE_URL: "https://cleared.id/api/v1/verification-client",
       CLEARED_FRONT_END_HOST: "https://cleared.id/verification",
       CLEARED_API_PUBLIC_HOST: "https://cleared.id/api/v1/public/verification-client",
   };

   Usage:

   import { verificationConfig } from './config';
   
   <VerificationSession
       authToken="your-auth-token"
       services={['identity']}
       customerReferenceId="customer-id"
       customerData={{ emailAddress: '[email protected]' }}
       config={verificationConfig}
   />

Configuration Keys

| Key | Description | |-------------------------|-----------------------------------------------------------------------------| | CLEARED_API_PUBLIC_KEY| The public API key for authentication. | | CLEARED_API_BASE_URL | Base URL for the API endpoint. | | CLEARED_FRONT_END_HOST| URL for the frontend verification application. | | CLEARED_API_PUBLIC_HOST| URL for public API endpoints, typically used for user-facing operations. |

To obtain a public API key, visit the Admin Portal (https://swfcloud.com/admin/integrations/api) and go to Integrations or API menu to the left.

Verification Components

Overview

This library provides modular React components that can be dynamically rendered into specific HTML elements on a webpage. It simplifies integration with third-party systems by allowing each component to be targeted and configured independently. Components are attached to the global window object for easy access and are also available for modular imports.

The original package was built with React, but we used an API to provide these components to a regular JavaScript page, via the bundled export script. Whenever we deploy a new version of this project, we publish an updated JavaScript file to pur S3 bucket. The script can be found at: s3.amazonaws.com/swf.cdn/cleared-verification-client/client-{{ ENVIRONMENT:qa|prod }}-{{ VERSION_NUMBER }}.js

You can always get the latest version at https://s3.amazonaws.com/swf.cdn/cleared-verification-client/client-qa-latest.js for non-prod environments, or https://s3.amazonaws.com/swf.cdn/cleared-verification-client/client-latest.js for production environments.

Components Included

1. VerificationBadge: Displays a public badge indicating the verification status of the associated subject.
2. VerificationStatus: Displays the statuses of a subject to the client, privately. A use case for this is when a client needs to display the status of a subject in their admin/back-office portal.
3. CustomerView: Displays the statuses of a subject to them, privately. A use case for this is when a customer logs in via client's website, conducts verification and then can see their own verification status.
4. VerificationSession: Manages and displays the session details of a verification flow.
5. SessionExpired: Indicates when a session has expired.
6. Welcome: A welcome screen for users entering the verification process.

Examples

To see how exactly the client can be implemented or even copy example code, go to the Code tab on this page and browse to examples.

Features

• Dynamic Rendering: Each component can be rendered into a specified HTML element by its id.
• Fallback Handling: If the target container is not found, a new container is appended to the body.
• Reusable API: A consistent render method for all components.
• Global Access: Components are attached to the window object.
• Modular Export: Components can also be imported individually in ES6 environments.

Installation

Ensure the library is available in your project. You can include the bundled script directly or import it as a module in your React project.

Direct Inclusion

Include the bundled JavaScript file in your HTML:

<script src="https://s3.amazonaws.com/swf.cdn/cleared-verification-client/client-latest.js"></script>

ES6 Import

Install the library via npm or yarn:

npm install cleared-verification-client/

Import the components into your project:

import { VerificationBadge, VerificationStatus } from 'cleared-verification-client';

Usage

1. Render a Component

Each component exposes a render method that accepts a config object and a targetId of the HTML element where the component will be rendered.

Example:

<div id="badge-container"></div>
<div id="status-container"></div>

window.VerificationBadge.render({ status: 'verified' }, 'badge-container');
window.VerificationStatus.render({ status: 'active' }, 'status-container');

If the target element does not exist, the component will create a new div and append it to the body.

2. Modular Usage

You can import and use the components programmatically:

import { VerificationBadge } from 'verification-components';

VerificationBadge.render({ status: 'verified' }, 'badge-container');

3. Advanced Example

The following example demonstrates rendering the VerificationBadge component with a detailed configuration:

let { VerificationBadge } = window.ClearedVerificationClient;
VerificationBadge.render({
    customerData: { userPublicToken: "JWT_PUBLIC_USER_TOKEN" },
    service: 'identity',
    config: {
        CLEARED_API_PUBLIC_KEY: "JWT_CLIENT_API_KEY",
        CLEARED_API_BASE_URL: "https://cleared.id/api/v1/verification-client",
        CLEARED_FRONT_END_HOST: "https://cleared.id/verification",
        CLEARED_API_PUBLIC_HOST: "https://cleared.id/api/v1/public/verification-client",
    }
}, 'cleared-verification-badge');

4. Contextual Usage in React

For React apps, you can dynamically render components based on the user state. For example:

{authToken && customerId && <>
    <div className='mt-5 w-5/6 md:w-1/2'>
        <VerificationSession authToken={authToken} services={['identity']} customerReferenceId={customerId} customerData={{ emailAddress }} />
    </div>
</>}
{loaded && !authToken &&
    <div className='mt-5 w-5/6 md:w-1/2'>
        <Welcome customerReferenceId={customerId} customerData={{ emailAddress, firstName, lastName }} />
    </div>
}

This ensures that:

• If the user is authenticated (by your app), the VerificationSession component is displayed.
• If the user is not authenticated, the Welcome component is shown with customer data passed as props.

API Reference

General Render Method

All components share the same API:

render(config, targetId)

Parameters:

• config: (Object) Configuration object specific to the component.
• targetId: (String) The id of the HTML element where the component will render.

Behavior:

1. Searches for the HTML element with the given targetId.
2. If not found, logs an error and appends a new container to the body.
3. Renders the React component inside the target container.

Components

VerificationBadge

• Purpose: Displays a public badge indicating the verification status of the associated subject.
• Example:

  window.VerificationBadge.render(config, 'badge-container');

VerificationStatus

• Purpose: Displays the statuses of a subject to the client, privately. A use case for this is when a client needs to display the status of a subject in their admin/back-office portal.
• Example:

  window.VerificationStatus.render(config, 'status-container');

CustomerView

• Purpose: Displays the statuses of a subject to them, privately. A use case for this is when a customer logs in via client's website, conducts verification and then can see their own verification status.
• Example:

  window.CustomerView.render(config, 'customer-view-container');

VerificationSession

• Purpose: Manages and displays the session details of a verification flow.
• Example:

  window.VerificationSession.render(config, 'session-container');

SessionExpired

• Purpose: Indicates when a session has expired.
• Example:

  window.SessionExpired.render(config, 'expired-container');

Welcome

• Purpose: A welcome screen for users entering the verification process.
• Example:

  window.Welcome.render(config, 'welcome-container');

Development

To modify or extend the library:

1. Clone the repository.
2. Install dependencies:

   npm install

3. Build the library:

   npm run build

4. Add new components in the src/components directory.

Testing

Ensure all components are working as expected by running the test suite:

npm test

License

This library is licensed under the MIT License.