Getting started with Smart UI

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.

Supported Countries

Below is a list of countries that are fully supported by the smart UI.

Australia
New Zealand
Indonesia
Thailand
Singapore Manual Input (not Singpass)
Generic International Passport
Generic International National ID

Future supported countries

USA
UK
All Others

Step 1: Create a session

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

Construct the API credential

Serialize your FrankieOne API credentials to a string using ':' as a separator.
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-session 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.

Environment	Base URL
Demo	https://backend.demo.frankiefinancial.io
UAT	https://backend.kycaml.uat.frankiefinancial.io
Production	https://backend.kycaml.frankiefinancial.io

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 name	Required	Description
`referrer`	Required	A referrer URL pattern used to verify the webpage that Smart UI is hosted on. See CSP and Smart UI Security Recommendations.
`permissions`	Required	A hash containing `preset` and `reference`.
`permissions.preset`	Required	The string `"smart-ui"`.
`permissions.reference`	Required*	A string containing your customer reference for the individual being onboarded. Only required if entityId isn't provided
`permissions.entityId`	Required*	A string containing the entity id if the entity exists previously. Only required if reference isn't provided.

* Only provide either reference or entityId, not both.

📘
️ 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 name	Required	Description
ffToken	Required	The token you obtained from the `/auth/v2/machine-session` endpoint.
applicantReference		A 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.
width		A string defining the width of Smart UI. See Customizing the appearance of Smart UI.
height		A string defining the height of Smart UI. See Customizing the appearance of Smart UI.
config		A hash containing onboarding configuration for Smart UI. See Smart UI configuration reference.

View the Smart UI configuration reference 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,wght@0,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: {
            frankieBackendUrl: "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:

Getting started with Smart UI

Before you begin

Step 1: Create a session

Construct the API credential

Obtain a temporary session token

Base URL

Authorization header

Request body

📘
️ Note

Request example

🚧
Keep Your Secrets Safe

Read the token from the response

Step 2: Set up Smart UI

Install the Smart UI widget

Add the widget to your page

Create initialization object

Initialize the Smart UI widget

Step 3: Test and go live

Next steps

Before you begin

Step 1: Create a session

Construct the API credential

Obtain a temporary session token

Base URL

Authorization header

Request body

📘️ Note

Request example

🚧Keep Your Secrets Safe

Read the token from the response

Step 2: Set up Smart UI

Install the Smart UI widget

Add the widget to your page

Create initialization object

Initialize the Smart UI widget

Step 3: Test and go live

Next steps

📘
️ Note

🚧
Keep Your Secrets Safe