Customization

The Incode Onboarding Cordova Plugin exposes several APIs for customizing the UI: theming, string overrides, localization, UX options, and asset replacement. This page documents each customization API.

V1 and V2 screens

The plugin has two generations of UI:

V2 screens are the redesigned, cross-platform UX used on Android and iOS. All Android customization uses V2. On iOS, opt into V2 by passing "experimentV2" as the clientExperimentId parameter to initializeSDK().
V1 screens are the legacy iOS UX. If clientExperimentId is not set to "experimentV2", iOS uses V1.

setTheme() supports both formats. Some options (like setUXConfig()'s showFooter) apply only to V2 screens. Each method section below notes V1 or V2 applicability where relevant.

The Cordova plugin passes customization JSON directly to the native SDKs; there is no separate API for selecting between V1 and V2 customization schemas.

setTheme()

setTheme() accepts a JSON string describing the theme. Two formats are supported:

V2 (cross-platform, current). Recommended for new integrations.
V1 (iOS legacy only).

Call setTheme() before starting any onboarding section or flow.

cordova.exec(
  function () { console.log("Theme applied"); },
  function (err) { console.log("setTheme error:", err); },
  "Cplugin",
  "setTheme",
  [jsonThemeString]
);

V2 theme

The V2 theme is composed of displayMode, typography, colorPalette, and components.buttons.

{
  "displayMode": "light",
  "typography": {
    "family": {
      "text": {
        "android": {
          "regular": "onboard_sdk_dm_sans_regular",
          "bold": "onboard_sdk_dm_sans_bold",
          "medium": "onboard_sdk_dm_sans_medium"
        },
        "ios": {
          "regular": "DMSans-Regular",
          "bold": "DMSans-Bold",
          "medium": "DMSans-Medium"
        }
      },
      "display": {
        "android": {
          "regular": "onboard_sdk_dm_sans_regular",
          "bold": "onboard_sdk_dm_sans_bold",
          "medium": "onboard_sdk_dm_sans_medium"
        },
        "ios": {
          "extraBold": "DMSans-ExtraBold"
        }
      }
    },
    "letterSpacing": {
      "none": 0,
      "medium": -0.5,
      "large": -1.0,
      "extraLarge": -1.5
    }
  },
  "colorPalette": {
    "neutralLight": "#ffffff",
    "neutralDark": "#000000",
    "brand50": "#e5f0ff",
    "brand200": "#99c3ff",
    "brand300": "#66a6ff",
    "brand400": "#3388ff",
    "brand500": "#006aff",
    "brand600": "#0055cc",
    "brand900": "#21273b",
    "gray50": "#FCFCFD",
    "gray100": "#EBECEF",
    "gray200": "#C6C8D2",
    "gray300": "#A3A8B8",
    "gray500": "#60667C",
    "gray700": "#3A3E4B",
    "gray800": "#262831",
    "gray900": "#14151A",
    "brandSecondary50": "#F2E2FE",
    "brandSecondary500": "#820AD1",
    "negative50": "#FFF0F0",
    "negative500": "#FF5A5F",
    "negative600": "#E71111",
    "negative950": "#240001",
    "warning50": "#FFF7EB",
    "warning400": "#FFB647",
    "warning500": "#FF9900",
    "warning950": "#523100",
    "positive50": "#E4FBF0",
    "positive600": "#189F60",
    "positive800": "#0C5030"
  }
}

displayMode

Key	Values	Description
`displayMode`	`"light"` or `"dark"`	Base display mode.

typography

Key	Description
`family.text.android`	Android font resource names for body text (`regular`, `bold`, `medium`).
`family.text.ios`	iOS font names for body text (`regular`, `bold`, `medium`).
`family.display.android`	Android font resource names for display and headline text.
`family.display.ios`	iOS font names for display and headline text (for example, `extraBold`).
`letterSpacing`	Letter-spacing tokens: `none`, `medium`, `large`, `extraLarge`.

colorPalette

Key group	Keys
Neutral	`neutralLight`, `neutralDark`
Brand	`brand50`, `brand200`, `brand300`, `brand400`, `brand500`, `brand600`, `brand900`
Gray	`gray50`, `gray100`, `gray200`, `gray300`, `gray500`, `gray700`, `gray800`, `gray900`
Brand secondary	`brandSecondary50`, `brandSecondary500`
Negative (errors)	`negative50`, `negative500`, `negative600`, `negative950`
Warning	`warning50`, `warning400`, `warning500`, `warning950`
Positive (success)	`positive50`, `positive600`, `positive800`

components.buttons

Each entry in components.buttons targets a button style ("primary", "secondary", "text") and lets you override surface color, text color, and border per state.

{
  "components": {
    "buttons": [
      {
        "style": "primary",
        "surface": {
          "default": "#006aff",
          "hover": "#3388ff",
          "pressed": "#0055cc",
          "disabled": "#C6C8D2"
        },
        "text": {
          "default": "#ffffff",
          "disabled": "#A3A8B8"
        },
        "border": {
          "color": {
            "default": "#006aff",
            "hover": "#3388ff",
            "pressed": "#0055cc",
            "disabled": "#C6C8D2"
          },
          "width": 0,
          "radius": 200
        }
      }
    ]
  }
}

surface and text default values accept either a single hex string or a two-element array for light and dark mode override: ["#lightHex", "#darkHex"].

Field	Description
`style`	Which button type to style: `"primary"`, `"secondary"`, or `"text"`.
`surface.default`	Background color in the default state.
`surface.hover`	Background color on hover (primarily web and desktop).
`surface.pressed`	Background color when pressed or tapped.
`surface.disabled`	Background color when the button is disabled.
`text.default`	Label text color in the default state.
`text.disabled`	Label text color when disabled.
`border.color.default`	Border color in the default state.
`border.color.hover`	Border color on hover.
`border.color.pressed`	Border color when pressed.
`border.color.disabled`	Border color when disabled.
`border.width`	Border width in points or dp (`0` for no border).
`border.radius`	Corner radius in points or dp.

V1 theme

The V1 theme applies only to legacy iOS screens. It is composed of colors, fonts, buttons, labels, and customComponents.

{
  "colors": {
    "accent": "#00B2FD",
    "primary": "#20263D",
    "background": "#FFFFFF",
    "secondaryBackground": "#E9E9EB",
    "success": "#0CD5A2",
    "error": "#FF5C6F",
    "warning": "#F3AB3C",
    "cancel": "#20263D"
  },
  "fonts": {
    "buttonBig": { "name": "CircularXXTT-Black", "size": "20" },
    "buttonMedium": { "name": "CircularXXTT-Black", "size": "16" },
    "buttonSmall": { "name": "CircularXXTT-Black", "size": "12" },
    "title": { "name": "CircularXXTT-Black", "size": "25" },
    "hugeTitle": { "name": "CircularXXTT-Black", "size": "40" },
    "subtitle": { "name": "CircularXXTT-Black", "size": "18" },
    "boldedSubtitle": { "name": "CircularXXTT-Bold", "size": "18" },
    "smallSubtitle": { "name": "CircularXXTT-Black", "size": "14" },
    "info": { "name": "CircularXXTT-Black", "size": "16" },
    "body": { "name": "CircularXXTT-Medium", "size": "14" },
    "boldedBody": { "name": "CircularXXTT-Bold", "size": "14" },
    "textFieldBig": { "name": "CircularXXTT-Black", "size": "20" },
    "textFieldMedium": { "name": "CircularXXTT-Black", "size": "15" }
  },
  "buttons": {
    "primary": {
      "states": {
        "normal": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "#00B2FD",
          "borderColor": "",
          "borderWidth": 0,
          "cornerRadius": 32,
          "shadowColor": "#000000",
          "shadowOffset": [0, 5],
          "shadowOpacity": 0.15,
          "shadowRadius": 9,
          "textColor": "#FFFFFF",
          "transform": { "a": 1, "b": 0, "c": 0, "d": 1, "tx": 0, "ty": 0 }
        },
        "highlighted": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "#20263D",
          "borderColor": "",
          "borderWidth": 0,
          "cornerRadius": 32,
          "shadowColor": "#000000",
          "shadowOffset": [0, 5],
          "shadowOpacity": 0.15,
          "shadowRadius": 9,
          "textColor": "#00B2FD",
          "transform": { "a": 1, "b": 0, "c": 0, "d": 1, "tx": 0, "ty": 0 }
        },
        "disabled": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "#E9E9EB",
          "borderColor": "",
          "borderWidth": 0,
          "cornerRadius": 32,
          "shadowColor": "#000000",
          "shadowOffset": [0, 5],
          "shadowOpacity": 0,
          "shadowRadius": 9,
          "textColor": "#FFFFFF",
          "transform": { "a": 1, "b": 0, "c": 0, "d": 1, "tx": 0, "ty": 0 }
        }
      },
      "big": {
        "height": 64,
        "minWidth": 200,
        "contentInsets": { "top": 19, "left": 32, "bottom": 19, "right": 32 },
        "kerning": 0
      },
      "medium": {
        "height": 46,
        "minWidth": 0,
        "contentInsets": { "top": 12, "left": 24, "bottom": 12, "right": 24 },
        "kerning": 0
      }
    },
    "secondary": {
      "states": {
        "normal": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "#FFFFFF",
          "borderColor": "#20263D",
          "borderWidth": 1,
          "cornerRadius": 32,
          "shadowColor": "",
          "shadowOffset": [0, 0],
          "shadowOpacity": 0,
          "shadowRadius": 0,
          "textColor": "#20263D",
          "transform": { "a": 1, "b": 0, "c": 0, "d": 1, "tx": 0, "ty": 0 }
        },
        "highlighted": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "#20263D",
          "borderColor": "#20263D",
          "borderWidth": 1,
          "cornerRadius": 32,
          "shadowColor": "",
          "shadowOffset": [0, 0],
          "shadowOpacity": 0,
          "shadowRadius": 0,
          "textColor": "#00B2FD",
          "transform": { "a": 1, "b": 0, "c": 0, "d": 1, "tx": 0, "ty": 0 }
        },
        "disabled": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "#FFFFFF",
          "borderColor": "#E9E9EB",
          "borderWidth": 1,
          "cornerRadius": 32,
          "shadowColor": "",
          "shadowOffset": [0, 0],
          "shadowOpacity": 0,
          "shadowRadius": 0,
          "textColor": "#E9E9EB",
          "transform": { "a": 1, "b": 0, "c": 0, "d": 1, "tx": 0, "ty": 0 }
        }
      },
      "big": {
        "height": 64,
        "minWidth": 200,
        "contentInsets": { "top": 19, "left": 32, "bottom": 19, "right": 32 },
        "kerning": 0
      },
      "medium": {
        "height": 46,
        "minWidth": 0,
        "contentInsets": { "top": 12, "left": 24, "bottom": 12, "right": 24 },
        "kerning": 0
      }
    },
    "text": {
      "states": {
        "normal": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "",
          "borderColor": "",
          "borderWidth": 0,
          "cornerRadius": 0,
          "shadowColor": "",
          "shadowOffset": [0, 0],
          "shadowOpacity": 0,
          "shadowRadius": 0,
          "textColor": "#20263D",
          "transform": { "a": 1, "b": 0, "c": 0, "d": 1, "tx": 0, "ty": 0 }
        }
      },
      "big": {
        "height": 40,
        "minWidth": 200,
        "contentInsets": { "top": 8, "left": 16, "bottom": 8, "right": 16 },
        "kerning": 0
      },
      "medium": {
        "height": 30,
        "minWidth": 0,
        "contentInsets": { "top": 12, "left": 24, "bottom": 12, "right": 24 },
        "kerning": 0
      }
    },
    "help": {
      "states": {
        "normal": {
          "animateStateChange": true,
          "alpha": 1,
          "backgroundColor": "#00B2FD",
          "cornerRadius": 32,
          "textColor": "#FFFFFF"
        }
      },
      "big": {
        "height": 64,
        "minWidth": 200,
        "contentInsets": { "top": 19, "left": 32, "bottom": 19, "right": 32 },
        "kerning": 0
      }
    }
  },
  "labels": {
    "title": { "textColor": "#20263D", "kerning": 0 },
    "secondaryTitle": { "textColor": "#FFFFFF", "kerning": 0 },
    "subtitle": { "textColor": "#20263D", "kerning": 0 },
    "secondarySubtitle": { "textColor": "#FFFFFF", "kerning": 0 },
    "smallSubtitle": { "textColor": "#20263D", "kerning": 0 },
    "info": { "textColor": "#636670", "kerning": 0 },
    "secondaryInfo": { "textColor": "#FFFFFF", "kerning": 0 },
    "body": { "textColor": "#20263D", "kerning": 0 },
    "secondaryBody": { "textColor": "#FFFFFF", "kerning": 0 },
    "code": { "textColor": "#20263D", "kerning": 16 }
  },
  "customComponents": {
    "cameraFeedback": {
      "alpha": 0.8,
      "backgroundColor": "#000000",
      "cornerRadius": 20,
      "textBackgroundColor": "",
      "textColor": "#FFFFFF"
    },
    "idCaptureHelp": {
      "commonIssueLayoutOrientation": "horizontal"
    },
    "idSideLabel": {
      "alpha": 1,
      "backgroundColor": "#FFFFFF",
      "borderColor": "",
      "borderWidth": 0,
      "cornerRadius": 5
    },
    "separator": {
      "alpha": 1.0,
      "color": "#20263D",
      "cornerRadius": 0,
      "padding": 24,
      "thickness": 1
    },
    "signature": {
      "signatureColor": "#04BD19",
      "canvasBorderColor": "#EC03FC"
    },
    "idAutocaptureCountdown": {
      "backgroundColor": "#00B2FD",
      "numberColor": "#FFFFFF"
    }
  }
}

V1 theme sections:

Section	Description
`colors`	Semantic colors: `accent`, `primary`, `background`, `secondaryBackground`, `success`, `error`, `warning`, `cancel`.
`fonts`	Per-role font name and size: buttons, titles, subtitles, body, info, text fields, and so on.
`buttons`	Per-type (`primary`, `secondary`, `text`, `help`) state styling (`normal`, `highlighted`, `disabled`) plus `big` and `medium` sizing.
`labels`	Per-role text color and kerning.
`customComponents`	Component-specific styling: `cameraFeedback`, `idCaptureHelp`, `idSideLabel`, `separator`, `signature`, `idAutocaptureCountdown`.

setString()

Override individual UI strings with custom copy. setString() accepts an object mapping locale keys to custom strings. The key format is platform-specific and is defined by the underlying Android and iOS SDKs.

Refer to the native SDK customization documentation for the current keys:

Android: Android SDK customization
iOS: iOS SDK customization

let strings = {
  "someKey": "Your custom string"
  // ...more keys
};

cordova.exec(
  function () { console.log("Strings overridden"); },
  function (err) { console.log("setString error:", err); },
  "Cplugin",
  "setString",
  [strings]
);

String keys are overridden for the current locale.

setLocalizationLanguage()

Change the UI language at runtime. Accepts a language code string.

Code	Language
`en`	English
`es`	Spanish
`pt`	Portuguese
`he`	Hebrew

cordova.exec(
  function () { console.log("Language set"); },
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "setLocalizationLanguage",
  ["es"]
);

setUXConfig()

Set UX configuration at runtime. Accepts a JSON string.

Option	Type	Description
`showFooter`	boolean	Show or hide the footer in V2 `addId` and `addSelfieScan` modules.

let uxConfig = JSON.stringify({ showFooter: false });

cordova.exec(
  function () {},
  function (err) { console.log("setUXConfig error:", err); },
  "Cplugin",
  "setUXConfig",
  [uxConfig]
);

setFaceAuthenticationHint()

Set a hint text shown to the user during face authentication. Accepts a string.

cordova.exec(
  function () {},
  function (err) { console.log("Error:", err); },
  "Cplugin",
  "setFaceAuthenticationHint",
  ["Look straight into the camera"]
);

showCloseButton()

Show or hide the close and cancel button during onboarding flows. Accepts a string: "true" shows the button, "false" hides it.

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

showCloseButton() replaces the deprecated setCommonConfig() (deprecated since 4.6.0).

Asset instructions

Custom fonts on Android

Place your font files (.ttf or .otf) in res/font/ of the Android app.
Reference them by their resource name in the V2 theme typography.family block (for example, "regular": "onboard_sdk_dm_sans_regular"). The resource name must match the file name (without extension).

Custom fonts on iOS

Add the font files to your iOS project (drag them in and ensure they are part of the app target's "Copy Bundle Resources").
Register them in Info.plist under the UIAppFonts (Fonts provided by application) array.
Reference them by their PostScript font name in the theme JSON (for example, "regular": "DMSans-Regular").

Custom icons and videos

Icon and video replacement is not handled by the Cordova plugin. Follow the native SDK asset customization instructions:

Android: Android SDK customization
iOS: iOS SDK customization