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 a unique identifier such as an email address or user ID, which you assign to the applicant data generated by the Smart UI. Smart UI uses this to save the user's progress across multiple attempts to complete onboarding. When the user completes onboarding this value is displayed in the portal as the Customer Reference. Ensure that this value is the same as what you passed when obtaining a session token.
  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. See list of accepted types after this table

v4 Update
"DRIVERS_LICENCE" can be replaced with an object
{"type": "DRIVERS_LICENCE", digitalLicence: true}
to opt-in to collecting digital licenses

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 ,
ctaText: boolean | string


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

htmlContent will take an HTML stringwith inline styles, but only basic elements will be accepted. Read more after this table.




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;

HTML string with inline styles is also accepted, but only basic elements will be accepted. Read more after this table.

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

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.6.4 and above)



ID attribute assigned to either the style or link tag with css to be injected into the Smart UI. CORS will fail. 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.

Accepted HTML elements in HTML strings

"img", "address", "article", "aside", "footer", "header", "h1", "h2", "h3", "h4",
"h5", "h6", "hgroup", "main", "nav", "section", "blockquote", "dd", "div",
"dl", "dt", "figcaption", "figure", "hr", "li", "main", "ol", "p", "pre",
"ul", "a", "abbr", "b", "bdi", "bdo", "br", "cite", "code", "data", "dfn",
"em", "i", "kbd", "mark", "q", "rb", "rp", "rt", "rtc", "ruby", "s", "samp",
"small", "span", "strong", "sub", "sup", "time", "u", "var", "wbr", "caption",
"col", "colgroup", "table", "tbody", "td", "tfoot", "th", "thead", "tr"

Accepted values for documentTypes


Configuration for documentUploads (v4 ONLY)

documentUploads is an optional key you can add to the configuration that will add in the Document Uploads page which will appear last before the summaries page.

  "documentUploads": {
    "uploads": [
        "title": "Label or Title", 
        "description": "Optional description", 
        "types": ["DocumentUploadType" or { type: "DocumentUploadType", label: "Custom Label" }]
// To disable either omit the key or use 
  "documentUploads": false
// Do not set the key to null



title is required and will be saved with the document and display on the portal as Label

description is optional and will only display on the SmartUI as helper text above the upload field

types is required and will be a dropdown selection above the file upload, you can use any of the types in DocumentType or an object where you specify a custom label used for that type. This is where you may provide a translated version of the label.

For the customer they will not be able to progress until selecting a type and providing an image or pdf upload, for each upload

You can provide as many upload fields as you require


"document_uploads": {
    "title": "Upload document",
    "guide_text": "Upload a document please",
    "select_placeholder": "Select Document Type",
    "upload_cta": "Next",
    "upload_success": "Uploaded",
    "generic_error": "There was an error while uploading",
    "summary_title": "Document uploaded",
    "unsupported_file_type": "Unsupported file type"

Will appear at the top of the Document Uploads page

title - title of page e.g. Document Uploads
guide_text - description at top of page, can be a string or HTML e.g.

<div><p>Please upload 1 of the following supporting documents:<br /><br /></p><ul><li>Passport</li><li>Driver's licence</li><li>House Registration</li></ul><p>This can be either a picture or PDF document</p><div>

Will appear inside the upload button

select_placeholder - text inside the upload component e.g. “Upload file“

Will appear at the bottom of the Document Uploads page

upload_cta - text inside the ‘Next’ button at the bottom of the page e.g. “Next”

Will appear underneath upload button

upload_success - text that shows in green when the upload is succesful e.g. “Upload Success“
generic_error - text that displays generic file upload failure message
unsupported_file_type - text that displays as an error if user tries to upload an unsupported file type

Will appear on summary screen as the heading for the document upload section

summary_title - text displayed as a header for the document upload on the summary screen

Did this page help you?