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

```js
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**

```js
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()](results#initializesdk) for the full list.

**Example**

```js
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&#x20;_`initializeSDK()`_&#x20;more than once per app lifecycle is a no-op. See [Known Issues](known-issues)._

### isInitialized()

Returns whether the native SDK is fully initialized.

**Signature**

```js
isInitialized(successCallback, errorCallback)
```

**Parameters**

- None.

**Callbacks**

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

**Example**

```js
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**

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

**Optional parameters**

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

**Example**

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

`showCloseButton()`_&#x20;replaces the deprecated&#x20;_`setCommonConfig()`_&#x20;(deprecated since 4.6.0).&#x20;_`setCommonConfig()`_&#x20;now forwards internally to&#x20;_`showCloseButton()`_&#x20;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**

```js
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**

```js
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**

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

**Required parameters**

- `theme`: The theme JSON string. See [Customization — setTheme()](customization#settheme).

**Example**

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

### setUXConfig()

Sets UX configuration at runtime.

**Signature**

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

**Required parameters**

- `config`: UX configuration JSON string, for example `{ "showFooter": false }`. See [Customization — setUXConfig()](customization#setuxconfig).

**Example**

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

### setLocalizationLanguage()

Sets the UI language at runtime.

**Signature**

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

**Required parameters**

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

**Example**

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

### setString()

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

**Signature**

```js
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()](customization#setstring).

**Example**

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

### setFaceAuthenticationHint()

Sets a hint text shown during face authentication.

**Signature**

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

**Required parameters**

- `faceAuthenticationHint`: The hint text to display.

**Example**

```js
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**

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

**Required parameters**

- `sessionConfig`: Session configuration. See [Shared types — sessionConfig](#sessionconfig).

**Callbacks**

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

**Example**

```js
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&#x20;_`configurationId`_&#x20;string._

### startOnboarding()

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

**Signature**

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

**Required parameters**

- `sessionConfig`: Session configuration. See [Shared types — sessionConfig](#sessionconfig).
- `flowConfig`: Array of module objects. See [Modules](modules).

**Optional parameters**

- `recordSessionConfig`: Recording configuration. See [Shared types — recordSessionConfig](#recordsessionconfig). Object or `null`. Default is `null`.

**Callbacks**

- **Success:** aggregated module results. See [Results — startOnboarding()](results#startonboarding).

**Example**

```js
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**

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

**Required parameters**

- `flowConfig`: Array of module objects. See [Modules](modules).
- `recordSessionConfig`: Recording configuration. See [Shared types — recordSessionConfig](#recordsessionconfig). Object.
- `sectionTag`: Unique tag echoed back in the result.

**Callbacks**

- **Success:** `{ status, sectionTag, ...moduleResults }`. See [Results — startOnboardingSection()](results#startonboardingsection).
- **Error:** typed string. See [Results — startOnboardingSection()](results#startonboardingsection) for the full list.

**Example**

```js
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**

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

**Required parameters**

- `sessionConfig`: Session configuration. `configurationId` is required. See [Shared types — sessionConfig](#sessionconfig).

**Optional parameters**

- `moduleId`: Module name to start from, for example `"addEmail"` or `"addPhone"`. Omit to start from the first module.

**Example**

```js
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**

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

**Required parameters**

- `sessionConfig`: Session configuration. `configurationId` is required. See [Shared types — sessionConfig](#sessionconfig).

**Example**

```js
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**

```js
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()](results#getuserscore).

**Example**

```js
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**

```js
faceMatch(successCallback, errorCallback)
```

**Parameters**

- None.

**Callbacks**

- **Success:** face match result. See [Results — faceMatchData](results#facematchdata).

**Example**

```js
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**

```js
finishOnboarding(successCallback, errorCallback)
```

**Parameters**

- None.

**Example**

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

### startFaceLogin()

Authenticates an enrolled user via face login.

**Signature**

```js
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()](results#startfacelogin).
- **Error:** typed string, for example `faceLoginFailed` or `noUserFound`.

**Example**

```js
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**

```js
deleteUserLocalData(successCallback, errorCallback)
```

**Parameters**

- None.

**Example**

```js
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](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](results#module-result-objects) for the full list of keys and their shapes.

#### Example: listening for section completion

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

<br />