# Incode Cordova SDK API Reference

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`:

## JavaScript

```javascript
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.

## Table of Contents

- **Lifecycle & configuration:** [initializeSDK](https://developer.incode.com/docs/cordova-api-reference#initializesdk), [isInitialized](https://developer.incode.com/docs/cordova-api-reference#isinitialized), [showCloseButton](https://developer.incode.com/docs/cordova-api-reference#showclosebutton), [setSdkMode](https://developer.incode.com/docs/cordova-api-reference#setsdkmode)
- **Customization:** [setTheme](https://developer.incode.com/docs/cordova-api-reference#settheme), [setUXConfig](https://developer.incode.com/docs/cordova-api-reference#setuxconfig), [setLocalizationLanguage](https://developer.incode.com/docs/cordova-api-reference#setlocalizationlanguage), [setString](https://developer.incode.com/docs/cordova-api-reference#setstring), [setFaceAuthenticationHint](https://developer.incode.com/docs/cordova-api-reference#setfaceauthenticationhint)
- **Session & flow:** [setupOnboardingSession](https://developer.incode.com/docs/cordova-api-reference#setuponboardingsession), [startOnboarding](https://developer.incode.com/docs/cordova-api-reference#startonboarding), [startOnboardingSection](https://developer.incode.com/docs/cordova-api-reference#startonboardingsection), [startFlow](https://developer.incode.com/docs/cordova-api-reference#startflow), [startWorkflow](https://developer.incode.com/docs/cordova-api-reference#startworkflow)
- **Results & finalization:** [getUserScore](https://developer.incode.com/docs/cordova-api-reference#getuserscore), [faceMatch](https://developer.incode.com/docs/cordova-api-reference#facematch), [finishOnboarding](https://developer.incode.com/docs/cordova-api-reference#finishonboarding), [startFaceLogin](https://developer.incode.com/docs/cordova-api-reference#startfacelogin), [deleteUserLocalData](https://developer.incode.com/docs/cordova-api-reference#deleteuserlocaldata)
- **Event handling:** [flowListeners](https://developer.incode.com/docs/cordova-api-reference#flowlisteners)

---

## initializeSDK

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

### Signature

```javascript
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`.

### Example

```javascript
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.

---

## isInitialized

Returns whether the native SDK is fully initialized.

### Signature

```javascript
isInitialized(successCallback, errorCallback)
```

### Parameters

- None.

### Returns / Callbacks

- **Success:** boolean — `true` if initialized, `false` otherwise.

### Example

```javascript
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

```javascript
showCloseButton(successCallback, errorCallback, allowUserToCancel)
```

### Optional Parameters

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

### Example

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

> **Deprecation:** `setCommonConfig(successCallback, errorCallback, setShowCloseButton)` is deprecated since 4.6.0.

---

## setSdkMode

Switches the SDK operating mode at runtime without reinitializing.

### Signature

```javascript
setSdkMode(successCallback, errorCallback, sdkMode)
```

### Required Parameters

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

### Example

```javascript
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).

### Signature

```javascript
setTheme(successCallback, errorCallback, theme)
```

### Required Parameters

- `theme`: The theme JSON string.

### Example

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

---

## setUXConfig

Sets UX configuration at runtime.

### Signature

```javascript
setUXConfig(successCallback, errorCallback, config)
```

### Required Parameters

- `config`: UX configuration JSON string, e.g. `{ "showFooter": false }`.

### Example

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

---

## setLocalizationLanguage

Sets the UI language at runtime.

### Signature

```javascript
setLocalizationLanguage(successCallback, errorCallback, language)
```

### Required Parameters

- `language`: "en", "es", "pt", or "he".

### Example

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

---

## setString

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

### Signature

```javascript
setString(successCallback, errorCallback, strings)
```

### Required Parameters

- `strings`: Map of platform-specific locale keys to custom strings (object).

### Example

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

---

## setFaceAuthenticationHint

Sets a hint text shown during face authentication.

### Signature

```javascript
setFaceAuthenticationHint(successCallback, errorCallback, faceAuthenticationHint)
```

### Required Parameters

- `faceAuthenticationHint`: The hint text to display.

### Example

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

---

## setupOnboardingSession

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

### Signature

```javascript
setupOnboardingSession(successCallback, errorCallback, sessionConfig)
```

### Required Parameters

- `sessionConfig`: Session configuration.

### Returns / Callbacks

- **Success:** `{ interviewId: string, token: string }`.

### Example

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

---

## startOnboarding

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

### Signature

```javascript
startOnboarding(successCallback, errorCallback, sessionConfig, flowConfig, recordSessionConfig = null)
```

### Required Parameters

- `sessionConfig`: Session configuration.
- `flowConfig`: Array of module objects.

### Optional Parameters

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

### Returns / Callbacks

- **Success:** aggregated module results.

### Example

```javascript
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.

### Signature

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

### Required Parameters

- `flowConfig`: Array of module objects.
- `recordSessionConfig`: `{ recordSession: "true"/"false", forcePermissions: "true"/"false" }`. Object.
- `sectionTag`: Unique tag echoed back in the result.

### Returns / Callbacks

- **Success:** `{ status, sectionTag, ...moduleResults }`.

### Example

```javascript
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

```javascript
startFlow(successCallback, errorCallback, sessionConfig, moduleId)
```

### Required Parameters

- `sessionConfig`: Session configuration; `configurationId` required.

### Optional Parameters

- `moduleId`: Module name to start from (e.g. "EMAIL", "PHONE"). Omit to start from the first module.

### Example

```javascript
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

```javascript
startWorkflow(successCallback, errorCallback, sessionConfig)
```

### Required Parameters

- `sessionConfig`: Session configuration; `configurationId` required.

### Example

```javascript
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

```javascript
getUserScore(successCallback, errorCallback, mode)
```

### Required Parameters

- `mode`: "fast" or "accurate".

### Returns / Callbacks

- **Success:** full score JSON object.

### Example

```javascript
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

```javascript
faceMatch(successCallback, errorCallback)
```

### Returns / Callbacks

- **Success:** face match result.

### Example

```javascript
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

```javascript
finishOnboarding(successCallback, errorCallback)
```

### Example

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

---

## startFaceLogin

Authenticates an enrolled user via face login.

### Signature

```javascript
startFaceLogin(successCallback, errorCallback, sessionConfig = null)
```

### Optional Parameters

- `sessionConfig`: Enables E2EE in Face Login on Android.

### Returns / Callbacks

- **Success:** face login result object.

### Example

```javascript
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.

### How it works

```undefined
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 |
| Unknown error | `errorCallback` | "unknown" |

---

## deleteUserLocalData

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

### Signature

```javascript
deleteUserLocalData(successCallback, errorCallback)
```

### Example

```javascript
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.
- `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.