Common Implementation Patterns

← Back to Documentation Index

This document describes the three most common ways to integrate the plugin. All three require that the SDK is initialized first via initializeSDK.

Pattern	Configuration source	Control granularity	Primary APIs
1. Configure flows locally, run end to end	Local (`flowConfig` array)	Whole flow in one call	`startOnboarding`
2. Configure flows locally, run step by step	Local (`flowConfig` array)	Section by section	`setupOnboardingSession`, `startOnboardingSection`, `finishOnboarding`, `getUserScore`, `deleteUserLocalData`
3. Run flows configured online	Incode dashboard (`configurationId`)	Whole flow / from a module	`startWorkflow`, `startFlow`

All module options used in flowConfig arrays are documented in Modules. Result shapes are documented in Results.

Prerequisite: Initialize the SDK

cordova.exec(
  function () { console.log("SDK initialized"); },
  function (err) { console.log("Init error: " + err); },
  "Cplugin",
  "initializeSDK",
  [
    "YOUR_API_KEY",          // apiKey
    "https://your.api.url",  // apiUrl
    "true",                  // loggingEnabled
    "false",                 // testMode ("true" on emulator/simulator)
    "false",                 // isExternalTokenEnabled
    "false",                 // disableJailbreakDetection (iOS only)
    null,                    // clientExperimentId
    null,                    // e2eeUrl
    { enabled: false, forceSSLPinning: false } // sslPinningConfig
  ]
);

Pattern 1 — Configure Flows Locally and Run End to End

Use startOnboarding when you want to define the complete list of modules in your app code and run the entire flow in a single call. The SDK creates the session, runs every module in order, and reports back when done.

let sessionConfig = {
  configurationId: "your-workflow-id", // optional, applies dashboard settings
  region: "ALL",
  mergeSessionRecordings: false
};

let flowConfig = [
  { module: "addPhone" },
  { module: "addId", showIdTypeChooser: "true", showTutorials: "true" },
  { module: "addDocumentScan", documentType: "ADDRESS_STATEMENT" },
  { module: "addGeolocation", isSkippable: "true" },
  { module: "addSelfieScan", showTutorials: "true" },
  { module: "addFaceMatch" },
  { module: "addSignature" },
  { module: "addVideoSelfie" }
];

let recordSessionConfig = {
  // optional
  recordSession: "false",
  forcePermissions: "false"
};

cordova.exec(
  function (result) {
    console.log("Onboarding completed: ", result);
    // result contains the aggregated module results
  },
  function (error) {
    console.log("Onboarding error:", error);
  },
  "Cplugin",
  "startOnboarding",
  [sessionConfig, flowConfig, recordSessionConfig]
);

See Modules for every module and its parameters. See startOnboarding for the full signature.

Pattern 2 — Configure Flows Locally and Run Step by Step

Use this pattern when you need fine-grained control over each section — for example, to display your own intermediate UI, branch the flow based on intermediate results, or run sections at different times.

The lifecycle is:

setupOnboardingSession — create the session (returns interviewId and token).
startOnboardingSection — run one or more sections. Can be called multiple times, but only one section at a time.
finishOnboarding — finalize the session (call exactly once, after all sections succeed).
getUserScore — fetch verification scores/results.
deleteUserLocalData — clear local cache.

// Step 1 — set up the session
let sessionConfig = {
  configurationId: "your-flow-id",   // optional
  externalId: "your-external-id",    // optional
  e2eEncryptionEnabled: false,       // optional
  region: "ALL"                      // optional
};

cordova.exec(
  function (data) {
    console.log("Session ready. interviewId:", data.interviewId, "token:", data.token);
    runFirstSection();
  },
  function (err) { console.log("setupOnboardingSession error:", err); },
  "Cplugin",
  "setupOnboardingSession",
  [sessionConfig]
);

// Step 2 — run a section (repeat as needed)
function runFirstSection() {
  let flowConfig = [
    { module: "addId", showIdTypeChooser: "true" },
    { module: "addSelfieScan" },
    { module: "addFaceMatch", matchType: "idSelfie" }
  ];
  let recordSessionConfig = { recordSession: "false", forcePermissions: "false" };
  let sectionTag = "identity-section-001";

  cordova.exec(
    function (result) {
      console.log("Section status:", result.status);          // "success" | "userCancelled"
      console.log("Section tag:", result.sectionTag);
      console.log("Front ID:", result.frontIdData);
      console.log("Face match:", result.faceMatchData);
      // You can now call startOnboardingSection again for the next section,
      // or proceed to finishing the session.
      finishSession();
    },
    function (error) {
      // typed error string, e.g. "permissionsDenied", "rootDetected", ...
      console.log("Section error:", error);
    },
    "Cplugin",
    "startOnboardingSection",
    [flowConfig, recordSessionConfig, sectionTag]
  );
}

// Step 3 — finish the onboarding
function finishSession() {
  cordova.exec(
    function () {
      console.log("Onboarding finished");
      fetchScore();
    },
    function (err) { console.log("finishOnboarding error:", err); },
    "Cplugin",
    "finishOnboarding",
    []
  );
}

// Step 4 — fetch the user score
function fetchScore() {
  cordova.exec(
    function (winParam) {
      console.log("Score:", JSON.stringify(winParam));
      cleanup();
    },
    function (err) { console.log("getUserScore error:", err); },
    "Cplugin",
    "getUserScore",
    ["fast"] // "fast" | "accurate"
  );
}

// Step 5 — delete local data
function cleanup() {
  cordova.exec(
    function () { console.log("Local data deleted"); },
    function (err) { console.log("deleteUserLocalData error:", err); },
    "Cplugin",
    "deleteUserLocalData",
    []
  );
}

Notes:

recordSessionConfig and sectionTag are mandatory parameters of startOnboardingSection (since 4.2.0).
You can start multiple sections, but only one at a time — wait for each section's callback before starting the next.
See Modules for module options and Results for the structure of each module's result.

Pattern 3 — Run Flows Configured Online

Use this pattern when the flow/workflow is defined on the Incode dashboard. Your app only supplies a configurationId; the modules and their settings come from the dashboard.

Option A — `startWorkflow`

Runs a workflow defined on the dashboard end to end.

let sessionConfig = {
  configurationId: "your-workflow-id", // required
  region: "ALL"
};

cordova.exec(
  function (result) { console.log("Workflow result:", result); },
  function (error) { console.log("Workflow error:", error); },
  "Cplugin",
  "startWorkflow",
  [sessionConfig]
);

Option B — `startFlow`

Runs a dashboard-configured flow, optionally starting from a specific module.

let sessionConfig = {
  configurationId: "your-flow-id" // required
};
let moduleId = "EMAIL"; // optional; omit to start from the first module

cordova.exec(
  function (winParam) { console.log("Flow result:", winParam); },
  function (err) { console.log("Flow error:", err); },
  "Cplugin",
  "startFlow",
  [sessionConfig, moduleId]
);

See the API Reference for the full startWorkflow and startFlow signatures and all supported sessionConfig fields.