IncdOnboarding SDK Customization Guide v2

Customization for ID Capture v2

You can customize the appearance of the SDK by setting colors and fonts. This can be done in two ways: through a JSON configuration file or using code.

Customization Through JSON

You can define appearance settings in a JSON file and load it during initialization:

Note: If you are already using themes loaded from JSON, you should extend the existing JSON file with the new structure described here.

Example JSON File

{
  "displayMode": "system",
  "colorPalette": {
    "neutralLight": "#FFFFFF",
    "neutralDark": "#000000",
    "brand50": "#E5FFF0",
    "brand200": "#99FFC3",
    "brand300": "#66FFA6",
    "brand400": "#33FF88",
    "brand500": "#00FF6A",
    "brand600": "#00CC55",
    "brand900": "#213B27",
    "gray50": "#FCFDFC",
    "gray100": "#EBEFEC",
    "gray150": "#D9DAE1",
    "gray200": "#C6D2C8",
    "gray250": "#B5B8C5",
    "gray300": "#A3B8A8",
    "gray400": "#82879A",
    "gray500": "#607C66",
    "gray600": "#4D5264",
    "gray700": "#3A4B3E",
    "gray750": "#30333E",
    "gray800": "#263128",
    "gray900": "#141A15",
    "gray1000": "#000000",
    "brandSecondary50": "#F2FEE2",
    "brandSecondary500": "#82D10A",
    "negative50": "#FFF0F0",
    "negative400": "#FF5F5A",
    "negative500": "#E71111",
    "negative950": "#240100",
    "warning50": "#FFEBF7",
    "warning400": "#FF47B6",
    "warning500": "#FF0099",
    "warning950": "#520031",
    "positive50": "#E4F0FB",
    "positive500": "#18609F",
    "positive950": "#0C3050"
  },
  "typography": {
    "family": {
      "text": {
        "ios": {
          "regular": "Helvetica",
          "medium": "Helvetica-Medium",
          "bold": "Helvetica-Bold"
        },
        "android": {
          "regular": "some font"
        }
      },
      "display": {
        "ios": {
          "extraBold": "Helvetica-Black"
        },
        "android": {
          "extraBold": "some font"
        }
      }
    },
    "letterSpacing": {
      "none": 0,
      "medium": -0.5,
      "large": -1.0,
      "extraLarge": -1.5
    }
  }
}

Loading the JSON File

if let path = Bundle.main.path(forResource: "AppearanceConfig", ofType: "json"),
   let jsonString = try? String(contentsOf: URL(fileURLWithPath: path)) {
    IncdTheme.loadJsonTheme(jsonString)
}

Customization Through Code

Use the API in code to set colors and fonts programmatically:

Setting Colors

IncdTheme.colorPalette = .init(
    neutral: UIColor.white,
    black: UIColor.black,
    brand50: UIColor.red,
    // ...
)

Setting Fonts

IncdTheme.typography = .init(
    family: .init(
        text: .init(regular: "Helvetica", medium: "Helvetica-Medium", bold: "Helvetica-Bold"),
        display: .init(extraBold: "Helvetica-ExtraBold")
    ),
    letterSpacing: .init(
        none: 0,
        medium: -0.5,
        large: -1.0,
        extraLarge: -1.5
    )
)

Setting Display Mode

IncdTheme.displayMode = .system // or .light, .dark

About Colors

The color scheme is based on the palette, which consists of colors that can be overridden:

Color Format

In the JSON configuration file, colors should be specified in hex with the format #RRGGBB or #AARRGGBB.

About Fonts

The typography system is based on font families, which can include the following optional styles:

Text Fonts

For text, the following styles are currently used:

Display Fonts

For display, the following style is used:

By default, these styles can be set using the Family structure in the JSON configuration file or programmatically in the code.

About Display Mode

The display mode controls whether the SDK uses light or dark UI appearance. It works in conjunction with your color palette to provide appropriate theming.

Available Options:

About Components

The components section in the JSON configuration allows you to customize specific UI components beyond the base color palette and typography. Currently, component-level customization is available for buttons.

Components JSON Structure

"components": {
  "buttons": [
    {
      "style": "primary",
      "surface": {
        "default": ["#00FF6A", "#00CC55"],
        "pressed": "#00CC55",
        "disabled": ["#C6D2C8", "#3A4B3E"]
      },
      "text": {
        "default": ["#FFFFFF", "#141A15"],
        "disabled": "#607C66"
      }
    },
    {
      "style": "secondary",
      "surface": {
        "default": ["#EBEFEC", "#263128"],
        "pressed": "#C6D2C8",
        "disabled": ["#FCFDFC", "#141A15"]
      },
      "text": {
        "default": ["#000000", "#FFFFFF"],
        "disabled": "#A3B8A8"
      }
    }
  ]
}

Button Styles

Each entry in the buttons array describes the appearance of a button style:

For surface, text, and border.color state values, you can use either:

If a particular state, color, or button style is not defined in components, the SDK falls back to the default appearance derived from the base colorPalette and typography.

Logo

We support the ability for you to use your own logo image which is shown on some of the onboarding screens. To achieve this, name your image incdOnboardingLogo and place it in your app’s asset catalog (usually called Assets.xcassets). The image will resize to fit 35pt height.

To hide the logo shown on some screens please create a fully transparent image, name it incdOnboardingLogo and place it in your app’s asset catalog.

UX Configuration

In addition to visual theming, you can customize the user experience behavior through UX configuration. This allows you to control the positioning of UI elements and interaction patterns.

UX Configuration Through JSON

You can define UX settings in a JSON file and load it during initialization:

Example UX Configuration JSON

{
  "closeButtonPosition": "topRight",
  "helpButtonPosition": "bottomRight",
  "realtimeFeedbackMessageUIFlavor": "minimal",
  "showFooter": true,
  "headerAlignment": "center"
}

Loading UX Configuration

if let path = Bundle.main.path(forResource: "IncdUXConfig", ofType: "json"),
   let jsonString = try? String(contentsOf: URL(fileURLWithPath: path)) {
    IncdUXConfig.loadUXConfig(jsonString)
}

UX Configuration Options

Close Button Position

Controls where the X (close) button appears on screens:

Help Button Position

Controls where the help button appears on ID Capture V2 screens:

Realtime Feedback Message UI Flavor

Controls the style of realtime feedback messages in ID Capture V2:

Show Footer

Controls whether the "Verified by Incode" footer is displayed:

Header Alignment

Controls the alignment of header content on certain screens:

Animation Theming

The SDK uses Lottie animations throughout its UI. These animations are automatically tinted to match your brand color (brand500 in the color palette). This ensures animations visually integrate with the rest of your themed experience without any additional work.

The following elements are tinted with your brand500 color:

If you change brand500 — whether via JSON or code — all animations update automatically.

Replace Lottie Animations

You can replace the default animations used by the SDK with your own. To do so, add a Lottie file (.json or .lottie) with the matching name to your app bundle.

Tutorial animations

These animations are shown before capture begins. They are replaceable:

Animation name Shown before
id_scan_tutorial Front side ID scan
id_back_scan_tutorial Back side ID scan
passport_scan_tutorial Passport scan
tutorial_selfie_v2 Selfie / face enrollment

Place a file named id_scan_tutorial.json (or .lottie) in your app bundle to override the default. The same applies for the other names.

Processing animation

Animation name Where it appears
incode-processing-animation Generic processing / loading screens

Static icons

Document chooser icons (chooserId2, chooserPass2, chooserDigitalId) use Lottie internally but are not replaceable with custom Lottie files. To customize these icons, provide a static image asset (PNG, PDF, or SVG) with the same name in your app's asset catalog. The SDK will use your image instead of the animated icon.