npm package: @paag-io/sdk-identity-validation
Description: ## Overview
Author: Maycon Santos
Latest version: 0.2.2

# Identity Validation SDK Documentation

## Overview

The Identity Validation SDK provides a flexible way to validate identities using different mechanisms such as `iframe`, `window`, `tab`, and `redirect`. It allows developers to easily integrate validation functionalities into their web applications.

## Installation

### Using CDN

```html
<script src="https://cdn.jsdelivr.net/npm/@paag-io/sdk-identity-validation/dist/sdk-identity-validation.umd.js"></script>
```

### Using npm

```bash
npm install @paag-io/sdk-identity-validation
```

### Using Yarn

```bash
yarn add @paag-io/sdk-identity-validation
```

## Basic Usage

### Importing

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

### Usage Examples

#### Example in Vanilla JavaScript

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Identity Validation</title>
    <script src="https://cdn.jsdelivr.net/npm/@paag-io/sdk-identity-validation/dist/sdk-identity-validation.umd.js"></script>
    <script>
      let validation;

      window.onload = () => {
        const button = document.getElementById('validate-button');
        const iframeContainer = document.getElementById('iframe-container');

        button.onclick = () => {
          if (validation) {
            validation.cleanup();
          }

          validation = new IdentityValidation({
            validationMechanism: 'iframe',
            host: 'https://your-host.com',
            token: 'your-token',
            target: iframeContainer,
          });

          validation.on('success', () => {
            console.log('Validation successful!');
          });

          validation.on('error', () => {
            console.error('Validation error.');
          });

          validation.makeFullIdentityValidation('12345678900');
        };
      };
    </script>
  </head>
  <body>
    <button id="validate-button">Start Validation</button>
    <div id="iframe-container"></div>
  </body>
</html>
```

#### Example in React

```jsx
import React, { useEffect, useRef } from 'react';
import IdentityValidation from '@paag-io/sdk-identity-validation';

const App = () => {
  const iframeContainerRef = useRef(null);
  const validationRef = useRef(null);

  const handleValidation = () => {
    if (validationRef.current) {
      validationRef.current.cleanup();
    }

    const validation = new IdentityValidation({
      validationMechanism: 'iframe',
      host: 'https://your-host.com',
      token: 'your-token',
      target: iframeContainerRef.current,
    });

    validation.on('success', () => {
      console.log('Validation successful!');
      validation.close();
    });

    validation.on('error', () => {
      console.error('Validation error.');
      validation.close();
    });

    validation.on('fail', () => {
      console.log('Validation failed.');
    });

    validation.on('close', () => {
      console.log('Validation closed before completion.');
    });

    validation.makeFullIdentityValidation('12345678900');
    validationRef.current = validation;
  };

  useEffect(() => {
    return () => {
      if (validationRef.current) {
        validationRef.current.cleanup();
        validationRef.current = null;
      }
    };
  }, []);

  return (
    <div>
      <button onClick={handleValidation}>Start Validation</button>
      <div ref={iframeContainerRef}></div>
    </div>
  );
};

export default App;
```

#### Example in Vue

```vue
<template>
  <div>
    <button @click="startValidation">Start Validation</button>
    <div ref="iframeContainer"></div>
  </div>
</template>

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

export default {
  data() {
    return {
      validation: null,
    };
  },
  methods: {
    startValidation() {
      if (this.validation) {
        this.validation.cleanup();
      }

      this.validation = new IdentityValidation({
        validationMechanism: 'iframe',
        host: 'https://your-host.com',
        token: 'your-token',
        target: this.$refs.iframeContainer,
      });

      this.validation.on('success', () => {
        console.log('Validation successful!');
        this.validation.close();
      });

      this.validation.on('error', () => {
        console.error('Validation error.');
        this.validation.close();
      });

      this.validation.makeFullIdentityValidation('12345678900');
    },
  },
  beforeDestroy() {
    if (this.validation) {
      this.validation.cleanup();
      this.validation = null;
    }
  },
};
</script>
```

#### Example in Angular

```typescript
import { Component, OnDestroy, ViewChild, ElementRef } from '@angular/core';
import IdentityValidation from '@paag-io/sdk-identity-validation';

@Component({
  selector: 'app-identity-validation',
  template: `
    <button (click)="startValidation()">Start Validation</button>
    <div #iframeContainer></div>
  `,
})
export class IdentityValidationComponent implements OnDestroy {
  @ViewChild('iframeContainer', { static: true }) iframeContainer!: ElementRef;
  private validation: IdentityValidation | null = null;

  startValidation() {
    if (this.validation) {
      this.validation.cleanup();
    }

    this.validation = new IdentityValidation({
      validationMechanism: 'iframe',
      host: 'https://your-host.com',
      token: 'your-token',
      target: this.iframeContainer.nativeElement,
    });

    this.validation.on('success', () => {
      console.log('Validation successful!');
    });

    this.validation.on('error', () => {
      console.error('Validation error.');
    });

    this.validation.makeFullIdentityValidation('12345678900');
  }

  ngOnDestroy() {
    if (this.validation) {
      this.validation.cleanup();
      this.validation = null;
    }
  }
}
```

## Methods

### `makeFullIdentityValidation(userDocument?: string): void`

Starts the identity validation process. The `userDocument` parameter is optional and represents the user's document.

### `makeFacematchValidation(userDocument: string, imgDocFront?: string): void`

Starts the facematch validation process.

- `userDocument`: Required. It represents the user's document.
- `imgDocFront`: Optional. A base64-encoded image of the front of the user's document to assist in the facematch comparison.

### `on(event: SDKEvent, handler: () => void): void`

Registers a handler for a specific event. Available events include:

- `success`: Triggered when validation is successful.
- `fail`: Triggered when **logical validation** fails, meaning the user's provided data or the expected process does not meet the required criteria. Examples:
  - Document validation fails due to incorrect or incomplete information.
  - **Liveness** validation fails because the detected face does not match or facial detection is absent.
- `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 validation window is closed.

### `off(event: SDKEvent, handler?: () => void): void`

Removes the registered handler for a specific event. If a `handler` is provided, only that handler will be removed. If no `handler` is provided, **all** handlers for the event will be removed.

### `close(): void`

Closes the window, iframe, or tab opened for the validation process.

### `cleanup(): void`

Removes all registered event handlers to prevent multiple event instances when starting a new validation. Additionally, this method closes the window, tab, or iframe opened during the validation process.