Getting started

To quickly get started with OneSDK on a Web app, please do the following steps.

How it works

The user onboarding flow works as follows:

1. The user navigates to your registration page.
2. Before serving the front-end, your server communicates with our server to create a temporary session
3. Your server passes the session object to your front-end page.
4. Your page initializes OneSDK using the session object.
5. OneSDK handles the collection and process of user details.
6. You onboard the individual using OneSDK's submit() method.

Step 1: Create a session

Obtain a session on your back-end and forward it to your front-end web page.

Construct the API credentials

1. Serialize your FrankieOne API credentials to a string using ':' as a separator.
2. Encode the resulting string using Base64 encoding.

Run the following command:

echo -n 'CUSTOMER_ID:API_KEY' | openssl base64

const base64EncodedCredentials = Buffer.from(`${CUSTOMER_ID}:${API_KEY}`).toString("base64");

If you have a child account with FrankieOne, modify the above command to the following:

echo -n 'CUSTOMER_ID:CUSTOMER_CHILD_ID:API_KEY' | openssl base64

Obtain a temporary session token

Send a POST request to the /machine-sessions endpoint of our Backend for Frontend server (BFF). The appropriate URL for BFF depends on the environment you're integrating with:

📘

Different Base URL

The base URL for the /machine-sessions endpoint is different to the server API.

Pass the encoded credential in the Authorization request header using machine as the scheme:

Authorization: machine YOUR_ENCODED_CREDENTIAL

Include the following parameters in the body of the request:

The following example creates a session object for a user using a unique customer reference:

ENCODED_CREDENTIAL=$(echo -ne "$YOUR_CUSTOMER_ID:$API_KEY" | base64);

curl https://backend.demo.frankiefinancial.io/auth/v2/machine-session \
  -X POST \
  -H "Authorization: machine $ENCODED_CREDENTIAL"
  -H 'Content-Type: application/json' \
  -d '{
    "permissions": {
      "preset": "one-sdk",
      "reference": "YOUR_UNIQUE_CUSTOMER_REF",
    }
  }';

const sessionObject = fetch(`${FRANKIE_BFF_URL}/auth/v2/machine-session`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    authorization: "machine " + Buffer.from(`${CUSTOMER_ID}:${CUSTOMER_CHILD_ID}:${API_KEY}`).toString("base64"),
  },
  body: JSON.stringify({
    permissions: {
      preset: "one-sdk",
      reference: "YOUR_UNIQUE_CUSTOMER_REF",
    },
  }),
}).then((response) => response.json());

🚧

Keep your credentials confidential

Do not publish your credentials to your front-end. They should remain accessible only from your server.

Sample response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Pre-fill applicant data

If you use an existing reference or entityId when creating session object, OneSDK will retrieve the existing data and pre-fill the applicant, and new information captured by the user will be updated to the same entity:

//using existing entityId
permissions: {
  preset: "one-sdk",
    entityId: "YOUR_ENTITY_ID",
}

//using existing reference
permissions: {
  preset: "one-sdk",
    reference: "YOUR_EXISTING_REF",
}

Step 2: Set up OneSDK

Use OneSDK to onboard an individual into your application.

Install the SDK

We recommend installing OneSDK via a

Embed script

The current version is v1.2-beta

<script src="https://assets.frankiefinancial.io/one-sdk/v1.2-beta/oneSdk.umd.js"></script>

NPM Module

npm install @frankieone/one-sdk

Import the SDK into your application:

import OneSdk from '@frankieone/one-sdk'

If you install OneSDK as an npm package, you are responsible for updating the version in your package.json file to ensure you always have the most up-to-date version.

Create a configuration object

Create an object for the global configuration of your SDK integration. This section shows the required and recommended parameters.

Sample configuration:

const configuration = {
  session: sessionObject,
};

Pass the entire object returned from the response of the /machine-sessions endpoint as the value for the session parameter. Do not extract the token or any other field from the response.

For example, your code may look like this:

<?php $sessionResponse = createFrankieSession(); ?>
<script>
  const session = JSON.parse('<?php echo json_encode($sessionResponse) ?>'); // session is the object { token: "...." }
  const oneSdk = await OneSdk({ session });
</script>

<script>
  {% set sessionObject = await createFrankieSession(); %}

  const sessionObject = JSON.parse("{{ sessionObject | json_encode | raw }}"); // session is the object { token: "...." }
  const oneSdk = await OneSdk({ session: sessionObject });
</script>

Initialize the OneSdk object

Create an instance of OneSdk using the configuration object you created.

The OneSDK function returns a promise, which can be await-ed in JavaScript ES2017's await.

const oneSdk = await OneSdk(configuration);

Otherwise, you can use Javascript's Promise API.

OneSdk(configuration).then((oneSdk) => {
  // The oneSDK instance is ready to use...
});

Step 3: Verify document details via OCR

Use the OCR Component provided by OneSDK to verify document details.

Create the OCR Component

Create an instance of the OCR Component by passing 'ocr' in component(type).

const ocr = oneSdk.component("ocr");

Obtain results

Listen to the results event to get notified when the OCR extracted results are available.

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) {
  } else {
  }
});

Handle errors

Listen to the error event to handle any errors from the OCR component. For example, the supplied image may be unprocessable.

ocr.on("error", (error) => {
  console.error(error.message);
});

Start the document capture flow

Finally, start the document capture flow by mounting the OCR component.

ocr.mount("#<countainer>")

Step 5: Verify biometrics

Use the Biometrics Component provided by OneSDK to verify the user's facial image/video.

You may skip this step if biometrics is not required in your onboarding flow.

Create the container element for the Biometrics component

Create a DOM container element on your onboarding web page where you want the component to be rendered. Make sure to give the container element a descriptive ID. The container element for Biometrics and OCR components can be the same.

For example:

<div id="biometrics-container"></div>

If you are using JavaScript frameworks such as Vue or React, make sure that you use references instead of selectors and that you don't re-render the DOM element.

Create the Biometrics component

Create an instance of the Biometrics component by passing 'biometrics' in component(type, options?).

const biometrics = oneSdk.component("biometrics");

Obtain results

Listen to the results event to get notified when biometrics results are available.

biometrics.on("results", ({ checkStatus, processing }) => {
  // Decide whether to proceed to the next stage of the onboarding process
  // depending on whether biometrics verification was successful.
  if (processing) {
  } else {
  }
});

Handle errors

Handle detection failed events

When the biometrics component fails to detect the user, it will emit a detection_failed event.

You can re-attempt another capture by mounting the component again upon receiving the detection_failed event.

biometrics.on("detection_failed", (error) => {
  console.error(error);

  if (retriesAttempted < 3) {
    biometrics.mount("#biometrics-container");
  }
});

Listen to the error event to handle any other errors.

biometrics.on("error", ({ message, payload }) => {
  console.error(message);
});

Start the biometrics flow

Mount the component

Finally, start the facial capture flow by mounting the component in your container element.

biometrics.mount("#biometrics-container");

Get notified when the capture feed is ready

The component may take a moment to initialize and display the image/video capture feed. During this time you can optionally display your own loading state. Listen to the ready event to know when the biometrics capture feed is ready to use.

biometrics.on("ready", () => {
  // If you provided your own loading state it can now be hidden.
  loadingElement.remove();
});

Step 6: Submit information

Access the Individual object to represent the person being onboarded.

const individual = oneSdk.individual();

Make sure that the user consent has been added and then submit the information to verify the individual according to your recipe.

individual.addConsent();
individual.submit({
  verify: true,
});