API Reference

← Back to Documentation Index

This is the complete reference for every public JavaScript API exposed by the plugin. 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.

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

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, disableJailbreakDetection, 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"/"false". Default is "true".
testMode: Emulator/simulator mode. Set "true" on simulators/emulators. String "true"/"false". Default is "false".
isExternalTokenEnabled: Use external token authentication. String "true"/"false". Default is "false".
disableJailbreakDetection: iOS only — disable jailbreak check (no effect on Android). String "true"/"false". Default is "false".
clientExperimentId: Enroll in experimental features (e.g. "experimentV2"). String or null. Default is null.
e2eeUrl: E2EE endpoint URL. Required if e2eEncryptionEnabled is used in a session. String or null. Default is null.
sslPinningConfig: Object { enabled: boolean, forceSSLPinning: boolean }. Default is { enabled: false, forceSSLPinning: false }.

Returns / Callbacks

Success: SDK initialized.
Error: typed string — simulatorDetected, testModeEnabled, invalidInitParams, configError, sslPinningFailed, unknown. See Results — Error Reference.

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.

Returns / 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/cancel button during onboarding flows.

Signature

showCloseButton(successCallback, errorCallback, allowUserToCancel)

Optional Parameters

allowUserToCancel: "true" shows the close/cancel button. String "true"/"false". Default is "false".

Example

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

Deprecation: setCommonConfig(successCallback, errorCallback, setShowCloseButton) is deprecated since 4.6.0 and now internally forwards to showCloseButton (logging a deprecation warning). It will be removed in a future major release. Use showCloseButton instead.

setSdkMode

Switches the SDK operating mode at runtime without reinitializing.

Signature

setSdkMode(successCallback, errorCallback, sdkMode)

Required Parameters

sdkMode: "standard", "captureOnly", or "submitOnly".

Example

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

setTheme

Applies a custom theme. Accepts a JSON string (V2 cross-platform or V1 iOS-legacy format). Call before starting any section/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, e.g. { "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). iOS uses 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"]);

setupOnboardingSession

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

Signature

setupOnboardingSession(successCallback, errorCallback, sessionConfig)

Required Parameters

sessionConfig: Session configuration. See Session config fields.

Returns / 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 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 = null)

Required Parameters

sessionConfig: Session configuration. See Session config fields.
flowConfig: Array of module objects. See Modules.

Optional Parameters

recordSessionConfig: { recordSession: "true"/"false", forcePermissions: "true"/"false" }. Object or null.

Returns / 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: { recordSession: "true"/"false", forcePermissions: "true"/"false" }. Object.
sectionTag: Unique tag echoed back in the result.

Returns / Callbacks

Success: { status, sectionTag, ...moduleResults }. See Results — startOnboardingSection.
Error: typed string — simulatorDetected, rootDetected, hookDetected, permissionsDenied, virtualEnvDetected, unknown.

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 required. See Session config fields.

Optional Parameters

moduleId: Module name to start from (e.g. "EMAIL", "PHONE"). 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" }, "EMAIL" ]
);

startWorkflow

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

Signature

startWorkflow(successCallback, errorCallback, sessionConfig)

Required Parameters

sessionConfig: Session configuration; configurationId required. See Session config fields.

Example

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

getUserScore

Fetches the identity verification scores/results.

Signature

getUserScore(successCallback, errorCallback, mode)

Required Parameters

mode: "fast" or "accurate".

Returns / Callbacks

Success: full score JSON object (passed through from the Incode API).

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.

Returns / 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/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 = null)

Optional Parameters

sessionConfig: Enables E2EE in Face Login on Android (no effect on iOS). Object or null.

Returns / Callbacks

Success: face login result object.
Error: typed string — e.g. faceLoginFailed, noUserFound.

Example

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

flowListeners

The Cordova plugin does not expose a separate event-emitter or listener API. Instead, flow events are delivered through the standard Cordova successCallback / errorCallback pair passed to each API call. Internally, the native side implements IncodeWelcome.OnboardingListener and fires results back as the corresponding callbacks fire.

How it works

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

Callback contract

Event	Delivered via	Payload
Section completed	`successCallback`	`{ status: "success", sectionTag: string, ...moduleResults }`
User cancelled	`errorCallback`	`"onUserCancelled"`
Permissions denied	`errorCallback`	`"permissionsDenied"`
Root / hook / virtual env detected	`errorCallback`	`"rootDetected"` / `"hookDetected"` / `"virtualEnvDetected"`
SSL pinning failed	`errorCallback`	`"sslPinningFailed"`
Face authentication failed	`errorCallback`	typed string — see faceAuthenticationData errors
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 Results for the full list of keys and their shapes.

Example — listening for section completion

cordova.exec(
  function (result) {
    // section completed
    console.log("Status:", result.status);           // "success" | "userCancelled"
    console.log("Tag:", result.sectionTag);
    console.log("ID front:", result.frontIdData);
    console.log("Selfie:", result.selfieData);
    console.log("Face match:", result.faceMatchData);
  },
  function (error) {
    // error or user cancel
    switch (error) {
      case "permissionsDenied":
        // prompt user to grant camera/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]
);

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

Session config fields

Used by setupOnboardingSession, startOnboarding, startFlow, and startWorkflow.

configurationId: Dashboard flow/workflow configuration ID. Required for startFlow/startWorkflow.
region: "ALL", "BR", or "IN".
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 (outside Incode Omni).
externalCustomerId: Links the session to an entity in an external system.
e2eEncryptionEnabled: Enable E2EE. Requires e2eeUrl in initializeSDK. Boolean.
mergeSessionRecordings: Merge ID + face recordings into a single video. Boolean.
voiceConsentLanguage: VideoSelfie voice consent language: "en", "es", "pt", "he".
validationModules: List of validation modules to enable. Array of strings.
customFields: Custom key-value data attached to the session. Object.

Table of Contents

initializeSDK

isInitialized

showCloseButton

setSdkMode

setTheme

setUXConfig

setLocalizationLanguage

setString

setFaceAuthenticationHint

setupOnboardingSession

startOnboarding

startOnboardingSection

startFlow

startWorkflow

getUserScore

faceMatch

finishOnboarding

startFaceLogin

flowListeners

How it works

Callback contract

Module-level results

Example — listening for section completion

deleteUserLocalData

Session config fields