API Reference

This page is the complete reference for every public JavaScript API the Incode Onboarding Cordova Plugin exposes. All APIs are invoked through the Cordova bridge feature name Cplugin:

cordova.exec(successCallback, errorCallback, "Cplugin", "<action>", [...args]);

The plugin also exposes wrapper functions in Cplugin.js; the underlying cordova.exec call is shown for each method below.

Table of Contents

• Lifecycle & configuration: initializeSDK, isInitialized, showCloseButton, setSdkMode
• Customization: setTheme, setUXConfig, setLocalizationLanguage, setString, setQuantityStrings, setFaceAuthenticationHint
• Session & flow: setupOnboardingSession, startOnboarding, startOnboardingSection, startFlow, startWorkflow
• Results & finalization: getUserScore, faceMatch, finishOnboarding, startFaceLogin, deleteUserLocalData
• Event handling: flowListeners

Shared types

Common types used by multiple API methods.

sessionConfig

Used by setupOnboardingSession(), startOnboarding(), startFlow(), startWorkflow(), and (on Android) startFaceLogin().

• configurationId: Dashboard flow or workflow configuration ID. Required for startFlow() and startWorkflow().
• region: "ALL", "BR", or "IN". "ALL" covers all regions; "BR" and "IN" are optimized for Brazil and India respectively.
• queue: Queue name the session attaches to.
• interviewId: Existing session ID to resume.
• token: External session token from your backend. configurationId can be omitted when this is passed.
• externalId: Client-side identifier used outside Incode Omni.
• externalCustomerId: Links the session to an entity in an external system.
• e2eEncryptionEnabled: Enable end-to-end encryption. Requires e2eeUrl to have been passed to initializeSDK(). Boolean.
• mergeSessionRecordings: Merge ID and face capture recordings into a single video. Boolean.
• voiceConsentLanguage: Voice consent language for addVideoSelfie: "en", "es", "pt", or "he".
• validationModules: List of validation modules to enable. Array of strings.
• customFields: Custom key-value data attached to the session. Object.

recordSessionConfig

Used by startOnboarding() and startOnboardingSection().

• recordSession: "true" enables ID and selfie capture screen recording. String "true" or "false".
• forcePermissions: "true" aborts the session if the user denies permissions. String "true" or "false".

Lifecycle and configuration

initializeSDK()

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

Signature

initializeSDK(successCallback, errorCallback, apiKey, apiUrl, loggingEnabled, testMode, clientExperimentId, e2eeUrl, sslPinningConfig, sdkMode, externalAnalyticsEnabled, externalScreenshotsEnabled, sendDiagnosticsData)

Required parameters

• apiKey: API key provided by Incode. May be empty or null when authenticating with a session token instead — see Token-based Setup and sessionConfig.token.
• apiUrl: API base URL provided by Incode.

Optional parameters

• loggingEnabled: Enable SDK logging. String "true" or "false". Default is "true".
• testMode: Simulator or emulator mode. Set "true" on simulators and emulators. String "true" or "false". Default is "false".
• clientExperimentId: Enroll in experimental features, for example, UXv2 ("experimentV2"). String or null. Default is null.
• e2eeUrl: E2EE endpoint URL. Required if e2eEncryptionEnabled is used in any session. String or null. Default is null.
• sslPinningConfig: Object enabled: boolean, forceSSLPinning: boolean. enabled turns on SSL pinning. forceSSLPinning controls what happens when a pinning check fails: when true, the connection is dropped; when false, network traffic continues even after a failed pinning check. Default is enabled: false, forceSSLPinning: false.
• sdkMode: SDK operating mode at initialization. "standard", "captureOnly", or "submitOnly". Default is "standard". Can also be changed later via setSdkMode().
• externalAnalyticsEnabled: Enable external analytics. String "true" or "false". Default is "true".
• externalScreenshotsEnabled: Allow external screenshots. String "true" or "false". Default is "true".
• sendDiagnosticsData: Enables or disables sending of SDK diagnostics to Incode. String "true" or "false". iOS only — accepted but ignored on Android. Default is "true".

Callbacks

• Success: SDK initialized. No structured payload.
• Error: string "<code>: <message>". Codes: simulatorDetected, testModeEnabled, invalidInitParams, configError, unknown. See Results — initializeSDK().

Example

cordova.exec(
  function () { console.log("Initialized"); },
  function (err) {
    // err is "<code>: <message>" — match on code prefix if needed
    if (typeof err === "string" && err.indexOf("configError") === 0) {
      console.log("Invalid initialize config:", err);
    } else {
      console.log("Init error:", err);
    }
  },
  "Cplugin",
  "initializeSDK",
  [
    "YOUR_API_KEY",
    "https://your.api.url",
    "true",
    "false",
    null,
    null,
    { enabled: false, forceSSLPinning: false },
    "standard",
    "false",
    "false",
    "true"
  ]
);

On iOS, calling initializeSDK() more than once per app lifecycle is a no-op. See Known Issues.

isInitialized()

Returns whether the native SDK is fully initialized.

Signature

isInitialized(successCallback, errorCallback)

Parameters

• None.

Callbacks

• Success: boolean. true if initialized, false otherwise.

Example

cordova.exec(
  function (initialized) { console.log("Initialized:", initialized); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "isInitialized",
  []
);

showCloseButton()

Shows or hides the close and cancel button during onboarding flows.

Signature

showCloseButton(successCallback, errorCallback, allowUserToCancel)

Optional parameters

• allowUserToCancel: "true" shows the button, "false" hides it. String. Default is "false".

Example

cordova.exec(function () {}, function (err) {}, "Cplugin", "showCloseButton", ["true"]);

setSdkMode()

Switches the SDK operating mode at runtime without reinitializing.

Signature

setSdkMode(successCallback, errorCallback, sdkMode)

Required parameters

• sdkMode: "standard", "captureOnly", or "submitOnly". "captureOnly" works offline and captures ID and selfie images without validations. "submitOnly" submits previously captured data without new captures.

Example

cordova.exec(function () {}, function (err) {}, "Cplugin", "setSdkMode", ["captureOnly"]);

Customization

setTheme()

Applies a custom theme. Accepts a JSON string in the V2 cross-platform format or the V1 iOS-legacy format. Call before starting any section or flow.

Signature

setTheme(successCallback, errorCallback, theme)

Required parameters

• theme: The theme JSON string. See Customization — setTheme().

Example

cordova.exec(function () {}, function (err) {}, "Cplugin", "setTheme", [jsonThemeString]);

setUXConfig()

Sets UX configuration at runtime.

Signature

setUXConfig(successCallback, errorCallback, jsonConfig)

Required parameters

• jsonConfig: UX configuration JSON string, for example { "showFooter": false }. See Customization — setUXConfig.

Example

cordova.exec(function () {}, function (err) {}, "Cplugin", "setUXConfig", [JSON.stringify({ showFooter: false })]);

setLocalizationLanguage()

Sets the UI language at runtime.

Signature

setLocalizationLanguage(successCallback, errorCallback, language)

Required parameters

• language: "en", "es", "pt", or "he".

Example

cordova.exec(function () {}, function (err) {}, "Cplugin", "setLocalizationLanguage", ["es"]);

setString()

Overrides individual UI strings with custom copy, keyed by the current locale.

Signature

setString(successCallback, errorCallback, strings)

Required parameters

• strings: Map of platform-specific locale keys to custom strings. Object. See Customization — setString().

Example

cordova.exec(
  function () {}, function (err) {},
  "Cplugin", "setString",
  [{ "incdOnboarding.userInformation.email.title": "Your email" }]
);

setQuantityStrings()

Overrides the SDK's pluralized (quantity) strings. These are strings that change depending on a count — for example "1 attempt remaining" versus "3 attempts remaining". Call it after initializeSDK() and before starting onboarding.

Signature

setQuantityStrings(successCallback, errorCallback, locale, quantityStrings)

Required parameters

• locale: A BCP 47 language tag such as "en", "es", or "en-US".
• quantityStrings: Single nested object shaped as plural name → quantity keyword → value:
  • Plural name — the SDK string resource key to override (for example, "onboard_sdk_validation_attempts_remaining").
  • Quantity keyword — one of "zero", "one", "two", "few", "many", or "other" (matched case-insensitively). Provide the forms that apply to the target language; "other" is the required fallback.
  • Value — the localized string. Use %d as the placeholder for the count.

Error callback

The error callback receives a JSON object (not a string):

{
  code: string,       // for example, "configError"
  message: string,
  cause: {            // null when no underlying throwable
    type: string,     // Java exception class name
    message: string | null,
    stackTrace: string
  } | null
}

Use optional chaining when reading cause fields (error.cause?.type). Missing locale or quantityStrings returns code: "configError" with cause: null.

Example

const quantityStrings = {
  "onboard_sdk_validation_attempts_remaining": {
    "one": "%d attempt remaining",
    "other": "%d attempts remaining"
  }
};
cordova.exec(
  function(result) {
    console.log("setQuantityStrings Success");
  },
  function(error) {
    console.log("setQuantityStrings Error:", error.code, error.message, error.cause?.type);
  },
  "Cplugin",
  "setQuantityStrings",
  ["en", quantityStrings]
);

setFaceAuthenticationHint()

Provides an identity hint to speed up face authentication by indicating which identity is expected.

Signature

setFaceAuthenticationHint(successCallback, errorCallback, identityId)

Required parameters

• identityId: Identity id used as the face authentication hint.

Example

cordova.exec(function () {}, function (err) {}, "Cplugin", "setFaceAuthenticationHint", ["customer@example.com"]);

Session and flow

setupOnboardingSession()

Creates or resumes an onboarding session. Returns interviewId and token.

Signature

setupOnboardingSession(successCallback, errorCallback, sessionConfig)

Required parameters

• sessionConfig: Session configuration. See Shared types — sessionConfig.

Callbacks

• Success: { interviewId: string, token: string }. On iOS the payload may also include regionCode.

Example

var sessionConfig = {
  configurationId: "your-flow-id",
  externalId: "your-external-id",
  e2eEncryptionEnabled: false,
  region: "ALL"
};
cordova.exec(
  function (data) { console.log(data.interviewId, data.token); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "setupOnboardingSession",
  [sessionConfig]
);

Since 4.2.0, this method accepts a session config object, not a plain configurationId string.

startOnboarding()

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

Signature

startOnboarding(successCallback, errorCallback, sessionConfig, flowConfig, recordSessionConfig)

Required parameters

• sessionConfig: Session configuration. See Shared types — sessionConfig.
• flowConfig: Array of module objects. See Modules.

Optional parameters

• recordSessionConfig: Recording configuration. See Shared types — recordSessionConfig. Object or null. Default is null.

Callbacks

• Success: aggregated module results. See Results — startOnboarding().

Example

cordova.exec(
  function (result) { console.log("Done:", result); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "startOnboarding",
  [
    { configurationId: "your-workflow-id" },
    [{ module: "addId" }, { module: "addSelfieScan" }, { module: "addFaceMatch" }],
    { recordSession: "false", forcePermissions: "false" }
  ]
);

startOnboardingSection()

Runs one section of a previously set-up session. Can be called multiple times, one section at a time.

Signature

startOnboardingSection(successCallback, errorCallback, flowConfig, recordSessionConfig, sectionTag)

Required parameters

• flowConfig: Array of module objects. See Modules.
• recordSessionConfig: Recording configuration. See Shared types — recordSessionConfig. Object.
• sectionTag: Unique tag echoed back in the result.

Callbacks

• Success: { status, sectionTag, ...moduleResults }. See Results — startOnboardingSection().
• Error: typed string. See Results — startOnboardingSection() for the full list.

Example

cordova.exec(
  function (result) { console.log(result.status, result.sectionTag); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "startOnboardingSection",
  [[{ module: "addId" }], { recordSession: "false", forcePermissions: "false" }, "section-001"]
);

startFlow()

Starts a session based on a configurationId, optionally resuming it from a specific module.

Signature

startFlow(successCallback, errorCallback, sessionConfig, moduleId)

Required parameters

• sessionConfig: Session configuration. configurationId is required. See Shared types — sessionConfig.

Optional parameters

• moduleId: Case-sensitive module identifier to start from, for example "EMAIL" or "PHONE". Omit to start from the first module. On Android, this parameter is applied only when sessionConfig.interviewId is also provided.

Example

cordova.exec(
  function (winParam) { console.log("Result:", winParam); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "startFlow",
  [{ configurationId: "your-flow-id", interviewId: "interview-id" }, "EMAIL"]
);

Valid moduleId values

moduleId values correspond to the module identifier rather than the local flowConfig module name. Use these case-sensitive values when calling startFlow():

ACCEPT_VIDEO_SELFIE is an Android local-only identifier and is not valid as a startFlow() moduleId.

startWorkflow()

Starts a workflow defined on the Incode Dashboard, end to end.

Signature

startWorkflow(successCallback, errorCallback, sessionConfig)

Required parameters

• sessionConfig: Session configuration. configurationId is required. See Shared types — sessionConfig.

Example

cordova.exec(
  function (result) { console.log("Result:", result); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "startWorkflow",
  [{ configurationId: "your-workflow-id", region: "ALL" }]
);

Results and finalization

getUserScore()

Fetches the identity verification scores and results.

Signature

getUserScore(successCallback, errorCallback, mode)

Optional parameters

• mode: "fast" or "accurate". Controls the trade-off between speed and accuracy of the returned score. Default is "accurate".

Callbacks

• Success: score payload. Shape differs by platform — see Results — getUserScore().

Example

cordova.exec(
  function (winParam) { console.log("Score:", JSON.stringify(winParam)); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "getUserScore",
  ["fast"]
);

faceMatch()

Performs a server-side face match without UI.

Signature

faceMatch(successCallback, errorCallback)

Parameters

• None.

Callbacks

• Success: face match result. Shape differs by platform — see Results — faceMatch() and faceMatchData.

Example

cordova.exec(function (res) { console.log(res); }, function (err) {}, "Cplugin", "faceMatch", []);

finishOnboarding()

Finalizes the session. Call exactly once after all sections or modules complete successfully.

Signature

finishOnboarding(successCallback, errorCallback)

Parameters

• None.

Example

cordova.exec(
  function () { console.log("Finished"); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "finishOnboarding",
  []
);

startFaceLogin()

Authenticates an enrolled user via face login.

Signature

startFaceLogin(successCallback, errorCallback, sessionConfig)

Optional parameters

• sessionConfig: Enables E2EE in face login on Android (no effect on iOS). Object or null. Default is null.

Callbacks

• Success: face login result object. See Results — startFaceLogin().
• Error: platform-specific string from the native SDK. See Results — startFaceLogin().

Example

cordova.exec(
  function (result) { console.log("Face login success:", result); },
  function (error) { console.log("Face login error:", error); },
  "Cplugin",
  "startFaceLogin",
  [{}]
);

deleteUserLocalData()

Deletes the SDK's local cached user data. Call after finishing all steps.

Signature

deleteUserLocalData(successCallback, errorCallback)

Parameters

• None.

Example

cordova.exec(
  function () { console.log("Local data deleted"); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "deleteUserLocalData",
  []
);

Event handling

flowListeners

The Cordova plugin does not expose a separate event-emitter or listener API. Flow events are delivered through the standard Cordova success and error callback pair passed to each API call. Internally, the native side implements IncodeWelcome.OnboardingListener and fires results through the corresponding callbacks.

How it works

startOnboardingSection(successCallback, errorCallback, flowConfig, ...)
       │
       ├─ Each module completes  ─► native listener accumulates results
       │
       ├─ Section finishes       ─► successCallback({ status, sectionTag, ...moduleResults })
       │
       └─ Error or user cancel   ─► errorCallback(typedErrorString)

Callback contract

Detailed face-authentication failure reasons appear on faceAuthenticationData.error, not as the section errorCallback string. See Results — startOnboardingSection() for the full list.

Module-level results

Each module that completes during a section contributes a key to the success payload. You do not need to register any additional listeners; all results are aggregated and returned in the single successCallback. See Results — Module result objects for the full list of keys and their shapes.

Example: listening for section completion

cordova.exec(
  function (result) {
    console.log("Status:", result.status);           // "success"
    console.log("Tag:", result.sectionTag);
    console.log("ID front:", result.frontIdData);
    console.log("Selfie:", result.selfieData);
    console.log("Face match:", result.faceMatchData);
  },
  function (error) {
    switch (error) {
      case "permissionsDenied":
        // Prompt user to grant camera or location permissions.
        break;
      case "faceAuthenticationFailed":
        // Face authentication module failed.
        break;
      case "sslPinningFailed":
        // SSL pinning failure.
        break;
      case "onUserCancelled":
      case "userCancelled":
        // User cancelled the flow.
        break;
      default:
        console.log("Unhandled error:", error);
    }
  },
  "Cplugin",
  "startOnboardingSection",
  [flowConfig, recordSessionConfig, sectionTag]
);