@trully/trully-document-reader NPM

TrullyDocumentReader

TrullyDocumentReader is a Mexican document validator focused on INE and Passport ⚠️ The component only works under the HTTPS protocol ⚠️ For develop, you should pass isDev true. See How to use section ⚠️ This is a client-side component. If your project was created with Next.js, follow the steps in the Add it to Next.js section

Install
1. Add styles
2. Prefetch the images/videos
How to use
Tracking process
Combine with other Decision Maker analysis
Personalize
Add it to Next.js
1. Next.js App Router System
2. Next.js Page Router System
Data handling
1. handleData
2. handleError
Full Example
Known issues
1. Camera permission was accepted, but a message asking to accept it appears

Install

npm i @trully/trully-document-reader

Add styles

To import the styles, go to your main.js file and add the following import

import "../node_modules/@trully/trully-document-reader/dist/styles.css";

Prefetch the images/videos

Optionally, add the following link tag to the head of your your HTML to improve the loading time of the images and videos

<head>
  <!-- ...Rest of head tags -->
  <link
    rel="prefetch"
    href="https://trully-api-documentation.s3.amazonaws.com/trully-sdk/"
  />
</head>

How to use

The component receives the "configuration" prop. This prop should be an object containing the keys that will let you adapt it to your needs. There are the only five required keys: "isDev", "apiKey", "user_id", "handleData" and "handleError".

Key	Description
`isDev`	Set it to true when your working in development
`apiKey`	Your cliente API Key
`user_id`	String. Will match the response you get with the user completing the process
`handleData`	Should be a callback function receiving a parameter. This parameter will hold the process result.
`handleError`	Should be a callback function receiving a parameter. This parameter will hold an error object.

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    isDev: true,
    apiKey: "YOUR_API_KEY",
    user_id: "YOUR_USER_ID",
    handleData: (response) => {
      //What should be done with the obtained response?
    },
    handleError: (error) => {
      //What should be done if there is an error retrieving the response?
    },
  }}
/>;

Tracking process

You can declare a tag to track every process TrullyDocumentReader has run. This key is optional but we recommend using it from the start.

Key	Description
`tag`	Valid uuid string. If you do not provide it, one will automatically generated.
	One analysis could run several process. Each one will be available with this tag

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    isDev: true,
    apiKey: "YOUR_API_KEY",
    user_id: "YOUR_USER_ID",
    tag: "VALID_V4_UUID",
    handleData: (response) => {
      //What should be done with the obtained response?
    },
    handleError: (error) => {
      //What should be done if there is an error retrieving the response?
    },
  }}
/>;

Combine with other Decision Maker analysis

TrueDeepfakeDetection helps you to get the selfie of a candidate so our Decision Maker can analyze it. But our Decision Maker could be used to analyze different data points and you may want to combine every Decision Maker response you get for every data point (learn more about Decision Maker on the API Docs). You can join the response you get from the TrueDeepfakeDetection with others Decision Maker responses passing the request_id in the configuration object.

Key	Description
`request_id`	String. The id generated by the Decision Maker for any analysis run.

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    isDev: true,
    apiKey: "YOUR_API_KEY",
    user_id: "YOUR_USER_ID",
    tag: "VALID_V4_UUID",
    handleData: (response) => {
      //What should be done with the obtained response?
    },
    handleError: (error) => {
      //What should be done if there is an error retrieving the response?
    },
    request_id: "REQUEST_ID_FOR_THE_ANALYSIS_OF_OTHER_DATA_POINT",
  }}
/>;

Personalize

To customize the component, add the corresponding keys to the configuration prop. Every one of these keys are optional

Key	Description
`showLogo`	Set it to false to remove the logo image
`showExit`	If false will show only icon check when the process is finished
`termsAndConditions*`	String. URL to your terms and conditions page
`privacyPolicy*`	String. URL to your privacy policy page
`images`	Object containing the images to replace the default ones
`videos`	Object containing the videos to replace the default ones
`texts`	Object containing the texts to replace the default ones
`styles`	Object containing two optionals keys. textsStyles and colors keys

*By default the component uses our terms and conditions and privacy policy

pages

Example

This example shows the default values for the showLogo, showExit, termsAndConditions and privacyPolicy keys

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    // ...required keys
    showLogo: true,
    showExit: true,
    termsAndConditions: "https://www.trully.ai/terminos-y-condiciones/",
    privacyPolicy: "https://www.trully.ai/politica-de-datos/",
  }}
/>;

Change images

Images are loaded using an image HTML tag, so to change it you should pass the corresponding path to the image. Every one of these keys are optional. These are the default values

Key	Description
`logo`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/logo-trully.svg
`docIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/ID-1.svg
`docOkIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon_INEOK+color.svg
`brightnessIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon_Reflejo+color.svg
`docFocusedIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon_Ine+enfoque.svg
`docUnfocusedIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon_blur+color.svg
`permissions`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/ModalWeb.svg
`cameraDeniedImage`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/cameraDenied-1.svg
`timeoutIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/no_element_timeout.svg
`errorIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/face_timeout.svg
`iconCheck`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon-check.svg
`landscapeNotAllowedIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/rotate.svg
`poorWifiIcon`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon_coneccio%CC%81n.webp

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    // ...required keys
    images: {
      logo: "YOUR_LOGO_PATH",
      docIcon: "YOUR_IMG_PATH",
      docOkIcon: "YOUR_IMG_PATH",
      brightnessIcon: "YOUR_IMG_PATH",
      docFocusedIcon: "YOUR_IMG_PATH",
      docUnfocusedIcon: "YOUR_IMG_PATH",
      permissions: "YOUR_IMG_PATH",
      cameraDeniedImage: "YOUR_IMG_PATH",
      timeoutIcon: "YOUR_IMG_PATH",
      errorIcon: "YOUR_IMG_PATH",
      iconCheck: "YOUR_IMG_PATH",
      landscapeNotAllowedIcon: "YOUR_IMG_PATH",
    },
  }}
/>;

Change videos

Videos are loaded using a video HTML tag, to change it you should pass the corresponding path to the video. We recommend to change the videoFallback image if you're going to change livenessVideo. videoFallback is use as livenessVideo poster. Every one of these keys are optional. These are the default values.

Key	Description
`docFront`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/IneFront.webm
`docBack`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/IneBack.webm
`docFail`	https://trully-api-documentation.s3.amazonaws.com/trully-sdk/IneFail.webm

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    // ...required keys
    videos: {
      docFront: "YOUR_VIDEO_PATH",
      docBack: "YOUR_VIDEO_PATH",
      docFail: "YOUR_VIDEO_PATH",
    },
  }}
/>;

Change texts

You can change some texts by using the texts key. This key should receive an object. Every property in the object is optional. Here is the structure. Each key is an object with the following optional properties: title, subtitle, docType and btnText. This properties will be used accordingly.

Key	Description
`appIntro`	This page is used to introduce the process and ask for consent on terms and conditions and privacy policy
`docFrontIntro`	This page will show the user how to take the picture to the front of the credential
`cameraPermissions`	This page will let the user know we will be asking for permission to use the camera
`docBackIntro`	This page will show the user how to take the picture to the back of the credential
`exit`	This page will thank the user and let them know we got the data

Keys structure

Here you'll the default values for each an every text you could modify.

appIntro

Key	Description
`title`	String. Vamos a verificar tu identidad
`subtitle`	String. Para este proceso necesitas:
`docType`	Number. 1 (see docType configuration)
`btnText`	String. Comenzar

docType configuration

Key	Description
`docType`	Number. Will let you change the text asking for document type
	0.- INE o Pasaporte vigente. 1.- INE vigente. 2.- Pasaporte vigente

docFrontIntro

Key	Description
`title`	String. Toma una foto de la parte frontal de tu INE
`btnText`	String. Tomar fotografía

cameraPermissions

Key	Description
`title`	String. Para continuar permite el acceso a la cámara
`subtitle`	String. Cuando se le solicite, selecciona “Permitir” para habilitar el acceso a la cámara.
`btnText`	String. Activar cámara

docBackIntro

Key	Description
`title`	String. Toma una foto de la parte trasera de tu INE
`btnText`	String. Tomar fotografía

exit

Key	Description
`title`	String. ¡Gracias!
`subtitle`	String. Tu información fue recibida con éxito

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    // ...required keys

    texts: {
      appIntro: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
        docType: 1,
        btnText: "YOUR_TEXT",
      },
      docFrontIntro: {
        title: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      cameraPermissions: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      docBackIntro: {
        title: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      exit: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
      },
    },
  }}
/>;

Change styles

The styles personalization is divided in sections

Key	Description
`textsStyles`	Receives an object to declare font specific styles
`colors`	Receives an object to declare colors styles

textsStyles

You can change the entire font using fonFamily or changes an specific font using the individualFamily object. Every one of these keys are optional. These are the default values.

Key	Description
`fontFamily`	"DM Sans", sans-serif
`individualFamily`	Object to declare font for specific elements
`primaryTextColor`	#181c21 (titles)
`secondaryTextColor`	#181c21 (texts)

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    // ...required keys

    styles: {
      textsStyles: {
        fontFamily: "YOUR_FONT",
        // Colors should be expressed in hexadecimal
        primaryTextColor: "YOUR_HEX_COLOR",
        secondaryTextColor: "YOUR_HEX_COLOR",
      },
    },
  }}
/>;

individualFamily

Every one of these keys are optional. If not specified will default to "DM Sans", sans-serif

Key	Description
`text1BoldFamily`	Titles. Each bold text
`text1Family`	Texts

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    // ...required keys

    styles: {
      textsStyles: {
        individualFamily: {
          text1BoldFamily: "YOUR_FONT", //titles
          text1Family: "YOUR_FONT", //texts
        },
        // Colors should be expressed in hexadecimal
        primaryTextColor: "YOUR_HEX_COLOR",
      },
    },
  }}
/>;

colors

Colors will allow you change the different colors to match your brand design. Every one of these keys are optional. These are the default values.

Key	Description
`primary`	#475fff
`secondary`	#001063
`disabled`	#E5EBF3
`white`	#FFFFFF
`background`	#FFFFFF
`icons`	None

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

<TrullyDocumentReader
  configuration={{
    // ...required keys

    styles: {
      colors: {
        primary: "YOUR_HEX_COLOR",
        secondary: "YOUR_HEX_COLOR",
        disabled: "YOUR_HEX_COLOR",
        white: "YOUR_HEX_COLOR",
        background: "YOUR_HEX_COLOR",
        icons: "YOUR_HEX_COLOR",
      },
    },
  }}
/>;

Add it to Next.js

Next.js App Router System

Add styles

To import the styles, go to your app level layout.js file (RootLayout Component)

and add the following import

import "../node_modules/@trully/trully-document-reader/dist/styles.css";

Prefetch the images/videos

Optionally, add the following link tag to the head of your your HTML to improve the loading time of the images and videos

<head>
  <!-- ...Rest of head tags -->
  <link
    rel="prefetch"
    href="https://trully-api-documentation.s3.amazonaws.com/trully-sdk/"
  />
</head>

Example

import { Inter } from "next/font/google";
import "./globals.css";
import "../node_modules/@trully/trully-document-reader/dist/styles.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <link
          rel="prefetch"
          href="https://trully-api-documentation.s3.amazonaws.com/trully-sdk/"
        />
      </head>
      <body className={inter.className}>{children}</body>
    </html>
  );
}

TrullyDocumentReader is a client-side component, which means it needs to run on the client. By default, every component created in Next.js is executed on the server. You need to make sure our component runs only on the client.

Creating a client-side component

To ensure a component runs on the client, it should be marked as a client-side component using the "use client" tag. In the Next.js project, create a new component and mark it as a client-side component.

Example

"use client";

import { TrullyDocumentReader } from "@trully/trully-document-reader";

const Trully = () => {
  return (
    <TrullyDocumentReader
      configuration={{
        isDev: true,
        apiKey: "YOUR_API_KEY",
        user_id: "YOUR_USER_ID",
        tag: "VALID_V4_UUID",
        handleData: (response) => {
          //What should be done with the obtained response?
        },
        handleError: (error) => {
          //What should be done if there is an error retrieving the response?
        },
      }}
    />
  );
};

export default Trully;

Dynamically import the component

Then, to ensure the component runs only on the client, make a dynamic import with ssr: false.

Example

import dynamic from "next/dynamic";

const DynamicComponent = dynamic(() => import("@/components/Trully"), {
  ssr: false,
});

export default function Home() {
  return <DynamicComponent />;
}

Next.js Page Router System

Add styles

To import the styles, go to your _app.js file and add the following import

import "../node_modules/@trully/trully-document-reader/dist/styles.css";

Prefetch the images/videos

Optionally, add the following link tag to the head of your your HTML to improve the loading time of the images and videos

<head>
  <!-- ...Rest of head tags -->
  <link
    rel="prefetch"
    href="https://trully-api-documentation.s3.amazonaws.com/trully-sdk/"
  />
</head>

Example

import Head from "next/head";
import "../styles/globals.css";
import "../node_modules/@trully/trully-document-reader/dist/styles.css";

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Head>
        <link
          rel="prefetch"
          href="https://trully-api-documentation.s3.amazonaws.com/trully-sdk/"
        />
      </Head>
      <Component {...pageProps} />
    </>
  );
}

export default MyApp;

Creating a component

First, create a new component so you can configure TrullyDocumentReader component

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader-next12";

const Trully = () => {
  return (
    <TrullyDocumentReader
      configuration={{
        isDev: true,
        apiKey: "YOUR_API_KEY",
        user_id: "YOUR_USER_ID",
        tag: "VALID_V4_UUID",
        handleData: (data) => {
          //What should be done with the obtained data?
        },
        handleError: (error) => {
          //What should be done if there is an error retrieving the data?
        },
      }}
    />
  );
};

export default Trully;

Dynamically import the component

Then, to ensure the component runs only on the client, make a dynamic import with ssr: false.

Example

import dynamic from "next/dynamic";

const DynamicComponent = dynamic(() => import("@/components/Trully"), {
  ssr: false,
});

export default function Home() {
  return <DynamicComponent />;
}

Data handling

TrullyDocumentReader will perform an analysis of the video capture during the process and will make the result available by running the callback you declare in "handleData" key. Same way, if there is any problem during the process will run the callback in "handleError" key. Here are the values you can access through them.

handleData

Key	Description
`tag`	String. The tag from the process. Automatically generated when you didn't pass one through configuration prop
`user_id`	String. The user_id you passed in configuration
`front_session_id`	Boolean. The id for the valid document front image
`back_session_id`	Boolean. The id for the valid document back image
`images`	Object. Contains the images get during the process
`DMResponse`	You'll find more details in Decision Maker API Docs

Images

Key	Description
`document_image`	String base64. Cropped document front image
`document_back`	String base64. Cropped document back image
`document_image_complete`	String base64. Document front image
`document_back_complete`	String base64. Document back image

DMResponse data

Key	Description
`request_id`	String. The id of the DM Response
`label`	String. The label generate by the Decision Maker for the user who has completed the process
	No Threat - low risk user. Review - medium risk user. Potential Threat - high risk user
`reason`	Array. Contains the reasons behind the decision
`request_date`	String. UTC timezone date for the request

Receiving data with webhook

If you prefer it is possible to set a webhook url to receive the Decision Maker response. To do it, just pass the key webhook to the configuration object

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

const handleData = (response) => {
  console.log("Response - tag", response.tag);
  console.log("Response - userId", response.userId);
  console.log("Response - front_session_id", response.front_session_id);
  console.log("Response - back_session_id", response.back_session_id);
  console.log("Response - images", response.images);
  console.log("Response - DM", response.DMResponse);
};

<TrullyDocumentReader
  configuration={{
    isDev: true,
    apiKey: "YOUR_API_KEY",
    user_id: "YOUR_USER_ID",
    tag: "VALID_V4_UUID",
    handleData,
    handleError: (error) => {
      //What should be done if there is an error retrieving the response?
    },
    webhook: "VALID_WEBHOOK_URL",
  }}
/>;

handleError

We recommend you save this error into a log file.

Key	Description
`process`	Which part of the process trigger the function.
`message`	Error message
`userID`	The userID you passed during initialization.
`timestamp`	UTC timezone. When the function was trigger.
`error`	Object. Extra information about the error

Names Table

Name	Description
`GETTING_FRONT_IMAGE`	HTTP error getting document front image.
`GETTING_BACK_IMAGE`	HTTP error getting document front image.
`GETTING_DM_RESPONSE`	HTTP error processing images.

Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

const handleError = (error) => {
  console.log("Error - name", error.name);
  console.log("Error - description", error.description);
  console.log("Error - error", error.error);
};

<TrullyDocumentReader
  configuration={{
    isDev: true,
    apiKey: "YOUR_API_KEY",
    user_id: "YOUR_USER_ID",
    tag: "VALID_V4_UUID",
    handleData: (response) => {
      //What should be done with the obtained response?
    },
    handleError,
  }}
/>;

Full Example

import { TrullyDocumentReader } from "@trully/trully-document-reader";

const handleData = (response) => {
  console.log("Response - tag", response.tag);
  console.log("Response - userId", response.userId);
  console.log("Response - front_session_id", response.front_session_id);
  console.log("Response - back_session_id", response.back_session_id);
  console.log("Response - images", response.images);
  console.log("Response - DM", response.DMResponse);
};

const handleError = (error) => {
  console.log("Error - name", error.name);
  console.log("Error - description", error.description);
  console.log("Error - error", error.error);
};

<TrullyDocumentReader
  configuration={{
    isDev: true,
    apiKey: "YOUR_API_KEY",
    user_id: "YOUR_USER_ID",
    tag: "VALID_V4_UUID",
    handleData,
    handleError,
    showLogo: true,
    showExit: true,
    images: {
      logo: "YOUR_LOGO_PATH",
      lightIcon: "YOUR__ICON_PATH",
      crossIcon: "YOUR__ICON_PATH",
      iconCheck: "YOUR__ICON_PATH",
      videoFallback: "YOUR_IMAGE_PATH",
    },
    videos: {
      docFront: "YOUR_VIDEO_PATH",
      docBack: "YOUR_VIDEO_PATH",
      docFail: "YOUR_VIDEO_PATH",
    },
    texts: {
      appIntro: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
        docType: 1,
        btnText: "YOUR_TEXT",
      },
      docFrontIntro: {
        title: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      cameraPermissions: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      docBackIntro: {
        title: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      exit: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
      },
    },
    styles: {
      textsStyles: {
        fontFamily: "YOUR_FONT",
        // Colors should be expressed in hexadecimal
        primaryTextColor: "YOUR_HEX_COLOR",
      },
      colors: {
        primary: "YOUR_HEX_COLOR",
        secondary: "YOUR_HEX_COLOR",
        disabled: "YOUR_HEX_COLOR",
        white: "YOUR_HEX_COLOR",
        background: "YOUR_HEX_COLOR",
        icons: "YOUR_HEX_COLOR",
      },
    },
  }}
/>;

Known issues

This section provides workarounds for some known issues that may occur while using the component.

Camera permission was accepted, but a message asking to accept it appears

This may happen for three reasons:

The component needs to work under the HTTPS protocol because the Browser Camera API will revoke access to the device if the connection is not secure. Make sure that you're working with HTTPS.
Some browsers will revoke access to the device while using auto-signed certificates. If you're working in development, you're probably creating an auto-signed certificate to force the HTTPS protocol. If that's the case, open your app in an incognito tab.
The Browser Camera API will automatically revoke permissions if there is another instance running. Make sure that you're only working in one tab at a time.
The Browser Camera API will automatically revoke permissions if the App has the Camera permissions denied. It's important to let the users know they'll have to change the App permissions to allow the Browser Camera API to ask for permissions

@trully/trully-helpers-react @trully/trully-image-reader-react

8 months ago

9 months ago

9 months ago

9 months ago

10 months ago