Documentation
incode.com
  1. SDK Reference
  2. Incode Flutter SDK reference

Common Implementation Patterns

Initialize the SDK

Before starting any onboarding flow, you need to initialize the SDK by calling IncodeOnboardingSdk.init() method.

IncodeOnboardingSdk.init(
  apiKey: 'YOUR_API_KEY',
  apiUrl: 'YOUR_API_URL',
  testMode: false,
  onError: (String error) {
    IncodeSdkInitError? e = error.toIncodeSdkInitError();
    switch (e) {
      case IncodeSdkInitError.simulatorDetected:
        print('Incode init failed, simulator detected: $IncodeSdkInitError.simulatorDetected');
        break;
      case IncodeSdkInitError.testModeEnabled:
        print('Incode init failed, test mode enabled: $IncodeSdkInitError.testModeEnabled');
        break;
      default:
        print('Incode init failed: $error');
        break;
    }
  },
  onSuccess: () {
    // Update UI, safe to start Onboarding
    print('Incode initialized successfully!');
  },
);

apiUrl and apiKey will be provided to you by Incode.
If you're running the app on a simulator, please set the testMode parameter to true.

In case initialization isn't successful, onError() callback will be triggered and the error String will contain more information. Possible values are listed in the IncodeSdkInitError enum: simulatorDetected, testModeEnabled, jailbreakDetected and unknown.

Configure Flows Locally and Run End to End

Use startOnboarding() when you want to configure the flow locally on the device and run all the modules end to end in a single call.

Configure Onboarding session

You should create an instance of OnboardingSessionConfiguration:

OnboardingSessionConfiguration sessionConfig = OnboardingSessionConfiguration();

Optionally, you can provide these parameters to the OnboardingSessionConfiguration object constructor:

  • region: ALL by default
  • onboardingValidationModules: list of OnboardingValidationModule items. This list determines which modules are used for verification and calculation of the onboarding score. If you pass null as validationModuleList, the default values will be used: id, faceRecognition and liveness.
  • customFields: custom fields which are sent to the server.
  • externalId: User identifier outside of Incode Omni database.
  • externalCustomerId: This identifier links the onboarding session to an entity in an external system not part of the Incode Omni Platform. It could represent a prospect Id or a customer Id from the client's database, providing a bridge between the Incode session and the client's internal user management systems.
  • interviewId: Unique identifier of an existing session
  • token: Token of an existing session
  • configurationId: Flow configurationId found on Incode dashboard.
  • e2eEncryptionEnabled: Enable e2e encryption.

Specifying interviewId or token will return an existing session that will be resumed.
Specifying externalId will return an existing session in case a session with the same externalId was already started, otherwise new session will be created.

Configure Onboarding Flow

You should create an instance of OnboardingFlowConfiguration:

OnboardingFlowConfiguration flowConfig = OnboardingFlowConfiguration();

Depending on your needs you should specify the steps you want to include, i.e.:

flowConfig.addIdScan();
flowConfig.addSelfieScan();
flowConfig.addFaceMatch();

The steps will be executed in the order you added them to the flowConfig.

For the full list of modules you can add and their configuration parameters, see the Modules section.

Start the onboarding

IncodeOnboardingSdk.startOnboarding(
  sessionConfig: sessionConfig,
  flowConfig: flowConfig,
  onSuccess: () {
    print('Incode Onboarding completed!');
  },
  onError: (String error) {
    print('Incode onboarding error: $error');
    IncodeSdkFlowError? e = error.toIncodeSdkFlowError();
      // Handle the error accordingly
    switch (e) {
      case IncodeSdkFlowError.permissionsDenied:
        print('Incode SDK onError user denied permissions: $IncodeSdkFlowError.permissionsDenied');
        break;
      // Deprecated: no longer reported. The native SDK terminates the process when a
      // compromised device environment is detected, so this case is never delivered.
      case IncodeSdkFlowError.badEnvDetected:
        print('Incode SDK onError bad environment detected: $IncodeSdkFlowError.badEnvDetected');
        break;
      case IncodeSdkFlowError.jailbreakDetected:
        print('Incode SDK onError jailbreak detected: $IncodeSdkFlowError.jailbreakDetected');
        break;
      case IncodeSdkFlowError.faceAuthenticationFailed:
        print('Incode SDK onError face authentication failed: $IncodeSdkFlowError.faceAuthenticationFailed');
        break;
      case IncodeSdkFlowError.unknown:
        print('Incode SDK onError unknown error: $IncodeSdkFlowError.unknown');
        break;
      default:
        print('Incode SDK onError called: $error');
        break;
    }
  },
  onSelfieScanCompleted: (SelfieScanResult result) {
    print('Selfie completed result: $result');
  },
  onIdFrontCompleted: (IdScanResult result) {
    print('onIdFrontCompleted result: $result');
  },
  onIdBackCompleted: (IdScanResult result) {
    print('onIdBackCompleted result: $result');
  },
  onIdProcessed: (String ocrData) {
    print('onIdProcessed result: $ocrData');
  },
);

Once all the steps are completed by the user, the onSuccess method will be called.
In case some error occurred that stopped the flow from completing, the onError method will be called and the error String will contain more information. Possible values are listed in IncodeSdkFlowError enum.
If user cancels the flow, the onUserCancelled method is triggered.

To listen for the results of the steps in the flow as soon as they're completed, you can add optional callback methods, i.e. onSelfieScanCompleted that was added in the above example.

Optionally, if you want to store ID and Selfie capture session recordings, specify recordSessionConfig parameter to the startOnboarding method. Set OnboardingRecordSessionConfiguration.forcePermission to true if you wish to force the user to accept the recording permissions, otherwise the onboarding session will be aborted.

OnboardingRecordSessionConfiguration recordSessionConfig =  OnboardingRecordSessionConfiguration(recordSession: true, forcePermission: false);

IncodeOnboardingSdk.startOnboarding(
  sessionConfig: sessionConfig,
  flowConfig: flowConfig,
  recordSessionConfig: recordSessionConfig,
  onSuccess: () {
    print('Incode Onboarding completed!');
  },
  onError: (String error) {
    print('Incode onboarding error: $error');
  },
  onSelfieScanCompleted: (SelfieScanResult result) {
    print('Selfie completed result: $result');
  },
  onIdFrontCompleted: (IdScanResult result) {
    print('onIdFrontCompleted result: $result');
  },
  onIdBackCompleted: (IdScanResult result) {
    print('onIdBackCompleted result: $result');
  },
  onIdProcessed: (String ocrData) {
    print('onIdProcessed result: $ocrData');
  },
);

Configure Flows Locally and Run Step by Step

If you would like to use the SDK in a way that the default flow builder doesn't provide, you can separate the Onboarding SDK flow into multiple sections based on your needs, calling individual SDK modules or grouping SDK modules in sections, and returning control to your host application in between.

Set up an onboarding session

Before calling any other Onboarding SDK components it is necessary to set up an onboarding session.

OnboardingSessionConfiguration sessionConfiguration = OnboardingSessionConfiguration();
IncodeOnboardingSdk.setupOnboardingSession(
  sessionConfig: sessionConfiguration,
  onError: (String error) {
    print('Incode onboarding session error: $error');
  },
  onSuccess: (OnboardingSessionResult result) {
    print('Incode Onboarding session created! $result');
  },
);

Session configuration can be configured in the same way as explained in the Configure Onboarding session.

Configure section flow

Once the new onboarding session is created, you can separate Onboarding SDK flow into multiple sections based on your needs.

IncodeOnboardingFlowConfiguration flowConfig = IncodeOnboardingFlowConfiguration();
flowConfig.addIdScan();

For the full list of modules you can add and their configuration parameters, see the Modules section.

Start onboarding section

Once the IncodeOnboardingFlowConfiguration is created, call the following method and provide a required flowTag as an identifier for the section:

IncodeOnboardingSdk.startNewOnboardingSection(
  flowConfig: flowConfig,
  flowTag: 'idSection',
  onError: (String error) {
    print('Incode onboarding session error: $error');
  },
  onIdFrontCompleted: (IdScanResult result) {
    print('onIdFrontCompleted result: $result');
  },
  onIdBackCompleted: (IdScanResult result) {
    print('onIdBackCompleted result: $result');
  },
  onIdProcessed: (String ocrData) {
    print('onIdProcessed result: $ocrData');
  },
  onOnboardingSectionCompleted: (String flowTag) {
    print('section completed');
  },
);

Finish onboarding session

Make sure to call finishFlow() at the end of the flow (when you are sure user has finished all onboarding modules, and you won't be reusing same interviewId again).

IncodeOnboardingSdk.finishFlow();

Run Flows Configured Online

Use startFlow() (and startWorkflow()) when your flow is configured online on the Incode dashboard.

Start flow

Starts the flow based on the OnboardingSessionConfiguration provided - specify the configurationId, and optionally the interviewId if you want to resume a certain onboarding session and/or moduleId to start from a specific step within the flow.

 OnboardingSessionConfiguration sessionConfig = OnboardingSessionConfiguration(
   configurationId: "YOUR_CONFIGURATION_ID",
   interviewId: "YOUR_INTERVIEW_ID"
); // optional

IncodeOnboardingSdk.startFlow(
   sessionConfig: sessionConfig,
   moduleId: 'YOUR_MODULE_ID', // optional, ie. "PHONE"
   onError: (String error) {
    print('Incode startFlow error: $error');
   },
   onSuccess: () {
    print('Incode startFlow completed!');
   },
   onUserCancelled: () {
    print('User cancelled');
   },
);

Start flow from deep link

Starts the flow based on the deeplink URL. This method will read configurationId, interviewId and a step from which it should start.

   IncodeOnboardingSdk.startFlowFromDeepLink(
      url: 'YOUR_DEEPLINK_URL',
      onError: (String error) {
        print('Incode startFlowFromDeepLink error: $error');
      },
      onSuccess: () {
        print('Incode startFlowFromDeepLink completed!');
      },
      onUserCancelled: () {
        print('User cancelled');
      },
    );