Customization

setTheme

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

V2 — cross-platform (Android + iOS V2 UX). This is the current, recommended format.
V1 — iOS legacy UX only.

Call setTheme before starting any onboarding section/flow.

JavaScript

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

V2 theme (cross-platform, current)

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

JSON

{
  "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"` / `"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/headline text.
`family.display.ios`	iOS font names for display/headline text (e.g. `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`

Migration note (4.6.0, Android): the neutral and black keys were renamed to neutralLight and neutralDark. Theme JSON using the old keys silently falls back to defaults (#FFFFFF / #000000).

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

JSON

{
  "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/dark mode override: ["#lightHex", "#darkHex"].

Field	Description
`style`	Which button type to style: `"primary"`, `"secondary"`, or `"text"`.
`surface.default`	Background color in the default/idle state.
`surface.hover`	Background color on hover (primarily web/desktop).
`surface.pressed`	Background color when pressed/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/dp (`0` for no border).
`border.radius`	Corner radius in points/dp.

V1 theme (iOS legacy)

The V1 theme is for the legacy iOS UX only. It is composed of colors, fonts, buttons, labels, and customComponents.

JSON

{
  "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 + size: buttons, titles, subtitles, body, info, text fields, etc.
`buttons`	Per-type (`primary`, `secondary`, `text`, `help`) state styling (`normal`, `highlighted`, `disabled`) plus `big`/`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 keys are platform-specific — on iOS they use the incdOnboarding.* namespace (e.g. incdOnboarding.userInformation.email.title).

JavaScript

let strings = {
  "incdOnboarding.userInformation.email.title": "Your email address"
  // ...more keys
};

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

The 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

JavaScript

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 IdScan and SelfieScan modules.

JavaScript

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.

JavaScript

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

showCloseButton

Show or hide the close/cancel button during onboarding flows. Accepts a string ("true" shows the button).

JavaScript

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

Asset Instructions

Custom fonts on Android

Place your font files (.ttf / .otf) in res/font/ of the Android app.
Reference them by their resource name in the V2 theme typography.family block (e.g. "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 (e.g. "regular": "DMSans-Regular").