initialize

Initializes the native Incode SDK. Must be called at least once per app lifecycle before any other operation.

Signature

IncodeSdk.initialize({
  testMode?: boolean;
  apiConfig: {
    key?: string;
    url: string;
    e2eeUrl?: string;
  };
  sdkMode?: 'standard' | 'captureOnly' | 'submitOnly';
  waitForTutorials?: boolean;
  sslPinningConfig?: { enabled: boolean };
  disableJailbreakDetection?: boolean;
  externalAnalyticsEnabled?: boolean;
  loggingEnabled?: boolean;
  externalScreenshotsEnabled?: boolean;
  clientExperimentId?: string | null;
}): Promise<void>

Required Parameters

• apiConfig.url: API URL provided by Incode.

Optional Parameters

• testMode: Set to true if running on simulators/emulators, false when running on devices. Default is false.
• apiConfig.key: API key provided by Incode. Omit this when using a backend-created token with the Sections API.
• apiConfig.e2eeUrl: Custom server URL used for End-to-End Encryption (E2EE).
• sdkMode: Specify standard, captureOnly, or submitOnly. Default is standard. captureOnly works completely offline and for ID and Selfie scan only captures images without validations. submitOnly submits previously captured data without performing new captures.
• waitForTutorials: Specify false to let users press continue on video tutorial screens without waiting for the video to complete. Default is true.
• sslPinningConfig.enabled: Set to true to enable SSL pinning, false otherwise.
• disableJailbreakDetection: Set to true to disable jailbreak detection. Valid only for iOS. Default is false.
• externalAnalyticsEnabled: Set to true to enable external analytics. Default is true.
• loggingEnabled: Set to true to enable logging. Default is true.
• externalScreenshotsEnabled: Set to true to enable external screenshots. Default is false.
• clientExperimentId: Used to enroll the customer into experimental features like ID V2.

Returns / Callbacks

• Returns Promise<void> when initialization succeeds.
• Rejects with IncodeSdkInitError. Exported code values include simulatorDetected, testModeEnabled, invalidInitParams, configError, and unknown. Older native payloads may also include `activityNotPresent.

Example

try {
  await IncodeSdk.initialize({
    testMode: false,
    apiConfig: {
      key: 'YOUR_API_KEY',
      url: 'YOUR_API_URL',
    },
  });
  console.log('Incode initialized successfully');
} catch (error) {
  const e = error as IncodeSdkInitError;
  console.error(e.code + ' - ' + e.message);
}

isInitialized

Checks whether the native Incode SDK has finished initialization.

Signature

IncodeSdk.isInitialized(): Promise<boolean>

Parameters

• None.

Returns / Callbacks

• Returns Promise<boolean> that resolves to true if the native SDK is initialized, otherwise false.

Example

const ready = await IncodeSdk.isInitialized();
if (ready) {
  // Safe to start onboarding.
}

setSdkMode

Changes the SDK mode after initialization.

Signature

IncodeSdk.setSdkMode(
  sdkMode: 'standard' | 'captureOnly' | 'submitOnly'
): Promise<any>

Required Parameters

• sdkMode: One of standard, captureOnly, or submitOnly.

Returns / Callbacks

• Returns a promise that resolves after the native SDK mode is updated.
• Rejects if sdkMode is not one of the supported values.

Example

await IncodeSdk.setSdkMode('captureOnly');

startOnboarding

Creates a session and runs a complete, locally-defined onboarding flow end to end.

Signature

IncodeSdk.startOnboarding({
  sessionConfig?: OnboardingSessionConfig;
  flowConfig?: OnboardingFlowConfig;
  recordSessionConfig?: OnboardingRecordSessionConfig;
}): Promise<OnboardingResponse>

Optional Parameters

• sessionConfig: Session configuration. Use it to pass region, queue, dashboard configuration, backend-created interviewId/token, custom fields, validation modules, E2EE, and recording settings.
• flowConfig: Ordered list of modules to execute. See Modules.
• recordSessionConfig: Optional configuration for recording ID and Selfie capture.

Returns / Callbacks

• Returns Promise<OnboardingResponse>.
• Resolves with { status: 'success' } when the flow completes.
• Resolves with { status: 'userCancelled' } when the user cancels.
• Rejects with IncodeSdkFlowError. Exported code values include simulatorDetected, rootDetected, hookDetected, virtualEnvDetected, permissionsDenied, jailbreakDetected, faceAuthenticationFailed, and unknown.

Example

const result = await IncodeSdk.startOnboarding({
  sessionConfig: {
    region: 'ALL',
  },
  flowConfig: [
    { module: 'IdScan' },
    { module: 'SelfieScan' },
    { module: 'FaceMatch' },
  ],
});

setupOnboardingSession

Creates or attaches to an onboarding session for section-based flows.

Signature

IncodeSdk.setupOnboardingSession({
  sessionConfig?: OnboardingSessionConfig;
}): Promise<OnboardingSession>

Optional Parameters

• sessionConfig: Session configuration. Provide token or interviewId to attach to a backend-created session.

Returns / Callbacks

• Returns Promise<OnboardingSession>.
• interviewId: Unique identifier of the onboarding session.
• token: Token created for this onboarding session.

Example

const session = await IncodeSdk.setupOnboardingSession({
  sessionConfig: {
    token: 'YOUR_TOKEN',
  },
});

console.log(session.interviewId, session.token);

startOnboardingSection

Starts one section in a section-based flow.

Signature

IncodeSdk.startOnboardingSection({
  flowConfig?: OnboardingFlowConfig;
  recordSessionConfig?: OnboardingRecordSessionConfig;
  sectionTag?: string;
}): Promise<OnboardingSectionResponse>

Optional Parameters

• flowConfig: Ordered list of modules for this section. startOnboardingSection accepts the same modules as startOnboarding; see Modules.
• recordSessionConfig: Optional configuration for recording ID and Selfie capture.
• sectionTag: Unique identifier for the section you want to start.

Returns / Callbacks

• Returns Promise<OnboardingSectionResponse>.
• status: success or userCancelled.
• sectionTag: Value of the sectionTag parameter passed in config.

Example

const idSection = await IncodeSdk.startOnboardingSection({
  flowConfig: [{ module: 'IdScan' }],
  sectionTag: 'idSection',
});

if (idSection.status === 'success') {
  await IncodeSdk.startOnboardingSection({
    flowConfig: [{ module: 'SelfieScan' }],
    sectionTag: 'selfieSection',
  });
}

You can start multiple sections, but only one at a time. Call finishOnboardingFlow() after all sections complete.

finishOnboardingFlow

Finishes the current section-based onboarding session.

Signature

IncodeSdk.finishOnboardingFlow(): Promise<any>

Parameters

• None.

Returns / Callbacks

• Returns a promise that resolves after the current section-based onboarding session is finished.

Example

await IncodeSdk.finishOnboardingFlow();

startFlow

Starts a dashboard-configured flow.

Signature

IncodeSdk.startFlow({
  sessionConfig?: OnboardingSessionConfig;
  moduleId?: string;
}): Promise<OnboardingResponse>

Required Parameters

• sessionConfig.configurationId: Configuration ID of a flow on the dashboard.

Optional Parameters

• sessionConfig: Same session configuration shape used by startOnboarding.
• moduleId: Module name to start the flow from, for example EMAIL or PHONE. If omitted, the flow starts from the first module in the configuration.

Returns / Callbacks

• Returns Promise<OnboardingResponse>.
• Resolves with { status: 'success' } or { status: 'userCancelled' }.
• Rejects with IncodeSdkFlowError.

Example

await IncodeSdk.startFlow({
  sessionConfig: {
    configurationId: 'YOUR_CONFIGURATION_ID',
  },
  moduleId: 'EMAIL',
});

startWorkflow

Starts a dashboard-configured workflow.

Signature

IncodeSdk.startWorkflow({
  sessionConfig?: OnboardingSessionConfig;
}): Promise<OnboardingResponse>

Required Parameters

• sessionConfig.configurationId: Configuration ID of a workflow on the dashboard.

Optional Parameters

• sessionConfig: Same session configuration shape used by startOnboarding.

Returns / Callbacks

• Returns Promise<OnboardingResponse>.
• Resolves with { status: 'success' } or { status: 'userCancelled' }.
• Rejects with IncodeSdkFlowError.

Example

const result = await IncodeSdk.startWorkflow({
  sessionConfig: {
    configurationId: 'YOUR_CONFIGURATION_ID',
  },
});

startFlowFromDeepLink

Starts a flow from a deep link URL.

Signature

IncodeSdk.startFlowFromDeepLink(
  url?: string,
  isShortened?: boolean
): Promise<OnboardingResponse>

Optional Parameters

• url: Deep link URL.
• isShortened: Specify whether the URL is shortened. Defaults to false.

Returns / Callbacks

• Returns Promise<OnboardingResponse>.
• Rejects with IncodeSdkFlowError.

Example

await IncodeSdk.startFlowFromDeepLink('YOUR_DEEP_LINK_URL', false);

onSessionCreated

Subscribes to onboarding session creation events.

Signature

IncodeSdk.onSessionCreated(
  listener: (session: OnboardingSession) => void
): () => void

Required Parameters

• listener: Callback that receives OnboardingSession.

Returns / Callbacks

• Returns an unsubscriber function.
• Listener receives interviewId and token.

Example

const unsubscribe = IncodeSdk.onSessionCreated((session) => {
  console.log('Onboarding session created, interviewId: ' + session.interviewId);
});

onStepCompleted

Subscribes to step completion events for a specific module.

Signature

IncodeSdk.onStepCompleted({
  module: string;
  listener: (event: StepCompletedEvent) => void;
}): () => void

Required Parameters

• module: Module name to listen for.
• listener: Callback invoked when the selected module completes.

Returns / Callbacks

• Returns an unsubscriber function.
• Listener payloads are documented in Results.

Example

const unsubscribe = IncodeSdk.onStepCompleted({
  module: 'SelfieScan',
  listener: (event) => {
    console.log('SELFIE SCAN completed', event.result);
  },
});

onStepUpdated

Subscribes to in-progress step update events.

Signature

IncodeSdk.onStepUpdated({
  module: 'Conference' | 'IdScanFront' | 'IdScanBack' | 'SelfieScan';
  listener: (event: StepUpdatedEvent) => void;
}): () => void

Required Parameters

• module: Supported update module: Conference, IdScanFront, IdScanBack, or SelfieScan.
• listener: Callback invoked when the selected module emits an update.

Returns / Callbacks

• Returns an unsubscriber function.
• Fires for Conference queue/wait-time changes and after every individual capture attempt for IdScanFront, IdScanBack, and SelfieScan.

Example

const unsubscribe = IncodeSdk.onStepUpdated({
  module: 'IdScanFront',
  listener: (event) => {
    console.log('ID Scan Front Attempt: ', event.result);
    console.log('allAttemptsExhausted:', event.result.allAttemptsExhausted);
  },
});

onStepError

Subscribes to module error events.

Signature

IncodeSdk.onStepError({
  module: string;
  listener: (event: StepErrorEvent) => void;
}): () => void

Required Parameters

• module: Module name to listen for.
• listener: Callback invoked when the selected module emits an error.

Returns / Callbacks

• Returns an unsubscriber function.
• Error payloads are documented in Results.

Example

const unsubscribe = IncodeSdk.onStepError({
  module: 'FaceMatch',
  listener: (event) => {
    console.log('FaceMatch error', event);
  },
});

onEvents

Subscribes to tracking events.

Signature

IncodeSdk.onEvents(
  listener: (events: Events) => void
): () => void

Required Parameters

• listener: Callback invoked with { events: EventDetails[] }.

Returns / Callbacks

• Returns an unsubscriber function.
• Register before starting the flow.

Example

const unsubscribe = IncodeSdk.onEvents((eventBatch) => {
  for (const event of eventBatch.events) {
    console.log(event.event, event.data);
  }
});

approve

Programmatically initiates approval of the current user.

Signature

IncodeSdk.approve({
  forceApproval: boolean;
}): Promise<ApprovalResult>

Required Parameters

• forceApproval: If true, the user will be force-approved.

Older text may call this setting forceApprove; in the React Native SDK config object the current parameter is forceApproval.

Returns / Callbacks

• Returns Promise<ApprovalResult>.
• Result contains status, id, and customerToken.
• The field status can take values: approved and failed.

Example

IncodeSdk.approve({ forceApproval: false })
  .then((result) => {
    console.log('approve finished: ', result);
  })
  .catch((error) => {
    console.log('approve error: ', error);
  });

getUserScore

Fetches the current user score programmatically.

Signature

IncodeSdk.getUserScore(config?: {
  mode?: 'accurate' | 'fast';
}): Promise<UserScore>

Optional Parameters

• mode: accurate or fast. Defaults to accurate. accurate fetches server-side results and can take longer; fast uses on-device processing.

Returns / Callbacks

• Returns Promise<UserScore>.
• Result contains the same data as the UserScore module result.

Example

IncodeSdk.getUserScore({ mode: 'accurate' })
  .then((score) => console.log(score))
  .catch((error) => {
    console.error('Get user score failed', error);
  });

faceMatch

Programmatically initiates face match between photo from the ID and Selfie.

Signature

IncodeSdk.faceMatch(): Promise<FaceMatchCompleteEvent>

Parameters

• None.

Returns / Callbacks

• Returns Promise<FaceMatchCompleteEvent>.
• Runs silently in the background, compared to the regular FaceMatch module that shows UI feedback to the user.

Example

IncodeSdk.faceMatch()
  .then((faceMatchResult) => {
    console.log('Face match result: ', faceMatchResult);
  })
  .catch((error) => {
    console.error('Face match failed', error);
  });

startFaceLogin

Starts Face Login authentication. A prerequisite for a successful Face Login is that the user has an approved account with an enrolled face.

Signature

IncodeSdk.startFaceLogin({
  showTutorials: boolean;
  customerUUID?: string;
  faceMaskCheck?: boolean;
  lensesCheck?: boolean;
  brightnessThreshold?: number;
  logAuthenticationEnabled?: boolean;
  e2eeEncryptionEnabled?: boolean;
}): Promise<FaceLoginResult>

Required Parameters

• showTutorials: Show tutorials before Face Login.

Optional Parameters

• customerUUID: Required for 1:1 Face Login. Omit for 1:N database lookup.
• faceMaskCheck: Specify true to prevent login for users wearing a face mask.
• lensesCheck: Specify whether the SDK should check for lenses/glasses.
• brightnessThreshold: Deprecated. Adjusts minimum lighting requirements.
• logAuthenticationEnabled: Enable authentication logging.
• e2eeEncryptionEnabled: Enable E2EE for the authentication flow.

Returns / Callbacks

• Returns Promise<FaceLoginResult>.
• Response fields are documented in Results.

Example

1:1 Face Login performs a 1:1 face comparison and returns a successful match if the two faces match. For 1:1 Face Login, you need the user's customerUUID. If the user was approved during onboarding on the mobile device, you should have received customerUUID as a result of the Approve step.

const result = await IncodeSdk.startFaceLogin({
  showTutorials: true,
  customerUUID: 'YOUR_CUSTOMER_UUID',
  faceMaskCheck: false,
  lensesCheck: false,
  logAuthenticationEnabled: false,
  e2eeEncryptionEnabled: false,
});

1:N Face Login performs a database face lookup and returns a successful match if the face is found in the database. Omit customerUUID for 1:N Face Login.

const result = await IncodeSdk.startFaceLogin({
  showTutorials: true,
  faceMaskCheck: false,
  lensesCheck: false,
  logAuthenticationEnabled: false,
  e2eeEncryptionEnabled: false,
});

To enable faceMaskCheck on Android, add:

Gradle

implementation 'com.incode.sdk:model-mask-detection:2.0.0'

deleteLocalUserData

Deletes locally stored onboarding session data on Android devices.

Signature

IncodeSdk.deleteLocalUserData(): Promise<any>

Parameters

• None.

Returns / Callbacks

• Returns a promise that resolves after local onboarding data is deleted.
• This can remove up to 5-6 MB of data stored locally during onboarding.

Older text may refer to this method as deleteUserLocalData; the current React Native SDK method is deleteLocalUserData.

Example

await IncodeSdk.deleteLocalUserData();

showCloseButton

Shows or hides the close button during SDK flows.

Signature

IncodeSdk.showCloseButton(
  shouldShowCloseButton: boolean
): Promise<void>

Required Parameters

• shouldShowCloseButton: Set to true to show the close button, or false to hide it.

Returns / Callbacks

• Returns Promise<void>.
• When the user presses the close button, the flow is aborted.

Example

IncodeSdk.showCloseButton(true);

setLocalizationLanguage

Sets runtime localization language.

Signature

IncodeSdk.setLocalizationLanguage(
  language: string
): Promise<string>

Required Parameters

• language: Language used for runtime localization. Supported values are currently en, es, and pt.

Returns / Callbacks

• Returns Promise<string>.

Example

await IncodeSdk.setLocalizationLanguage('en');

Android requires:

Gradle

implementation 'com.incode.sdk:extensions:1.2.1'

setString

Sets and updates string resources at runtime.

Signature

IncodeSdk.setString(
  strings: { [key: string]: string }
): Promise<void>

Required Parameters

• strings: Map of string keys and values.

Returns / Callbacks

• Returns Promise<void>.

Some native documentation writes this as IncodeSDK.setString; in React Native, call IncodeSdk.setString.

Example

IncodeSdk.setString({
  // iOS labels
  'incdOnboarding.idChooser.idButton': 'Id',
  // Android labels
  onboard_sdk_btn_passport: 'Passport',
});

Android requires:

Gradle

implementation 'com.incode.sdk:extensions:1.2.1'

For iOS, see Localization Guide. For Android, see Dynamic Localization.

setQuantityStrings

Sets Android plural strings at runtime.

Signature

IncodeSdk.setQuantityStrings(
  strings: { [key: string]: any }
): Promise<any>

Required Parameters

• strings: Map of language codes to plural string keys and plural values.

Returns / Callbacks

• Returns a promise that resolves after plural strings are updated.

Example

await IncodeSdk.setQuantityStrings({
  en: {
    onboard_sdk_validation_attempts_remaining: {
      one: '%d attempt remaining',
      other: '%d attempts remaining',
    },
  },
});

setTheme

Applies a JSON theme.

Signature

IncodeSdk.setTheme({
  jsonTheme: string;
}): Promise<any>

Required Parameters

• jsonTheme: JSON string containing theme configuration.

Returns / Callbacks

• Returns a promise that resolves after the theme is applied.

Example

await IncodeSdk.setTheme({
  jsonTheme: JSON.stringify({
    colors: {
      accent: '#00B2FD',
      primary: '#20263D',
    },
  }),
});

setUXConfig

Applies UX configuration for V2 ID scan and Selfie experiences.

Signature

IncodeSdk.setUXConfig({
  jsonConfig: string;
}): Promise<any>

Required Parameters

• jsonConfig: JSON string containing UX configuration.

Returns / Callbacks

• Returns a promise that resolves after the UX configuration is applied.

Example

await IncodeSdk.setUXConfig({
  jsonConfig: JSON.stringify({}),
});

setFaceAuthenticationHint

Provides a face authentication hint for the FaceAuthentication module.

Signature

IncodeSdk.setFaceAuthenticationHint(
  faceAuthenticationHint: string | { faceAuthenticationHint: string }
): Promise<void>

Required Parameters

• faceAuthenticationHint: Hint string, or object containing faceAuthenticationHint.

Returns / Callbacks

• Returns Promise<void>.

Example

await IncodeSdk.setFaceAuthenticationHint('customer@example.com');

onResourceDownloadProgressUpdated

Subscribes to Dynamic Delivery resource download progress.

Signature

IncodeSdk.onResourceDownloadProgressUpdated(
  listener: (event: { progress: Number }) => void
): () => void

Required Parameters

• listener: Callback invoked with download progress.

Returns / Callbacks

• Returns an unsubscriber function.

Example

const unsubscribe = IncodeSdk.onResourceDownloadProgressUpdated(({ progress }) => {
  console.log(progress);
});

checkOnDemandResourcesDownloaded

Checks whether Dynamic Delivery resources are already downloaded.

Signature

IncodeSdk.checkOnDemandResourcesDownloaded(config?: {
  moduleName: string;
}): Promise<any>

Optional Parameters

• moduleName: Module name to check resources for.

Returns / Callbacks

• Returns a promise with the native resource status.

Example

await IncodeSdk.checkOnDemandResourcesDownloaded({ moduleName: 'IdScan' });

downloadOnDemandResources

Downloads Dynamic Delivery resources.

Signature

IncodeSdk.downloadOnDemandResources(config?: {
  moduleName: string;
}): Promise<any>

Optional Parameters

• moduleName: Module name to download resources for.

Returns / Callbacks

• Returns a promise that resolves when the native download operation completes.

Example

await IncodeSdk.downloadOnDemandResources({ moduleName: 'IdScan' });

removeOnDemandResources

Removes Dynamic Delivery resources.

Signature

IncodeSdk.removeOnDemandResources(config?: {
  moduleName: string;
}): Promise<any>

Optional Parameters

• moduleName: Module name to remove resources for.

Returns / Callbacks

• Returns a promise that resolves when the native remove operation completes.

Example

await IncodeSdk.removeOnDemandResources({ moduleName: 'IdScan' });

Shared types

Signature

type OnboardingSessionConfig = {
  region?: string;
  queue?: string;
  interviewId?: string;
  token?: string;
  configurationId?: string;
  externalId?: string;
  externalCustomerId?: string;
  customFields?: { [key: string]: string };
  validationModules?: ValidationModule[];
  e2eEncryptionEnabled?: boolean;
  mergeSessionRecordings?: boolean;
  voiceConsentLanguage?: string;
};

type OnboardingRecordSessionConfig = {
  recordSession: boolean;
  forcePermissions: boolean;
};

type OnboardingResponse = {
  status: 'success' | 'userCancelled';
};

type OnboardingSession = {
  interviewId: string;
  token: string;
};

type OnboardingSectionResponse = OnboardingResponse & {
  sectionTag: string;
};

OnboardingSessionConfig Fields

• region: Region, currently ALL (covers all regions), BR (optimized for Brazil), or IN (optimized for India).
• queue: Queue to attach this onboarding session to.
• interviewId: Backend-created onboarding session interview ID.
• configurationId: Dashboard flow configuration ID.
• token: Backend-created onboarding session token.
• externalId: ID used outside of Incode Omni.
• externalCustomerId: Identifier that links the onboarding session to an external prospect or customer ID.
• validationModules: Validation modules enabled for this session.
• customFields: Custom data attached to this onboarding session.
• e2eEncryptionEnabled: Enable E2EE.
• mergeSessionRecordings: Merge recordings from ID capture and Face capture into a single video.
• voiceConsentLanguage: Language for VideoSelfie voice consent. Supported values are currently en, es, pt, and he.

OnboardingRecordSessionConfig Fields

• recordSession: Set to true to enable ID and Selfie capture screen recording.
• forcePermissions: Set to true to abort the session if the user denies permissions, or false otherwise.