Repository navigation
OndatoConfig builder configuration
The OndatoConfig class contains the builder method, which allows setting up and customising the SDK experience, ranging from whitelabelling options to enabling/disabling some of the UI features inside the SDK.
The following sections contain each of the builder methods and how they operate.
fun setIdentityVerificationId(identificationId: String)This method sets the identity verification ID for the SDK, so that the verification session based on that ID could be started. The identificationId parameter should be generated by the caller application each time a new identification session is started, as running multiple user identifications on the same session is not possible.
Note that this method greatly correlates with setMode() method, since it is very important for which environment (sandbox or production) the identification ID was generated, otherwise the SDK couldn't start the process if the ID is generated against sandbox environment and the SDK is set up to run against production environment, for example.
By default this value is empty, therefore, it is mandatory to provide a non-empty identificationId so that the flow inside the SDK could be started properly.
fun setMode(mode: Mode)This method sets the environment, on which the SDK runs. The environment parameter mode is of Mode enum class and contains two entries:
-
TEST-> this is for sandbox environment; -
LIVE-> this is for production environment.
This method is tightly coupled with setIdentityVerificationId() method, meaning that identificationId provided for setIdentityVerificationId() must be generated against a correct environment, whether that would be sandbox or production. If the identification ID and environment are misaligned, then the SDK would close with the failure status and the end user wouldn't be able to even start the identification process.
By default the SDK picks Mode.TEST (sandbox) environment, so if you are planning to work on production environment after testing, use this method to change the environments.
fun setLanguage(language: Language)fun setLanguage(languageString: String)This method has two overloaded implementations, one taking the Language enum class as a parameter and another one taking the languageString, which is essentially a two-letter language code (e.g. en, de, lt and so on).
Both methods achieve the same outcome - they set the SDK language to the one provided by the client application. It is more recommended to use Language enum class for stability and convenience, although if providing a language string is an easier option from the client app perspective, then it is perfectly fine to use that method instead.
Language enum class contains all supported languages by the SDK out-of-the-box. You can override these translation values in your own res/values/strings.xml with the correct language variety (e.g. res/values-el-rGR/strings.xml for a Greek translation). The list of supported languages can be found inside the main README file here.
Note that if you use the languageString parameter for the setLanguage() method and the language code is not correct, i.e. it cannot be mapped to any of the supported languages, then the default language (English) will be used. To utilise completely custom languages, see the setCustomLanguage() method in the following section.
By default the SDK uses English as a displayed language.
fun setCustomLanguage(languageString: String, countryCode: String)This method sets the custom SDK language provided by the client application. In order for this method to work as designed, the client app must have a res/values/strings.xml file with the standard language variety which is not officially supported by the SDK in the following format:
res/values-<languageString>-r<countryCode>/strings.xml
For example: given Anglic language variety with languageString being ang and the region being used (countryCode) as Great Britain (GB), then the following strings.xml file should be located inside res/values-ang-rGB/strings.xml of the client app project. Subsequently, the setCustomLanguage() for the config builder should be called like .setCustomLanguage("ang", "GB").
Note that by using this method, all string keys must match the existing ones inside the strings.xml files provided by the SDK (the reference point can be found here), otherwise the untranslated keys will be displayed in the default language (English).
When the client is providing their own custom language translations, Ondato is not responsible for their factual correctness and the responsibility for displaying true and valid translation values for the end user rests solely on the client.
fun setSkipRegistrationIfDriverLicense(skipRegistrationIfDriverLicense: Boolean)This method allows skipping TRN (tax registration) code registration step if the user selects driver licence as a document for identification.
By default skipRegistrationIfDriverLicense is set to false.
fun setConfiguration(json: String)This method sets the whitelabel configuration from JSON-formatted string. Usually the client application would store the .json file somewhere in the project and it would be read by the system and parsed as a string into this method, but clients are free to do their own implementations as long as json parameter contains valid JSON.
Punctuation and variable names inside JSON are important - you will not get whitelabelled UI elements if the JSON is malformed (e.g. extra curly brackets or commas) or the variable names do not follow the structure provided in the README file or the variable values set would not adhere to the type the value is converted to, e.g. a string is provided where a float or an int is expected.
It is not necessary to provide all the parameters described in the README - if you are satisfied with some of the elements containing default colours and sizes, then it is perfectly fine to omit those variables from JSON.
By default the SDK is not whitelabelled and it uses its own colouring scheme and UI element sizing and behaviour.
The SDK does not support dark mode out-of-the-box by design, meaning that if the end user decides to switch the device from light mode to dark mode and vice versa, the parameters set from the whitelabel JSON would persist throughout the identification process.
This method sets the custom font resources for each of the possible text formats (h1, h2, body, list etc.). There are six different text sizing types, as described in the Ondato Mobile SDK whitelabelling documentation page:
-
heading1FontResource- title text (h1 tag in HTML) font resource ID -
heading2FontResource- subtitle text (h2 tag in HTML) font resource ID -
normalFontResource- body text font resource ID -
listFontResource- list text font resource ID -
inputLabelFontResource- input label text (in textfields) font resource ID -
buttonTextFontResource- button text font resource ID
Note that the client application has to provide the font resource ID, e.g. R.font.helvetica_regular which would sit inside res/font folder of the client application project.
Usually fonts would be the same for all text types, but with this method is it possible to set different fonts for different text types, so one could have Times New Roman font for title texts and Comic Sans for ordinary size texts. The text sizing and other parameters like line height, font size, font weight, colour, alignment etc. are controlled through the whitelabel parameters instead.
fun enableNetworkIssuesScreen(shouldEnable: Boolean)This method enables network issues screen when the end user faces Internet connection problems and is not able to proceed with the verification.
By default this method is set to true and it is highly recommended to keep it so, but if clients have their own global network handling mechanisms and UI, then by providing "false" to shouldEnable parameter would disable the SDK's network issues modal.
fun disablePdfFileUploadForProofOfAddress(shouldDisable: Boolean)This method allows disabling PDF type file upload as a proof-of-address (PoA). By default, PDF is allowed to be submitted as a PoA, although clients are free to disable this by providing "false" to the shouldDisable parameter of this method and only the images (.jpg, .png) could be submitted as a proof-of-address.
Note that this method does not disable the document uploading option in the PoA step, where the end user could either capture the PoA by camera or upload the file from the device file system.
fun setSwitchPrimaryButtons(switchPrimaryButtons: Boolean)This method switches primary and secondary button placement in the SDK. If the primary button is on top and the secondary is on the bottom, then the secondary button moves up and the primary button moves down. If the buttons are placed in one line (default placement is secondary on the left and primary on the right), then the primary button moves left, and the secondary button - to the right.
By default this value is set to false, meaning that in a vertical configuration, the primary button is at the top and the secondary button is at the bottom. In a horizontal configuration, the primary button is on the right hand side and the secondary button is on the left hand side.
fun setLoggingLevel(loggingLevel: Level)This method sets the logging level to the SDK process. The loggingLevel parameter takes the Level enum class, which contains three distinct logging levels as enum entries:
-
Error- only the application crashes or unexpected behaviour is logged. -
Info-Errorlogging level plus some generic information about the device and the backend configuration parameters as well as parameters set fromOndatoConfig. -
Debug-Error+Infolevels and more troubleshooting info which is helpful during the triage process.
The default logging level is Info, that is, if this method is not called, then the SDK would run with the Info logging level.
More on this can be read in the README file.
fun setTermsAndConditionsRules(enableTermsAgreementButtonAfterScrolling: Boolean, termsAgreementButtonTimeout: Long? = null)This method sets the consent reading validation rules so that the "agree" button could be enabled for the end user.
The terms and conditions screen, if enabled from the backend configuration, enforces the end user to at least try to read the contents and give consent on what data is being collected and processed. The rules to enable the "I agree" consent confirmation button are as follows:
- The end user has to scroll down to the end of the text, essentially confirming that the user has read all of the contents;
- The end user has to wait for a specific amount of time (default value is 10 seconds), which naively checks if the user actually read the text and not scrolled down to the bottom of the page just for the sake of it.
Both rules 1 and 2 are enabled by default. To disable the rules completely, set the enableTermsAgreementButtonAfterScrolling to "false" and termsAgreementButtonTimeout to 0.
Note that rule 1 (scroll-to-bottom) and rule 2 (timeout) are independent of each other, therefore you can have options where only rule 1 is enabled (enableTermsAgreementButtonAfterScrolling is set to "true") and timer is set to 0 or an option where rule 2 is applied only (termsAgreementButtonTimeout is set to any value you want, enableTermsAgreementButtonAfterScrolling is set to "false").
If the timeout is kept blank, it will revert to null and the default timer of 10 seconds would apply.
fun showComplianceTextDocSelect(showComplianceTextDocSelect: Boolean)This method enables compliance text shown in the document selection screen, just above the certificate cards.
The default value is false, meaning that there is no text shown above the certificate cards.
The following methods are unique in a sense that the client has to provide a custom UI implementation for specific flow steps in case the default screen configuration does not satisfy the client. More information can be read on the Confluence page.
fun setLoadingScreenProvider(provider: LoadingScreenProvider)This method allows setting the custom loading screen, provided that provider parameter is a class implementing the LoadingScreenProvider interface. The interface contains one method, get() which returns a Fragment (since it is a fragment based navigation) and the fragment returned is the one the client must provide and implement:
interface LoadingScreenProvider {
fun get(): Fragment
}fun setSuccessScreenProvider(provider: SuccessScreenProvider)This method allows setting the custom identification success screen, provided that provider parameter is a class implementing the SuccessScreenProvider interface. The interface contains one method, get() which returns a Fragment (since it is a fragment based navigation) and the fragment returned is the one the client must provide and implement:
interface SuccessScreenProvider {
fun get(callback: SuccessScreenCallback): Fragment
}This method also needs to have a callback parameter, which is again an interface of SuccessScreenCallback and it needs to be implemented too, with the onCompleted() method described in this interface. This callback essentially informs the SDK from the client's custom screen that the end user has clicked the completion/continuation button and the SDK could proceed with other processes so that it could close the identification flow gracefully.
fun setInstructionsScreenProvider(provider: InstructionsScreenProvider)This method allows setting the custom document capture instructions screens, provided that provider parameter is a class implementing the InstructionsScreenProvider interface. The interface contains one method, get() which returns a Fragment (since it is a fragment based navigation) and the fragment returned is the one the client must provide and implement:
interface InstructionsScreenProvider {
fun get(mode: OndatoTutorialContentMode, callback: InstructionsScreenCallback): Fragment
}Note that InstructionsScreenCallback is also an interface with onCompleted() method which needs to be implemented, too.
The client can provide the same instructions screen but with different content inside based on the OndatoTutorialContentMode, meaning that the layout of the UI could stay the same if the client overrides with one screen, but the inside content could changed based on the document type, e.g. string values and images. However, clients are free to have their own implementations on how the document capture instructions screen(s) should look like, the SDK is only concerned about the callback which informs that the SDK has to move on to a different step (usually that would be the camera feed and document capture).
fun setDocumentSelectionScreenProvider(provider: DocumentSelectionScreenProvider)This method allows setting the custom document selection screen, provided that provider parameter is a class implementing the DocumentSelectionScreenProvider interface. The interface contains one method, get() which returns a Fragment (since it is a fragment based navigation) and the fragment returned is the one the client must provide and implement:
interface DocumentSelectionScreenProvider {
fun get(documentTypes: List<DocumentType>, callback: DocumentSelectionScreenCallback): Fragment
}The list of documentTypes is important here for the SDK to know which of the supported document types need to be wired with the custom UI implementation. The callback (DocumentSelectionScreenCallback interface) contains onSelected(documentType: DocumentType) method, and this needs to be called so that the SDK is informed of the end user document selection and that the SDK could proceed with the next step accordingly.