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, approve
• 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(). startWorkflow() requires configurationId or token.
• region: "ALL", "BR", or "IN". "ALL" covers all regions; "BR" is Brazil and "IN" is for India.
• queue: Queue name the session attaches to.
• interviewId: Existing session ID to resume.
• token: External session token from your back end. configurationId can be omitted when this is passed.
• externalId: Client-side identifier used outside Incode.
• 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" for English, "es" for Spanish, "pt" for Portuguese, or "he" for Hebrew.
• 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, appleWalletMerchantID)

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".
• appleWalletMerchantID: Apple Wallet merchant ID. When set, the Dashboard-configured Apple Wallet ID verification option becomes available in the ID Scan chooser. Must be set at initialization, before onboarding starts. String or null. iOS only; accepted but ignored on Android. Default is null, which leaves the option off.

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 in Dashboard, end to end.

Signature

startWorkflow(successCallback, errorCallback, sessionConfig)

Required parameters

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

Errors

The error callback receives { code, message, cause }.

sessionConfig must include a non-empty configurationId or token. Otherwise, startWorkflow() fails with configError before the Workflow starts, without making any network requests. An interviewId alone is not enough.

For all error codes, see Results — startWorkflow().

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 identity verification scores and results.

Signature

getUserScore(successCallback, errorCallback, fetchMode, interviewId)

Optional parameters

• fetchMode: "fast" or "accurate", case-insensitive. Controls the trade-off between speed and accuracy of the returned score. Default is "accurate"; unrecognized values also fall back to "accurate".
• interviewId: Session to fetch the score for. Omit to target the current session. String or null. Default is null.

Callbacks

• Success: Score payload. See Results — getUserScore().
• Error: Typed string—userScoreFailed, userCancelled. See Results — Error Reference.

Example

cordova.exec(
  function (result) {
    console.log("Score:", JSON.stringify(result));
  },
  function (error) {
    console.log("Error:", error);
  },
  "Cplugin",
  "getUserScore",
  ["accurate"]
);

faceMatch()

Performs a server-side face match without UI.

Signature

faceMatch(successCallback, errorCallback, matchType, interviewId, idCategory)

Optional Parameters

• matchType: Which sources are compared—"idSelfie", "nfcSelfie", or "nfc3Way". Omit to use the native SDK default.
• interviewId: Identifier of the session to run the match against. Defaults to the current session's interview.
• idCategory: Which scanned ID to use—"primary" or "secondary". Default is "primary".

Callbacks

• Success: The face match result, flat and identical on both platforms. See Results — faceMatch(). Fields are only present when the native SDK actually produced a value.
• Error: An object { code, message, cause }, where message carries the native detail. cause is always present and carries the underlying native exception's description on Android, or null on iOS.

Treat userCancelled as an optional refinement of faceMatchError, not a separate branch you must guard by platform. Handling both unconditionally works everywhere; the userCancelled check simply never matches on iOS.

Example

cordova.exec(
  function (res) {
    console.log("Matched:", res.isFaceMatched, "confidence:", res.confidence);
  },
  function (err) {
    if (err.code === "userCancelled") return;
    console.log("Face match failed:", err.message);
  },
  "Cplugin",
  "faceMatch",
  ["idSelfie", null, "primary"]
);

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

approve()

Decides whether to approve the user, and adds approved users to the Incode database. This module has no UI on either platform. Run it after the modules the approval decision depends on.

Signature

approve(successCallback, errorCallback, forceApproval)

Optional parameters

• forceApproval: Approves the user regardless of the onboarding score. Boolean. Defaults to false.

Callbacks

• Success: { success, uuid, customerToken, error }. See Results — approveData. A user who ran through approval but was not approved is a success with success: false, not an error.
• Error: code, using the codes below.

Example

cordova.exec(
  function (result) {
    console.log("Approved:", result.success, "uuid:", result.uuid);
  },
  function (error) {
    console.log("Error approve:", error);   // e.g. userCancelled
  },
  "Cplugin",
  "approve",
  [false]
);

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