Smart UI Configuration

The function initializeOnboardingWidget takes the following object

  ffToken: string,
  applicantReference: string
  config?: ConfigurationParameters
  height?: string
  width?: string


  1. ffToken is the token retrieved in Getting Started
  2. applicantReference is the reference string to be assigned to the applicant data generated by the Smart UI. This is the same applicantReference passed when creating a token. Found hereGetting Started -> Initialise-Smart-UI-in-the-frontend
  3. config is the configuration object defined with the fields described below.
  4. height and width take one of the following values:
    1. pixels string, such as “600px”. With fixed dimensions, the Smart UI fits predictably in your layout.
    2. percent string, such as “80%”. The Smart UI will be sized based on it’s parent. This allows for more flexibility than what’s provided by the Smart UI by default. Making the Smart UI 100% width and height of a div allows you to produce more advanced layouts using floats and flexbox
    3. the string “FULL”. The Smart UI will be sized full screen, mimicking the dimensions from window.innerWidth and window.innerHeight. This is useful if you want the Smart UI to look like a mobile App within your website, or to render it inside your own app in a web view.
    4. the string “AUTO”. Only available on v3.6 and later. This will mimic the default behaviour of HTML block elements, where height auto will fit to its contents and width auto will take 100% of the parent's width. This value inverts the logic of using specific sizes for the borders of the Smart UI and instead allowing the Smart UI height to adapt to its contents.
    5. Check Custom Styling for more details

Configuration Parameters



Default Value





If your organisation has a special Frankie Backend URL, provide it here. If that's not applicable in your case, skip this configuration.



Additional support for custom document type from v3.5

{ "type": "CUSTOM_NEW_DOC_TYPE_1", "label": "New document label", "subtitle": "(takes longer to process)", "customEventPayload": { "docType": "CUSTOM_NEW_DOC_TYPE_1", "userFlow": "SIGNUP_FLOW_3" } }]


array of accepted document types

v3.5 Update

For users using the v3.5 and above versions, you can now also pass unknown/custom document types to be included as buttons in the document selection page. When clicking them, Instead of displaying any page, an event DOC_TYPE_SELECTED is dispatched to window.

Each “unknown” documentTypes must start with CUSTOM_.

The customEventPayload object can be defined to contain any static data they you may need to be sent as part of the event payload.


boolean | {
htmlContent: string | false | null ,
ctaText: boolean | string


To hide the welcome screen, simply make welcomeScreen === false.

htmlContent is the html string to be displayed in the welcome screen. It accepts style tags,but script tags will be stripped out.




The number of times the applicant will be allowed to review personal details and try. New documents before failing their application


boolean | {
ctaUrl: string | null ,
ctaText: string

ctaUrl= null
ctaText= 'Continue to My Account'

ctaUrl is the url to redirect after applicant clicks button in the successful page
by default (ctaUrl === null) the Smart UI only displays a successful message
you can always include the applicant-reference as a query parameter to continue any remaining onboarding steps that might come after the identity verification.
As any traditional html link, ctaUrl can also include a call to a global javascript function, "javascript:ffSuccess('string-with-applicant-reference')"


boolean | {
ctaUrl: string | null ,
ctaText: string

ctaUrl= null
ctaText= 'Contact Us'

ctaUrl is the url to redirect after applicant clicks button when onboarding has failed
by default the Smart UI only displays a failure message
you can always include the applicant-reference as a query parameter to provide any further steps.
As any traditional html link, ctaUrl can also include a call to a global javascript function, "javascript:ffFailure('string-with-applicant-reference')"


false | {
ctaActions: { text: string, url: string }[],

This page is shown whenever the reason for a failure cannot be resolved on the widget.
In that case it will be necessary to resolve the issue manually, either on the portal or via direct API
such situation would happen if the user was flagged with a PEP result
the configuration in this case accepts multiple cta actions with text and url.
It's recommended to use no more than three actions




If the progress bar should be rendered




A "profile" is a collection or recipe of rules and checks that you wish to perform on all of your customers.
As part of the onboarding process with Frankie, we'll work with you to define these.
However, the service also makes it easy to automate this and you can just use "auto" to have our rules engine work this out for you.
See Entity Profiles/ Recipes - Introduction for more


string | false


Google api key for the address auto complete. For the demo we provide our own api automatically.
Otherwise if this field is missing the Smart UI will skip the address autocomplete screen.
More information can be found in the section below.


char3[] | null


List of up to 5 char3 country codes to include in the country selects in the Addresses form. Otherwise all countries will be displayed.


[number, number]

[18, 125]

Tuple of two numeric values minimumAge and maximumAge in the exact order



Your organisation's name as displayed in the data submission consent text. Defaults to the name we have on record.


string | null


Consent text to be displayed in the review page. Defaults to null, which will display our generic consent text

I consent to the collection, use and disclosure of my personal information in accordance with ${organisationName} Privacy Policy, and consent to my personal information being disclosed to a credit reporting agency or my information being checked with the document issuer or official record holder in connection with a request to verify my identity in accordance with the AML/CTF Act;

YOU MUST confirm your consent text with FrankieOne onboarding team before you go live




When true the user will be required to include an address, when false the address pages are skipped.
When loading an existing applicant, if requestAddress is true and applicant doesn't have an address yet,
one will be included and the user will be required to input their address details. Defaults to true, including the address pages by default.




when lazyIDCheck is true, it means that the ID details will only be requested to the user if they fail KYC check using their personal details




similarly to requestAddress above, when requestID is false, the screens requesting document details are skipped to successfully use this configuration, checkProfile needs to be configured to a profile type that allowed optional IDs.
Contact our support team to help sorting this out.


boolean |
welcomeScreen: boolean | {
title: string,
content: string[],
ctaText: boolean | string,

idScanVerification: {
welcomeScreen: {
title: 'Verify your identity',
content: ["We need to collect some personal information to verify your identity before we can open your account."],
ctaText: 'Start Identity Verification',

useMobileDevice: boolean,

useLiveness: boolean,

injectedCss: string,

  • useLiveness and injectedCss works only in V3+

when idScanVerification is truthy (either a boolean true or a configuration object), we'll include the Onfido ID Verification UI at the end of the normal flow to request and check the validity of document scans using OCR.

The welcome screen for idScanVerification is the introduction screen belonging to the onfido UI (third party).
You may use this to explain in your own terms that they will be required to supply identity documents and a photo of their face
If no configuration object is provided, you must pass the boolean true, otherwise by default there will be no id scan verification.
In that case, the default welcome screen is displayed. You can find a screenshot of that screen in the section ID Validation Using Onfido .

useLiveness enables you to take a video instead of selfie in the Facial ID capture process.

useMobileDevice enforces the user to use a mobile device in the IDV process if there are on a desktop app to reduce chances of fraud.

injectedCss allows you to override and customize the styling in the Onfido SDK.


{[key: string] } | null

The keys can be found Here.

An object containing the keys you want to customise and add in custom text to specific screens.
They can be passed as a nested object or as a string using the dot notation for nested values.




To disable third party analytics, which the Smart UI uses for analytical purposes

(v3 and above)



Css to be used to customise the Smart UI. See Migrating v2 to v3

(v3 and above)



ID attribute assigned to either the style or link tag with css to be injected into the Smart UI. Either use this, or the above injectedCss. See Migrating v2 to v3

To Obtain a Google API Key

Please visit the Google Developer Console.
The API's that you have to enable in your Google API Manager Dashboard are Google Maps Geocoding API, Google Places API Web Service and Google Maps Javascript API.

You should also lock these keys to your domain as well for added security.

Did this page help you?