npm.io
1.11.3 • Published 2 years ago

@trully/true-deepfake-detection

Licence
MIT
Version
1.11.3
Deps
5
Size
89 kB
Vulns
1
Weekly
0
DeprecatedThis package is deprecated

TrueDeepfakeDetection

TrueDeepfakeDetection is a liveness validator especially equip to detect deepfake fraud.

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

Table of Contents

  1. Install
  2. Add styles
  3. How to use
  4. Tracking process
  5. Combine with other Decision Maker analysis
  6. Personalize
    1. Change images
    2. Change videos
    3. Change texts
    4. Change styles
  7. Add it to Next.js
    1. Next.js App Router System
      1. Add styles
      2. Creating a client-side component
      3. Import the client-side component
    2. Next.js Page Router System
      1. Add styles
      2. Creating a component
      3. Dynamically import the component
  8. Data handling
    1. handleData
    2. handleError
  9. Full Example
  10. Known issues

Install

npm i @trully/true-deepfake-detection

Add styles

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

import "../node_modules/@trully/true-deepfake-detection/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 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
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.
user_id String. Will match the response you get with the user completing the process
Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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 TrueDeepfakeDetection 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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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.
Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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
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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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
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
cameraDeniedImage https://trully-api-documentation.s3.amazonaws.com/trully-sdk/cameraDenied-1.svg
cameraPermissions https://trully-api-documentation.s3.amazonaws.com/trully-sdk/ModalWeb.svg
rotate https://trully-api-documentation.s3.amazonaws.com/trully-sdk/rotate.svg
iconError https://trully-api-documentation.s3.amazonaws.com/trully-sdk/face_timeout.svg
poorWifiIcon https://trully-api-documentation.s3.amazonaws.com/trully-sdk/icon_coneccio%CC%81n.webp
Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  configuration={{
    // ...required keys
    images: {
      logo: "YOUR_LOGO_PATH",
      lightIcon: "YOUR__ICON_PATH",
      crossIcon: "YOUR__ICON_PATH",
      iconCheck: "YOUR__ICON_PATH",
      videoFallback: "YOUR_IMAGE_PATH",
      rotate: "YOUR_IMAGE_PATH",
      iconError: "YOUR_IMAGE_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
livenessVideo https://trully-api-documentation.s3.amazonaws.com/trully-sdk/LivenessVideo.webm
Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  configuration={{
    // ...required keys
    videos: {
      livenessVideo: "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, warning 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
cameraPermissions This page will let the user know we will be asking for permission to use the camera
retry This page will appear whenever it is necessary to repeat the process
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. Ahora toma un video selfie
warning String. La siguiente verificación contiene luces intermitentes que podrían afectar a personas con fotosensibilidad
btnText String. Tomar video
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
retry
Key Description
title String. Inténtalo de nuevo
btnText String. Reintentar
exit
Key Description
title String. ¡Gracias!
subtitle String. Tu información fue recibida con éxito
Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  configuration={{
    // ...required keys
    texts: {
      appIntro: {
        title: "YOUR_TEXT",
        warning: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      cameraPermissions: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      retry: {
        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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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/true-deepfake-detection/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/true-deepfake-detection/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>
  );
}

TrueDeepfakeDetection 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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

const Trully = () => {
  return (
    <TrueDeepfakeDetection
      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;
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/true-deepfake-detection/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/true-deepfake-detection/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 TrueDeepfakeDetection component

Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection-next12";

const Trully = () => {
  return (
    <TrueDeepfakeDetection
      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

TrueDeepfakeDetection 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
isAlive Boolean. If true, the video is real
selfie Base64 string. An image taken during the analysis
user_id String. The user_id you passed in configuration
tag String. The tag from the process. Automatically generated when you didn't pass one through configuration prop
sessionId String. The id from the valid analysis.
DMResponse You'll find more details in Decision Maker API Docs
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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

<TrueDeepfakeDetection
  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?
    },
    webhook: "VALID_WEBHOOK_URL",
  }}
/>;
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
Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

const handleData = (response) => {
  console.log("Response - isAlive", response.isAlive);
  console.log("Response - selfie", response.selfie);
  console.log("Response - userId", response.userId);
  console.log("Response - tag", response.tag);
  console.log("Response - sessionId", response.sessionId);
  console.log("Response - DM", response.DMResponse);
};

<TrueDeepfakeDetection
  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?
    },
  }}
/>;

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_SESSION_ID HTTP error getting sessionId.
GETTING_CREDENTIALS HTTP error authenticating session.
GETTING_LIVENESS HTTP error processing image.
GETTING_DM_RESPONSE HTTP error getting Decision Maker response.
Example
import { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

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

<TrueDeepfakeDetection
  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 { TrueDeepfakeDetection } from "@trully/true-deepfake-detection";

const handleData = (response) => {
  console.log("Response - isAlive", response.isAlive);
  console.log("Response - selfie", response.selfie);
  console.log("Response - userId", response.userId);
  console.log("Response - tag", response.tag);
  console.log("Response - sessionId", response.sessionId);
  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);
};

<TrueDeepfakeDetection
  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",
      rotate: "YOUR_IMAGE_PATH",
      iconError: "YOUR_IMAGE_PATH",
    },
    videos: {
      livenessVideo: "YOUR_VIDEO_PATH",
    },
    texts: {
      appIntro: {
        title: "YOUR_TEXT",
        warning: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      cameraPermissions: {
        title: "YOUR_TEXT",
        subtitle: "YOUR_TEXT",
        btnText: "YOUR_TEXT",
      },
      retry: {
        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:

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