TrullyWebSDK

TrullyWebSDK is an identity validation component designed to be integrated into your decision-making process.

⚠️ The component only works under the HTTPS protocol ⚠️ For develop, you should pass environment true. See Document Reader 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

npm i trully-sdk-react-2

Add styles

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

import "../node_modules/trully-sdk-react-2/dist/styles.css";

How to use

The component receives the configuration prop, which should contain an object for configuring and personalizing the experience. This object has three keys: DocumentReader, AppConfiguration, and usage. Of these keys, only usage is required for the component to function properly.

The DocumentReader key will pass data related to document scanning. The AppConfiguration key will pass colors, images, fonts, and URLs that can be used to create your own KYC experience. Finally, the usage key will receive the necessary API Key to obtain the Decision Maker data, the user ID to match Decision Maker response with user, two functions to manage the response: handleData will allow you to access the response, while handleError will let you control what to do in case of a communication error.

| Key | Description | | ------------------ | ------------------------------------------------ | | usage | Object containing process configuration settings | | AppConfiguration | Object containing process configuration settings | | DocumentReader | Object containing document processing setting |

usage key

For the component to work you only need to pass apiKey, user_id, handleData, and handleError using the usage key. These are the keys you can pass.

| Key | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------- | | apiKey | String (required). These will allow you to enter your client API KEY. The component won't work with out it | | handleData | Callback (required). These function should declare a parameter that will hold the process resulting data | | handleError | Callback (required). These function should declare a parameter that will hold the process error | | user_id | String (required). Will match the response you get with the user completing the process. | | handleTrack | Callback. Catch the step changing of the operation. | | handleTrackDetail | Callback. Catch the user's interaction during the operation. | | forceLocation* | Boolean. If true, the process won't finished unless the candidate share their location. Default true | | userIDIsCURP** | Boolean. If you're using the CURP as user_id and want to send it to the Decision Maker mark this as true. Default false |

*If the candidate chooses to use a mobile device, the access to the location will depend on the Browser App permissions. iOS devices block location access by default so the user will need to manually set the permission. ⚠️ If you choose not to force the location, we won't be able to guarantee location related information **curp input won't be showing in form page

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      apiKey: "YOUR_API_KEY",
      user_id: "YOU_USER_ID",
      handleData: (processResponse) => {
        //What should be done with the obtained processResponse?
      },
      handleError: (error) => {
        //What should be done if there is an error?
      },
    },
  }}
/>;

Callbacks data structure

Here you'll found the structures of the data received in each callback function

handleTrack

This function will be called every time the user starts a new step on the process. There are five different steps. When a new step is started, you'll receive the data from the previous completed step.

| Key | Description | | -------------- | ------------------------------------ | | step | Name of the previous completed step. | | user_id | The user_id you passed in usage key. | | started_on | UTC timezone. Step starting time. | | completed_on | UTC timezone. Step completion time. |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //...other usage data
      handleTrack: (step) => {
        console.log(step);
      },
    },
  }}
/>;

Steps Table

| Name | Description | | --------------------- | ------------------------------------------------- | | form_start | User is currently scanning the document. | | form_document | Process is currently trying to obtained location. | | form_location | User is currently completing liveness process. | | form_selfie | User reach the final step of the operation. | | form_decision_maker | Operation has the Decision Maker respond. |

handleTrackDetail

This function will be called when the user take some actions during the operation. The actions that will trigger it are the ones related to the data needed for the Decision Maker.

| Key | Description | | ----------- | --------------------------------------------- | | user_id | The user_id you passed in usage key. | | action | Name of the action that trigger the function. | | timestamp | UTC timezone. When the function was trigger. |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //...other usage data
      handleTrackDetail: (trackDetail) => {
        console.log(trackDetail);
      },
    },
  }}
/>;

Actions Table

| Name | Description | | ---------------------------------------- | ---------------------------------------------------------------------- | | LEGAL_DOCUMENTATION_ACCEPTED | User accept Privacy Policy and Terms and Conditions. | | LEGAL_DOCUMENTATION_DECLINED | User declined Privacy Policy and Terms and Conditions. | | LOAD_NEXT_PAGE | Operation start new page. | | NO_CAMERA_AVAILABLE | The operation couldn't start camera. | | FRONT_IMAGE_OBTAINED | Operation has document front. | | BACK_IMAGE_OBTAINED | Operation has document back. | | DOCUMENT_ANALYSIS_RETRY | Operation needs to re start document analysis. | | DOCUMENT_ANALYSIS_COMPLETE | Operation has analyzed front and back image. | | LOCATION_OBTAINED | Operation has user's location. | | LOCATION_SKIPPED | Operation has continued without user's location. | | LIVENESS_RECOGNITION_PROCESS_STARTED | Operation has start liveness analysis. | | LIVENESS_RECOGNITION_PROCESS_COMPLETED | Operation has analyzed liveness status. | | DATA_SEND_TO_DECISION_MAKER | Operation has sended data collected to Decision Maker. Awaiting result | | END_KYC_PROCESS | Operation has Decision Maker result. |

handleData

This function will be called when the operation gets the Decision Maker result. Go to Data handling section to get more information

onError

This function will be called in case of an error during the operation. You'll receive the error object as is generated

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 |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //...other usage data
      handleError: (error) => {
        console.log(error);
      },
    },
  }}
/>;

Process Table

| Name | Description | | ------------------------------ | ---------------------------------------------------- | | SAVING_TRACK_STEP | HTTP error when saving track data. | | OBTAINING_IP | HTTP error when getting ip data. | | INITIALIZING_DOCUMENT_READER | Process error during document reader initialization. | | READING_DOCUMENT | Process error analyzing document. | | GETTING_LIVENESS | Process error analyzing liveness. | | OBTAINING_DM_RESPONSE | HTTP error when getting Decision Maker response. |

Personalize

To customize the component, add the AppConfiguration key to the object passed in the configuration prop. These are the keys you can pass. Neither of them are required.

| Key | Description | | --------------------- | -------------------------------------------------------------------------------- | | termsAndConditions* | String. URL to your terms and conditions page | | privacyPolicy* | String. URL to your privacy policy page | | pagesToInclude | Strings array. Will allow to add/remove pages from the process | | inputs | Object. Will allow to add/remove inputs from form page | | texts | Object. The keys from this object will modify some of the texts of the component | | styles | Object. Will allow you to modify images, videos, font and colors |

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

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      termsAndConditions: "URL_TO_TERMS_AND_CONDITIONS",
      privacyPolicy: "URL_TO_PRIVACY_POLICY",
    },
  }}
/>;

pagesToInclude key

With these key you'll be able to adapt the process to take some extra data from your user by adding pages to the process. To add the pages you should pass an array containing the following strings. Each string represents one page to include.

| String | Description | | --------------- | ------------------------------------------------------------------------------------------------------------- | | form | This will add a form to your process. The data collect with it can be select using the inputs key | | personal_info | This will add a form asking for personal info such as complete name, date of birth, place of birth and gender |

inputs key

If you include form page, inputs will let you choose which data will be asked for. There are no inputs shown by default.

| Key | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | | email | Input asking for valid email address | | phone_number | Input asking for valid mexican phone number | | curp | Input asking for valid curp. If are using curp as user_id and and passed true in userIDIsCURP key. This input won't be showing | | address | Input asking for valid address |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //...required usage configuration
    },
    AppConfiguration: {
      pagesToInclude: ["form"],
      inputs: {
        phone_number: true,
      },
    },
  }}
/>;

texts key

You can change some texts by using the texts key. This key should receive an object. Here are key you could pass

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

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //...required usage configuration
    },
    AppConfiguration: {
      texts: {
        docType: 0,
      },
    },
  }}
/>;

styles key

The styles key will let customized the look and feel of the component. Every one of these are optional.

| Key | Description | | ----------- | -------------------------------------------------------- | | boxShadow | Set it to false to remove the component shadow | | showLogo | Set it to false to remove the logo image | | images | Object containing the images to replace the default ones | | videos | Object containing the videos to replace the default ones | | font | Receives an object to declare font specific styles | | colors | Receives an object to declare colors styles |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      styles: {
        showLogo: false,
        boxShadow: false,
        images: {
          //...images
        },
        videos: {
          //...videos
        },
        font: {
          //...font
        },
        colors: {
          //...colors
        },
      },
    },
  }}
/>;

images key

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 | Object. Receiving source key. This is the default url https://trully-api-documentation.s3.amazonaws.com/trully-sdk/logo-trully.svg | | DatosIcon | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/Datos-1.svg | | IDIcon | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/ID-1.svg | | VideoIcon | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/Video-1.svg | | IDImage | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/ID2-1.svg | | locationDeniedImage | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/pin-1.svg | | cameraDeniedImage | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/cameraDenied-1.svg | | permissions | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/ModalWeb.svg | | timeout | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/timeout.webp | | lightIcon | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/luzIcon.svg | | crossIcon | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/retirarElementosIcon.svg | | iconCheck | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon-check.svg | | videoFallback | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/livenessFallback.svg |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      styles: {
        images: {
          logo: {
            source: "logo_image_url",
          },
          IDIcon: "image_url",
          VideoIcon: "image_url",
          IDImage: "image_url",
          locationDeniedImage: "image_url",
          cameraDeniedImage: "image_url",
          permissions: "image_url",
          timeout: "image_url",
          iconCheck: "image_url",
          lightIcon: "image_url",
          crossIcon: "image_url",
          videoFallback: "image_url",
        },
      },
    },
  }}
/>;

videos key

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 corresponding image if you're going to change a video. Every one of these keys are optional. These are the default values.

| Key | Description | | --------------- | ------------------------------------------------------------------------------- | | timeoutVideo | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/timeout.webm | | livenessVideo | https://trully-api-documentation.s3.amazonaws.com/trully-sdk/LivenessVideo.webm |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      styles: {
        videos: {
          timeoutVideo: "video_url",
          livenessVideo: "video_url",
        },
      },
    },
  }}
/>;

font key

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 | | secondaryTextColor | #5f6877 |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      styles: {
        font: {
          family: "font_family",
          colors: {
            primaryTextColor: "hexadecimal_color_value",
            secondaryTextColor: "hexadecimal_color_value",
          },
        },
      },
    },
  }}
/>;

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 | Subtitles. Texts providing some explanation to titles | | textFamily | Texts |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      styles: {
        font: {
          individualFamily: {
            heading1: "font_family",
            heading2: "font_family",
            text: "font_family",
          },
          colors: {
            primaryTextColor: "hexadecimal_color_value",
            secondaryTextColor: "hexadecimal_color_value",
          },
        },
      },
    },
  }}
/>;

colors key

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 | #121e40 | | disabled | #D6A0FF | | white | #FFFFFF | | background | #FFFFFF |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      colors: {
        primary: "hexadecimal_color_value",
        secondary: "hexadecimal_color_value",
        disabled: "hexadecimal_color_value",
        white: "hexadecimal_color_value",
        backgroundColor: "hexadecimal_color_value",
      },
    },
  }}
/>;

Document Reader

To ensure that the component works correctly during development, it is necessary to pass a boolean value of true to inform the component that it is in development mode. This can be achieved by adding the DocumentReader key to the configuration prop.

| Key | Description | | -------------- | ---------------------------------------------------------- | | processParam | Object. Will let you configure the document reader process | | devOptions | Object. Will let you configure development options |

processParam key

| Key | Description | | --------- | -------------------------------------------------------------------------------------------------------- | | timeout | Number. How long should be wait for a valid document. Time represent in milliseconds. Default one minute |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    DocumentReader: {
      processParam: {
        timeout: 60000,
      },
    },
  }}
/>;

devOptions key

| Key | Description | | ------------- | ------------------------------------------------------------------------------------------ | | environment | Boolean. Make sure is true for development. By default the component will run on prod mode | | logErrors | Boolean. Will show error on browser console. Make sure to set it on false for prod |

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    DocumentReader: {
      devOptions: {
        environment: true,
        logErrors: true,
      },
    },
  }}
/>;

Add it to Next.js

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

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-sdk-react-2/dist/styles.css";

Example

import { Inter } from "next/font/google";
import "./globals.css";
import "../node_modules/trully-sdk-react-2/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">
      <body className={inter.className}>{children}</body>
    </html>
  );
}

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.

"use client";
import { TrullyWebSDK } from "trully-sdk-react-2";

const Trully = () => {
  return (
    <TrullyWebSDK
      configuration={{
        usage: {
          apiKey: "YOUR_API_KEY",
          user_id: "YOU_USER_ID",
          handleData: (processResponse) => {
            //What should be done with the obtained processResponse?
          },
          handleError: (error) => {
            //What should be done if there is an error?
          },
        },
      }}
    />
  );
};
export default Trully;

Import the client-side component

Once created, import it into any page

import Trully from "./components/Trully";

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

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-sdk-react-2/dist/styles.css";

Creating a component

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

Example

import { TrullyWebSDK } from "trully-sdk-react-2";

const Trully = () => {
  return (
    <TrullyWebSDK
      configuration={{
        usage: {
          apiKey: "YOUR_API_KEY",
          user_id: "YOU_USER_ID",
          handleData: (processResponse) => {
            //What should be done with the obtained processResponse?
          },
          handleError: (error) => {
            //What should be done if there is an error?
          },
        },
      }}
    />
  );
};
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

TrullyWebSDK sends the obtained data to the API Decision Maker to assist in your decision-making process. Using this component, you can access the response data from the Decision Maker and all the data collected during the KYC process. The required "usage" key should have a "handleData" function and an "handleError" function, both of which should receive a parameter. The "handleData" function stores an object with the data processed by the Decision Maker and the data obtained during the KYC process in its parameter. On the other hand, the "handleError" function stores the error generated during the query. This way, we can specify the actions to be taken when the server request is successful (handleData) or if there is an error in the process (handleError).

Process completed successfully

| Key | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | raw_data | Object containing the unprocessed data from the Decision Maker. You can learn more about here | | 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_id | String. ID created by the Decision Maker | | user_id | String. The user_id you passed in usage | | image | Base64 string. Selfie | | document_image | Base64 string. Document front cropped image | | document_image_complete | Base64 string. Document front uncropped image | | document_image_back | Base64 string. Document back cropped image | | document_image_back_complete | Base64 string. Document back uncropped image |

Example

const Trully = () => {
  return (
    <TrullyWebSDK
      configuration={{
        usage: {
          apiKey: "YOUR_API_KEY",
          user_id: "YOU_USER_ID",
          //data - Decision Maker response
          handleData: (processResponse) => {
            const { label, reason } = processResponse;
            console.log(label, reason);
          },
          handleError: (error) => {
            //error - AJAX error
          },
        },
      }}
    />
  );
};
export default Trully;

How to use the images obtained

import { TrullyWebSDK } from "trully-sdk-react-2";
import { useState } from "react";

const Trully = () => {
  const [doc, setDoc] = useState("");
  const [selfie, setSelfie] = useState("");

  return (
    <>
      <TrullyWebSDK
        configuration={{
          usage: {
            apiKey: "YOUR_API_KEY",
            user_id: "YOU_USER_ID",
            handleData: (processResponse) => {
              console.log(processResponse);
              const { document_image, image } = processResponse;
              setDoc(() => document_image);
              setSelfie(() => image);
            },
            handleError: (err) => {
              console.log(err);
            },
          },
        }}
      />
      <h2>Document</h2>
      <img src={`data:image/png;base64,${doc}`} alt="" />
      <h2>Selfie</h2>
      <img src={`data:image/png;base64,${selfie}`} alt="" />
    </>
  );
};
export default Trully;

Full Example

import { TrullyWebSDK } from "trully-sdk-react-2";

const Trully = () => {
  return (
    <TrullyWebSDK
      configuration={{
        usage: {
          apiKey: "YOUR_API_KEY",
          user_id: "YOU_USER_ID",
          handleTrackDetail: (trackDetail) => {
            console.log(trackDetail);
          },
          handleTrack: (step) => {
            console.log(step);
          },
          handleData: (processResponse) => {
            console.log(processResponse);
          },
          handleError: (err) => {
            console.log(err);
          },
        },
        DocumentReader: {
          processParam: {
            timeout: 60000,
          },
          devOptions: {
            environment: true,
            logErrors: true,
          },
        },
        AppConfiguration: {
          termsAndConditions: "URL_TO_TERMS_AND_CONDITIONS",
          privacyPolicy: "URL_TO_PRIVACY_POLICY",
          pagesToInclude: ["form"],
          inputs: {
            phone_number: true,
          },
          texts: {
            docType: 0,
          },
          styles: {
            showLogo: false,
            boxShadow: false,
            images: {
              logo: {
                source: "logo_image_url",
              },
              IDIcon: "image_url",
              VideoIcon: "image_url",
              IDImage: "image_url",
              locationDeniedImage: "image_url",
              cameraDeniedImage: "image_url",
              permissions: "image_url",
              timeout: "image_url",
              iconCheck: "image_url",
              lightIcon: "image_url",
              crossIcon: "image_url",
              videoFallback: "image_url",
            },
            videos: {
              timeoutVideo: "video_url",
              livenessVideo: "video_url",
            },
            font: {
              family: "font_family",
              colors: {
                primaryTextColor: "hexadecimal_color_value",
                secondaryTextColor: "hexadecimal_color_value",
              },
            },
            colors: {
              primary: "hexadecimal_color_value",
              secondary: "hexadecimal_color_value",
              disabled: "hexadecimal_color_value",
              white: "hexadecimal_color_value",
              backgroundColor: "hexadecimal_color_value",
            },
          },
        },
      }}
    />
  );
};
export default Trully;

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:

1. 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.
2. 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.
3. 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.

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

This may happen for two reasons:

1. The component needs to work under the HTTPS protocol because the Browser Geolocation API will revoke access to the device if the connection is not secure. Make sure that you're working with HTTPS.
2. 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.