Web App Step-by-step Guide

How it works

The user onboarding flow works as follows:

User navigates to your registration page.
Before serving the front-end, your server communicates with Frankie’s server to create a temporary session.
Your server passes the session object to your front-end for it to initialize OneSDK using the session object.
OneSDK modules are activated to handle the collection and processing of identity verification data.
You verify the individual using OneSDK’s submit() method.

Create a session and forward it to your front-end

Construct the API credentials

Serialize your FrankieOne API credentials to a string using the ’:’ separator.
Encode the resulting string using Base64 encoding.

Run the following command:

Shell

echo -n 'CUSTOMER_ID:API_KEY' | openssl base64

JavaScript

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-session endpoint of our Backend for Frontend server (BFF). The appropriate URL for BFF depends on the environment you’re integrating with:

Environment	URL
Demo	`<https://backend.demo.frankiefinancial.io/auth/v1/machine-session>`
UAT	`<https://backend.kycaml.uat.frankiefinancial.io/auth/v1/machine-session>`
Production	`<https://backend.kycaml.frankiefinancial.io/auth/v1/machine-session>`

Different Base URL”>

The base URL for the /machine-session 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_CREDENTIALInclude the following parameters in the body of the request:| Parameter name | Required | Description |

Parameter	Required	Description
`permissions`	Required	A hash containing `preset` and either `entityId` or `reference`.
`permissions.preset`	Required	The string `'one-sdk'`.
`permissions.reference`	Required*	A string containing a unique customer reference for the individual being verified. If a new reference is used, once the individual completes verification this value can be used to retrieve the details via the API or the Portal. If an existing reference is used, the existing data will be retrieved and the new information captured by users will be attached to the same entity.
`permissions.entityId`	Required*	A string containing the entity ID for the individual being verified.

* Either entityId or reference is required, but not both.The following example creates a session object for a user using a unique customer reference:

Shell

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

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

JavaScript

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());

Don’t publish your credentials to your front-end. They should remain accessible only from your server.

Sample response:

JSON

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

Pre-fill applicant data

If you use an existing reference or entityId when creating a 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:

JavaScript

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

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

Set up OneSDK

Use OneSDK to onboard an individual into your application.

Install the SDK

We recommend installing OneSDK via a <script> tag so that your webpage always receives the latest, most up-to-date version.

Embed script

The URL below will point to the latest stable v1 version. Alternatively, you can point to a specific version by swapping out the v1 URL parameter with a specific major and minor version (i.e. v1.6.1-beta).

JavaScript

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

NPM Module

We’re working on enabling other frameworks such as Next.js, Vue, and React + Webpack.

Shell

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.

Parameter name	Required	Description
`session`	Required, unless `mode` is specified as `"dummy"`.	The session object from your call to `/machine-session`.
`mode`	Optional	One of `"production"` or `"dummy"`. If this is set as `"dummy"`, then `session` doesn’t need to be specified. The default value is `"production"`.

Sample configuration:

const configuration = {
  session: sessionObject,
};

Pass the entire object returned from the response of the /machine-session endpoint as the value for the session parameter. Don’t extract the token or any other field from the response.For example, your code may look like this:

JavaScript

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

JavaScript

<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...
});

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

JavaScript

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 not be processable.

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("#<container>");

Verify biometrics

Use the Biometrics Component provided by OneSDK to verify the user’s facial image/video.You may skip this step if biometrics isn’t 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?).

JavaScript

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

Obtain results

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

JavaScript

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 <Steps 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();
});

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,
});

​How it works

​Construct the API credentials

​Obtain a temporary session token

Different Base URL”>

​Pre-fill applicant data

​Install the SDK

Embed script

NPM Module

​Create a configuration object

​Initialize the OneSDK object

​Create the OCR Component

​Obtain results

​Handle errors

​Start the document capture flow

​Create the container element for the Biometrics component

​Create the Biometrics component

​Obtain results

​Handle errors

Handle detection failed events

​Start the biometrics flow

Mount the component

​Get notified when the capture feed is ready

How it works

Construct the API credentials

Obtain a temporary session token

Pre-fill applicant data

Install the SDK

Create a configuration object

Initialize the OneSDK object

Create the OCR Component

Obtain results

Handle errors

Start the document capture flow

Create the container element for the Biometrics component

Create the Biometrics component

Obtain results

Handle errors

Start the biometrics flow

Get notified when the capture feed is ready