Using SDK

Instantiation Example

To get started, import and instantiate the IdentityValidation class by passing the required configuration object to the constructor.

import IdentityValidation from '@paag-io/sdk-identity-validation';

const identityValidation = new IdentityValidation({
  host: 'https://identity-shield.uat.paag.dev', // Shield UI URL (UAT or Production)
  token: 'your-publishable-key',                // Publishable Key issued by Paag
  validationMechanism: 'iframe',               // Options: 'iframe', 'window', 'tab', or 'redirect'
  // target: document.querySelector('#target-element'), // Required only for 'iframe' (Optional if fullscreen is desired)
  // returnUrl: 'https://your-app.com/callback'          // Required only for 'redirect' mode
});

Constructor Parameters

• host (Required): The URL of the Shield interface for the desired environment.
• token (Required): Your Publishable Key issued by Paag. The origin (domain) of your application must be registered to this key.
• validationMechanism (Optional): Defines how the UI will be displayed to the user. Default is 'iframe'.
• target (Conditional): The HTML element where the iframe will be embedded.
• returnUrl (Conditional): The destination URL where the user will be redirected after completing the flow in redirect mode.

Available Methods

The SDK exposes dedicated methods to trigger different validation flows depending on your application's business logic.

makeFullIdentityValidation(cpf)

Initiates the full identity validation process, including OCR, Liveness and Facematch.

• Parameters:
  • cpf (Optional): The user's CPF (Brazilian Individual Taxpayer Registry identification number). If provided, the user will not need to input it manually.
• Usage Examples:

// Full validation passing the CPF beforehand:
identityValidation.makeFullIdentityValidation('12345678900');

// Full validation where the user will manually type their CPF on screen:
identityValidation.makeFullIdentityValidation();

makeFacematchValidation(cpf, imageDocument)

Skips the physical document extraction step (OCR) and immediately initiates the Proof of Life (Liveness) process followed by the facial comparison (Facematch).

• Parameters:
  • cpf (Required): The user's CPF.
  • imageDocument (Optional): The document image in base64 format.

Note: If the imageDocument parameter is not provided, the SDK will try to find the last document image uploaded by the user. If there is no image, the validation will fail.

• Usage Examples:

// Facematch validation by sending a new Base64 document image:
identityValidation.makeFacematchValidation('12345678900', 'data:image/jpeg;base64,...');

// Facematch validation utilizing the historical document already saved in the session:
identityValidation.makeFacematchValidation('12345678900');

makeLivenessValidation(cpf)

Initiates exclusively the Proof of Life (Liveness Detection) flow. It verifies that the user is active and present in front of the camera in real-time, without cross-checking photos against physical documents.

• Parameters:
  • cpf (Required): The user's CPF.
• Usage Example:

identityValidation.makeLivenessValidation('12345678900');

Event Handling

The IdentityValidation class emits events that can be used to enhance user experience and handle different scenarios.

Supported Events:

• success: Triggered when the validation is successful.
• fail: Triggered when the validation fails.
• error: Triggered when a technical problem or unexpected error occurs during validation. Examples:
  • User connection issues (unstable or unavailable internet).
  • Integration or implementation failures in the system processing the validation.
  • System exceptions (such as timeouts or server errors).
• close: Triggered when the user closes the iframe.

Event Handling Example:

import IdentityValidation from '@paag-io/sdk-identity-validation';

const identityValidation = new IdentityValidation({
    host: 'https://identity-shield.uat.paag.dev',
    token: 'your-token-here',
});

identityValidation.on('success', () => {
    console.log('with success');
});

identityValidation.on('fail', () => {
    console.log('with fail');
});

identityValidation.on('close', () => {
    console.log('with close');
});

identityValidation.on('error', () => {
    console.error('A technical error occurred during execution.');
});

Additional Notes

• CPF: "Cadastro de Pessoas Físicas," Brazilian individual taxpayer identification number.
• OCR: Optical Character Recognition, technology to extract text from images.
• Facematch: Facial comparison between the selfie and the document photo.
• Liveness Detection: Verification to ensure that the selfie was taken live and is not a static image.