OneSDK with Onfido Motion

Get the basics on using Onfido Motion with FrankieOne OneSDK

Suggest Edits

OneSDK works with Onfido Motion to capture document and face details via OCR and Biometrics components.

Integration methods

There are two integration methods that you can use for Onfido with OneSDK:

  • IDV flow
  • OCR and Biometrics

The following sections provide further details for implementing each integration method.

Integrating OneSDK for IDV flow

To integrate with OneSDK for IDV flow using Onfido, please follow the standard integration of OneSDK for IDV flow.

🚧

Recommended devices

Since most desktop computers do not have high resolution built-in cameras, we recommend end users run the IDV flow on mobile devices.

Sample code for IDV flow

<html lang="en">
  <head> 
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>oneSdk onboarding</title>
   <script src="https://assets.frankiefinancial.io/one-sdk/v1.2-beta/oneSdk.umd.js"></script>

  <script>
  async function startOneSdk() {
    // const oneSdk = await OneSdk({ mode: "dummy" });
    const CUSTOMER_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx-xxxx"
    const CUSTOMER_CHILD_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    const API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

    const tokenResultRaw = await fetch("https://backend.latest.frankiefinancial.io/auth/v2/machine-session", {
            method: "POST",
            headers: {
                "authorization": "machine " + btoa(`${CUSTOMER_ID}:${CUSTOMER_CHILD_ID}:${API_KEY}`),
                "Content-Type": "application/json"
            },
            body: JSON.stringify({
                permissions: {
                    "preset": "one-sdk",
                    "reference": "<YOUR_UNIQUE_CUSTOMER_REF>"
                }
            })
        });

    const tokenResult = await tokenResultRaw.json();

    const sessionObjectFromBackend = tokenResult;

    const oneSdk = await OneSdk({
            session: sessionObjectFromBackend,
            //isPreloaded: false,
            mode: "development",
            recipe: {
              ocr: {
                provider: {
                  name: "onfido"
                }
              },
              biometrics: {
                provider: {
                  name: "onfido"
                }
              },
              idv: {
                provider: {
                  name: "onfido"
                }
              }
            }
          });

    const oneSdkIndividual = oneSdk.individual();
    oneSdkIndividual.addConsent("general");
    oneSdkIndividual.addConsent("docs");
    oneSdkIndividual.addConsent("creditheader");
    await oneSdkIndividual.submit();

    const idv = oneSdk.flow("idv");

    idv.on("results", async ({checkStatus, document, entityId}) => {
        if (checkStatus) {
          console.log("results succesfful");
          console.log(checkStatus);
          console.log(document);
          console.log(entityId);
        } else {
          console.log("no data returned");
        }
    });

    idv.on("error", ({ message, payload }) => {
      console.log("received error");
      console.log(message, payload);
    });


    idv.on("detection_complete", (message) => {
      console.log("capture finished");
      console.log(message);
    });

    idv.mount("#idv-el");

  }

</script>

<style>
  
</style>

</head>
<body style="background-color: white" onload="startOneSdk()">
  <div id="idv-el" style="position:fixed;top: 0;left: 0; width: 100%; height: 100%;"></div>
</body>

Integrating OneSDK for OCR and biometrics

To integrate with Onfido Motion in OneSDK, please follow the standard integration here: OneSDK for OCR and biometrics. Your customer account should be configured to use Onfido as the IDV vendor and is part of the applied recipe.

📘

Default liveness check and fallback options.

Onfido Motion is set as the default liveness check. If the user's device doesn't support Onfido Motion, the user will get an error in the browser.

To allow end users to continue with the process, we can configure Onfido Motion in OneSDK to fall back to either liveness video or selfie when the user's device doesn't support Onfido Motion.

OCR Headed and headless

You can use the OCR component with a headed or headless integration. Visit Handling image capture for more details.

Synchronous or asynchronous

Onfido IDV flow can be either synchronous or asynchronous. When it's synchronous, the COMPLETE event will be returned after a successful IDV flow on OneSDK.

When it's an asynchronous, the CHECK_PROCESSING event will be returned after a successful IDV flow. This indicates that OneSDK is done running the IDV flow. A webhook needs to be configured for clients to receive the results of IDV.

How to use it in your onboarding flow

There are two main use cases you can use the above integration methods in your onboarding flow:

  • Onfido - Biometrics first
  • Onfido with an existing entity

These two use cases are discussed in the following section.

Onfido - Biometrics first

The Biometrics-first approach using Onfido doesn't require an existing entity beforehand. In this use case, you can start the flow with OCR/Biometrics first to pre-fill the user details. You don't need to have an entity, instead, the FrankieOne service creates a new entity and fills it with the OCR-extracted results.

📘

A security note on the machine token

To initialise OneSDK, you need to generate a machine token on your backend for security reasons, and then pass it through the client-side application. You should not generate the machine token in your front-end application.

In the following section, the machine token is generated in the example, for simplicity.

Sample HTML to run Onfido with Biometrics first

Below is a sample HTML code for running Onfido with Biometrics first.

<html lang="en">
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1.0" charset="UTF-8"/>
  <title>oneSdk onboarding</title>
  <script src="https://assets.frankiefinancial.io/one-sdk/v1.2-beta/oneSdk.umd.js"></script>
  <script>
    async function startOneSdk() {
      const CUSTOMER_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
      const API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
      const ENTITY_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

      const tokenResultRaw = await fetch('https://backend.latest.frankiefinancial.io/auth/v2/machine-session', {
        method: 'POST',
        headers: {
          authorization: 'machine ' + btoa(`${CUSTOMER_ID}:${API_KEY}`),
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          permissions: {
            preset: 'one-sdk',
            reference: "your_unique_customer_refrence"
          },
        }),
      });

      const sessionObjectFromBackend = await tokenResultRaw.json();

      const oneSdk = await OneSdk({ session: sessionObjectFromBackend, telemetry: false });
      oneSdk.on('*', console.log);

      const oneSdkIndividual = oneSdk.individual();
      oneSdkIndividual.on('*', console.log);

      // Display and update name
      const name = oneSdkIndividual.access('name');
      const { givenName, familyName } = name.getValue();
      const newGivenName = prompt('Confirm given name', givenName);
      name.setValue({ givenName: newGivenName, familyName });
      oneSdkIndividual.addConsent("general");
      oneSdkIndividual.addConsent("docs");
      oneSdkIndividual.addConsent("creditheader");
      // Submit changes
      oneSdkIndividual.submit();

      // Setup OCR and Biometrics
      const mountElement = document.getElementById('biometrics-container');
      const ocr = oneSdk.component('ocr');
      const biometrics = oneSdk.component('biometrics');

      // On input required, try running the OCR component again
      ocr.on('input_required', () => ocr.mount(ocr, mountElement));
      ocr.on('error', console.error);
      biometrics.on('error', console.error);

      let error = false;
      biometrics.on('detection_failed', () => (error = true));
      biometrics.on('session_closed', () => {
        // If the session was closed due to an error, try running the biometrics component again.
        if (error) biometrics.mount('#biometrics-container');
        error = false;
      });

      ocr.on('results', ({ document }) => {
        // Present the details of the document that were detected from the uploaded image or images.
        // Decide whether to proceed to the next stage of the onboarding process
        // depending on whether document verification was successful.
        if (document) {
          console.log(document);
          console.log(document.ocrResult.dateOfBirth);

          biometrics.mount('#biometrics-container');
        } else {
          console.log('No document returned');
        }
      });

      biometrics.on('processing', () => alert('We will get back to you with results soon'));
      biometrics.on('results', (result) => {
        // Decide whether to proceed to the next stage of the onboarding process
        // depending on whether biometrics verification was successful.
        console.log(result);
      });

      ocr.mount("#biometrics-container");
    }
  </script>
</head>
<body style="background-color: blue" onload="startOneSdk()">
  <div id="biometrics-container"></div>
</body>
</html>

Onfido with an existing entity

In this use case, you can capture some information manually from the user to create an entity, then run OCR/Biometrics on the entity. To use OneSDK with an existing entity, you can use the same sample code but instead of using customer reference, pass an existing entityID to create a session:

const tokenResultRaw = await fetch('https://backend.latest.frankiefinancial.io/auth/v2/machine-session', {
        method: 'POST',
        headers: {
          authorization: 'machine ' + btoa(`${CUSTOMER_ID}:${API_KEY}`),
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          permissions: {
            preset: 'one-sdk',
            entityId: ENTITY_ID
          },
        }),
      });

Updated 3 months ago