Trully-sdk-react NPM

TrullyWebSDK

Install

npm i trully-sdk-react

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 to obtain the Decision Maker data, as well as 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.

import TrullyWebSDK from "trully-sdk-react";

<TrullyWebSDK
  configuration={{
    usage: {
      apiKey: "YOUR_API_KEY",
      handleData: (data) => {
        //What should be done with the obtained data?
      },
      handleError: (error) => {
        //What should be done if there is an error retrieving the data?
      },
      //If true, the process won't finished unless the candidate share their location*
      forceLocation: true,
    },
  }}
/>;

*If the candidate chooses to use a mobile device, the access to the location will depend on the Browser App permissions

Personalize

To customize the component, add the "AppConfiguration" key to the object passed in the "configuration" prop. The "AppConfiguration" key should contain an object with the "styles" key. Neither of the keys in "styles" are required.

import TrullyWebSDK from "trully-sdk-react";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    AppConfiguration: {
      termsAndConditions: "URL_TO_TERMS_AND_CONDITIONS",
      privacyPolicy: "URL_TO_PRIVACY_POLICY",
      pagesToInclude: ["form", "personal_info", "document_reader", "liveness"],
      styles: {
        //show/hide logo
        showLogo: true,
        images: {
          logo: {
            source: "logo_image_url",
            //Default logo styles
            style: {
              width: "100%",
              maxWidth: "250px",
              minWidth: "150px",
              mobile: {
                maxWidth: "150px",
              },
            },
          },
          DatosIcon: "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",
        },
        //Default font
        font: {
          //Use this to change the font of every text.
          family: "'DM Sans', sans-serif",
          //Use this to change the font of a single type of text
          individualFamily: {
            heading1: "'DM Sans', sans-serif",
            heading2: "'DM Sans', sans-serif",
            text: "'DM Sans', sans-serif",
          },
        }
        //Default colors
        colors: {
          primary: "#475FFF",
          primary50: "#475FFF50",
          primary75: "#475FFF75",
          secondary: "#232f7f",
          disabled: "#D6A0FF",
          white: "#FFFFFF",
          black: "#000000",
          backgroundColor: "#FFFFFF",
        },
      },
    },
  }}
/>;

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.

import TrullyWebSDK from "trully-sdk-react";

<TrullyWebSDK
  configuration={{
    usage: {
      //required configuration
    },
    DocumentReader: {
      processParam: {
        //default time un milliseconds
        timeout: 60000,
      },
      devOptions: {
        //only in development
        environment: true,
        //show errors in console. Add it if you have an error to know what is happening
        logErrors: true,
      },
    },
  }}
/>;

Add it to Next.js

TrulyWebComponent is a client-side component, which means it needs to run on the client side. By default, every component created in Next.js is executed on the server side. To make sure our component runs only on the client side, we need to generate a dynamic import.

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

const Trully = () => {
  return (
    <TrullyWebSDK
      configuration={{
        usage: {
          apiKey: "YOUR_API_KEY",
          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).

const Trully = () => {
  return (
    <TrullyWebSDK
      configuration={{
        usage: {
          apiKey: "YOUR_API_KEY",
          //data - Decision Maker response and KYC data
          handleData: (data) => {
            const { data, request } = data;
            //data - Decision Maker response
            //request - KYC data
          },
          handleError: (error) => {
            //error - AJAX error
          },
        },
      }}
    />
  );
};
export default Trully;

KYC data

data: {
	//Decision Maker response,
  data: {
    //Parameters used to generate decision
    raw_data: {},
    //No Threat - low risk user. Review - medium risk user. Potential Threat - high risk user
    label: "No Threat" || "Review" || "Potential Threat",
    //Contains the reasons behind the decision
    reason: []
  }
	//KYC data
	request: {
		//location of the device from which the KYC process is done
        location: {
            lat: 0,
            lng: 0
        },
		//Selfie image
        image: "",
		//Document front image
        document_image: "",
		//IP of the device from which the KYC process is done
        ip: "",
		//Name as is written in the document
        name: "",
        metadata: {
			//Browser from which the KYC process is done
            userAgent: "",
			//Operative System of the device from which the KYC process is done
            platform: "",
			//Estimated age of the person in the Selfie
            estimatedAge: 0,
			//MRZ document code
            mrzCode: ""
			//MRZ code type
            mrzType: "",
			//Document issuing country
            issuingCountryCode: "",
			//Document number
            documentNumber: "",
			//Date of Birth as is written in the document
            DoB: "",
			//Sex as is written in the document
            sex: "",
			//Document's expiration date
            expirationDate: "",
			//Age
            age: "",
			//Nationality as is written in the document
            nationalityCode: "",
			//Document type
            documentType: "",
			//Document number check digit
            documentNumber_checkdigit: "",
			//Document number check digit validator
            documentNumber_checkdigit_validity: 0,
			//Date of Birth check digit
            DoB_checkdigit: "",
			//Date of Birth check digit validator
            DoB_checkdigit_validity: 0,
			//Expiration date check digit
            expirationDate_checkdigit: "",
			//Expiration date check digit validator
            expirationDate_checkdigit_validity: 0,
			//Final check digit
            final_checkdigit: "",
			//Final check digit validator
            final_checkdigit_validity: 0
        }
    }
}

How to use the images obtained

import { useState } from "react";

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

  return (
    <>
      <TrullyWebSDK
        configuration={{
          usage: {
            apiKey: "YOUR_API_KEY",
            handleData: (data) => {
              console.log(data);
              const { request } = data;
              setDoc(() => request.document_image);
              setSelfie(() => request.image);
            },
            handleError: (err) => {
              console.log(err);
            },
            forceLocation: true,
          },
        }}
      />
      <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:

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.

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

This may happen for two reasons:

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