1 de 96

English (United States)

Welcome

Here you will find the technical information for the Unico IDCloud platform's REST APIs

Overview

Welcome to the Unico IDCloud platform REST API documentation! On this page, you'll find everything you need to know to enhance the security and quality of your applications using our REST API.

Learn more about

GETTING STARTED

Capabilities

In this section, you will find a description of all the capabilities of the Unico IDCloud platform

Below, you will find a detailed explanation of how each capability works:

Liveness

When there is a need to verify if the person is real and alive at the time of the operation, it can be used either independently or in conjunction with the capabilities of Identity Verification, Behavior Alert, Risk Score, and Validation (1:1). It should always be used in conjunction with the SDKs.

The possible responses are:

YES: indicates that the user is alive at the moment the selfie is captured.
NO: indicates that the user is not alive at the moment the selfie is captured.

Commonly referred to as IDLive or Smartlive/Liveness with Interaction.

Identity Verification

When there is a need to ensure that the user performing the process is who they claim to be, it is by default always used in conjunction with the Liveness capability.

The possible responses are:

YES: indicates that the face belongs to the actual holder of the CPF (Cadastro de Pessoas Físicas).
NO: indicates that the face does not belong to the actual holder of the CPF.
INCONCLUSIVE: indicates that there is insufficient evidence to determine whether the face belongs to the actual holder of the CPF.

Commonly referred to as IDUnico.

Behavior Alert

The Behavior Alert complements the Identity Verification response by adding the behavior component, which provides certainty about a risk associated with that identity, based on previous fraudulent behavior. It can only be used in conjunction with the Identity Verification capability.

The possible responses are:

YES: indicates that the face has been involved in fraudulent identity transactions.
SUSPICIOUS: indicates that the face has had at least one occurrence in our database with a different identifier.
INCONCLUSIVE: indicates that there is insufficient evidence to suggest that the face is involved in fraudulent transactions in our database.

Commonly referred to as Trust or IDTrust.

Risk Score

The Risk Score capability is being deprecated and can only be used in exceptional cases. To verify the eligibility of your case, please contact the person responsible for your account.

When there is a need to obtain a probability score about whether the user performing the process is who they claim to be, it can only be used in orchestration with the Identity Verification capability when the response is "INCONCLUSIVE."

The possible responses are:

Positive Score: can range from +10 to +100. The higher the score, the greater the probability that the face belongs to the actual holder of the CPF. (Cadastro de Pessoas Físicas).
Zero Score: indicates a registration error. We recommend a new capture be taken.
Negative Score: can range from -10 to -100. The lower the score, the greater the probability that the face does not belong to the actual holder of the CPF.

Classification

Score

Recommendation

Negative

Between -40 and -100

We recommend denying the registration

Negative

Between -10 and -39

We recommend that the client assess the associated risks before making a decision

Neutral

Zero Score

We recommend denying the registration and asking the user to capture a new photo of the actual holder of the CPF

Positive

Between +10 and +49

We recommend that the client evaluate the risks involved in making a decision

Positive

Between +50 and +100

We recommend approving the registration

Commonly referred to as Check or Unico Check.

Validation (1:1)

When there is a need to recognize if the person in the operation is the same one who completed the registration, it is by default always used in conjunction with the Liveness capability. It can only be used in cases where an Identity Verification process has already been completed.

The possible responses are:

YES: indicates that the face performing the transaction is the same as the one that completed the process used as a reference.
NO: indicates that the face performing the transaction is not the same as the one that completed the process used as a reference.

Commonly referred to as Biometric Token or Transactional Token.

Document Capture and Reuse

When there is a need to request, store, and reuse documents, we offer the ability to leverage users' personal documents (Passport, CIN, RG, and CNH—both digital and physical), reducing friction. If we do not have the documents in our database, it is possible to capture them.

This capability can only be used in conjunction with the Identity Verification capability. For document validation, we use the following technologies:

Typification: indicates whether the provided document is valid or not.
OCR: involves extracting data from the document based on an image.
FaceMatch: involves comparing the face in the selfie with the face on the document.
CPF Match: involves searching for a specific CPF in the provided document.

Commonly referred to as IDDOCS.

Electronic Signature

When there is a need to use biometrics to sign a document, utilize the same method of user authentication throughout the journey to finalize the operation with the contract signature.

*The electronic signature capability is only available through the by Unico integration mode in flows that involve other capabilities.

Commonly referred to as SIGN or IDSIGN.

Serpro Similarity Return

The Serpro similarity return is not a native capability of IDCloud but rather an additional feature incorporated to comply with a regulation from Dataprev concerning INSS payroll credit operations aimed at retirees and pensioners.

Since these operations require the SERPRO similarity return, the IDCloud platform has been adjusted to include this functionality as an option in the product. When using the SERPRO similarity feature, the API response will be the score of similarity.

Commonly referred to as IDSerpro.

When Serpro finds the face, it returns a score from 0-100, as in the example below:

"government": {
        "serpro": 93.0
    }

When Serpro does not find the face, the score -1 is returned, as in the example below:

"government": {
        "serpro":-1
    }

When there is an error in the integration with Serpro, the score -2 is returned, as in the example below:

"government": {
        "serpro":-2
    }

To understand how you can use each of the capabilities, be sure to visit the "Integration Methods" section at the link below:

Integration Methods

In this section, you will learn more about the integration methods of the Unico IDCloud platform

by Unico

For companies that wish to have a partner to manage the user experience with best practices and privacy, as well as the ease of orchestrating flows with Unico's capabilities and automatic technology updates, such as SDKs.

With by Unico, you will have a team of security experts and UX design best practices to ensure the best possible conversion in your operation. It can be used responsively on both Desktop and Mobile. Offering the following usage possibilities:

Channel

Redirect

Open.window()

iFrame

Webview

Mensagens

Desktop

Webmobile

App mobile

For the message flow, it is possible to send notifications through the channels of WhatsApp and/or SMS.

Check out the end-user experience with by Unico in Messaging, Webview, and iFrame, respectively, in the tabs below:

by Client

For companies that wish to control the user experience with their own frontend, as well as build flows using Unico’s capabilities on the backend alongside other technologies and resources used for authentication.

With by Client, you have the freedom you need to create and manage the end-user journey as you see fit, leveraging the capabilities of the Unico IDCloud platform as necessary.

Capabilities and Integration Methods

In this section, you will find which capabilities are available for each integration method of the Unico IDCloud platform

To meet the various use cases of your operation, the capabilities of IDCloud have different availability depending on the integration methods. Below, check out the table with all the usage possibilities, separated by integration method:

In each integration method, it is possible to combine various capabilities with each other. To learn more about the possible flows in each integration method, access the respective menus below:
For both integration methods, it is also possible to obtain the similarity response from Serpro.

INTEGRATIONS

Quickstart

In this section, you will find an overview of how to integrate with the Unico IDCloud platform

Integration Overview

Authenticate

Define the Capabilities You Will Use

What capabilities do you need for your operation? Identity Verification? Liveness?

Define Your Integration Method

Create a Process

Check the Process Result

Once the process is complete, check the result in the integration method you chose.

Done. With the result in hand, make the decision to approve or deny the user's registration.

Authentication

In this section, you will find the full technical specifications for the authentication method required to use the IDCloud platform’s REST APIs

To use the IDCloud platform, it is necessary to authenticate via an access token, using the authentication system known as OAuth2.

The OAuth2 authentication system from Unico supports server-to-server interaction between a web application and Unico's services.

For this scenario, you will need a service account, which is an impersonal account belonging to your application and not to an individual user. Your application calls Unico’s APIs on behalf of the service account, so users are not directly involved. This scenario is called “two-legged OAuth,” or “2LO.” Typically, an application uses a service account when the application calls Unico’s APIs to work with its own data rather than user data.

This is step zero to begin your implementation; therefore, do not skip this step.

Creating a Service Account

In this section, you will find instructions on how to create a service account to authenticate with the Unico IDCloud platform.

To use server-to-server interactions, you need to request the creation of a service account through the project manager responsible for your company by providing the following information: company name, application name, name, email, and phone number of the person responsible for the application within the company. Separate accounts are required for the Homologation and Production environments.

Once this information is received, a service account responsible for authenticating your application will be created, and an email will be sent to generate the key pair for the account.

A service account credential includes a unique account name, a company identifier (Tenant ID), and at least one key pair (public and private). After generating the keys, you will only receive the private key (a .key.pem file) along with the payload that must be used to construct the JWT. This payload will follow the format below:

If you need the public key to configure it in your system, contact the project manager responsible for your account. It is also possible to generate a public key using the following openssl command:

openssl req -x509 -new -nodes -sha256 -days 720 \
-key fileName.key.pem -out fileName.cert.pem

Preparing to Make an Authenticated API Request

In this section, you’ll find instructions on how to complete the authentication process on the Unico IDCloud platform

After creating and configuring a service account, your application needs to complete the following steps:

Create a JSON Web Token (JWT), which includes the header, payload, and signature.
Request an Access Token from the OAuth2 authentication platform.
Process the JSON response returned by the authentication platform.

If the response includes an access token, you can use it to make requests to Unico product APIs for which the service account has access permissions. (If the response does not include an access token, your JWT or token request may be incorrect, or the service account might lack the necessary permissions to access the requested resources.)

The access token generated in the above request has a default validity of 3600 seconds, but this may vary based on the security configuration set for your company. When the access token expires, your application must generate a new JWT, sign it, and request a new access token from the authentication platform.

1 - Creating the JWT

A JWT (JSON Web Token) consists of three parts: a header, a payload, and a signature. The header and payload are JSON objects, which are serialized in UTF-8 and then encoded using Base64url encoding. This encoding ensures resilience against modifications due to repeated encoding operations. The header, payload, and signature are concatenated using a period (.) separator.

A JWT is structured as follows:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

The base text for the signature is formed in the following way:

{Header in Base64url}.{Payload em Base64url}

1.1 - Forming the JWT Header

The header consists of two fields that specify the signing algorithm and the token format. Both fields are mandatory, and each field has only one value. Service accounts rely on the RSA SHA-256 algorithm and the JWT token format.

As a result, the JSON representation of the header is as follows:

{"alg":"RS256","typ":"JWT"}

The Base64url representation is as follows:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

This ensures that both header and payload are properly encoded before signing, which is crucial for secure authentication.

1.2 - Forming the JWT Payload

The JWT payload contains information about the JWT, including the requested permissions (scopes), the account requesting access, the issuer, the time the token was issued, and the token's lifespan. Most fields are mandatory. Like the JWT header, the payload is a JSON object and is used in the composition of the signature.

1.3 - Required Fields

The required fields in the JWT are shown in the table below. They can appear in any order within the payload.

Name

Description

iss

The identifier of the service account within the company.

scope

A space-delimited list or a list separated by the plus sign (+) of the permissions that the application is requesting. If all permissions of the account are required, use the asterisk sign (*) for that purpose.

aud

exp

The expiration time of the token, specified in seconds since 00:00:00 UTC, January 1, 1970. This value has a maximum time of 1 hour after the moment of issuing the JWT. This value must be numeric. Common cases that DO NOT work:

Using quotes to delimit the value. For example: “1524161193” is a string and will not work. However, 1524161193 is a number and will work.

iat

The moment of issuing the JWT, specified in seconds since 00:00:00 UTC, January 1, 1970. This value must be numeric.

Using quotes to delimit the value. For example: “1524161193” is a string and will not work. However, 1524161193 is a number and will work.

Understand how the conversion works for the issuance (iat) and expiration (exp) fields of the JWT, and also see examples of how to use the values of these fields here. Additionally, the "iat" field should reflect the current time in the required format, and the "exp" field must adhere to the calculation below:

exp = iat + 3600

The representation of the mandatory JSON fields in the JWT payload is as follows:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, //This is just an example. Use the current value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}

1.4 - Calculating the Signature

The JSON Web Signature (JWS) specification is the mechanism that guides the calculation of the signature for a JWT. The input content for the signature calculation is the byte array of the following content:

{Header in Base64url}.{Payload in Base64url}

The same algorithm specified in the header of the JWT must be used for the signature calculation. The only signature algorithm supported by the OAuth2 authentication platform is RSA using SHA-256. It is expressed as RS256 in the alg field of the JWT header.

Sign the UTF-8 representation of the input content using SHA256withRSA (also known as RSASSA-PKCS1-V1_5-SIGN with SHA-256 hash) with the private key that was created and associated with the service account (the .key.pem file generated from the request received by email). The output content will be a byte array.

The signature must then be encoded in Base64url. The header, payload, and signature must be concatenated with a period (.). The result is the JWT. It should be in the following format: {Header in Base64url}.{Payload in Base64url}.{Signature in Base64url} Below is an example of a JWT token before Base64url encoding:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

Below is an example of a JWT token before Base64url encoding:

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, //This is just an example. Use the current value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}.
[byte array from signature]

Below is an example of the JWT that has been signed and is ready for transmission:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRf
bmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb
3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2
-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqo
YSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-
H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-
gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-
2mhIxuecNSw

2 - Making a Request for an Access Token

After generating the signed JWT, an application can use it to request an access token. The access token request is a POST HTTPS request, and the body must be URL encoded. The URL is as follows:

https://identityhomolog.acesso.io/oauth2/token

The parameters below are mandatory in the request:

Name

Description

grant_type

Use the following text, URL-encoded if necessary: urn:ietf:params:oauth:grant-type:jwt-bearer.

assertion

The JWT, including the signature.

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-
bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY
291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsInN1YiI6InVzZXJfaWRlbnRpZmllciIs
ImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI
6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.TjH-mTtwP6tBB93O1sDPaAA6yUF7N2-HZDlpIPz
bf_dxO8A6KZuRWG8ZnICrxX56qj0HREiMlYy27XJgxowrUa0JHvbqc8HJkT7-6Mh7J67UnubZKG1-hi
6jDtkC9BIXBcOhtkNUfZvZetXjLzsRsSDkqxdMtzYZwkRlocvaxL5QXiQhweeEwK_Ux81Adh3z0EIhT
yl7CKJLJ69PuHS7s9IdrjUl79owipp4LF1FvtMhoe7YIL69ohPgFqSv_-Y9qpPdW6be3OEAyKlOM08S
ZBbHBwW4XMvw3uZjTY1sgJ4cBoxrftDpjYOw34oPOKxirqc5-90uOCYe1O1hRtG45w

If the JWT and the access token request were properly formed and the service account has the necessary permissions, then the response from the authentication platform returns a JSON object containing an access token. Here’s an example of a response from the platform:

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

4 - The duration of the access token

The duration of the access token is variable. Its duration is specified in the "expires_in" field, returned along with the access token. The same access token should be used during its validity for all calls to the product APIs.

Do not request a new access token until the validity of the current token is nearing its end. We recommend a margin of 600 seconds (10 minutes). To do this, perform the calculation:

decoded token:
new Date(token.exp - 600)

Where token.exp is the timestamp of the token's expiration.

By default, the token sent to the company is valid for 1 hour, but this can be changed. It is recommended to always use the expires_in as a reference and subtract 600 seconds from it to request a new token.

Examples:

Standard scenario:
expires_in: 3600 (1h) - Token generation at 2:42 PM

Request a new token only at 3:32, that is, 2:42 + (3600 - 600)

Scenario with altered duration:
expires_in: 7200 (2h) - Token generation at 2:42 PM

Request a new token only at 4:32, that is, 2:42 + (7200 - 600)

A new access token can be requested when there are 10 minutes left until expiration.

Do not use a fixed time to obtain a new token, as the duration of the received token may be shorter than the established time, which will result in service usage failures.

¹ According to RFC 4648 for BaseN encoding, the Base64url format is similar to the Base64 format, except that the character = should be omitted, and the characters + and / should be replaced with - and _, respectively.

Additional Resources

In this section, you will find additional resources related to authentication

Postman Collection

In this section, you will find the Postman collection for the REST API to authenticate on the Unico IDCloud platform

Download the file below, import it into Postman, and replace the values of the parameters "service_account," "tenant_id," and "secret_key" to test the request.

API

In this section, you will find everything related the REST APIs for using the by Unico integration method

API Reference

In this section, you will find all available REST APIs for using the by Unico integration method

CreateProcess

In this section, you will find how to create a process in Unico via the REST API

Introduction

In this section, you will find detailed documentation on how the Process Creation endpoint works in by Unico. Note that to utilize the capabilities of the IDCloud platform in this integration method, you only need to change the value of the "flow" parameter when creating the process. Unico will handle the orchestration of all the desired capabilities.

Learn more about using capabilities in by Unico in the Overview section.

Getting started

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

Endpoints:

Process Creation

Processes must be created exclusively through backend-to-backend communication, due to our CORS policy, which prevents processes from being created through frontend-to-backend communication.

The requirement for parameters in process creation may change depending on the flows used. For example:

In flows that involve Electronic Signature, it is mandatory to send the payload object and all its properties;
In flows that involve Validation (1:1), it is mandatory to send the bioTokenId property.

Tips:

For more information about the possible errors for this endpoint, refer to the Errors section.

GetProcess

In this section, you will find how to obtain the result of a process in by Unico through the REST API

Introduction

In this section, you will find detailed documentation on how the Process Result Query endpoint works in by Unico.

Getting started

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

Endpoints:

Process Result

Processes must be created exclusively through backend-to-backend communication, due to our CORS policy, which prevents processes from being created through frontend-to-backend communication.

The content returned in the process.services.documents.doc.data parameter, referring to the OCR Extraction technology, can be consulted below:

If we are unable to extract a field from the document, it is not listed in the API return.

Tips:

To implement your business rules, always validate the response from the capabilities by checking the parameters in the following order:
- state = PROCESS_STATE_FINISHED AND result = PROCESS_RESULT_OK;
  - THEN, you can proceed with decision-making by analyzing the authenticationInfo parameter.
  - If you receive state = PROCESS_STATE_FINISHED with results result = PROCESS_RESULT_INVALID_IDENTITY or PROCESS_RESULT_ERROR, interpret this as an error in the biometric process and attempt the process again.
To improve the performance of your operation, you can use our Webhooks and only query the results of processes that are in the finalized statuses.
For more information about the possible errors for this endpoint, refer to the Errors section.

GetEvidenceSet

In this section, you will find instructions on how to obtain the evidential set from a process in by Unico via the REST API

Introduction

In this section, you will find detailed documentation on how the Get Evidence Set endpoint works in by Unico. This endpoint will provide the evidence set of the completed biometric transaction, allowing you to store it for possible future disputes by the end user.

Getting started

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

Endpoints:

Obtaining the Evidentiary Set

Processes must be created exclusively through backend-to-backend communication, due to our CORS policy, which prevents processes from being created through frontend-to-backend communication.

The evidentiary set is only available for completed processes.

For more information about the possible errors for this endpoint, refer to the Errors section.

Additional Resources

In this section, you will find additional resources related to the by Unico integration method

Controlling the experience

In this section, you will find the experience components that can be used with by Unico

API

In this section, you will find everything related the REST APIs for using the by Client integration method

API Reference

In this section, you will find all the available REST APIs for using the by Client integration method

Additional Resources

In this section, you will find additional resources related to the by Client integration method

SDK

In this section, you will find all the technical specifications of the available SDKs from the Unico IDCloud platform

SDK Integration

In this section, you will find all the necessary information to implement the SDKs of the Unico IDCloud platform

Android SDK

In this section, you will find all the necessary information to implement the Android SDK of the Unico IDCloud platform

iOS SDK

In this section, you will find all the necessary information to implement the Unico IDCloud platform's iOS SDK

Flutter SDK

Nesta seção, você encontrará todas as informações necessárias pra implementar o SDK Flutter da plataforma Unico IDCloud

Web SDK

In this section, you will find all the necessary information to implement the Web SDK of the Unico IDCloud platform

Additional Resources

In this section, you will find additional resources related to the SDK

help & faq

Preparing to Make an Authenticated API Request

In this section, you’ll find instructions on how to complete the authentication process on the Unico IDCloud platform

After creating and configuring a service account, your application needs to complete the following steps:

Create a JSON Web Token (JWT), which includes the header, payload, and signature.
Request an Access Token from the OAuth2 authentication platform.
Process the JSON response returned by the authentication platform.

1 - Creating the JWT

A JWT is structured as follows:

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

The base text for the signature is formed in the following way:

{Header in Base64url}.{Payload em Base64url}

1.1 - Forming the JWT Header

As a result, the JSON representation of the header is as follows:

{"alg":"RS256","typ":"JWT"}

The Base64url representation is as follows:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

This ensures that both header and payload are properly encoded before signing, which is crucial for secure authentication.

1.2 - Forming the JWT Payload

1.3 - Required Fields

The required fields in the JWT are shown in the table below. They can appear in any order within the payload.

Name

Description

iss

The identifier of the service account within the company.

scope

aud

Address of the authentication platform that issues access tokens. This value must always and exactly be Common cases that DO NOT work:

Inserting a trailing slash at the end of the address:
Using the HTTP protocol instead of HTTPS:

exp

Using quotes to delimit the value. For example: “1524161193” is a string and will not work. However, 1524161193 is a number and will work.

iat

The moment of issuing the JWT, specified in seconds since 00:00:00 UTC, January 1, 1970. This value must be numeric.

Using quotes to delimit the value. For example: “1524161193” is a string and will not work. However, 1524161193 is a number and will work.

exp = iat + 3600

The representation of the mandatory JSON fields in the JWT payload is as follows:

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, //This is just an example. Use the current value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}

1.4 - Calculating the Signature

{Header in Base64url}.{Payload in Base64url}

{Header in Base64url}.{Payload in Base64url}.{Signature in Base64url}

Below is an example of a JWT token before Base64url encoding:

{"alg":"RS256","typ":"JWT"}.
{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "exp": 1626296976, //This is just an example. Use the current value generated here.
  "iat": 1626293376 //This is just an example. Use the current value generated here.
}.
[byte array from signature]

Below is an example of the JWT that has been signed and is ready for transmission:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRf
bmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb
3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2
-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqo
YSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-
H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-
gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-
2mhIxuecNSw

It is also possible to use pre-established libraries to create the JWT. As a reference, you can find a list of libraries on the website.

2 - Making a Request for an Access Token

After generating the signed JWT, an application can use it to request an access token. The access token request is a POST HTTPS request, and the body must be URL encoded. The URL is as follows:

https://identityhomolog.acesso.io/oauth2/token

The parameters below are mandatory in the request:

Name

Description

grant_type

Use the following text, URL-encoded if necessary: urn:ietf:params:oauth:grant-type:jwt-bearer.

assertion

The JWT, including the signature.

POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-
bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY
291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsInN1YiI6InVzZXJfaWRlbnRpZmllciIs
ImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI
6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.TjH-mTtwP6tBB93O1sDPaAA6yUF7N2-HZDlpIPz
bf_dxO8A6KZuRWG8ZnICrxX56qj0HREiMlYy27XJgxowrUa0JHvbqc8HJkT7-6Mh7J67UnubZKG1-hi
6jDtkC9BIXBcOhtkNUfZvZetXjLzsRsSDkqxdMtzYZwkRlocvaxL5QXiQhweeEwK_Ux81Adh3z0EIhT
yl7CKJLJ69PuHS7s9IdrjUl79owipp4LF1FvtMhoe7YIL69ohPgFqSv_-Y9qpPdW6be3OEAyKlOM08S
ZBbHBwW4XMvw3uZjTY1sgJ4cBoxrftDpjYOw34oPOKxirqc5-90uOCYe1O1hRtG45w

3 - Handling the response from the authentication platform

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": "3600"
}

The access token returned in the “access_token” field of the JSON object is also a JWT that should be used for the APIs of Unico’s products. If an error occurs in the request, you can check the type of error in the error table by clicking .

4 - The duration of the access token

Do not request a new access token until the validity of the current token is nearing its end. We recommend a margin of 600 seconds (10 minutes). To do this, perform the calculation:

decoded token:
new Date(token.exp - 600)

Where token.exp is the timestamp of the token's expiration.

Examples:

Standard scenario:
expires_in: 3600 (1h) - Token generation at 2:42 PM

Request a new token only at 3:32, that is, 2:42 + (3600 - 600)

Scenario with altered duration:
expires_in: 7200 (2h) - Token generation at 2:42 PM

Request a new token only at 4:32, that is, 2:42 + (7200 - 600)

A new access token can be requested when there are 10 minutes left until expiration.

Do not use a fixed time to obtain a new token, as the duration of the received token may be shorter than the established time, which will result in service usage failures.

¹ According to RFC 4648 for BaseN encoding, the Base64url format is similar to the Base64 format, except that the character = should be omitted, and the characters + and / should be replaced with - and _, respectively.
² JSON Web Signature: .

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 .

Capabilities

In this section, you will find a description of all the capabilities of the Unico IDCloud platform

Below, you will find a detailed explanation of how each capability works:

Liveness

The possible responses are:

YES: indicates that the user is alive at the moment the selfie is captured.
NO: indicates that the user is not alive at the moment the selfie is captured.

Commonly referred to as IDLive or Smartlive/Liveness with Interaction.

Identity Verification

When there is a need to ensure that the user performing the process is who they claim to be, it is by default always used in conjunction with the Liveness capability.

The possible responses are:

YES: indicates that the face belongs to the actual holder of the CPF (Cadastro de Pessoas Físicas).
NO: indicates that the face does not belong to the actual holder of the CPF.
INCONCLUSIVE: indicates that there is insufficient evidence to determine whether the face belongs to the actual holder of the CPF.

Commonly referred to as IDUnico.

Behavior Alert

The possible responses are:

YES: indicates that the face has been involved in fraudulent identity transactions.
SUSPICIOUS: indicates that the face has had at least one occurrence in our database with a different identifier.
INCONCLUSIVE: indicates that there is insufficient evidence to suggest that the face is involved in fraudulent transactions in our database.

Commonly referred to as Trust or IDTrust.

Risk Score

The Risk Score capability is being deprecated and can only be used in exceptional cases. To verify the eligibility of your case, please contact the person responsible for your account.

The possible responses are:

Positive Score: can range from +10 to +100. The higher the score, the greater the probability that the face belongs to the actual holder of the CPF. (Cadastro de Pessoas Físicas).
Zero Score: indicates a registration error. We recommend a new capture be taken.
Negative Score: can range from -10 to -100. The lower the score, the greater the probability that the face does not belong to the actual holder of the CPF.

Classification

Score

Recommendation

Negative

Between -40 and -100

We recommend denying the registration

Negative

Between -10 and -39

We recommend that the client assess the associated risks before making a decision

Neutral

Zero Score

We recommend denying the registration and asking the user to capture a new photo of the actual holder of the CPF

Positive

Between +10 and +49

We recommend that the client evaluate the risks involved in making a decision

Positive

Between +50 and +100

We recommend approving the registration

Commonly referred to as Check or Unico Check.

Validation (1:1)

The possible responses are:

YES: indicates that the face performing the transaction is the same as the one that completed the process used as a reference.
NO: indicates that the face performing the transaction is not the same as the one that completed the process used as a reference.

Commonly referred to as Biometric Token or Transactional Token.

Document Capture and Reuse

This capability can only be used in conjunction with the Identity Verification capability. For document validation, we use the following technologies:

Typification: indicates whether the provided document is valid or not.
OCR: involves extracting data from the document based on an image.
FaceMatch: involves comparing the face in the selfie with the face on the document.
CPF Match: involves searching for a specific CPF in the provided document.

Commonly referred to as IDDOCS.

Electronic Signature

When there is a need to use biometrics to sign a document, utilize the same method of user authentication throughout the journey to finalize the operation with the contract signature.

*The electronic signature capability is only available through the by Unico integration mode in flows that involve other capabilities.

Commonly referred to as SIGN or IDSIGN.

Serpro Similarity Return

Commonly referred to as IDSerpro.

When Serpro finds the face, it returns a score from 0-100, as in the example below:

"government": {
        "serpro": 93.0
    }

When Serpro does not find the face, the score -1 is returned, as in the example below:

"government": {
        "serpro":-1
    }

When there is an error in the integration with Serpro, the score -2 is returned, as in the example below:

"government": {
        "serpro":-2
    }

To understand how you can use each of the capabilities, be sure to visit the "Integration Methods" section at the link below:

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 .

Overview

In this section you will find all the technical specifications of the by Unico REST APIs

Introduction

by Unico is a channel that provides an infrastructure of identity validation solutions from the IDCloud platform.

Its goal is to simplify the use of the capabilities of the IDCloud platform by offering a solution that can be integrated into your back-end and front-end, enhancing the security of transactions.

Compatible devices

Android

iOS

Compatible with all devices with front camera, Android 8+, armv7 or arm64.

Compatible with all iOS devices version 11 or higher.

Web

Compatible with all devices with a front camera, whether on laptops or mobile devices, adhering to the list of officially supported browsers below:

Native browsers

Mobile browsers

Computer/notebook browsers

iOS:
- version greater than or equal to 12.
Android:
- version greater than or equal to 5.

Android:
- Chrome: version greater than or equal to 90.
iOS:
- Safari: version greater than or equal to 14.1;
- Chrome: version greater than or equal to 90 (only for IOS version equal to or greater than 14.4).

Chrome:
- version greater than or equal to 85.

Firefox:
- version greater than or equal to 94.

Safari:
- version greater than or equal to 11.

Other browsers are not supported.

Possible Flows

To do this, you will only need to change the flow parameter in the REST API payload, which will give you several verification journey possibilities. See below the table relating the available flows and their respective capabilities:

Flow

Liveness

Identity Verification

Behavior Alert

Document Capture and Reuse

Electronic Signature

Validation (1:1)

Serpro Similarity Return

idlive

idlivetrust

idtrust

idunicodocs

idunicosign

idunicodocssign

idtrustdocs

idtrustsign

idtrustdocssign

idtoken

idtokentrust

idtokensign

If you use the Document Reuse and Capture capability, consider the following documents:

Brazilian ID (RG), Brazilian Driver's License, CIN and Brazilian Passport.

Flow depracateds

Flow with Risk score

Flow

Capabilities

idcheck

Liveness + Identity Verification + Risk Score

iddocs

Liveness + Identity Verification + Risk Score + Document Capture and Reuse

idsign

Prova de vida + Verificação de IdentidLiveness + Identity Verification + Risk Score + Electronic Signature

iddocssign

Liveness + Identity Verification + Risk Score + Document Capture and Reuse + Electronic Signature

idchecktrust

Prova de vida + Verificação de Identidade + Score de risco + Alerta de comportamento

idchecktrustdocs

Liveness + Identity Verification + Risk Score + Behavior Alert + Document Capture and Reuse

idchecktrustsign

Liveness + Identity Verification + Risk Score + Behavior Alert + Electronic Signature

idchecktrustdocssign

Liveness + Identity Verification + Risk Score + Behavior Alert + Document Capture and Reuse + Electronic Signature

idcheckserpro

Liveness + Identity Verification + Risk Score + Serpro Similarity Return

idcheckserprodocs

Liveness + Identity Verification + Risk Score + Serpro Similarity Return + Document Capture and Reuse

idcheckserprodocssign

Liveness + Identity Verification + Risk Score + Serpro Similarity Return + Document Capture and Reuse + Electronic Signature

creditoconsignado

Liveness + Identity Verification + Risk Score + Serpro Similarity Return + Electronic Signature

This flow works conditionally:

If the similarity result from Serpro is positive, we request the electronic signature;
If the similarity result from Serpro is negative, we ask for the user's documents to perform the facematch:
- If the facematch result is positive, we request the electronic signature;
- If the facematch result is negative, we end the journey without requesting the electronic signature.

The Risk Score capability is being discontinued and can only be used in special cases.

How to integrate

Authenticate

First, you must have a service account and perform OAuth2 authentication to obtain a valid access token.

Create a Process

With the access token obtained in the previous step, make a POST request to the endpoint client/v1/process (here you will specify the "flow" you wish to use).

Define Your User’s Journey

In this step, you will define where your user's journey will take place.

Check the Process Result

With the access token obtained in step 1, make a GET request to the endpoint client/v1/process/{id} (here you will provide the "id" of the process created in step 2), check the process result, and decide whether to approve or reject the user.

(1) Using Redirect:

It is recommended to follow these steps:

In your common flow (which includes the by Unico Registration), you will redirect the client to the link generated through the API;
After that, the client within the platform carries out the necessary procedures to continue the flow;
When completed, they are redirected to your page (using the redirectUrl provided during the process creation).

(2) Using `window.open()`:

The window.open() option consists of opening a new tab in the user's browser so that they can complete the process. At the end, this tab is closed and redirected to your application.

For this, it is recommended to:

Follow the public documentation on this, which can be found ;
Monitorar se houve alteração de URL (para a redirectUrl) e então fechar a aba utilizando window.close().

Step 1: Using CustomTabs for Integration

1 - Add the necessary dependency for using CustomTabs in your app/build.gradle:

implementation("androidx.browser:browser:1.5.0")

Step 2: Opening a CustomTab

import android.net.Uri
import androidx.activity.ComponentActivity
import androidx.browser.customtabs.CustomTabsClient
import androidx.browser.customtabs.CustomTabsIntent

class CustomTabActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)

       openCustomTab(<URL_CBU>)
    }

    fun openCustomTab(url: String) {
        val builder = CustomTabsIntent.Builder()
        val customTabsIntent = builder.build()
        customTabsIntent.launchUrl(this, Uri.parse(url))
    }
}

Step 3: Modifying AndroidManifest

Add the necessary permissions and intents in the AndroidManifest.xml for the Activity that you want to receive the callback_uri. It is necessary to include the attribute android:launchMode="singleTop" as well as the <data> tag providing the URI data.

xml

<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-permission android:name="android.permission.CAMERA"/> 
// ermissions for camera and geolocation are required

<activity
    android:name=".CustomTabActivity"
    android:exported="true"
    android:label="@string/app_name"
    android:theme="@style/Theme.Customtabs"
    android:launchMode="singleTop">

    <intent-filter android:label="Custom Tab">
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <!-- scheme e host são os dados fornecidos na criação de um processo no campo callback_uri
        callback_uri: "foobar://success?code=1234" -->
        <data android:scheme="foobar" android:host="success"/>
    </intent-filter>

</activity>

The following permissions are necessary for it to function correctly:

Camera
Geolocation

Step 4: Getting Return Information

o retrieve redirect information with the provided data, you can use the following code in the onNewIntent method of your Activity:

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    val url = intent.data
    val scheme = url.scheme // "foobar"
    val host = url.host // "success"
    val code = url.getQueryParameter("code") // "1234"
}

Passo 1: Criar o controlador de autenticação

1 - O primeiro passo é criar o controlador de autenticação, e, para isso crie uma classe chamada UnicoAuthenticationController (ou como preferir chamar).

2 - Na sequência, importe o framework AuthenticationServices no topo da classe.

3 - Declare a classe como NSObject e implemente o protocolo ASWebAuthenticationPresentationContextProviding.

O resultado deve ser:

import AuthenticationServices

class UnicoAuthenticationController: NSObject, ASWebAuthenticationPresentationContextProviding {
    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
           if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
               if let mainWindow = windowScene.windows.first {
                   return mainWindow
               }
           }
           return ASPresentationAnchor()
       }
}

Passo 2: Implementar a autenticação

1 - Abra o arquivo onde você executa a autenticação e adicione as importações necessárias (como exemplo, o ContentView.swift é usado).

import SwiftUI
import AuthenticationServices

2 - Para controlar o estado do fluxo é preciso criar a propriedade @State.

@State private var finished = false

3 - Crie uma instância da classe UnicoAuthenticationController fora do corpo da estrutura ContentView.

let unicoController = UnicoAuthenticationController()

4 - Para a validação do processo, crie uma função chamada redirectUser.

func redirectUser() {
        guard let url = URL(string: "URL_AUTHENTICATION") else { return }

        var session: ASWebAuthenticationSession?
        session = ASWebAuthenticationSession(url: url, callbackURLScheme: "BUNDLE") { callbackURL, error in
            guard callbackURL != nil else {
                if let error = error {
                    return print("Erro durante o processo: \(error.localizedDescription)")
                }
                return
            }

            // Processa o URL de callback para verificar se o processo foi finalizado
            session?.cancel()
            finished = true
        }

        session?.presentationContextProvider = unicoController
        session?.prefersEphemeralWebBrowserSession = true
        session?.start()
    }

Ambientes:

Lembre-se de alterar a url URL_AUTHENTICATION para a URL de autenticação recebida em seu processo e também o callbackURLScheme BUNDLE para o redirect informado na criação do processo (o uso do Bundle Identifier de seu aplicativo é recomendado).

Autenticação única:

É importante setar prefersEphemeralWebBrowserSession para true para garantir uma autenticação única por processo.

Document Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud SDK into your Android applications for document capture

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 correctly positioned, the user must click the button to capture the photo of the document.

The SDK does not perform any type of validation on what is being captured.

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

Create an instance of the builder (generated through the IAcessoBioBuilder interface), providing the relevant context and the implementation of the AcessoBioListener class as parameters.

The implementation of this class is quite simple and can be done with just a few lines of code. All you need to do is instantiate the builder by specifying the context and override the callback methods with the business logic of your application:

Implementing Callback Functions

Note that the work of implementing the AcessoBioListener class is largely about configuring the callback methods. Each method is called in a specific situation based on the SDK's return.

Simply override the methods shown in the previous step with your application's business logic:

onErrorAcessoBio(ErrorBio errorBio)

onUserClosedCameraManually()

This method is invoked whenever the user manually closes the camera, such as by clicking the "Back" button.

onSystemClosedCameraTimeoutSession()

This method is invoked as soon as the maximum session time is reached (without capturing any image).

It can be configured in the builder through the setTimeoutSession method. This method should receive the maximum session time in seconds. You can change the maximum session time for your user when using the face detection feature (Selfie camera with smart capture). If the user exceeds the time set in your process to capture the photo, you can display a customizable message or instruction to the user. The default value is 40 seconds, and the minimum value is also 40 seconds.

onSystemChangedTypeCameraTimeoutFaceInference()

This method is invoked as soon as the maximum time for detecting the user's face is reached (without detecting anything). In this case, the camera mode is automatically switched to manual capture mode (without the smart capture outline).

The maximum capture time when using face detection (Selfie camera with smart capture) is 13 seconds. If the user encounters difficulty capturing the photo through face detection and exceeds the time set in the process, the capture is automatically switched to manual mode, aiming to make the action easier for the user (TimeoutToFaceInference).

All the above methods must be created as indicated in your project (even without any logic). Otherwise, the project will not compile successfully.

Implementing Listeners for Camera Events

The implementation of these listener methods must be done through an instance of the iAcessoBioSelfie class.

The camera opening method, which is called in the next step, needs to know what to do when it successfully captures an image or when an error occurs in the process. It is necessary to inform "what to do" to the camera opening method by implementing listeners that are called in cases of success or error.

Through the configuration of the listeners, you can specify what happens in your app in error situations (onErrorDocument method) or success situations (onSuccessDocument method) during image capture.

The example below illustrates the configuration of the listeners, building, and opening of the camera:

Prepare and open the camera

It is necessary to create an instance of the builder using the build() method. This method is provided through the object generated with the IAcessoBioBuilder interface and the AcessoBio class:

The next step is to prepare the camera using the prepareDocumentCamera() method with the object returned by the builder (named UnicoCheckCamera in the example above).

The prepareDocumentCamera() method generates an object of type UnicoCheckCameraOpener.Document, which is used to open the camera with its open() method, receiving the parameters for the type of document to be captured, which are:

If you need to capture a document for which we don't have a specific frame (e.g., RNE, among others), use the DocumentCameraType.None frame, which will provide you with a generic, rectangular frame that can be used to guide any capture.

`onSucessDocument` Method

When an image capture is successful, this method is invoked and returns an object of type ResultCamera, which is later used in the REST API calls:

The ResultCamera object returns two attributes: base64 and encrypted:

The base64 attribute can be used if you want to display a preview of the image in your app.

`onErrorDocument` Method

When an error occurs during image capture, this method is invoked and returns an object of type ErrorBio:

Making a POST Request to the Client API

Error Handling Guide

In this section, you will find all the necessary information for handling errors from the Unico IDCloud SDK in your Android applications

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

Available Methods

Method Name

Description

getCode()

Method used to obtain the error code that occurred.

getDescription()

Method used to obtain the description of the error that occurred.

Below is the list of possible error codes for the Android SDK:

Code

Description

73001

Context invalid

73002

Did not grant permission to open camera

73003

The lest API is 21(LOLLIPOP)

73004

Could not find implementation interface callback iAcessoBioSelfie

73005

Could not find implementation interface callback iAcessoBioDocument

73006

Unable to open camera on emulators

73100

Unable to connect to internet

73200

Please inform the json file name

73202

Unable to parse json file

73300

Unable to get unico authentication object

73301

Unable to parse object

73302

Could not find the unico token

73303

Current host is not registered

73400

Could not initialize camera

73500

Unable to get session token, service response error

73501

Unable to parce object

73502

Could not get session token

73701

Could not find active liveness import

73702

Unable to initialize active liveness in production mode

73703

Unable to get active liveness session

73704

The user pressed the cancel button and did not complete the Session.

73705

The Session was not performed successfully and a FaceScan was not generated. In general, other statuses will be sent to the

73706

The camera access is prevented because either the user has explicitly denied permission or the user's device is configured to

73707

The Session was cancelled due to the app being terminated, put to sleep, an OS notification, or the app was placed in the

73708

The Session was cancelled because device is in landscape mode. The user experience of devices in these orientations is poor

73709

The Session was cancelled because device is in reverse portrait mode. The user experience of devices in these orientations is

73710

The Session was cancelled because the user was unable to complete a Session in the default allotted time or the timeout set

73712

The Session was cancelled due to memory pressure.

73712

The Session was cancelled because your App is not in production and requires a network connection.

73713

The Session was cancelled because your key needs to be validated again.

73714

The Session was cancelled because the developer-configured encryption key was not valid.

73715

The Session was cancelled because not all guidance images were configured.

73716

The Session was cancelled because SDK was unable to start the camera on this device.

73717

The Session was cancelled because the user was in a locked out state.

73718

The Session was cancelled because of an unknown and unexpected error. SDK leverages a variety of iOS APIs including camera,

73719

The Session cancelled because user pressed the Get Ready screen subtext message. Note: This functionality is not available by

73800

Could not build encrypted key

Android Customization

In this section, you will find all the information necessary for customizing the SDK of the Unico IDCloud platform in your Android applications

The Android SDK allows for some customizations. Below, you can see 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:

unicoCheck.setLocale(LocaleTypes.EN_US);

unicoCheck.setLocale(LocaleTypes.EN_US);

A remote activation may be required to use it. If you wish to use it, please inform your project manager or Unico support.
If not configured, the SDK will use Portuguese as the default language.

Customize Capture Process Experience

Customize Selfie Capture Experience

This is an optional step, but highly recommended so that the capture process reflects your company's visual identity.

It is possible to customize some objects of the frame according to the camera mode used, through the setTheme() method.

The supported types for color representation are Color Resource or String containing the hexadecimal color code. Example: R.color.red or #FF0000.

All methods are available below:

IAcessoBioTheme unicoTheme = new IAcessoBioTheme() {
    @Override
    public Object getColorBackground() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorBoxMessage() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorTextMessage() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorBackgroundPopupError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorTextPopupError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorBackgroundButtonPopupError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorTextButtonPopupError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorBackgroundTakePictureButton() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorIconTakePictureButton() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorBackgroundBottomDocument() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorTextBottomDocument() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorSilhouetteSuccess() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorSilhouetteError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorProgressBar() { 
        return R.color.your_color;
    }
};
    
acessoBioBuilder.setTheme(unicoTheme);

val unicoTheme = object: IAcessoBioTheme {

    override fun getColorBackground() = R.color.your_color
    override fun getColorBoxMessage() = R.color.your_color
    override fun getColorTextMessage() = R.color.your_color
    override fun getColorBackgroundPopupError() = R.color.your_color
    override fun getColorTextPopupError() = R.color.your_color
    override fun getColorBackgroundButtonPopupError() = R.color.your_color
    override fun getColorTextButtonPopupError() = R.color.your_color
    override fun getColorBackgroundTakePictureButton() = R.color.your_color
    override fun getColorIconTakePictureButton() = R.color.your_color
    override fun getColorBackgroundBottomDocument() = R.color.your_color
    override fun getColorTextBottomDocument() = R.color.your_color
    override fun getColorSilhouetteSuccess() = R.color.your_color
    override fun getColorSilhouetteError() = R.color.your_color 
    override fun getColorSilhouetteNeutral() = R.color.your_color
    override fun getColorProgressBar() = R.color.your_color
}

acessoBioBuilder.setTheme(unicoTheme)

It is also possible to make static customizations. In your colors.xml file, add the following code:

<color name="unico_color_background"> #YourColor </color> 
<color name="unico_color_silhouette_success"> #YourColor </color> 
<color name="unico_color_silhouette_error"> #YourColor </color> 
<color name="unico_color_silhouette_neutral"> #YourColor </color> 
<color name="unico_color_box_message"> #YourColor </color> 
<color name="unico_color_text_message"> #YourColor </color> 
<color name="unico_color_background_popup_error"> #YourColor </color> 
<color name="unico_color_text_popup_error"> #YourColor </color> 
<color name="unico_color_background_button_popup_error"> #YourColor </color> 
<color name="unico_color_text_button_popup_error"> #YourColor </color> 
<color name="unico_color_background_take_picture_button"> #YourColor </color> 
<color name="unico_color_icon_take_picture_button"> #YourColor </color> 
<color name="unico_color_background_bottom_document"> #YourColor </color> 
<color name="unico_color_text_bottom_document"> #YourColor </color> 
<color name="unico_color_button_cancel"> #YourColor </color> 
<color name="unico_color_progress_bar_capture"> #YourColor </color>

Below, check the field specification for the customization:

Customize Document Capture Experience

This is an optional step, but highly recommended so that the capture process reflects your company's visual identity.

It is possible to customize some objects of the frame according to the camera mode used, through the setTheme() method.

The supported types for color representation are Color Resource or String containing the hexadecimal color code. For example: R.color.red or #FF0000.

All methods are available below:

IAcessoBioTheme unicoTheme = new IAcessoBioTheme() {
    @Override
    public Object getColorBackground() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBoxMessage() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextMessage() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundButtonPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextButtonPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundTakePictureButton() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorIconTakePictureButton() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundBottomDocument() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextBottomDocument() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorSilhouetteSuccess() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorSilhouetteError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorProgressBar() { 
        return R.color.your_color;
    }
};
    
acessoBioBuilder.setTheme(unicoTheme);

val unicoTheme = object: IAcessoBioTheme {
    override fun getColorBackground() = R.color.your_color
    override fun getColorBoxMessage() = R.color.your_color
    override fun getColorTextMessage() = R.color.your_color
    override fun getColorBackgroundPopupError() = R.color.your_color
    override fun getColorTextPopupError() = R.color.your_color
    override fun getColorBackgroundButtonPopupError() = R.color.your_color
    override fun getColorTextButtonPopupError() = R.color.your_color
    override fun getColorBackgroundTakePictureButton() = R.color.your_color
    override fun getColorIconTakePictureButton() = R.color.your_color
    override fun getColorBackgroundBottomDocument() = R.color.your_color
    override fun getColorTextBottomDocument() = R.color.your_color
    override fun getColorSilhouetteSuccess() = R.color.your_color
    override fun getColorSilhouetteError() = R.color.your_color
    override fun getColorSilhouetteNeutral() = R.color.your_color
    override fun getColorProgressBar() = R.color.your_color
}
acessoBioBuilder.setTheme(unicoTheme)

It is also possible to make static customizations. In your colors.xml file, add the following code:

<color name="unico_color_background"> #YourColor </color> 
<color name="unico_color_silhouette_success"> #YourColor </color> 
<color name="unico_color_silhouette_error"> #YourColor </color> 
<color name="unico_color_silhouette_neutral"> #YourColor </color> 
<color name="unico_color_box_message"> #YourColor </color> 
<color name="unico_color_text_message"> #YourColor </color> 
<color name="unico_color_background_popup_error"> #YourColor 
<color name="unico_color_text_popup_error"> #YourColor </color> 
<color name="unico_color_background_button_popup_error"> #YourColor 
<color name="unico_color_text_button_popup_error"> #YourColor </color> 
<color name="unico_color_background_take_picture_button"> #YourColor </color> 
<color name="unico_color_icon_take_picture_button"> #YourColor </color> 
<color name="unico_color_background_bottom_document"> #YourColor </color> 
<color name="unico_color_text_bottom_document"> #YourColor </color> 
<color name="unico_color_button_cancel"> #YourColor </color> 
<color name="unico_color_progress_bar_capture"> #YourColor </color>

Below, check the specification of the customization fields:

Selfie Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud platform SDK into your Android applications for selfie capture

Initializing the SDK

Create an instance of the builder (generated through the IAcessoBioBuilder interface), providing the context and environment as parameters, along with the implementation of the AcessoBioListener class.

The implementation of this class is quite simple and can be done in just a few lines of code. All you need to do is instantiate the builder by providing the relevant context and override the callback methods with the business logic of your application:

Environment configuration

Configure the environment that will be used during the SDK execution. Use the Environment enum, which contains the following options:

Environment.PROD: for production environment;
Environment.UAT: for approval environment.

See how to implement it in the example below:

Implementing Callback Functions

Note that the work of implementing the AcessoBioListener class is, for the most part, configuring the callback methods. Each method is called in a specific situation based on the SDK's return.

Simply override the methods shown in the previous step with your application's business logic.

This method is invoked whenever any implementation error occurs while using one of our methods:

onErrorAcessoBio(ErrorBio errorBio)

onUserClosedCameraManually()

This method is invoked whenever the user manually closes the camera, such as when clicking the "Back" button.

onSystemClosedCameraTimeoutSession()

This method is invoked as soon as the maximum session time is reached (without capturing any image).

It can be configured in the builder through the setTimeoutSession method. This method should receive the maximum session time in seconds. You can change the maximum session time for your user when using the face detection feature (Selfie camera with smart capture). If the user exceeds the time set for capturing the photo, you can display a customizable message or instruction to the user. The default value is 40 seconds, and the minimum value is also 40 seconds.

onSystemChangedTypeCameraTimeoutFaceInference()

This method is invoked as soon as the maximum time for face detection is reached (without detecting anything). In this case, the camera mode is automatically switched to manual capture mode (without the smart capture outline).

All of the above methods must be created as indicated in your project (even if without any logic). Otherwise, the project will not compile successfully.

Configuring Camera Mode

The SDK has smart framing and automatic capture configured and enabled by default. As a result, you must configure the camera mode in your builder as follows:

The false/true values of the methods above do not alter the capture experience; they are only used for the internal logic of the SDK's operation.

Implementing Listeners for Camera Events

The implementation of these listener methods must be done through an instance of the iAcessoBioSelfie class.

The camera opening method, which is called in the next step, needs to know what to do when it successfully captures an image or when an error occurs in the process. It is necessary to inform "what to do" to the camera opening method by implementing listeners that are called in cases of success or error.

Through the configuration of the listeners, you can specify what happens in your app in error situations (onErrorSelfie method) or success situations (onSuccessSelfie method) during image capture.

Changes in naming conventions for versions lower than 4.2.1:

The method prepareCamera, which was previously prepareSelfieCamera.
The class CameraListener, which was previously SelfieCameraListener.
The object UnicoCheckCameraOpener.Camera, which was previously UnicoCheckCameraOpener.Selfie.

To configure the listeners, it is necessary to implement:

Prepare and open the camera

When the camera is prepared, the onCameraReady event is triggered, which receives an object of type UnicoCheckCameraOpener.Camera as a parameter.

It is necessary to override this method, opening the camera with the object received through the open() method. The open() method should receive as parameters the listeners configured in the previous steps.

`onSucessSelfie` Method

When an image capture is successful, this method is invoked and returns an object of type ResultCamera, which is used later in the REST API calls:

The ResultCamera object returns two attributes: base64 and encrypted:

The base64 attribute can be used if you want to display a preview of the image in your app.

The encrypted attribute is strictly intended for sending the image through the by Client APIs. It should not be opened or serialized, as its characteristics may change without notice. Its use must be exclusive to interactions with the APIs to ensure data integrity and security. Unico is not responsible for any damages resulting from this practice, as modifications can occur unexpectedly.
The base64/encrypted files may vary in size due to several factors, including the quality of the devices and the photos generated by them, as well as Unico's business rules. To avoid issues in your application, do not limit the size of the string generated by the SDK for the files in your programming logic or infrastructure.

`onErrorSelfie` Method

When an error occurs during image capture, this method is invoked and returns an object of type ErrorBio:

Making a POST Request to the Client API

For security reasons, the interval between the generation of the encrypted and its submission via one of the available flows must be a maximum of 10 minutes. Submissions made beyond this period will be automatically rejected by the API.

Selfie Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud platform SDK into your iOS applications for selfie capture

Initializing the SDK

To get started with the Unico Check iOS SDK, import the SDK and implement the AcessoBioManagerDelegate interface within the ViewController you want to use.

The implementation of this class is straightforward and can be done with just a few lines of code. All you need to do is instantiate the builder, providing the context and environment in question, and override the callback methods with the business logic of your application:

Environment configuration

Configure the environment that will be used to run the SDK. Use the enumerated environment that contains the following enumerates:

PROD: for production environment;
UAT: for approval environment.

See how to implement it in the example below:

Implementing the Callback Functions

Note that, as shown in the previous example, the implementation of the AcessoBioManagerDelegate interface mainly involves configuring the callback methods. Each method is called in a specific situation in the SDK's return process.

You simply need to override the methods demonstrated in the previous step with the business logic of your application:

onErrorAcessoBioManager(_ error: ErrorBio!)

This method is invoked when any implementation error occurs while using one of the methods, such as providing an incorrect document type for the document capture functionality.

onUserClosedCameraManually()

This method is invoked whenever the user manually closes the camera, such as by clicking the "Back" button.

onSystemClosedCameraTimeoutSession()

This method is invoked as soon as the maximum session time is reached (without capturing any image).

It can be configured in the builder through the setTimeoutSession method. This method should receive the maximum session time in seconds. You can change the maximum session time for your user by using the face detection feature (Selfie camera with smart capture). If the time exceeds the duration specified for the process to capture the photo, you can display a customizable message or instruction to the user. The default value is 40 seconds, and the minimum value is also 40 seconds.

onSystemChangedTypeCameraTimeoutFaceInference()

This method is invoked as soon as the maximum time for detecting a user's face is reached (without detecting anything). In this case, the camera mode is automatically switched to manual capture mode (without the intelligent capture silhouette).

The maximum capture time when using face detection (Selfie camera with smart capture) is 13 seconds. If the user encounters any difficulty capturing the photo through face detection and exceeds the time specified in the process, the capture automatically switches to manual mode to facilitate the user's action (TimeoutToFaceInference).

All the methods above must be created as indicated in your project (even without any logic). Otherwise, the project will not compile successfully.

Configuring Camera Mode

The SDK has intelligent framing and automatic capture configured and enabled by default. As a result, you should configure the camera mode in your builder as follows:

The false/true values for the methods above do not change the capture experience; they are only used for the internal logic of the SDK's functionality.

Implementing Delegates for Camera Events

The camera opening method needs to know what to do when it successfully captures an image or encounters an error during the process. "What to do" is informed to the camera opening method through the configuration of delegates that are called in success or error situations.

By configuring the delegates, you can specify what happens in your app in error situations (method onErrorSelfie) or success (method onSuccessSelfie) when capturing images.

To configure the delegates, you need to implement the SelfieCameraDelegate and AcessoBioSelfieDelegate interfaces:

`onSuccessSelfie` Method

When successfully capturing an image, this method is invoked and returns an object of type SelfieResult, which is later used in the REST API calls.

The ResultCamera object returns 2 attributes: base64 and encrypted:

The base64 attribute can be used if you want to display a preview of the image in your app.

The encrypted attribute is strictly intended for sending the image through the by Client APIs. It should not be opened or serialized, as its characteristics may change without prior notice. Its use should be exclusive in interactions with the APIs to ensure data integrity and security. Unico is not responsible for any damages resulting from this practice, as modifications can occur unexpectedly.
The base64/encrypted files may vary in size depending on various factors, including the quality of the devices and photos generated by them, as well as Unico’s business rules. To avoid issues in your application, do not limit the size of the string generated by the SDK for the files within your programming logic or infrastructure.

`onErrorSelfie` Method

When an error occurs during the image capture, this method is invoked and returns an object of type ErrorBio:

Environment Configuration

If not configured, the SDK uses the environment set through the configuration file (getHostKey). If getHostKey is not being used, an error will be returned.

It is possible to configure the environment to be used during the execution of the SDK. Use the EnvironmentEnum enumerated type, which contains the following values:

EnvironmentEnum.PROD: for the Production environment
EnvironmentEnum.UAT: for the Staging environment

See how to implement it in the example below:

Prepare and Open Camera

To proceed with opening the camera, you must first prepare it using the prepareSelfieCamera method. This method takes as parameters the implementation of the SelfieCameraDelegate class and the JSON containing the credentials generated in the previous step.

Once the camera is prepared, the onCameraReady event is triggered and receives an object of type AcessoBioCameraOpenerDelegate as a parameter.

You should override this method and open the camera using the object received through the open() method:

If any error occurs while preparing the camera, the onCameraFailed event is triggered. You should implement this method applying your app's business rules.

Making a POST Request to the Client API

For security reasons, the time interval between the generation of the encrypted and its submission via one of the available flows must be no more than 10 minutes. Submissions made beyond this period will be automatically rejected by the API.

Document Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud SDK into your iOS applications for document capture

This guide has been designed to help you quickly and easily implement the Android 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 iOS Customization section.

Available Document Frames

In this camera mode, there is a capture frame to assist the user in positioning the document correctly. After positioning the document correctly, the user should click the button to capture the photo of the document.

The SDK does not perform any type of validation on what is being captured.

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

RG: Capture of the RG (separate front and back).
CNH: Capture of the CNH opened.
CNH Front: Capture of the front of the CNH.
CNH Back: Capture of the back of the CNH.
CPF: Capture of the CPF document.
Without Silhouette: Capture of a generic document.

Initializing the SDK

To get started with the Unico IDCloud iOS SDK, import the SDK and implement the AcessoBioManagerDelegate interface within the ViewController you wish to use.

The implementation of this class is straightforward and can be done with just a few lines of code. All you need to do is instantiate the builder by providing the relevant context and override the callback methods with the business logic of your application:

Implementing Callback Functions

Note that, as shown in the previous example, the implementation work of the AcessoBioManagerDelegate interface is largely about configuring the callback methods. Each method is called in a specific situation based on the SDK's response.

Simply override the methods illustrated in the previous step with your application's business logic:

onErrorAcessoBioManager(_ error: ErrorBio!)

This method is invoked whenever an implementation error occurs while using any of the methods, such as providing an incorrect document type for the document capture functionality.

onUserClosedCameraManually()

This method is invoked whenever the user manually closes the camera, such as by clicking the "Back" button.

onSystemClosedCameraTimeoutSession()

This method is also invoked once the maximum session time is reached (without capturing any image).

It can be configured in the builder through the setTimeoutSession method. This method should receive the maximum session time in seconds. You can modify the maximum session time for your user when using the face detection feature (Selfie camera with intelligent capture). If the time limit for capturing the photo is exceeded, you can present a customizable message or instruction to the user. The default value is 40 seconds, and the minimum value is also 40 seconds.

onSystemChangedTypeCameraTimeoutFaceInference()

This method is invoked once the maximum time for detecting the user's face is reached (without detecting anything). In this case, the camera mode is automatically switched to manual capture mode (without the intelligent capture silhouette).

The maximum capture time when using face detection (Selfie camera with intelligent capture) is 13 seconds. If the user faces difficulties capturing the photo using face detection and exceeds the time limit set in the process, the capture automatically switches to manual mode, aiming to facilitate the process for the user (TimeoutToFaceInference).

All of the above methods must be implemented as indicated in your project (even if with no logic). Otherwise, the project will not compile successfully.

Implementing Delegates for Camera Events

The camera opening method (which is called in the next step) needs to know what to do when it successfully captures an image or encounters an error during the process. The "actions" to be taken are specified to the camera opening method through the configuration of delegates, which are called in success or error situations.

By configuring the delegates, you can define what happens in your app during error situations (onErrorDocument method) or success situations (onSuccessDocument method) when capturing images.

To configure the delegates, you need to implement the DocumentCameraDelegate and AcessoBioDocumentDelegate interfaces:

`onSucessDocument` Method

When an image is successfully captured, this method is invoked and returns an object of type ResultCamera, which is used later in the REST API request.

The ResultCamera object returns two attributes: base64 and encrypted.

The base64 attribute can be used if you want to display a preview of the image in your app.
Both the encrypted and base64 attributes can be sent in the REST API calls of the by Client.

Método `onErrorDocument`

When an error occurs during image capture, this method is invoked and returns an object of type ErrorBio.

Learn more about the ErrorBio types in the error handling section of the SDK.

Preparing and Opening the Camera

To open the camera, it is necessary to prepare it using the method prepareDocumentCamera. This method takes as a parameter the implementation of the DocumentCameraDelegate class and the JSON with the credentials generated in the previous step.

When the camera is ready, the event onCameraReadyDocument is triggered, which receives as a parameter an object of type AcessoBioCameraOpenerDelegate.

You should override this method, opening the camera with the object received through the openDocument() method, receiving the document type parameters to be captured, which are:

If you need to capture a document for which we don't have a specific frame (e.g., RNE, among others), use the DocumentEnums.none frame, which will provide a generic, rectangular frame that can be used to guide any capture.

The delegates implemented above (referred to here as Self):

The ErrorPrepare type is an extension of ErrorBio, thus containing all its properties. Learn more about the ErrorBio type in the SDK error handling section.

If an error occurs while preparing the camera, the onCameraFailedDocument event is triggered. You should implement this method according to the business logic of your app.

In case of success, the onSuccessDocument event is triggered, as explained in the section above.

Making a POST Request to the Client API

Selfie Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud platform SDK into your Flutter applications for selfie capture

Initializing the SDK

To get started, create an instance of the builder (generated through the UnicoCheckBuilder interface), providing the context and environment as parameters, along with the implementation of the UnicoListener class.

The implementation of this class is quite simple and can be done with just a few lines of code. All you need to do is override the callback methods with your application's business logic.

class _MyHomePageState extends State<MyHomePage> implements UnicoListener {

    late UnicoCheckBuilder _unicoCheck;

    
      @override
      void onErrorUnico(UnicoError error) {}

      @override
      void onUserClosedCameraManually() {}

      @override
      void onSystemChangedTypeCameraTimeoutFaceInference() {}

      @override
      void onSystemClosedCameraTimeoutSession() {}
}

Environment configuration

Configure the environment that will be used to run the SDK. Use the enumerated environment that contains the following enumerates:

UnicoEnvironment.PROD: for production environment;
UnicoEnvironment.UAT: for approval environment.

See how to implement it in the example below:

 _unicoCheck.setEnvironment(unicoEnvironment: UnicoEnvironment.UAT);

Implementing the Callback functions

Note that, as shown in the previous example, the implementation of the UnicoListener class mostly involves configuring the callback methods. Each method will be called in a specific situation based on the SDK's return.

Simply override the methods demonstrated in the previous step with your application's business logic:

onErrorUnico(UnicoError error)

onUserClosedCameraManually()

This method is invoked whenever the user manually closes the camera, such as by clicking the "Back" button.

onSystemClosedCameraTimeoutSession()

This method is invoked as soon as the maximum session time is reached (without capturing any image).

It can be configured in the builder through the setTimeoutSession method. This method should receive the maximum session time in seconds. You can change the maximum session time for your user by using the face detection feature (Selfie camera with smart capture). If the user exceeds the time defined in your process to capture the photo, you can display a customizable message or instruction to the user. The default value is 40 seconds, and the minimum value is also 40 seconds.

onSystemChangedTypeCameraTimeoutFaceInference()

This method is invoked as soon as the maximum time for detecting a user's face is reached (without detecting anything). In this case, the camera mode is automatically changed to manual capture mode (without the smart capture silhouette).

The maximum capture time when using face detection (Selfie camera with smart capture) is 13 seconds. If the user has difficulty capturing the photo via face detection and exceeds the time set in your process, the capture mode automatically switches to manual to make the process easier for the user (TimeoutToFaceInference).

All of the above methods must be created as indicated in your project (even if with no logic). Otherwise, the project will not compile successfully.

Configuring Camera Mode

The SDK has intelligent framing and automatic capture configured and enabled by default. As a result, you should configure the camera mode in your builder as follows:

UnicoCheckCameraOpener _opener = new UnicoCheck (this)
    .setAutoCapture(autoCapture: true)
    .setSmartFrame(smartFrame: true)
    .build();

The false/true values for the methods above do not alter the capture experience; they are only used for the internal logic of the SDK's functionality.

Implementing Listeners for Camera Events

The implementation of these listener methods must be done through an instance of the UnicoSelfie class.

The camera opening method needs to know what to do when it successfully captures an image or encounters an error during the process. "What to do" is informed to the camera opening method by implementing listeners, which are called in cases of success or error.

Through the implementation of these listeners, you can specify what happens in your app in case of error (onErrorSelfie method) or success (onSuccessSelfie method) when capturing images.

`onSucessSelfie` Method

When successfully capturing an image, this method is invoked and returns an object of type ResultCamera, which is later used in the REST API requests:

@override
void onSuccessSelfie(ResultCamera result) { }

The ResultCamera object returns 2 attributes: base64 and encrypted:

The base64 attribute can be used if you want to display a preview of the image in your app.
The encrypted attribute must be sent in the REST API calls by Client.

The encrypted attribute is strictly intended for sending the image through the by Client APIs. It should not be opened or serialized, as its characteristics can be altered without prior notice. Its use should be exclusive for interactions with the APIs to ensure data integrity and security. Unico is not responsible for any damages resulting from this practice, as modifications can occur unexpectedly.
The base64/encrypted files may vary in size depending on several factors, including the quality of the devices and the photos generated by them, as well as Unico's business rules. To avoid issues in your application, do not limit the size of the string generated by the SDK for these files in your programming logic or infrastructure.

`onErrorSelfie` Method

If an error occurs during the image capture, this method is invoked and returns an object of type UnicoError:

@override
void onErrorSelfie(UnicoError error) { }

Learn more about the ErrorBio types in the SDK's error handling section.

Preparing and Opening the Camera

The openCameraSelfie method is used to open the camera. This method takes as parameters the implementation of the UnicoSelfie class and the JSON with the credentials, generated in the previous step.

The following example illustrates the steps for configuring the listeners and opening the camera:

_opener.openCameraSelfie(jsonFileName: androidJsonFileName, listener: this)

Making a POST Request to the Client API

For security reasons, the interval between the generation of the encrypted and its sending via one of the available flows must be a maximum of 10 minutes. Submissions made beyond this period will be automatically rejected by the API.

Error Handling Guide

In this section, you will find all the necessary information for handling errors from the Unico IDCloud SDK in your Android applications

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

Available Methods

Method Name

Description

getCode()

Method used to obtain the error code that occurred.

getDescription()

Method used to obtain the description of the error that occurred.

Below is a list of possible error codes from the Flutter SDK:

Code

Description

73001

Context invalid

73002

Did not grant permission to open camera

73003

The lest API is 21(LOLLIPOP)

73004

Could not find implementation interface callback iAcessoBioSelfie

73005

Could not find implementation interface callback iAcessoBioDocument

73006

Unable to open camera on emulators

73100

Unable to connect to internet

73200

Please inform the json file name

73202

Unable to parse json file

73300

Unable to get unico authentication object

73301

Unable to parse object

73302

Could not find the unico token

73303

Current host is not registered

73400

Could not initialize camera

73500

Unable to get session token, service response error

73501

Unable to parce object

73502

Could not get session token

73701

Could not find active liveness import

73702

Unable to initialize active liveness in production mode

73703

Unable to get active liveness session

73704

The user pressed the cancel button and did not complete the Session.

73705

The Session was not performed successfully and a FaceScan was not generated. In general, other statuses will be sent to the

73706

The camera access is prevented because either the user has explicitly denied permission or the user's device is configured to

73707

The Session was cancelled due to the app being terminated, put to sleep, an OS notification, or the app was placed in the

73708

The Session was cancelled because device is in landscape mode. The user experience of devices in these orientations is poor

73709

The Session was cancelled because device is in reverse portrait mode. The user experience of devices in these orientations is

73710

The Session was cancelled because the user was unable to complete a Session in the default allotted time or the timeout set

73712

The Session was cancelled due to memory pressure.

73712

The Session was cancelled because your App is not in production and requires a network connection.

73713

The Session was cancelled because your key needs to be validated again.

73714

The Session was cancelled because the developer-configured encryption key was not valid.

73715

The Session was cancelled because not all guidance images were configured.

73716

The Session was cancelled because SDK was unable to start the camera on this device.

73717

The Session was cancelled because the user was in a locked out state.

73718

The Session was cancelled because of an unknown and unexpected error. SDK leverages a variety of iOS APIs including camera,

73719

The Session cancelled because user pressed the Get Ready screen subtext message. Note: This functionality is not available by

73800

Could not build encrypted key

Document Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud SDK into your Flutter applications for document capture

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 properly positioned, the user must click the button to take a photo of the document.

The SDK does not perform any validation of what is being captured.

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, create an instance of the builder (generated through the UnicoCheckBuilder interface), providing the context and the implementation of the UnicoListener class as parameters.

The implementation of this class is quite simple and can be done with just a few lines of code. All you need to do is override the callback methods with your application's business logic.

class _MyHomePageState extends State<MyHomePage> implements UnicoListener {

    late UnicoCheckBuilder _unicoCheck;

    /// Unico callbacks
      @override
      void onErrorUnico(UnicoError error) {}

      @override
      void onUserClosedCameraManually() {}

      @override
      void onSystemChangedTypeCameraTimeoutFaceInference() {}

      @override
      void onSystemClosedCameraTimeoutSession() {}

      /// Document callbacks
      @override
      void onSuccessDocument(ResultCamera resultCamera) { }

      @override
      void onErrorDocument(UnicoError error) { }

}

Implementing the callback functions

Note that, as in the previous example, the implementation work of the UnicoListener class is largely about configuring the callback methods. Each method is called in a specific situation based on the SDK's response.

Override the methods exemplified above with your application’s business logic:

onErrorUnico(UnicoError error)

When invoked, the method receives a parameter of type UnicoError, which contains details about the error. Learn more about the UnicoError type in the SDK's error handling section.

onUserClosedCameraManually()

This method is invoked whenever the user manually closes the camera, such as by clicking the "Back" button.

onSystemClosedCameraTimeoutSession()

This method is invoked as soon as the maximum session time is reached (without capturing any image).

It can be configured in the builder through the setTimeoutSession method. This method should receive the maximum session time in seconds. You can change the maximum session time for your user by using the face detection feature (Selfie camera with smart capture). If the user exceeds the time set in your process to capture the photo, you can display a customizable message or instruction to the user. The default value is 40 seconds, and the minimum value is also 40 seconds.

onSystemChangedTypeCameraTimeoutFaceInference()

The maximum capture time when using face detection (Selfie camera with smart capture) is 13 seconds. If the user encounters difficulty capturing the photo via face detection and exceeds the time set in your process, the capture mode is automatically switched to manual, aiming to make the action easier for the user (TimeoutToFaceInference)..

All the methods above must be created as indicated in your project (even if without any logic). Otherwise, the project will not compile successfully.

Implementing Listeners for Camera Events

The implementation of these listener methods must be done through an instance of the iAcessoBioSelfie class.

The camera opening method needs to know what to do when it successfully captures an image or encounters an error during the process. "What to do" is communicated to the camera opening method by implementing listeners that are called in cases of success or error.

Through the implementation of the listeners, you can specify what happens in your app in case of error (onErrorDocument method) or success (onSuccessDocument method) when capturing images.

`onSucessDocument` Method

When successfully capturing an image, this method is invoked and returns an object of type ResultCamera, which is later used in the REST API requests:

public void onSuccessDocument(ResultCamera resultCamera) { }

The ResultCamera object returns 2 attributes: base64 and encrypted:

The base64 attribute can be used if you want to display a preview of the image in your app;
Both the encrypted and base64 attributes can be sent in the REST API calls to by Client.

`onErrorDocument` Method

If an error occurs during the image capture, this method is invoked and returns an object of type UnicoError:

public void onErrorDocument(UnicoError error) { }

Learn more about the types of ErrorBio in the SDK's error handling section.

Preparing and Opening the Camera

To open the camera, the openCameraDocument() method is used. This method is provided through the object generated with an instance of the UnicoCheck class.

This method takes the following parameters:

A JSON file with the credentials, generated in the credential setup step;
The listeners configured above;
The type of document to be captured, which can be:

Parameter

Description

DocumentCameraTypes.CPF

Capture the front of the CPF

DocumentCameraTypes.CNH

Capture the open CNH

DocumentCameraTypes.CNH_FRENTE

Capture the front of the CNH

DocumentCameraTypes.CNH_VERSO

Capture the back of the CNH

DocumentCameraTypes.RG_FRENTE

Capture the front of the RG

DocumentCameraTypes.RG_VERSO

Capture the back of the RG RG

DocumentCameraTypes.OUTROS("descrição")

Capture any other document

If you need to capture a document that doesn't have a specific frame (e.g., RNE, among others), use the frame DocumentCameraTypes.OUTROS("description"), which will provide a generic, rectangular frame that can be used to guide any capture.

Example using the open CNH:

 _unicoCheck.build().openCameraDocument(
        jsonFileName: androidJsonFileName,
        documentType: DocumentType.CNH,
        listener: this);

Making a POST Request to the Client API

Installation Guide

In this section, you will find all the information needed to install the Unico IDCloud platform SDK in your Flutter applications

Development Environment Prerequisites

Your development environment must meet the following prerequisites:

Have the Flutter Developer SDK installed.

The capture component provided through the Flutter SDK supports the following versions or higher for the technologies:

Android: 5.0 (API 21);
iOS: 11.

Compatible Devices

This SDK does not work on emulators, only on physical devices.

iOS Devices::

iOS: It is compatible with almost all devices running iOS 11.

Android Devices:

It is compatible with the vast majority of devices running Android 5.0 (API level 21) or higher.

The following table lists the devices tested in the lab, along with the availability of vendor/manufacturer extensions. Some extensions listed may be subject to specific manufacturer APIs or SKUs. Click below to see the tested devices:

ASUS - X01BDA

10.0.0

Físico

ASUS - Z01KD

8.0.1

Físico

HUAWEY - P30 Lite

9.0.0

Físico

LG - K22

10.0.0

Físico

LG - Q6

7.0.0

Físico

MOTOROLA - Moto one macro

10.0.0

Físico

MOTOROLA - Moto G4

6.0.1

Físico

MOTOROLA - Moto G5s Plus

8.1.0

Físico

MOTOROLA - Moto G6 Play

9.0.0

Físico

MOTOROLA - Moto G7 Play

10.0.0

Físico

MOTOROLA - Moto G7 Power

10.0.0

Físico

MOTOROLA - Moto G8 Power Lite

10.0.0

Físico

SAMSUNG - A01

10.0.0

Físico

SAMSUNG - J8 SM J810M

8.1.0

Físico

SAMSUNG - Galaxy A30s SM-A307GT

10.0.0

Físico

SAMSUNG - Galaxy A51

10.0.0

Físico

SAMSUNG - Galaxy A71

11.0.0

Físico

SAMSUNG - Galaxy S20+

11.0.0

Físico

SAMSUNG - s10e

11.0.0

Físico

XIAOMI - Mi 8 Lite

9.0.0

Físico

XIAOMI - Mi 8 Lite

10.0.0

Físico

XIAOMI - Poco X3

10.0.0

Físico

XIAOMI - Redmi Note 8

10.0.0

Físico

XIAOMI - Redmi Note 8 Pro

10.0.0

Físico

XIAOMI - Redmi Note 9

10.0.0

Físico

XIAOMI - Redmi Note 9 Pro

10.0.0

Físico

GOOGLE - Pixel sailfish

8.0.0

Virtual (TestLab)

HUAWEY - ALE L23

5.0.0

Virtual (TestLab)

HUAWEY - ANE LX1

9.0.0

Virtual (TestLab)

HUAWEY - ANE LX2

9.0.0

Virtual (TestLab)

HUAWEY - COR L29

8.1.0

Virtual (TestLab)

HUAWEY - MHA L29

7.0.0

Virtual (TestLab)

HUAWEY - NEO L29

9.0.0

Virtual (TestLab)

SAMSUNG - SC 02J

8.0.0

Virtual (TestLab)

SAMSUNG - SM G891A

9.0.0

Virtual (TestLab)

SAMSUNG - SM G930AZ

8.0.0

Virtual (TestLab)

SAMSUNG - SM G935A

8.0.0

Virtual (TestLab)

SAMSUNG - SM G965N

9.0.0

Virtual (TestLab)

SAMSUNG - SM G965U1

8.0.0

Virtual (TestLab)

SAMSUNG - SM G981U1

10.0.0

Virtual (TestLab)

SAMSUNG - SM J727V

8.1.0

Virtual (TestLab)

SAMSUNG - SM N950F

9.0.0

Virtual (TestLab)

SAMSUNG - SM N950N

9.0.0

Virtual (TestLab)

SAMSUNG - SM N950U

8.0.0

Virtual (TestLab)

SAMSUNG - SM N960F

9.0.0

Virtual (TestLab)

SAMSUNG - SM N960N

9.0.0

Virtual (TestLab)

SAMSUNG - SM N960U1

8.1.0

stLab)

Installing the Flutter SDK

To implement the Flutter SDK from the Unico IDCloud platform into your Flutter app, follow the step-by-step guide listed below:

Using the Flutter CLI

To add the Unico Check Flutter SDK to your project, run the following command using the Flutter CLI:

$ flutter pub add unico_check

This command adds the following line to the pubspec.yaml file of your package:

dependencies:
  unico_check: ^2.0.2

Manually fetching packages: The flutter pub add unico_check command implicitly runs flutter pub get. If the package is not installed correctly, make sure that unico_check is listed in your pubspec.yaml file and run flutter pub get manually.

Permissions for Camera and Internet Usage

To use the camera opening method in your project, you need to add the permissions before compiling your application. Here’s an example:

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

Including the Dependency

After configuring the Android SDK, simply import it into your project. To do this, import the package in your Dart code:

main.dart

import 'package:unico_check/unico_check.dart';

Obtaining the Credentials

Contact the CSs and/or Onboarding team.
Request the SDK Key by providing the identifiers of your applications: Bundle Identifier for iOS, PackageID for Android, and Host for WEB.
The identifiers of your applications will be linked to the SDK Key by the Unico team.
You will receive your SDK Key to implement the AcessoBioConfigDataSource.

Embedding the Credentials in Your Project

To embed the SDK Key into the project, implement the AcessoBioConfigDataSource protocol in your class:

  final _configIos = UnicoConfig(
      getBundleIdentifier: "Your BundleIdentifier Ios",
      getHostKey: "Your HostKey Ios"); 

  final _configAndroid = UnicoConfig(
      getBundleIdentifier: "Your BundleIdentifier Android",
      getHostKey: "Your HostKey Android");

  void initUnicoCamera() {
    _unicoCheck = new UnicoCheck(
        listener: this,
        unicoConfigIos: _configIos,
        unicoConfigAndroid: _configAndroid);
  }

Deprecated Method - Dart

  final _configIos = UnicoConfig(
      getProjectNumber: "Your ProjectNumber Ios",
      getProjectId: "Your ProjectId Ios",
      getMobileSdkAppId: "Your MobileSdkAppId Ios",
      getBundleIdentifier: "Your BundleIdentifier Ios",
      getHostInfo: "Your HostInfo Ios",
      getHostKey: "Your HostKey Ios");

  final _configAndroid = UnicoConfig(
      getProjectNumber: "Your ProjectNumber Android",
      getProjectId: "Your ProjectId Android",
      getMobileSdkAppId: "Your MobileSdkAppId Android",
      getBundleIdentifier: "Your BundleIdentifier Android",
      getHostInfo: "Your HostInfo Android",
      getHostKey: "Your HostKey Android");

@override
  void initState() {
    super.initState();
    initUnicoCamera();
    configUnicoCamera();
  }

  void initUnicoCamera() {
    _unicoCheck = new UnicoCheck(
        listener: this,
        unicoConfigIos: _configIos,
        unicoConfigAndroid: _configAndroid);
  }

Best Practices for SDK Implementation

In this section, you will find a list of best practices for implementing the Unico IDCloud platform SDK

Use a PoC to Facilitate Your Implementation

Always Keep Your SDKs Updated

The SDKs are constantly evolving to ensure greater security and new features and functionalities. It is essential for clients to maintain a routine of updates, as well as to be agile in applying critical updates.

Identify the Latest Version Available for the SDK

It is important to ensure that you update to the most recent version available:

Avoid Updating the SDK and Other Components/Functionalities Simultaneously

We understand that your application makes use of various other libraries and functionalities, often being loaded simultaneously with the Unico SDK. As a best practice for updates, avoid upgrading our SDK at the same time you update any other functionality or library. This is because, if you encounter a failure or a change in behavior, it may be challenging to identify the root cause. We recommend performing updates separately to ensure better control over validations, as well as using our staging environment.

Are You Having Difficulty Updating the SDK? We Can Help

If you are having difficulties, open a ticket in our client portal with the following information (to expedite the process):

What is the language of the SDK you are trying to update?
If it’s mobile (Android or iOS), is it a native or hybrid implementation (please provide details)?
In the case of JavaScript implementation, which framework is being used?
What is the current version of the SDK you are trying to update? (not necessary if it's a new installation);
What is the new version you are attempting to install/update?
Please provide the API Key you are using;
Does the update consist solely of upgrading the SDK, or are other components/functionalities also being changed/updated/modified? If so, please describe which additional items are being modified;
Provide a description of the steps executed and what the results/errors were;
Please attach evidence and inputs related to the failure/problem (log files containing error/failure excerpts, screenshots, and/or videos reproducing the problem).

Do not Manipulate the JWT Object (Encrypted)

When successfully capturing an image, the onSuccessSelfie method returns an object of type ResultCamera which has two attributes:

Base64 of the obtained image, which can be used if you want to display a preview of the image in your app;
Encrypted, which is a JWT object that must be sent in the REST API calls. The JWT (Encrypted) should be used strictly during image submission through Unico's APIs. You should not open or serialize this attribute, as its characteristics may change without prior notice. Its use should be exclusive for interactions with the APIs to ensure data integrity and security. Unico is not responsible for any damages arising from this practice, as modifications can occur unpredictably. As mentioned, the SDK already provides the Base64 attribute to obtain the image in question.

Um caso de exemplo em Swift: Método: onSuccessSelfie print("(result.encrypted)") para Encrypted print("(result.base64)") para para Base64 print("(result)") para Encrypted e Base64

In summary: never attempt to read or manipulate the Encrypted (JWT) attribute.

Send the JWT Within 10 Minutes

For security reasons, the JWT must be sent within a period of 10 minutes. If the sending exceeds this window, the package will be considered invalid. Consider this time during the user's journey in your application and avoid subsequent changes.

Send the JWT Only Once

For security reasons, the JWT must be sent only once to Unico's backend. If there is a problem processing the image and/or an error in the response, a new biometric capture must be performed to generate a new encrypted object and then send this new file to Unico's backend.

Do Not Use Virtualization

Virtualizing devices in your application's testing dynamics can be interpreted as an attempt to bypass the security layers incorporated into the biometrics provider, potentially returning the errors:

Mobile:
- 73006 - Unable to open camera on emulators.
Web:
- 73600 - Could not find camera resource.
- 73400 - Could not initialize camera.

To avoid rework and incorrect error identification, tests should be conducted on physical devices.

Use the Same API Key for Capturing and Sending the Photo to the Backend

All communication and requests are based on API Keys previously defined in the client's instance. It is very important that your implementation uses the same API Key in both the capture and submission flows, as this helps avoid integration errors, facilitates validation, and ensures traceability of processes and flows.

If you have any questions about your API Key, please contact technical support.

Do Not Keep DevTools Open When Performing Web Captures

During testing and validation processes, it is normal to keep DevTools open to check flows and requests. However, the capture validation method should not be considered during these tests, as the SDK identifies it as a possible fraud and invalidates the submission when sent to the backend. Therefore, when performing end-to-end flows, it is essential to keep DevTools disabled and proceed with normal capture.

Delete "Resources" Files When Updating to New Versions (Web)

When uploading versions for the WEB SDK, if there is also an update for resource files, always delete the old file and insert the new ones in the Public folder. This is because files may have the same name and not be replaced. Also, ensure that there is no internal cache of the old resource files after the update and new build.

Implementations in Flutter Applications Must Use Our Flutter Plugin

For implementation in Flutter applications, always use our specific Flutter plugin for this purpose. We reinforce that you should not try to implement the native versions of our SDK (Android, iOS) through bridges in Flutter applications, as this action often generates errors not mapped by Unico's engineering team.

Separate the Preparation and Camera Opening Flow into 2 Steps

The SDK implementation has 2 steps until the photo capture and generation of the encrypted:

Camera preparation;
Camera opening.

In the first step, you need to specify the type of camera to be used and the bundle with the API KEY information. If everything is correct, the authentication with the SDK backend is successfully carried out. In the second step, the camera is opened, usually triggered by a button click from the user. Authentication with the SDK backend may take a few seconds, so placing this step along with the camera opening in the user's button click can create frustration and a sense of slowness. Therefore, the ideal approach is to prepare the camera during the loading of the capture orientation page, so when the user decides to open the camera, the loading will be faster, enhancing the final experience.

This way, you will optimize your implementation and improve the speed of your application, reducing the perception of slowness in processing for your end user.

Cache Cleaning When Updating the Mobile SDK

Always perform cache cleaning before building and uploading new versions. If this cleaning is not performed, you may encounter errors related to cached dependencies that may have been removed or updated in new versions. Below are some examples of how to do this:

For Flutter, use the command:
- Remove the file: pubspec.lock or;
- flutter pub get.
For iOS, use the command:
- pod cache clean 'unicocheck-ios' –all or;
- pod cache clean –all or;
- Remove podfile.lock and follow up with pod install.
For Android in build Gradle, use the command:
- ./gradlew clean.

Obfuscation Settings

Obfuscation is a process of transforming bytecode into a form that is less human-readable, thus making reverse engineering more difficult. The obfuscation tool used in your application can affect the functionality of the SDK, so it is important that the SDK code is not obfuscated. A good indicator of obfuscation issues is when your application works in debug mode but fails when building in release mode, since obfuscation does not modify files in debug mode.

Therefore, it is essential that during the SDK implementation, you add the necessary obfuscation rules for the Unico SDK. Otherwise, you may face issues when trying to build the project using the iOS, Android, or Flutter SDK.

Below are the links for the obfuscation configuration for each OS:

Perform Tests and Validations in Unico's Staging Environment

Unico provides a staging environment for clients to perform tests and validations of their implementations before making any changes and modifications to the production environment. We emphasize the importance of this step in order to ensure greater security when performing the change window in production. Ensure that your testing plan includes as many validations and scenarios as possible that you will encounter in the production environment (such as device variations, tests with limited connectivity, etc.).

Important: remember that the staging environment has its own set of configurations/parameters, such as service account and specific API Keys (different from the production environment).

Create a Safe Checklist for Production Rollout

Create a script / checklist considering your company's change management plan.
Make sure you are using the correct production settings (such as the correct API Key).
Ensure that you have a rollback (recovery) plan in case of failure when deploying the new version to production.
When encountering a failure, collect all logs and relevant inputs.
Reactivate the previous functional version to mitigate impact in production.
Open a ticket on our customer portal containing all the information and inputs regarding the failure so that we can assist you.

Selfie Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud platform SDK into your Web applications for selfie capture

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

If not configured, by default, the Web SDK uses the production environment.

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.

The encrypted attribute is strictly intended for sending the image through the by Client APIs. This attribute should not be opened or serialized, as its characteristics may be altered without prior notice. Its use should be exclusive in interactions with the APIs to ensure the integrity and security of the data. Unico is not responsible for any damage resulting from this practice, as modifications may occur unexpectedly.
The base64/encrypted files may vary in size depending on several variables, including the quality of the devices and the photos generated by them, and Unico's business rules. To avoid issues in your application, do not limit the size of the string generated by the SDK for these files in your programming logic or infrastructure.

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 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.

To optimize camera startup, you can separate the calls to the methods prepareSelfieCamera() and open().

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
  });

TThe method prepareSelfieCameraForIFrame() only works if the implementation is inside an iFrame. Using it outside of an iFrame will result in error 73724. Similarly, using the method prepareSelfieCamera() inside an iFrame will also result in error 73724.

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:

Apple restricts the use of full-screen APIs specifically on iPhones (iPads are acceptable). Therefore, for captures on iPhones, it is necessary to manually configure the positioning of the iFrame.

Making a POST Request to the Client API

For security reasons, the interval between generating the encrypted data and sending it via one of the available flows should be no more than 10 minutes. Submissions made beyond this period will be automatically rejected by the API.

Document Capture

In this section, you will find all the necessary information for using and integrating the Unico IDCloud SDK into your Web applications for document capture

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.

The SDK does not perform any kind of validation on what is being captured.

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.

Often, the frame's functionality can be affected by design systems that have some type of grid system, such as Bootstrap or Material-UI. To minimize this risk, ensure that you position the frame (id="box-camera") in a place in the code where it does not inherit any unwanted CSS rules.

In the Web Desktop versions, it is possible to restrict the size of the frame so that it doesn't use the entire dimension of your WebApp. To do this, simply wrap the frame (id="box-camera") in another HTML tag, as shown in the example below:

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

Ideally, you should aim to maintain a proper ratio between height and width, as this will make it easier to frame the user's face. Here's an example:

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

Following the example above, the frame respects the size of the "parent" element, in this case represented by the container. This way, you have the flexibility to implement the frame in the most convenient way for your application (e.g., inside a modal).

Tests involving resizing the screen through your browser's developer mode will not work as expected. It is recommended to perform this type of test by resizing your browser window instead.

For a Web Mobile view, it is recommended that the capture frame occupy 100% of the screen to avoid issues with computer vision algorithms. If the capture area is distorted, the automatic capture feature (Smart Camera) may face issues in tracking the user's face.

Therefore, for the Web Mobile view:

The capture frame should occupy 100% of the device screen (100vw/vh);
Avoid horizontal or vertical scrolling (this can be minimized by using a modal).

You can check an example of implementation through a project on this page (Angular).

Testing devices using the developer mode in your browser won't work, as the camera used by your browser is the same as on your desktop, which has a resolution vastly different from a mobile device camera. We recommend that such tests be done directly on the device.

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 type of document to be captured, which are:

Parameter

Description

DocumentCameraTypes.CPF

Capture the front of the CPF

DocumentCameraTypes.CNH

Capture the open CNH

DocumentCameraTypes.CNH_FRENTE

Capture the front of the CNH

DocumentCameraTypes.CNH_VERSO

Capture the back of the CNH

DocumentCameraTypes.RG_FRENTE

Capture the front of the RG

DocumentCameraTypes.RG_VERSO

Capture the back of the RG

DocumentCameraTypes.RG_FRENTE_NOVO

Capture the front of the new RG

DocumentCameraTypes.RG_VERSO_NOVO

Capture the back of the new RG

DocumentCameraTypes.OTHERS("descrição")

Capture any other document

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
  });

If you need to capture a document for which there is no specific frame (e.g., RNE, among others), use the If you need to capture a document that does not have a specific frame (e.g., RNE, among others), use the frame DocumentCameraType.None, which will provide you with a generic, rectangular frame that can be used to guide any capture.