Compatible Browsers

The capture frame provided through the SDK is compatible with the following combinations of browsers and operating systems:

In general, the SDK supports WebRTC and the more recent versions of the browsers listed above. For compatibility and security reasons, functionality on very old versions of these browsers is not guaranteed.

Webview Operation

It is a system component that allows Android or iOS applications to display web content directly within the app, based on the same code project. It is responsible for navigation on websites and web content within the apps.

Preconditions

• It is necessary to have implemented the Web SDK in an application that contains a secure domain with the https protocol.

Compatibility with Operating Systems

Android:

The Web SDK is compatible with webviews running on Android 8 (API 26) or higher.

For the SDK to work correctly, it is necessary to add some permissions and configurations to the AndroidManifest file, which are as follows:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.webkit.PermissionRequest" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
<uses-feature android:name="android.hardware.camera2.full" />
<uses-feature android:name="android.hardware.camera2.autofocus" />

It is recommended to use Chromium-based webviews with some customizations for better JavaScript performance. You can find an implementation example through our PoCs here.

iOS

The Web SDK is compatible with webviews running on iOS 13 or higher.

For the SDK to function correctly, it is necessary to add some permissions and configurations to the info.plist file, which are as follows:

<key>NSCameraUsageDescription</key>
<string>Camera usage description</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Mensagem da cliente</string>

iOS provides two ways to use webviews in applications: WKWebView and SFSafariViewController. We recommend using SFSafariViewController for better compatibility with DOM resources. You can find an implementation example through our PoCs here.

Compatibility with Hybrid Frameworks

The component has been approved only for native layers. To be used in hybrid frameworks (Flutter or React Native), it is necessary to implement it in the native layer of Android and/or iOS.

Compatibility with social media webviews

The component has been approved on the Instagram and Facebook social media platforms in Liveness mode without interaction. The Liveness mode with interaction is not compatible with webviews in social media apps.

Installing the Web SDK

To implement the Unico IDCloud Android SDK into your Android application, follow the step-by-step guide below:

<meta
  http-equiv="Content-Security-Policy"
  content="
      script-src 'self' 'unsafe-eval' *.googleapis.com *.acesso.io *.unico.run *.unico.io *.unico.app; 
      worker-src 'self' blob:; 
      child-src 'self' blob:;
            style-src 'self' 'unsafe-inline' *.googleapis.com *.acesso.io *.unico.run *.unico.io *.unico.app;
            font-src 'self' https://fonts.gstatic.com *.acesso.io *.unico.run *.unico.io *.unico.app;
            img-src 'self' data: blob: *.acesso.io *.unico.run *.unico.io *.unico.app;
            media-src 'self' data: *.acesso.io *.unico.run *.unico.io *.unico.app;
      script-src-elem 'self' 'unsafe-inline' blob: *.googleapis.com *.acesso.io *.unico.run *.unico.io *.unico.app"
/>

import { UnicoConfig } from "unico-webframe"

const config = new UnicoConfig()
  .setHostname("<YOUR_HOSTNAME>")
  .setHostKey("<YOUR_HOST_KEY>");

import { UnicoConfig } from "unico-webframe"

const config = new UnicoConfig();
  .setProjectNumber("<YOUR_PROJECT_NUMBER>");
  .setProjectId("<YOUR_PROJECT_ID>");
  .setMobileSdkAppId("<YOUR_MOBILE_SDK_APP_ID>");
  .setHostname("<YOUR_HOSTNAME>");
  .setHostInfo("<YOUR_HOST_INFO>");
  .setHostKey("<YOUR_HOST_KEY>");

npm install unico-webframe

yarn add unico-webframe

import { UnicoCheckBuilder, SelfieCameraTypes, UnicoThemeBuilder, DocumentCameraTypes, UnicoConfig, LocaleTypes } from 'unico-webframe'

import { UnicoCheckBuilder, SelfieCameraTypes, UnicoThemeBuilder, DocumentCameraTypes, UnicoConfig, LocaleTypes } from 'UnicoCheckBuilder.min.js'

Done. Once the SDK installation is complete, proceed to the implementation by reading the following usage and integration guide:

Guia de uso e integração | IDCloud APIs

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

This guide has been designed to help you quickly and easily implement the Web SDK. Below, you'll find the step-by-step process for the complete integration. If you wish to customize the experience further, check out the Web Customization section.

Initializing the SDK

To get started, follow these 3 simple steps in your project:

Instantiate a new Builder:

const unicoCameraBuilder = new UnicoCheckBuilder();

Specify the path of the additional files (if added to your project):

unicoCameraBuilder.setResourceDirectory("/resources");

Specify the path of the AI model files, if using the Intelligent Camera feature.

unicoCameraBuilder.setModelsPath("https://meusite.com.br/models");

Environment Configuration

It is possible to configure the environment to be used when running the SDK. Use the enumerated SDKEnvironmentTypes, which contains the following enumerations:

• SDKEnvironmentTypes.PROD: for the Production environment;

• SDKEnvironmentTypes.UAT: for the Staging environment.

Here is an example of how to implement it:

import {
  ...
  UnicoCheckBuilder,
  SDKEnvironmentTypes
  ...
} from "unico-webframe"

unicoCameraBuilder.setEnvironment(SDKEnvironmentTypes.UAT);

Implementing the Callback Functions

One of the objects that should be passed as a parameter to the method responsible for rendering the capture frame is the callback object. This object should contain callback functions for success and error cases, as exemplified below.

  const callback = {
    on: {
      success: (obj) => {
        console.log(obj.base64);
        console.log(obj.encrypted);        
      },
      error: (error) => {
        console.error(error)
        //confira na aba "Referências" sobre os erros possíveis
      }
    }
  };

This object is mandatory, and if it is not correctly implemented (covering all success or error events), it will generate an exception, which, if not handled, will be displayed in the user's console.

Configure and Start

To start the camera with the settings made so far, you need to create an instance of the builder using the build() method.

const unicoCamera = unicoCameraBuilder.build();

Then, with the camera "assembled", you need to configure the camera's capture mode.

The camera preparation will be done using the prepareSelfieCamera() method, provided by the builder. This method takes 2 parameters:

• The UnicoConfig class obtained in this step;

• The desired camera mode, which can be one of the following:

  • SelfieCameraTypes.NORMAL for the normal camera mode;

  • SelfieCameraTypes.SMART for the smart camera mode.

This method returns a promise, which, when resolved, returns an object used to effectively open the camera via the open method. The open method takes as parameters the callback functions configured in the previous step.

If you wish to use automatic capture, pass the parameter Unico.SelfieCameraTypes.SMART to the prepareSelfieCamera method.

For smart capture, the computer vision models should also be loaded through the setModelsPath method, as explained in the first step of this guide.

Using the UnicoConfig class:

const config = new UnicoConfig()
  .setHostname("<YOUR_HOSTNAME>")
  .setHostKey("<YOUR_HOST_KEY>");

  unicoCamera.prepareSelfieCamera(
    config, 
    SelfieCameraTypes.SMART
  ).then(cameraOpener => {
    cameraOpener.open(callback);
  }).catch(error => {
    console.error(error);
    // confira na aba "Referências" sobre os erros possíveis
  });

Configure Capture Mode in iFrames

It is possible to use the Web SDK with embedded Interactive Liveness in an iFrame. To do this, you need to implement a process similar to the previous section when preparing the camera.

The camera preparation will be done through the method prepareSelfieCameraForIFrame(), also provided by the builder. This method takes the same parameters as prepareSelfieCamera():

const unicoCamera = unicoCameraBuilder.build();

const config = new UnicoConfig()
  .setHostname("<YOUR_HOSTNAME>")
  .setHostKey("<YOUR_HOST_KEY>");

  unicoCamera.prepareSelfieCameraForIFrame(
    config, 
    SelfieCameraTypes.SMART
  ).then(cameraOpener => {
    cameraOpener.open(callback);
  }).catch(error => {
    console.error(error);
    // confira na aba "Referências" sobre os erros possíveis
  });

Implementing the iFrame Element

For the capture to work correctly, it is necessary to implement the <iframe> element as shown in the example below:

<iframe allow="fullscreen;camera;geolocation" allowFullScreen src="your_app_url"></iframe>

Fullscreen Behavior

To perform the capture, it is required to be in full-screen mode in the browser so that the SDK can resize automatically. Therefore, when performing the capture, the SDK will display a screen requesting that the frame be opened in full-screen mode. See the following example:

After allowing fullscreen usage, the capture frame will open normally:

Making a POST Request to the Client API

Capturing the images is only the first part of the journey. After capturing the image, it is necessary to send the encrypted data generated by the SDK to the by Client REST APIs. For more information, refer to the CreateProcess section of by Client.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

This guide has been designed to help you implement the Web SDK quickly and easily. Below, you will find a step-by-step process for the entire integration. After that, if you wish to customize the experience, be sure to check the Web Customization section.

Available Document Frames

In this camera mode, there is a capture frame to assist the user in positioning the document correctly. Once the document is positioned properly, the user must click the button to capture the document photo.

In this camera mode, it is possible to capture the following documents:

• CPF: Capture the front of the CPF;

• CNH: Capture the open CNH;

• CNH Front: Capture the front of the CNH;

• CNH Back: Capture the back of the CNH;

• RG Front: Capture the front of the RG;

• RG Back: Capture the back of the RG;

• Others: Capture any other document.

Initializing the SDK

To get started, you need to perform 2 simple steps in your project:

Instantiate a new Builder:

const unicoCameraBuilder = new UnicoCheckBuilder();

Specify the path for additional files (if added to your project):

unicoCameraBuilder.setResourceDirectory("/resources");

Configure Frame Size

It is recommended that you configure the size of the frame within your application to optimize the capture area within your WebApp. Below is how to make this configuration for Web Desktop or Mobile.

<div class="container">
  <div id="box-camera"></div>
</div>

.container {
  width: 800px;
  height: 600px;
  position: relative;
}

Implementing the Callback functions

One of the objects that must be passed as a parameter to the method responsible for rendering the capture frame is the callback object. This object should contain callback functions for success and error cases, as exemplified below:

  const callback = {
    on: {
      success: (obj) => {
        console.log(obj.base64);
        console.log(obj.encrypted);
      },
      error: (error) => {
        console.error(error)
      },
    }
  };

This object is mandatory, and if not properly implemented (covering all success or error events), it raises an exception, which, if not handled, is displayed in the user's console.

Configure and Start Camera

To start the camera with the settings made so far, it is necessary to create an instance of the builder through the build() method.

const unicoCamera = unicoCameraBuilder.build();

Then, with the camera "assembled," the capture mode of the camera must be configured.

The camera preparation is carried out using the prepareDocumentCamera() method, available from the builder. This method takes two parameters:

• The UnicoConfig class obtained in this step;

• The type of document to be captured, which are:

This method returns a promise that, when resolved, returns an object that is used to actually open the camera through the open method, which takes as a parameter the callback functions configured in the previous step.

Below is an example using the CNH capture:

Using the UnicoConfig class:

  const config = new UnicoConfig()
    .setProjectNumber("<YOUR_PROJECT_NUMBER>")
    .setProjectId("<YOUR_PROJECT_ID>")
    .setMobileSdkAppId("<YOUR_MOBILE_SDK_APP_ID>")
    .setHostname("<YOUR_HOSTNAME>")
    .setHostInfo("<YOUR_HOST_INFO>")
    .setHostKey("<YOUR_HOST_KEY>");

  unicoCamera.prepareDocumentCamera(
    config, 
    DocumentCameraTypes.CNH
  ).then(cameraOpener => {
    cameraOpener.open(callback);
  }).catch(error => {
    console.error(error);
    // confira na aba "Referências" sobre os erros possíveis
  });

Making a POST Request to the Client API

Capturing the images is just the first part of the journey. After capturing the image, it is necessary to send the base64 generated by the SDK to the REST APIs of by Client. Learn more in the CreateProcess section of by Client.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

SDK Components

The SDK implements components prepared with HTML attributes for accessibility, such as aria-label, tabindex, role, among others, which enable keyboard navigation between elements, activate audio guidance, and are used by screen reader software.

Best Practices

When integrating the Web SDK into a page, there may be other interactive elements on the page that are not visible during the camera opening and image capture flow. These elements may end up causing conflicts with the information in the capture flow, disrupting the user experience. Therefore, it is important to remove or deactivate interaction with other elements while the capture is being performed.

This can be done in several ways, depending on the existing elements and frameworks used on the page. Below is an example using the aria-hidden attribute:

// page html
// <div id="main-content">
//  <header>...</header>
//  <button id="my-button">Interactive Button</click>
//  <footer>...</footer>
// </div>


const unicoSdk = new UnicoCheckBuilder().build();

unicoSdk
  .prepareSelfieCamera(...)
  .then((cameraOpener) => {
    const pageElement = document.getElementById('main-content');
    pageElement.setAttribute('aria-hidden', true);
    
    cameraOpener.open({
      on: {
        success: (obj) => {
          pageElement.setAttribute('aria-hidden', false);
        },
        error: (error) => {
          pageElement.setAttribute('aria-hidden', false);
        },
      },
    });
  });

References

• https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

ErrorBio​ Object

This object is returned whenever an error occurs in the Web SDK.

Available Methods

Below is a list of possible error codes from the Web SDK, in the prepareCamera method:

Below is a list of possible error codes from the Web SDK, in the openCamera method:​

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

The Web SDK allows for some customizations to be made. Below are all the possible customizations for this SDK.

Customize Language

It is possible to configure the experience of the informational messages in the capture frames by changing their language. Use the enumerated type LocaleTypes, which contains the following values:

• LocaleTypes.PT_BR: for Portuguese(Brazil);

• LocaleTypes.ES_MX: for Spanish(Mexico);

• LocaleTypes.ES_ES: for Spanish(Spain);

• LocaleTypes.EN_US: for English(USA).

See how to implement it in the example below:

import {
  ...
  UnicoCheckBuilder,
  LocaleTypes
  ...
} from "unico-webframe"

unicoCameraBuilder.setLocale(LocaleTypes.EN_US);

Customize Capture Experience

This is an optional step, but highly recommended to ensure the capture process aligns with your company's visual identity.

To customize the capture frame using the Theme Builder, simply create an instance of the UnicoThemeBuilder class and invoke the methods that customize each of the properties of the capture frame, as demonstrated in the example below:

const unicoTheme = new UnicoThemeBuilder()
.setColorSilhouetteSuccess("#0384fc")
.setColorSilhouetteError("#D50000")
.setColorSilhouetteNeutral("#fcfcfc")
.setBackgroundColor("#dff1f5")
.setColorText("#0384fc")
.setBackgroundColorComponents("#0384fc")
.setColorTextComponents("#dff1f5")
.setBackgroundColorButtons("#0384fc")
.setColorTextButtons("#dff1f5")
.setBackgroundColorBoxMessage("#fff")
.setColorTextBoxMessage("#000")
.setColorCancelButton("#0384fc")
.setColorProgressBar("#0384fc")
.setHtmlPopupLoading(`<div style="position: absolute; top: 45%; right: 50%; transform:
translate(50%, -50%); z-index: 10; text-align: center;">Carregando...</div>`)
.build();

After generating the theme object, as demonstrated above, it must be passed as a parameter to the setTheme method of the unicoCameraBuilder.

unicoCameraBuilder.setTheme(unicoTheme);

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Versão 3.20.5 - 09/06/2025

• Updating the Liveness SDK and server with interaction;

Version 3.20.4 - 04/06/2025

• Improvements in liveness flow with interaction against recurring market attacks.

• Internal product improvements. These improvements do not directly affect the end user experience, leaving the interface and external functionalities unchanged.

Version 3.20.3 - 26/05/2025

• Updating the Liveness SDK and server with interaction;

Version 3.20.2 - 17/05/2025

• Updating the Liveness SDK and server with interaction;

Version 3.20.1 - 07/05/2025

• Updating the Liveness SDK and server with interaction;

• Accessibility improvements to the Liveness flow with interaction.

Version 3.20.0 - 31/03/2025

• Update of the Liveness SDK and server with interaction;

• Fix for handling issues when using LocalStorage.

Version 3.19.3 - 10/03/2025

• Updated Liveness SDK and Interactive Server.

Version 3.19.2​ - 29/01/2025

• New method to customize fonts in the class UnicoThemeBuilder;

• Internal product improvements. These improvements do not directly affect the end-user experience, keeping the interface and external functionality unchanged.

Version 3.19.1​ - 20/01/2025

• Internal product improvements. These improvements do not directly affect the end-user experience, keeping the interface and external functionality unchanged.

Version 3.19.0​ - 17/01/2025

• Updated Liveness SDK and Interactive Server;

• Add frame OTHERS_V2;

• Internal product improvements. These improvements do not directly affect the end-user experience, keeping the interface and external functionality unchanged.

Version 3.18.11​ - 18/12/2024

• Updated Liveness SDK and Interactive Server;

• Internal product improvements. These improvements do not directly affect the end-user experience, keeping the interface and external functionality unchanged.

Version 3.18.10​ - 10/12/2024

• Updated Liveness SDK and Interactive Server;

• Accessibility improvements to the Liveness stream with interaction.

Version 3.18.9​ - 18/11/2024

• Updated Liveness SDK and Interactive Server.

Version 3.18.8​ - 24/10/2024

• Updated Liveness SDK and Interactive Server;

• Resolution of conflicts between observability tools.

Versão 3.18.7​ - 15/10/2024

• SDK Update and Liveness Server Interaction.

Still need help?​

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.