Smart UI Configuration

The function initializeOnboardingWidget takes the following object:

1
{
2
  ffToken: string,
3
  applicantReference: string
4
  config?: ConfigurationParameters
5
  height?: string
6
  width?: string
7
}

Where:

1. ffToken is the token retrieved in Getting Started

2. applicantReference is a unique identifier such as an email address or userID, 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 its 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 behavior of HTML block elements, where height auto will fit 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 allows the Smart UI height to adapt to its contents.
   5. Check Custom Styling for more details

Configuration Parameters

frankieBackendUrl

type: string
default: “https://backend.kycaml.frankiefinancial.io” (production url)

This url differs from Frankie One’s core API. Valid values are:

• Demo - https://backend.demo.frankiefinancial.io
• UAT (if you have a UAT environment) - https://backend.kycaml.uat.frankiefinancial.io
• Production - https://backend.kycaml.frankiefinancial.io

checkProfile

This option allows you to select the relevant entity Profile, for example from our standard set up “safe_harbour_id”, “safe_harbour”, “gov_id”.

Further details are available here https://apidocs.frankiefinancial.com/docs/using-an-entity-profile

documentTypes

type: array of (string | { type: string, …configurations })
default: [‘PASSPORT’, ‘DRIVERS_LICENCE’, ‘NATIONAL_HEALTH_ID’, ‘NATIONAL_ID’]

This option accepts an array of document type configuration objects OR simply the type as a string, which will use its default configuration object. The accepted type strings and their corresponding default configuration object are

• ”PASSPORT”: { type: “PASSPORT”, idExpiry: false, acceptedCountries: undefined }, where

  • idExpiry also captures the expiry date for the passport
  • acceptedCountries. Takes string “ALL”, or an array of valid ISO3166 Alpha3 country codes. When undefined will default to an array with “AUS” only.

• ”DRIVERS_LICENCE”: { type: “DRIVERS_LICENCE”, digitalLicence: false, acceptedCountries: undefined }, where

  • digitalLicence determines if Smart UI should confirm DL are digital or not. Wording is defined by the phrases item “type_drivers_licence.digital_consent” (see below).
  • acceptedCountries defines which countries to capture Drivers Licence from. Currently, only AUS and NZL are supported. Since version 4.12 on 27/05/2023
  Accepted Countries for Drivers Licence behaves differently!

  It only supports an array with the values “AUS” and/or “NZL”. Adding other values will result in a validation error.

• ”NATIONAL_HEALTH_ID”: { type: “NATIONAL_HEALTH_ID” }

• “NATIONAL_ID”: { type: “NATIONAL_ID”, acceptedCountries: undefined } v4 only

Phrases for documentTypes

1
"document": {
2
  	// document.number is deprecated and will be replaced with "number" in each document type
3
    "number": "Number",
4
    "type_passport": {
5
      "label": "Passport",
6
      "subtitle": "",
7
      "number": "Document Number",
8
      "country": "Country of Issue",
9
      "expiry": "Expiry Date"
10
    },
11
    "type_drivers_licence": {
12
      "label": "Drivers Licence",
13
      "subtitle": "(recommended)",
14
      "state": "State or territory of issue",
15
      "licence_number": "Licence Number",
16
      "digital_consent": "This is a digital licence and I don’t have my physical licence with me.",
17
      "digital_notification_banner": "A physical licence is required to open an account. You may complete the application however you may need to provide additional information."
18
    },
19
    "type_medicare": {
20
      "label": "Medicare Card",
21
      "subtitle": "",
22
      "number": "Number",
23
      "colour": "Colour",
24
      "position": "Position",
25
      "expiry": "Expiry Date",
26
      "name": "Name as shown on card"
27
    },
28
    "type_national_id": {
29
      "label": "National Id",
30
      "subtitle": "(Citizen/Permanent resident)",
31
      "laser_code": "Laser Code",
32
      "country": "Country of Citizenship",
33
      "identification_number": "Identification Number",
34
      "name": "Name as shown on card",
35
      "nationality": "Nationality"
36
    }
37
  },

Custom document types

You may also determine the display of custom document type options. In such cases, if the user selects a custom document type, the Smart UI will simply emit an event to allow your application to handle that selection and nothing else. More details on events in Events.

Custom types always begin with “CUSTOM*” and are defined as objects:
{
type: “CUSTOM_TYPE_NAME”,
label: “Custom type name,
subtitle?: “Hint shown under the label in smaller font size”,
customEventPayload: Anything
}
The CustomEvent “DOC_TYPE_SELECTED” will be emitted with the following _detail*:
{
applicant: Applicant data captured so far,
customEventPayload: As defined in the configuration above
}

1
{
2
  "documentTypes": [
3
    "NATIONAL_HEALTH_ID",
4
    "DRIVERS_LICENCE",
5
    {
6
      "type": "PASSPORT",
7
      "idExpiry": true
8
    },
9
    {
10
      "type": "CUSTOM_DOC",
11
      "label": "Other doc type",
12
      "subtitle": "Click here to try something else",
13
      "customEventPayload": {
14
        "docType": "CUSTOM_NEW_DOC_TYPE_1",
15
        "userFlow": "SIGNUP_FLOW_3"
16
      }
17
    }
18
  ]
19
}

And on your web page, listen for the specific event, for example:

1
<html>
2
  <head>
3
    <script>
4
      window.addEventListener('DOC_TYPE_SELECTED', function (e) {
5
      	const { userFlow, docType } = e.detail.customEventPayload;
6
      	if (userFlow === 'SIGNUP_FLOW_3)
7
            location.href = "www.yoursite.com/signup-3?docType=" + docType;
8
9
      });
10
    </script>
11
  </head>
12
</html>

Screens

welcomeScreen

type: boolean | { htmlContent: string, ctaText: string }
default: true

You may skip the welcome screen simply by setting this option to false.

htmlContent will take an HTML string with inline styles, but only basic elements will be displayed. Read more later in “Accepted HTML elements in HTML strings”.

ctaText is the label of the button at the bottom of the screen, which takes the user to the next page.

successScreen and failureScreen

failureScreen => type: boolean | { ctaUrl: string | null, ctaText: string }
successScreen => { ctaUrl: string | null, ctaText: string }

default: { ctaUrl: null } (no button)

Displayed when succeeding or failing checks definitively. Similar to welcomeScreen, you may skip these screens by setting these options to false (maybe to implement your own).

ctaText: Just like before, this option will set the label on the button at the bottom of the page
ctaUrl where to redirect the user when clicking the button, or even to run scripts with a “javascript:” url prefix. Beware this method of running javascript may not be fully supported by all browsers. Setting this to null removes the button.

pendingScreen

type: boolean | { ctaActions: array of {url: string, text: string} }
default: { ctaUrl: null }

This page is shown whenever the reason for a failure can’t be resolved on the widget. In such case it will be necessary to resolve the issue manually, either on the portal or via direct API. This would happen if the user was flagged with a PEP result, for example, or if some check might take too long to complete.

This is similar to the other screens but supports multiple buttons, instead of just one. It’s recommended to use no more than three actions.

googleAPIKey

type: false | string
default: false

Please visit the Google Developer Console.
The APIs 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.

acceptedCountries

type: array of char3 strings | string “ALL”
default: [“AUS”]

Widget wide configuration for restricting accepted countries. This brings obvious problems when your intention is for example to accept passports from anywhere, but want to restrict addresses from a single country. For that reason, this option is now deprecated in favor of specific configurations for documentTypes and requestAddress.

{
  "documentTypes": [
    "NATIONAL_HEALTH_ID",
    {
      type: "PASSPORT",
      acceptedCountries: "ALL"
    },
    "DRIVERS_LICENCE"
  ],
  "requestAddress": {
    acceptedCountries: [
      "USA",
      "SGP",
      "NZL",
      "AUS"
    ]
  },
  "googleAPIKey": <CUSTOMERS_GOOGLE_API_KEY>
}

consentText

type: HTML string
**default: ** I consent to my personal information being collected and used in accordance with the organisation’s Privacy Policy. In addition, for the purposes of verifying my identity, I consent to: a) the verification of my personal information with credit bureau header files (for verification only); b) against records held by official document issuers or official record holders via third party systems; and c) your verification agent(s) acting as a nominated intermediary in accordance with Australian Privacy Principles. I consent to the use by third parties of the results of any verification checks on my identity for the purposes of monitoring and improving their verification services.

HTML string with inline styles is also accepted, but only basic elements will be displayed.

requestAddress

type: boolean | { acceptedCountries: array of char3 strings OR string ‘ALL’ }
default: true

Defines if the address should be requested. You may specify an object where you list the accepted countries for the address. View notes for acceptedCountries for more information.

idScanVerification

type: boolean | IDScanVerificationConfigurationObject
default: false

To include the scan verification at the end of the Smart UI. You must either pass the boolean true, or the configuration object detailed below. By default, there will be no id scan verification.

Read more about this part of the flow in Onfido Web SDK

IDScanVerificationConfigurationObject is defined as follows:

1
{
2
        releaseVersion: "latest",
3
	welcomeScreen: {
4
		title: 'Verify your identity',
5
		content: ["We need to collect some personal information to verify your identity before we can open your account."],
6
		ctaText: 'Start Identity Verification',
7
	},
8
  useMobileDevice: true,
9
	useLiveness: boolean,
10
	injectedCss: string,
11
  language: PhrasesDictionary
12
}

welcomeScreen

welcomeScreen defaults to

1
welcomeScreen: {
2
	title: "Verify your identity",
3
	content: [
4
    "We need to collect some personal information to verify your identity before we can open your account.",
5
	],
6
	ctaText: "Start Identity Verification",
7
}

The welcomeScreen object:

documentUploads

type: { uploads: array of DocumentUpload }, see next
default: { uploads: [] }, no uploads

Document uploads are used to support the verification of an individual. A document such as “proof of address” may be of different types, ie “Visa” and “Lease”. For that reason, when configuring document uploads you’ll also define which types are acceptable for that upload. This particular example with a screenshot is demonstrated below.

DocumentUpload is defined as

1
{
2
	title: string,
3
	description?: string
4
	types: array of SupportingDocumentTypes
5
}

Where description is optional and the list of accepted Supporting Document types is defined here. Search for “idType”.

Types may be defined as plain strings or objects { type: string, label: string }, where you customize the label displayed. This is where you may translate types into different languages as well.

For example, the configuration below:

1
{
2
  documentUploads: {
3
    uploads: [
4
      {
5
        title: "Proof of address",
6
        description: "Upload some proof of address",
7
        types: [{ type: "OTHER", label: "Lease" }, "VISA"],
8
      },
9
    ];
10
  }
11
}

would generate the following screen

Note: type “ATTESTATION” can’t be used as a supporting document.

You can provide as many upload fields as you require

Phrases for document upload

1
"document_uploads": {
2
    "title": "Upload document",
3
    "guide_text": "<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>",
4
    "select_placeholder": "Select Document Type",
5
    "upload_cta": "Next",
6
    "upload_success": "Uploaded",
7
    "generic_error": "There was an error while uploading",
8
    "summary_title": "Document uploaded",
9
    "unsupported_file_type": "Unsupported file type"
10
  }

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.
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 review screen as the heading for the document upload section
summary_title - text displayed as a header for the document upload on the summary screen

dateOfBirth

type: { type: ‘gregorian’ | ‘buddhist’ }
default: {type: ‘gregorian’}

In case this option is configured with ‘buddhist’, the capture will be made in Buddhist years and converted to Gregorian transparently before being submitted. Our service only stores UTC Gregorian dates. A Key Value pair called “buddhist_solar_dob” will be stored to indicate the capture was done in a different calendar.

Since v4.4 we also support Buddhist date of birth to only contain years. Since the date of birth needs to be converted to a valid Gregorian date when stored in the entity’s dateOfBirth, in that field the missing day and month will be replaced with “01”. The original Buddhist date of birth will now also be stored in the a Key Value pair called dob.Buddhist, where missing day and month are replaced with “00”.

saveOnly

This configuration setting allows customers to only save their progress, and always proceed to biometrics verification. The default value is false. Set it to true to ensure biometric verification is performed.

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"

Device Fraud Detection

type: boolean
default: false

For Device Fraud characteristics check, the following flag needs to be enabled to gather the details about the device and the behaviours of the user during onboarding. In the background this will enable a session during which the device details are gathered as well as the behaviours that the customer does.

{enableDeviceCharacteristics: true}

Pre-load Phone & Email to Entity

type: string
default: empty

Email and Phone details can be preloaded into the SmartUI and will be saved for the entity if passed. For customers using Fraud checks for email and phone, these details will be used for verification.

_Note: These details aren’t visible to the SmartUI user and can’t be edited by the user in the SmartUI flow _

{preload: {
              email: "example@example.com",
              phone: "+61400000000",
            }}