trully-sdk-react-2 v3.1.2

TrullyWebSDK

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.

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.

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

Example

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

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

Steps Table

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.

Example

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

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

Actions Table

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.

Example

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

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

Process Table

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.

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

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.

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

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.

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

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.

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.

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

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.

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.

processParam key

Example

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

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

devOptions key

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.

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

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

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.