trully-sdk-react-2
TypeScript icon, indicating that this package has built-in type declarations

3.0.14 • Public • Published

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](#doc-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](#add-it-next) section

Install

npm i trully-sdk-react-2

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 (mandatory). These will allow you to enter your client API KEY. The component won't work with out it
handleData Callback (mandatory). These function should declare a parameter that will hold the process resulting data
handleError Callback (mandatory). These function should declare a parameter that will hold the process error
user_id String (mandatory). Will match the response you get with the user completing the process.
forceLocation* Boolean. If true, the process won't finished unless the candidate share their location
userIDIsCURP** Boolean. If you're using the CURP as user_id and want to send it to the Decision Maker mark this as true

*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

The following example shows the default values for forceLocation and userIDIsCURP keys

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

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

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

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.

Key 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

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

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

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

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

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

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: {
      termsAndConditions: "URL_TO_TERMS_AND_CONDITIONS",
      privacyPolicy: "URL_TO_PRIVACY_POLICY"
      pagesToInclude: ["form", "personal_info"],
      inputs: {
        email: false,
        phone_number: false,
        curp: false,
        address: false,
      },
      texts: {
        //Will let you change the text regarding document type to use for the process.
        //0.- INE o Pasaporte vigente. 1.- INE vigente. 2.- Pasaporte vigente
        docType: 0
      }
      styles: {
        showLogo: true,
        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",
        },
      },
    },
  }}
/>;

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

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: {
      processParam: {
        timeout: 60000,
      },
      devOptions: {
        environment: true,
        logErrors: true,
      },
    },
  }}
/>;

Add it to Next.js

⚠️ If your you're using Next.js page router, please use [this package instead](https://www.npmjs.com/package/@trully/trully-sdk-react-next12)

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.

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: (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;

Import the client-side component

Once created, import it into any page

import Trully from "./components/Trully";

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

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 un process 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: (data) => {
            const { label, reason } = data;
            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: (data) => {
              console.log(data);
              const { document_image, image } = data;
              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;

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.

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 3.0.14
    4
    • latest

Version History

Package Sidebar

Install

npm i trully-sdk-react-2

Weekly Downloads

10

Version

3.0.14

License

none

Unpacked Size

146 kB

Total Files

8

Last publish

Collaborators

  • anahiforesi
  • carl_trully