Getting started with Smart UI

Learn how to integrate the Smart UI widget in your application.

Smart UI allows you to connect your customers directly with FrankieOne’s identity verification and validation services.

Your customer provides their minimum basic information, FrankieOne will verify their identity according to your configured rules, and signal back to you that the customer is ready to be onboarded -- all without the customer leaving the webpage.

How it works

The user onboarding flow with Smart UI works as follows:

  1. The user navigates to your registration page.
  2. Your server uses your API credentials to create a Smart UI session token.
  3. Your webpage initializes Smart UI using the session token from the server.
  4. Smart UI handles the collection of the user's details, document information and, optionally, biometrics.
  5. FrankieOne verifies the user's details and returns the results to your application.
Simple Flow SequenceSimple Flow Sequence

Simple Flow Sequence

Before you begin

You will need the following to connect to the FrankieOne API,

  • Customer ID
  • Customer Child ID (Optional)
  • API key

If you do not have any yet get in touch with our sales team.

You must host Smart UI on your own webserver. FrankieOne does not provide a hosted version yet.

Step 1: Create a session

Obtain a session on your backend and forward it to your frontend web page.

Construct the API credential

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

If you are using a macOS or Linux operating system, run the following command in a terminal:

echo -n 'CUSTOMER_ID:API_KEY' | openssl 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 /auth/v2/machine-sessions endpoint.

Base URL

Use one of the following base URLs depending on the environment you are targeting. Note, Smart UI uses different URLs to FrankieOne's server-side APIs.

Authorization header

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

Authorization: machine YOUR_ENCODED_CREDENTIAL

Request body

Include the following parameters in the body of the request:

Parameter nameRequiredDescription
referrerRequiredA referrer URL pattern used to verify the webpage that Smart UI is hosted on. See CSP and Smart UI Security Recommendations.
permissionsRequiredA hash containing preset and reference.
permissions.presetRequiredThe string "smart-ui".
permissions.referenceRequiredA string containing your customer reference for the individual being onboarded.

📘

️ Note

Applicant Reference with whitespace characters are not supported by the Smart UI and will be rejected. Let us know if this will prevent you from integrating.

Request example

The following example creates a session object for a user in the Demo environment:

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": "smart-ui",
      "reference": "YOUR_CUSTOMER_REFERENCE"
    }
  }';

🚧

Keep Your Secrets Safe

Your Customer ID and API Key are both secret information and should not be included in the frontend code. For that reason, make sure to call the /auth/v2/machine-session endpoint from your backend server.

The /auth/v2/machine-session endpoint will respond with a 200 HTTP status code, indicating the session was created successfully.

The response body will include a configuration object that is used by Smart UI to customize its behavior. The configuration object includes a dictionary of strings that might seem like error messages, but they aren't. You may ignore anything found in the successful response body.

Read the token from the response

The successful response will contain a response header named token that contains the authentication token required to configure Smart UI. This token is valid for only one hour, and within the Smart UI, it is refreshed for another hour on each successful call to the backend server.

The following example reads the token from the response:

const res = await fetch('https://backend.demo.frankiefinancial.io/auth/v2/machine-session', {
  method: 'post',
  headers: {
    'Content-Type': 'application-json',
    'Authorization': 'machine ENCODED_CREDENTIAL'
  },
  body: JSON.stringify({
    permissions: {
      preset: "smart-ui",
      reference: "YOUR_CUSTOMER_REFERENCE"
    }
  })
})

const smartUIAuthToken = res.headers.get('token')

Make sure to access the header by name token rather an numeric index, as the order in which the response headers are returned is not guaranteed to be the same for each request.

Step 2: Set up Smart UI

Install the Smart UI widget

Include the Smart UI script tag within the <head /> section of your HTML page.

<!-- Production version (minified) -->
<script src="https://assets.frankiefinancial.io/onboarding/v4/ff-onboarding-widget.umd.min.js"></script>

<!-- Development version (non-minified) -->
<script src="https://assets.frankiefinancial.io/onboarding/v4/ff-onboarding-widget.umd.js"></script>

Add the widget to your page

Smart UI is implemented as a Web Component. This means it is a custom element whose internal structure and styles are isolated from your page.

Add the custom <ff-onboarding-widget> element to your page where you would like it to be rendered:

<div>
  <ff-onboarding-widget></ff-onboarding-widget>
<div>

Create initialization object

Create an object to initialize your Smart UI integration. This section shows the required and recommended parameters.

Parameter nameRequiredDescription
ffTokenRequiredThe token you obtained from the /auth/v2/machine-session endpoint.
applicantReferenceA string containing your customer reference for the customer being onboarded. This is used to identify the customer whose information should be pre-filled. Once the customer completes onboarding this value can be used to retrieve the customer's details via the API or the Portal.
widthA string defining the width of Smart UI. See Customizing the appearance of Smart UI.
heightA string defining the height of Smart UI. See Customizing the appearance of Smart UI.
configA hash containing onboarding configuration for Smart UI. See [Smart UI configuration reference](Smart U).

View the [Smart UI configuration reference](https://apidocs.frankiefinancial.com/docs/smart-ui-configuration\) for the full list of available parameters.

Sample initialization object:

const initializationParameters = {
  ffToken: "TOKEN_GENERATED_FROM_STEP_1"
  width: "full",
  height: "auto",
  config: {
    frankieBackendUrl: "https://backend.demo.frankiefinancial.io",
    successScreen: {
      ctaUrl: "https://mycompany.com/onboarding-success"
    },
    failureScreen: {
      ctaUrl: "https://mycompany.com/onboarding-failed"
    }
  }
};

Initialize the Smart UI widget

Initialize Smart UI by calling the initialiseOnboardingWidget method on the global frankieFinancial object.

The initialization needs to be done after the page is mounted/ready, so the HTML elements are available. The example below shows how to initialize Smart UI within the onload event.

<html>
  <head>
    <!-- viewport meta is recommended for responsive pages -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0,user-scalable=0"/>
    <!-- install your font, if you don't already have it -->
    <link href="https://fonts.googleapis.com/css2?family=Roboto:ital,[email protected],300;0,400;0,700;1,300;1,400&display=swap" rel="stylesheet">
    <script src="https://assets.frankiefinancial.io/onboarding/v4/ff-onboarding-widget.umd.min.js"></script>
    <script>
      function handleLoad() {
        frankieFinancial.initialiseOnboardingWidget({
          ffToken: "TOKEN_GENERATED_FROM_STEP_1",
          applicantReference: "YOUR_CUSTOMER_REFERENCE",
          width: "AUTO",
          height: "AUTO",
          config: {
            frankeiBackendUrl: "https://backend.demo.frankiefinancial.io",
            successScreen: {
              ctaUrl: "javascript:alert('Callback for successful onboarding')"
            },
            failureScreen: {
              ctaUrl: "javascript:alert('Callback for failed onboarding')"
            },
            documentTypes: ["DRIVERS_LICENCE", "PASSPORT", 'NATIONAL_HEALTH_ID'],
            acceptedCountries: ["AUS", "NZL"],
            ageRange: [18, 125],
            organisationName: "My Organisation",
          }
        });
      }
      var body = document.getElementsByTagName("body")[0];
    </script>
  </head>
  <body onload="handleLoad();">
    <ff-onboarding-widget></ff-onboarding-widget>
  </body>
</html>

Step 3: Test and go live

When you're ready to use the API in production mode using live data, you will need a Production API Key. To get the API Key, please contact your onboarding team representative.

Next steps

Now that have have integrated Smart UI end-to-end, you may wish to: