Customization

← Back to Documentation Index

The plugin exposes several APIs for branding the UI, overriding strings, switching languages, tweaking UX, and adding custom assets.

setTheme
- V2 theme (cross-platform, current)
- V1 theme (iOS legacy)
setString
setLocalizationLanguage
setUXConfig
setFaceAuthenticationHint
showCloseButton
Asset Instructions

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.

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.

{
  "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). See the Migration Guide.

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

{
  "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).

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. See the Migration Guide for renamed/removed string keys across versions.

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 IdScan and SelfieScan 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/cancel button during onboarding flows. Accepts a string ("true" shows the button).

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

showCloseButton replaces the deprecated setCommonConfig (deprecated since 4.6.0). See API Reference.

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").