SDK customization

Start here

The Onfido SDKs have multiple cutomizable features that provide flexibility, while also being easy to integrate. Customizing the Onfido SDKs to match the look and feel of your application can help improve your user experience.

This guide will provide an overview of the customization options available with the Onfido SDKs:

• flow customization
• language localization
• UI customization

For general technical documentation for our SDKs, follow the links on our main Developer Hub page.

Flow customization

Each SDK's flow can be customized by removing, adding or reshuffling certain steps. For example, you could have only document capture for your flow, or have both document and selfie capture.

The information displayed on some screens can also be customized. For example, specifying the document type options for document capture.

Mobile SDK flow

1. Welcome

The welcome screen displays a summary of the capture steps the user will pass through. These steps can be specified to match the flow required.

This is an optional screen in both Android and iOS SDK flows.

2. Document

In the Document Capture step, an end user can select the issuing country and document type before capture. In a very limited number of cases, the end user may also be asked if they have a card or paper version of their document.

This information is used to optimize the capture experience, as well as inform the end user about which documents they are allowed to use.

This selection screen is optional, and will be automatically hidden where the end user is not required to indicate which document will be captured.

By default, the country selection will be pre-populated based on the end user’s primary SIM, but the end user can select another country from the list where allowed. The selection will default to empty when no SIM is present.

Note: the above images for the document and country selection screens are for iOS SDK versions 25.2.0+ and Android SDK versions 12.3.0+. For previous designs, see previous SDK reference guides.

You can specify allowed issuing countries and document types for the document capture step in one of three ways:

• If you are using Onfido Studio, this is configured within a Document Capture task, documented in the Studio Product Guide
• Otherwise, for Onfido Classic you can set this globally in your Dashboard (recommended), or hard code it into your SDK integration. Both of these options are documented below.

Country and document type selection by Dashboard

Configuring the issuing country and document type selection step using your Dashboard is the recommended method of integration (available from iOS SDK version 28.0.0 and Android SDK version 16.0.0 onwards) as this configuration is also applied to your Document Reports. Any document that has been uploaded by an end user against your guidance will result in a Document Report sub-result of "rejected" and be flagged as Image Integrity > Supported Document.

We will be rolling out Dashboard-based configuration of allowed documents soon. In the meantime, contact support@onfido.com or your Customer Support Manager to request access to this feature.

• Open the Accounts tab on your Dashboard, then click Supported Documents
• You will be presented with a list of all available countries and their associated supported documents. Make your selection, then click Save Change.

Please note the following SDK behaviour:

• Hard coding any document type and issuing country configuration in your SDK integration will fully override the Dashboard-based settings
• Currently, only passport, national ID card, driving licence and residence permit are visible for document selection by the end user in the SDK. For the time being, if you nominate other document types in your Dashboard (visa, for example), these will not be displayed in the user interface
• If you need to add other document types to the document selection screen, you can mitigate this limitation in the near-term, using the Custom Document feature
• If for any reason the configuration fails or is not enabled, the SDK will fallback to display the selection screen for the complete list of documents supported within the selection screens

Country and document type customization by SDK integration code

If you want to use your own custom document selection UI instead of displaying the Onfido document selection screen, you will need to specify the document details during SDK initialization.

The document selection screen will be skipped automatically when the single document type is specified.

The SDK will accept the following:

• The Document Type is required. This controls fundamental SDK document capture behaviour
• The Country is optional, but recommended. This enables any optimizations the SDK may have for this specific document issued by this country
• The Document Format is optional, and only accepted for French driving licence, Italian national identity card and South African national identity card. This defaults to CARD, representing modern forms of these documents. If the end user indicates that they have an older, paper version of one of these documents, use FOLDED to ensure an optimized capture experience

See more details in the Technical Reference (here for Android, and here for iOS).

Note: You may still wish to configure the Dashboard-based approach to ensure that the Document Report also rejects any document that has been uploaded by an end user against your guidance.

3. Face

In the face step, a user can use the front camera to capture either a live photo of their face, or a live video.

The face step can be configured to allow for either a photo or video flow. Note: A custom flow cannot contain both the photo and video variants of the face capture.

• Photo

By default, an introduction screen will be shown before the start of the photo flow.

The photo flow introduction screen is optional for both the Android and iOS SDK.

• Video

If capturing a live video, the user will be prompted to perform two simple challenges. An introduction screen with a video example will be shown before the start of the video flow.

The video example shown on the introductory step can be removed in both the Android and iOS SDK.

4. Finish

The final screen displays a completion message to the user and signals the end of the flow.

This is an optional screen in the Android SDK only. It is not displayed in the iOS SDK flow.

Web SDK flow

1. Welcome

The welcome screen displays a summary of the capture steps the user will pass through. These steps can be specified to match the flow required.

This is an optional screen.

The custom string options are:

• title
• descriptions
• nextButton

2. Document

In the Document Capture step, an end user can select the issuing country and document type before capture.

This information is used to optimize the capture experience, as well as inform the end user about which documents they are allowed to use.

This selection screen is optional, and will be automatically hidden where the end user is not required to indicate which document will be captured.

By default, when the selection screen is shown, the country selection will be empty.

Note: the above images are for web SDK versions 8.3.0+. For previous designs, see previous SDK reference guides

You can specify allowed issuing countries and document types for the document capture step in one of three ways:

• If you are using Onfido Studio, this is configured within a Document Capture task, documented in the Studio Product Guide
• Otherwise, for Onfido Classic you can set this globally in your Dashboard (recommended), or hard code it into your SDK integration. Both of these options are documented below

Country and document type selection by Dashboard

Configuring the issuing country and document type selection step using your Dashboard is the recommended method of customization (available from Web SDK version 10.0.0 onwards) as this configuration is also applied to your Document Reports. Any document that has been uploaded by an end user against your guidance will result in a Document Report sub-result of "rejected" and be flagged as Image Integrity > Supported Document.

We will be rolling out Dashboard-based configuration of allowed documents soon. In the meantime, contact support@onfido.com or your Customer Support Manager to request access to this feature.

• Open the Accounts tab on your Dashboard, then click Supported Documents
• You will be presented with a list of all available countries and their associated supported documents. Make your selection, then click Save Change.

Please note the following SDK behaviour:

• Hard coding any document type and issuing country configuration in your SDK integration will fully override the Dashboard-based settings
• Currently, only passport, national ID card, driving licence and residence permit are visible for document selection by the end user in the SDK. If you nominate other document types in your Dashboard (visa, for example), these will not be displayed in the user interface
• If you need to add other document types to the document selection screen, you can mitigate this limitation in the near-term, using the Custom Document feature
• If for any reason the configuration fails or is not enabled, the SDK will fallback to display the selection screen for the complete list of documents supported within the selection screens

Country and document type customization by SDK integration code

If you want to use your own custom document selection UI instead of displaying the Onfido document selection screen, you will need to specify the document details during SDK initialization.

The document selection screen will be skipped automatically when the single document type is specified.

The SDK will accept the following:

• The Document Type is required. This controls fundamental SDK document capture behaviour
• The Country is optional, but recommended. This enables any optimizations the SDK may have for this specific document issued by this country
• The Document Format is optional, and only accepted for French driving licence, Italian national identity card and South African national identity card. This defaults to CARD, representing modern forms of these documents. If the end user indicates that they have an older, paper version of one of these documents, use FOLDED to ensure an optimized capture experience

In the Web SDK, it is also possible to remove the country selection entirely from the document selection screen. Set the hideCountrySelection option to true to show all supported document types in a single list with no country selection. Note that, without capturing the country information, the SDK is unable to apply optimized capture experiences for specific documents, and we are not able to perform fine-grained analytics based on country selection.

See more details in the Technical Reference here.

Note: You may still wish to configure the Dashboard-based approach to ensure that the Document Report also rejects any document that has been uploaded by an end user against your guidance.

Cross device flow

The Web SDK offers a cross-device flow where desktop users are directed to continue on their mobile device browser to complete the capture process, providing vastly improved image quality versus a typical desktop webcam and an increased likelihood of live capture.

The user is offered a QR code to scan with their camera app, which then resumes the flow on their mobile device browser. For users that cannot scan a QR code, a Copy Link feature and Send Link with SMS feature are also available. Regardless of the cross-device method, the secure URL is unique to this session.

When a user switches to the SDK's cross-device flow, they will see an introductory screen when the SDK client loads on their mobile browser. At the end of the capture process, users will be redirected back to their desktop to complete the SDK flow.

It is recommended to enforce the cross-device flow. The option is available in Onfido Studio, configurable in the workflow builder.

In a Classic integration, the cross-device flow is configured by setting forceCrossDevice to true:

options: {
  forceCrossDevice: true
}

• When configured, forceCrossDevice makes the cross-device flow mandatory for all users who will be required to complete the capture process on a mobile device browser
• The forceCrossDevice functionality can be configured for both the Document capture and Proof of Address verification steps
• forceCrossDevice cannot be configured for Face captures

When a user switches to the SDK's cross-device flow, they will see an introductory screen when the SDK client loads on their mobile browser. This screen notifies the user that this is part of a flow initiated on a desktop browser when they open the cross-device link on their mobile browser.

The following optional customizations are available for the introductory screen:

• Specify company or product name

  • crossDeviceClientIntroProductName
  • You can customize the text by adding your company or product name to the subtitle
  • We recommend that you set this so that the user can identify the purpose of the flow when they open the cross-device link. This is also an opportunity to include your branding in the SDK flow

• Display company or product logo

  • crossDeviceClientIntroProductLogoSrc
  • You can customize the icon by adding your company or product logo to be displayed instead of the default SDK icon image
  • We recommend that you set this so that the user can identify the purpose of the flow when they open the cross-device link. This is also an opportunity to include your branding in the SDK flow
  • The image used should be no more than 144px in both height and width

Image capture upload fallback

The SDK will attempt to load an optimized camera UI to take a live photo. When this is not possible (because of an unsupported browser or mobile devices with no camera), the user will be presented with an HTML5 File Input. Set uploadFallback to false to disable this fallback feature and ensure live capture. Note that disabling uploadFallback will prevent users with an unsupported browser or a mobile device with no camera from continuing.

3. Face

In the face step, users will be asked to capture their face in the form of a photo or video. They will also have a chance to check the quality of the photos or video before confirming.

The custom options are:

• Specify variant

  • requestedVariant
  • This includes photo or video options, with photo being the default
  • If a video cannot be taken, the face step will fallback to the standard photo option

• Upload Fallback

  • uploadFallback
  • When live photo or live video capture is not possible, upload fallback allows users to upload image files via their device's default camera application
  • Note: When the mobile device does not have a camera or lacks camera browser support, the user will not be able to complete the flow if this option is not configured

4. Finish

The final screen displays a completion message to signal the next steps to the user.

This is an optional screen.

The custom string options are:

• message
• submessge

Language customization

The Onfido SDKs allow for language customization across all platforms.

Supported languages

Onfido supports and maintains translations for 44 languages that can be implemented directly inside the SDK.

All of these languages are supported across Web, Android and iOS under the following locales:

Note: English is the default language (en_US).

Custom language

The Onfido SDKs also allow for the selection of a specific custom language for locales that Onfido does not currently support.

You need to provide custom translations and the relevant locale tag. Note: If a locale is not specfied the language is inferred from the device settings.

Further information can be found in our SDK reference pages for iOS, Android and Web.

UI customization

The Onfido mobile SDKs have additional UI options which allow you to customize the look and feel of the SDKs to match your application. This helps create a more seamless experience for your users.

iOS

The iOS SDK supports the customization of colors, fonts, buttons and strings used in the SDK flow.

Available attributes

• primaryColor: Defines the button color and back navigation button color
• primaryTitleColor: Defines the primary button text color
• secondaryTitleColor: Defines the secondary button text and border color
• primaryBackgroundPressedColor: Defines the primary button pressed state color
• secondaryBackgroundPressedColor: Defines the secondary button pressed state color

• backgroundColor: Defines the screen's background color for non-capture views.

  • light: Defines the backgroundColor in light mode
  • dark: Defines the backgroundColor in dark mode
• borderCornerRadius: Defines border corner radius for all the buttons (default 5.0)
• fontRegular: Defines the custom font name for the regular style labels
• fontBold: Defines the custom font name for the bold style labels

• interfaceStyle: Defines the interface style

  • Note: This property is applicable only for Xcode 11 and above built apps and devices running on iOS 13 and above

• captureSuccessColors: Defines the color values for the capture screen success auto capture state

  • borderColor: Defines the border color of the area of interest in capture screen
  • tickViewImageTintColor: Defines the tick icon's tint color shown in capture screen after auto capture happens
  • tickViewBackgroundColor: Defines the tick icon's background color shown in capture screen after auto capture happens

Dark mode customization

The interfaceStyle allows you to force light or dark mode via .dark and .light respectively, or follow the system's interface style with .unspecified. The value is .unspecified by default.

Note: The previous attribute supportDarkMode is now deprecated. Please use interfaceStyle instead.

Some example document selection screens using dark mode in iOS.

For more information on the available iOS customization options, see our SDK reference documentation.

Android

The Android SDK supports the customization of colors, buttons, fonts and strings used in the SDK flow.

Dark mode customization

Starting from version 19.1.0, Onfido's Android SDK supports dark mode. By default, the user's active device theme will be automatically applied to the SDK flow. However, you can opt out from dynamic theme switching at run time and set a theme statically at build time as illustrated below. In this case, the flow will always be in displayed in the selected theme regardless of the user's device setting.

To force select dark theme:

onfidoConfigBuilder.withTheme(OnfidoTheme.DARK)

To force select light theme:

onfidoConfigBuilder.withTheme(OnfidoTheme.LIGHT)

You can also automatically use the user's device theme:

onfidoConfigBuilder.withTheme(OnfidoTheme.AUTOMATIC)

Below you can see some example document selection screens using dark mode for Android.

Appearance and colors

You can customize colors and other appearance attributes by overriding Onfido themes (OnfidoActivityTheme and OnfidoDarkTheme) in your themes.xml or styles.xml files. Make sure to set OnfidoBaseActivityTheme as the parent of OnfidoActivityTheme and OnfidoBaseDarkTheme as the parent of OnfidoDarkTheme in your style definition. All colors referenced in the themes should be defined in your colors.xml file. Alternatively, you can use hexadecimal color values directly in the themes. When customizing fonts, all referenced fonts must be added to your project first. Further instructions for adding fonts can be found here.

The following attributes are currently supported:

• Colors

  • General

    • onfidoColorBackground: Background color of the non-capture screens
    • colorAccent: Defines alert dialogs' accent color, and text input fields' focused underline, cursor, and floating label color

  • Content

    • onfidoColorContentMain: Color of primary texts on screen, e.g. titles and regular body texts
    • onfidoColorContentMainDark: Color of the content on capture screens (those with dark backgrounds)
    • onfidoColorContentSecondary: Color of secondary texts on screen, e.g. subtitles
    • onfidoColorContentNegative: Color of error texts

  • Main buttons

    • onfidoColorActionMain: Background color of primary buttons
    • onfidoColorActionMainPressed: Background color of primary buttons when pressed
    • onfidoColorActionMainDisabled: Background color of primary buttons when disabled
    • onfidoColorContentOnAction: Text color of primary buttons
    • onfidoColorContentOnActionDisabled: Text color of primary buttons when disabled

  • Secondary buttons

    • onfidoColorActionSecondary: Background color of secondary buttons
    • onfidoColorActionSecondaryPressed: Background color of secondary buttons when pressed
    • onfidoColorActionSecondaryDisabled: Background color of secondary buttons when disabled
    • onfidoColorContentOnActionSecondary: Text color of secondary buttons
    • onfidoColorContentOnActionSecondaryDisabled: Text color of secondary buttons when disabled
    • onfidoColorActionSecondaryBorder: Border of the secondary buttons
    • onfidoColorActionSecondaryBorderDisabled: Border of the secondary buttons when disabled

  • Disclaimers

    • onfidoColorDisclaimerBackground: Background color of disclaimer boxes
    • onfidoColorContentDisclaimer: Text color of disclaimer boxes
    • onfidoColorIconDisclaimer: Icon color of disclaimer boxes

  • Toolbar and status bar

    • onfidoColorToolbarBackground: Background color of the Toolbar which guides the user through the flow
    • colorPrimaryDark: Color of the status bar (with system icons) above the Toolbar
    • onfidoColorContentToolbarTitle: Color of the Toolbar's title text

  • Icons

    • onfidoColorIconStroke: Stroke color of icons
    • onfidoColorIconStrokeNegative: Stroke color of error icons
    • onfidoColorIconFill: Fill color of icons
    • onfidoColorIconBackground: Background color of icons
    • onfidoColorIconAccent: Background color of accented icons
    • onfidoColorWatermark: Color of the Onfido logo and co-brand logo in the footer of non-capture screens
    • onfidoColorWatermarkDark: Color of the Onfido logo and co-brand logo in the footer of capture screens

  • Spinner / progress indicator

    • onfidoColorProgressTrack: Track color of progress indicators (background color)
    • onfidoColorProgressIndicator: Indicator color of progress indicators (foreground color)

Widgets

You can customize the appearance of some widgets in your dimens.xml file by overriding:

• onfidoButtonCornerRadius: Defines the radius dimension of all the corners of primary and secondary buttons

Typography

You can customize the fonts by providing font XML resources to the theme by setting OnfidoActivityTheme to one of the following:

• onfidoFontFamilyTitleAttr: Defines the fontFamily attribute that is used for text which has typography type Title
• onfidoFontFamilyBodyAttr: Defines the fontFamily attribute that is used for text which has typography type Body
• onfidoFontFamilySubtitleAttr: Defines the fontFamily attribute that is used for text which has typography type Subtitle
• onfidoFontFamilyButtonAttr: Defines the fontFamily attribute that is applied to all primary and secondary buttons
• onfidoFontFamilyToolbarTitleAttr: Defines the fontFamily attribute that is applied to the title and subtitle displayed inside the Toolbar
• onfidoFontFamilyDialogButtonAttr: Defines the fontFamily attribute that is applied to the buttons inside AlertDialog and BottomSheetDialog

For more information on the available Android customization options, see our SDK reference documentation.

React Native

The React Native SDK supports the customization of colors used in the SDK flow on iOS and Android.

iOS

You can customize the SDK by adding a colors.json file to your xcode project as bundle resource. The file should contain a single json object with the desired keys and values.

For specific details on the supported attributes, please refer to our React Native SDK documentation.

Dark mode customization

The interfaceStyle attribute allows you to force a specific SDK theme (.dark or .light) or follow the user's device style setting (.unspecified). The value is .unspecified by default.

Note: The previous attribute supportDarkMode is now deprecated. Please use interfaceStyle instead.

Some example document selection screens using dark mode in iOS.

Android

You can customize colors and other appearance attributes by overriding Onfido themes in your themes.xml or styles.xml files.

For specific details on the supported attributes, see our React Native SDK documentation.

Note: The usage of color.json and the updateColors command is now deprecated for Android. Please provide the theme attributes in your styles.xml or themes.xml.

Dark mode customization

Onfido's SDK supports dark mode. By default, the user's active device theme will be automatically applied to the SDK flow. However, you can opt out from dynamic theme switching at run time and set a theme statically at build time as illustrated below. In this case, the flow will always be in displayed in the selected theme regardless of the user's device setting.

To set a static theme, use the theme parameter in the SDK initialization config. The value type should be OnfidoTheme. Valid values in OnfidoTheme are: AUTOMATIC (default value), LIGHT, DARK.

Web

The Web SDK supports customization options across the SDK screen including text, the SDK main container, buttons, links, icon background color and popups.

To customize the SDK, you can pass the corresponding CSS values to the customUI object. For more information on the available options, see our Web SDK reference.