Introduction

This guide is intended as a migration reference for integrators migrating from the (legacy) Onfido Smart Capture SDKs to the new Entrust IDV SDKs, released in early 2026.

Notes:

• Migration information for the Flutter SDK will be added in H1 2026 when the new Entrust IDV SDK for Flutter is released
• The Web SDK is not yet in scope for this migration, with more information to be provided in H1 2026

It is highly recommended for all integrators to adopt Workflow Studio as part of their SDK migration, if orchestration is still based on manual step definitions. This will ensure a futureproof integration experience.

For the complete context and specifications of the Entrust IDV SDKs, please refer to its dedicated integration guide.

Summary of changes

New features:

• API:

  • All mobile SDKs now share the same API and configurability, closing any gaps that existed between previous versions. The new Flutter SDK (when released in early 2026) will follow the new, shared API
  • Error codes returned by the SDK are streamlined across all SDKs and are now grouped and labeled by 'category' to simplify integration effort
  • While the Exit button (X) is now visible by default, the abililty to hide the component (along the entire navigation bar) is available as part of the API

• Bundles: SDK bundle sizes have been dramatically reduced to under 3MB by default. At its minimum sizes, SDKs are fully functional with integrators given the option to add project dependencies for modules that need to be executed locally (instead of the default Web/JS version)

• Languages:

  • All SDKs now support the ability to predefine a language for use during a given flow
  • All SDKs now support localization based on the i18n pattern, already used by the Web SDK
  • (new) Integrators can reduce the languages available to end users by specifying a subset of the 44 supported languages during initialization

• UI:

  • The screen layouts have been updated to match the redesign introduced by the Web SDK 14.44.0. All SDKs are now visually aligned
  • All SDKs now have the same customization scope with common UI customization tokens and behaviors
  • Customizatition of the brand footer at the bottom of all screens no longer requires activation and is available by default

Deprecation:

• The iOS SDK is now solely distributed via Swift Package Manager as Cocoapods is nearing end-of-life
• The iOS SDK API is now only available in Swift, with no interface provided for Objective-C
• The ability to refresh SDK tokens is no longer supported as the validity of the new Studio SDK tokens is linked to the validation of the underlying workflow (typically 14 days)
• The UI no longer includes the 'Powered by Onfido' brand footer. The functionality to apply a custom brand remains available (and no longer requires activation)

Not yet released:

• SSL Certificate pinning
• Text overrides available via local bundle files (currently provided as delta during initialization of SDK)
• Ability to override the border radius of buttons in the UI
• Ability to modify typography (font size, weight etc.)

Breaking Changes

Minimum library versions

Android

iOS

React Native

SDK initialization

The overall SDK initialization process remains the same with regard to the applicant, workflow run and SDK token generation.

It is highly recommended for all integrators to adopt Workflow Studio as part of their SDK migration if orchestration is still based on manual step definitions. This will ensure a futureproof integration experience.

Android

iOS

React Native

1override fun onCreate(savedInstanceState: Bundle?) {
2  super.onCreate(savedInstanceState)
3  EntrustIdv.start(
4    StudioParameters(
5      sdkToken = "<SDK_STUDIO_TOKEN>"
6    )
7)}

1const val REQUEST_CODE = 0x05
2private lateinit var onfidoWorkflow: OnfidoWorkflow
3
4fun onCreate(savedInstanceState: Bundle?) {
5  val workflowConfig = WorkflowConfig.Builder(
6    workflowRunId = "<WORKFLOW_RUN_ID>",
7    sdkToken = "<SDK_TOKEN>"
8  ).build()
9}
10
11onfidoWorkflow = OnfidoWorkflow.create(this)
12startActivityForResult(onfidoWorkflow.createIntent(workflowConfig), REQUEST_CODE)

1@MainActor
2func startEntrustIdvSDK(from viewController: UIViewController) {
3  let parameters = StudioParameters(
4    sdkToken: "<SDK_STUDIO_TOKEN>"
5  )
6  let entrustIdv = EntrustIdv(
7    sdkParameters: parameters,
8    callbacks: callbacks    // Defined in next section
9  )
10  entrustIdv.start(from: viewController)
11}

1let workflowConfiguration = WorkflowConfiguration(
2  workflowRunId: "<WORKFLOW_RUN_ID>",
3  sdkToken: "<SDK_STUDIO_TOKEN>"
4)
5let onfidoRun = OnfidoFlow(workflowConfiguration: orchestrationConfig)
6customerViewController.present(
7  try onfidoRun.run(),
8  animated: true,
9  completion: nil
10)

1entrustIdv.start({
2  sdkToken: "<SDK_STUDIO_TOKEN>",
3})

1config = {
2  workflowRunId: "<WORKFLOW_RUN_ID>"
3  sdkToken: "<SDK_STUDIO_TOKEN>",
4}
5Onfido.start(config);

Mandatory callbacks

Callback functionality remains unchanged with the new versions. The main difference is the alignment of callback payloads across all SDK platforms.

For details about the optional callbacks, refer to the dedicated section of the integration guide.

Android

iOS

React Native

1private val entrustIdv = EntrustIdv(
2  activity = this,
3  callbacks = Callbacks(
4    onComplete = { result -> ...
5      // The verification flow was completed successfully with result: $result
6    },
7    onError = { error -> ...
8      // Flow errored with category:${error.type.category} and  type ${error.type.name}/${error.type.message}
9    },
10    onUserExit = { userAction -> ...
11      // User exited the verification flow. Reason: $exitReason
12  })
13)

1override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
2  onfidoWorkflow.handleActivityResult(resultCode, data, object : OnfidoWorkflow.ResultListener {
3    override fun onUserCompleted() {
4      // Corresponds to `onComplete`
5    }
6    override fun onUserExited(exitCode: ExitCode) {
7      // Corresponds to `onUserExit`
8    }
9    override fun onException(exception: OnfidoWorkflow.WorkflowException) {
10      // Corresponds to `onError`
11    }
12  })
13}

1@MainActor
2func startEntrustIdvSDK(from viewController: UIViewController) {
3  let callbacks :Callbacks = Callbacks(
4    onComplete: { (results: [String: CaptureResult]) in ...
5      // The verification flow was completed successfully with result: $result
6    },
7    onError: { (error: IdvError) in ...
8      // Flow errored with category:${error.type.category} and  type ${error.type.name}/${error.type.message}
9    },
10    onUserExit: { (userAction: UserAction) in ...
11      // User exited the verification flow. Reason: $exitReason
12    }
13  )
14}

1onfidoRun.with(responseHandler: { (response: OnfidoResponse) in
2  switch response {
3    case .success: ...              // Corresponds to `onComplete`
4    case .cancel(let cancellationReason): ...   // Corresponds to `onUserExit`
5    case .error(let error): ...     // Corresponds to `onError`
6  }
7})

1const entrustIdv = new EntrustIdv({
2  onComplete: (result) => {
3    // The verification flow was completed successfully with result: $result
4  },
5  onError: (error) => {
6    // Flow errored with category:${error.type.category} and  type ${error.type.name}/${error.type.message}
7  },
8  onUserExit: (userAction) => {
9    // User exited the verification flow. Reason: $exitReason
10  },
11})

1Onfido.start(config)
2  .then(res => ... )    // Corresponds to `onComplete`
3  .catch(err => ... )   // Corresponds to `onError`

By default and as per previous versions, the result payload returned by the completion callback, is an empty object for workflow-based sessions:

• The uploaded media are automatically processed by the workflow to generate reports
• If required, the media can be retrieved via the dedicated Document, Face Photo and Face Video API endpoints

The following tables provide the schema of the result payload for sessions that are yet to migrate to Workflow Studio.

1{
2"document": {
3  "type": "driving_licence",
4  "sides": {
5    "front": { "id": "<DOCUMENT_ID_FRONT>" },
6    "back":  { "id": "<DOCUMENT_ID_BACK>" },
7    "front_video": { "id": "<DOCUMENT_ID_FRONT_VIDEO>" },
8    "back_video":  { "id": "<DOCUMENT_ID_BACK_VIDEO>" }
9  }
10},
11"facePhoto":  { "id": "<MEDIA_ID>" },
12"faceVideo":  { "id": "<MEDIA_ID>" },
13"faceMotion": { "id": "<MEDIA_ID>" },
14"poa": {
15  "type": "utility_bill",
16  "sides": {
17    "front": { "id": "<POA_DOCUMENT_ID_FRONT>" },
18    "back":  { "id": "<POA_DOCUMENT_ID_BACK>" },
19    "front_video": { "id": "<POA_DOCUMENT_ID_FRONT_VIDEO>" },
20    "back_video":  { "id": "<POA_DOCUMENT_ID_BACK_VIDEO>" }
21  }
22}}

1{
2"document": {
3  "type": "DRIVING_LICENCE"
4    "front": {
5      "id": "document_id",
6      "side": "FRONT",
7      "type": "DRIVING_LICENCE",
8      "nfcSupported": false
9    },
10    "back": {
11      "id": "document_id",
12      "side": "BACK",
13      "type": "DRIVING_LICENCE",
14      "nfcSupported": false
15    },
16},
17"face": {
18  "id": "face_id",
19  "variant": "PHOTO"
20},
21"proofOfAddress": {
22  "type": "UTILITY_BILL",
23  "front": {
24    "id": "front_side_id",
25    "type": null
26  },
27  "back": {
28    "id": "back_side_id",
29    "type": null
30  }
31}}

The error payload returned by the error callback is defined as:

1{
2  "error": {
3    "errorType": {
4      "category": <<Error category>>,
5      "type": <<Error Type>>
6    },
7    "message": string
8  }
9}

The userAction payload returned by the callback is defined as:

UI Customization

The process for customizing the UI has been streamlined and aligned across all SDKs. The main differences include:

• Token names have been changed and streamlined across all SDKs
• Colors are now customized globally instead of per-component to reduce the amount of duplication

The complete description is available in the UI customization section of the integration guide.

Pre-selection of theme

Android

iOS

React Native

1EntrustIdv.start(
2  configuration = Configuration(
3    theme = Theme(
4      mode = ThemeMode.Light // or ThemeMode.Dark
5  ))
6)

1onfidoConfigBuilder.withTheme(
2  OnfidoTheme.DARK // or OnfidoTheme.LIGHT or OnfidoTheme.AUTOMATIC
3)

1EntrustIdv(
2  configuration: .init(
3    theme: .init(
4      mode: ThemeMode.light    // or ThemeMode.dark
5  ))
6)

1let appearance = Appearance()
2appearance.setUserInterfaceStyle(.dark)   // or .light or .unspecified (default)
3
4let configBuilder = OnfidoConfig.builder()
5configBuilder.withAppearance(appearance)  // Then apply the 'appearance' object

1entrustIdv.start({
2  configuration: {
3    theme: {
4      mode: ThemeMode.Light,    // or ThemeMode.Dark
5  }}
6});

Color customization

A key simplification introduced by the new SDK is that colors are modified centrally during initialization so that they can be applied uniformly across all UI assets.

The detailed mapping and mechanics of color customization is provided in the dedicated SDK UI Customization Guide.

The full mapping of legacy UI tokens to new is provided in the Appendix - UI token mapping.

Android

iOS

React Native

1configuration = Configuration(
2  theme = Theme(
3    lightColors = mapOf(
4      ColorTokens.BackgroundColorBrandDefault to "#FF00FF85",
5      ColorTokens.ContentColorBase to "#0B1B0B",
6    ),
7    darkColors = mapOf(
8      ColorTokens.BackgroundColorBrandDefault to "#0000FF85",
9      ColorTokens.ContentColorBase to "#FF1CFF",
10    ),
11))

1<!-- Light theme -->
2<style name="OnfidoLightTheme" parent="OnfidoBaseActivityTheme">
3  <item name="onfidoColorToolbarBackground">@color/brand_dark_blue</item>
4  <item name="onfidoColorActionMain">@color/brand_accent_color</item>
5</style>
6
7<!-- Dark theme -->
8<style name="OnfidoDarkTheme" parent="OnfidoBaseDarkTheme">
9  <item name="onfidoColorToolbarBackground">@color/brand_dark_blue</item>
10  <item name="onfidoColorActionMain">@color/brand_accent_color</item>
11</style>

1EntrustIdv(
2  configuration: .init(
3    theme: .init(
4      lightColors: [
5        ColorTokens.backgroundColorBrandDefault: "#FF00FF85",
6        ColorTokens.contentColorBase: "#0B1B0B"
7      ],
8      darkColors: [
9        ColorTokens.backgroundColorBrandDefault: "#0000FF85",
10        ColorTokens.contentColorBase: "#FF1CFF"
11      ],
12  ))
13)

1let appearance = Appearance()
2appearance.primaryColor = <DESIRED_UI_COLOR_HERE>
3appearance.primaryTitleColor = <DESIRED_UI_COLOR_HERE>
4
5let configBuilder = OnfidoConfig.builder()
6configBuilder.withAppearance(appearance)   // Then apply the 'appearance' object

1entrustIdv.start({
2  configuration: {
3    theme: {
4      lightColors: {
5        backgroundColorBrandDefault: '#FF00FF85',
6        contentColorBase: '#0b1c0b'
7      },
8      darkColors: {
9        backgroundColorBrandDefault: '#0000FF85',
10        contentColorBase: '#FF1cFF'
11      }
12  }}
13});

Brand footer customization

Android

iOS

React Native

1EntrustIdv.start(
2  configuration = Configuration(
3  theme = Theme(
4    branding = Branding(
5    text = "Custom Text",
6    logo = "https://upload.wikimedia.org/wikipedia/commons/d/d7/Android_robot.svg",
7    ),
8  ))
9)

1val enterpriseFeatures = EnterpriseFeatures.builder()
2  .withCobrandingText("MyCompany")
3  .withCobrandingLogo(
4    R.drawable.logo_light_mode, 
5    R.drawable.logo_dark_mode
6  )
7  .build()
8
9OnfidoConfig.builder(<context>)
10  .withEnterpriseFeatures(enterpriseFeatures)
11  .build()

1EntrustIdv(
2  configuration: .init(
3    theme: .init(
4      branding: .init(
5        text: "Custom Text",
6        logo: "https://commons.wikimedia.org/wiki/File:Apple_Logo.svg",
7      ),
8  ))
9)

1let enterpriseFeatures = EnterpriseFeatures.builder()
2  .withCobrandingText("MyCompany")
3  .withCobrandingLogo(
4    UIImage(
5      named: "imageName_for_lightmode"
6    )!,
7    cobrandingLogoDarkMode: UIImage(
8      named: "imageName_for_darkmode"
9    )!
10  )
11  .build()
12
13  let configBuilder = OnfidoConfig.builder()
14  configBuilder.withEnterpriseFeatures(enterpriseFeatures) // Then add 'enterpriseFeatures' object

1entrustIdv.start({
2  configuration: {
3    theme: {
4      branding: {
5        text: "Custom Text",
6        logo: "https://commons.wikimedia.org/wiki/File:React_Native_Logo.png"
7  }}}
8});

1Onfido.start({
2  logoCobrand: "<TRUE/FALSE>"
3})

Text and Locale Customization

The Entrust IDV SDK continues to support all languages/locales previously supported. The API now aligns all text customization options and follows the i18n pattern.

Android

iOS

React Native

1EntrustIdv.start(
2  configuration = Configuration(
3    localisation = Localisation(
4      language = "en"
5      allowedLanguages = listOf("en", "el") // New
6      overrides = mapOf(
7        "en" to mapOf(
8          "welcome.title" to "Custom welcome title",
9      )),
10)))

1final OnfidoConfig config = OnfidoConfig.builder()
2  .withLocale(fr)
3  .build();

1EntrustIdv(
2  configuration: .init(
3    theme: .init(localisation: .init(
4      language: "en",
5      allowedLanguages: ["en", "el"], // New
6      overrides: [
7        "en": [
8        "welcome.title": "Custom welcome title",
9        ]
10      ]
11  )))
12)

1(void)withCustomLocalization {
2  [self.configBuilder withCustomLocalization];
3}

1entrustIdv.start({
2  configuration: {
3    localisation: {
4      language: 'en',     // New (for React Native)
5      allowedLanguages: ['en', 'el'],   // New
6      overrides: {
7        en: {
8          'welcome.title': 'Custom welcome title',
9        },
10      },
11  }}
12});

1Onfido.start({
2  localisation: {
3    ios_strings_file_name: '<Your .strings file name in iOS app bundle>', // Only required for iOS
4  },
5})

The full list of new capabilities and how to identify text strings is available in the SDK integration guide.

Module Configuration

The configuration of sessions orchestrated with Workflow Studio remain unchanged. It is highly recommended for all integrators to adopt Workflow Studio as part of their SDK migration.

For integrations that are yet to migrate to workflow-based orchestration, the API for each of Document, Face (for all variants) and ProofOfAddress has been simplified to be common across all SDKs.

Details are available in the SDK integration guide.

Appendix - UI token mapping

This section only highlights the mapping of the legacy UI customization tokens used by the Onfido Smart Capture iOS, Android and React Native SDKs to their Entrust IDV SDK equivalent. The full list of UI customization tokens provided by the Entrust IDV SDKs is avaialble in the dedicated SDK UI Customization guide.

The ability to customize typography and border radii will be documented in an upcoming release.