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.

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, isExternalTokenEnabled, clientExperimentId, e2eeUrl, sslPinningConfig)

Required parameters

apiKey: API key provided by Incode.
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".
isExternalTokenEnabled: Use external token authentication. 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.

Callbacks

Success: SDK initialized. No structured payload.
Error: typed string. See Results — initializeSDK() for the full list.

Example

cordova.exec(
  function () { console.log("Initialized"); },
  function (err) {
    if (err === "sslPinningFailed") {
      console.log("SSL pinning failed. Possible MITM or misconfigured certificate.");
    } else {
      console.log("Init error:", err);
    }
  },
  "Cplugin",
  "initializeSDK",
  [
    "YOUR_API_KEY",
    "https://your.api.url",
    "true",
    "false",
    "false",
    "false",
    null,
    null,
    { enabled: false, forceSSLPinning: false }
  ]
);

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"]);

showCloseButton() replaces the deprecated setCommonConfig() (deprecated since 4.6.0). setCommonConfig() now forwards internally to showCloseButton() and logs a deprecation warning; it will be removed in a future major release.

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, config)

Required parameters

config: 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. On iOS, keys use the incdOnboarding.* namespace. See Customization — setString().

Example

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

setFaceAuthenticationHint()

Sets a hint text shown during face authentication.

Signature

setFaceAuthenticationHint(successCallback, errorCallback, faceAuthenticationHint)

Required parameters

faceAuthenticationHint: The hint text to display.

Example

cordova.exec(function () {}, function (err) {}, "Cplugin", "setFaceAuthenticationHint", ["Look at the camera"]);

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 }.

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 new session based on a configurationId, optionally 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: Module name to start from, for example "addEmail" or "addPhone". Omit to start from the first module.

Example

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

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: full score JSON object (passed through from the Incode API). 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. See Results — 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: typed string, for example faceLoginFailed or noUserFound.

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

Event	Delivered via	Payload
Section completed	`successCallback`	`{ status: "success", sectionTag: string, ...moduleResults }`
User cancelled	`errorCallback`	`"onUserCancelled"` on Android, `"userCancelled"` on iOS
Permissions denied	`errorCallback`	`"permissionsDenied"`
Root, hook, or virtual environment detected	`errorCallback`	`"rootDetected"` / `"hookDetected"` / `"virtualEnvDetected"`
SSL pinning failed	`errorCallback`	`"sslPinningFailed"`
Face authentication failed	`errorCallback`	typed string. See Results — faceAuthenticationData.
Unknown error	`errorCallback`	`"unknown"`

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 "rootDetected":
        // Device is rooted. Abort.
        break;
      case "userIsNotRecognized":
        // Face authentication failed. User not recognized.
        break;
      default:
        console.log("Unhandled error:", error);
    }
  },
  "Cplugin",
  "startOnboardingSection",
  [flowConfig, recordSessionConfig, sectionTag]
);