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",
    "gray200": "#C6D2C8",
    "gray300": "#A3B8A8",
    "gray500": "#607C66",
    "gray700": "#3A4B3E",
    "gray800": "#263128",
    "gray900": "#141A15",
    "brandSecondary50": "#F2FEE2",
    "brandSecondary500": "#82D10A",
    "negative50": "#FFF0F0",
    "negative500": "#FF5F5A",
    "negative600": "#E71111",
    "negative950": "#240100",
    "warning50": "#FFEBF7",
    "warning400": "#FF47B6",
    "warning500": "#FF0099",
    "warning950": "#520031",
    "positive50": "#E4F0FB",
    "positive600": "#18609F",
    "positive800": "#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 data = try? Data(contentsOf: URL(fileURLWithPath: path)) {
    IncdTheme.loadJsonTheme(data: data)
}

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:

neutralLight
neutralDark
brand50
brand200
brand300
brand400
brand500
brand600
brand900
gray0
gray50
gray100
gray200
gray300
gray500
gray700
gray800
gray900
brandSecondary50
brandSecondary500
negative50
negative500
negative600
negative950
warning50
warning400
warning500
warning950
positive50
positive600
positive800

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:

regular
medium
bold
extraBold

Text Fonts

For text, the following styles are currently used:

regular
medium
bold

Display Fonts

For display, the following style is used:

extraBold

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:

.light (default) - Forces light appearance regardless of system settings
.dark - Forces dark appearance regardless of system settings
.system - Automatically adapts to the device's system appearance setting

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

At the top level of the JSON file, you can add a components object:

"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:

style: The button style identifier. Supported values:
- "primary"
- "secondary"
surface: Colors used for the button surface (background) in different control states:
- default
- pressed (optional)
- disabled (optional)
text: Colors used for the button title in different control states (same keys as surface).
border: Border configuration for the button:
- color: Optional state-based colors for the border, with the same structure as surface.
- width: Border width in points.
- radius: Corner radius in points.

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

A single color value (for example, "#000000") that applies to both light and dark modes.
An array of up to two color values (for example, ["#000000", "#E8E8E8"]), where:
- The first value is used in light mode.
- The second value (if present) is used in dark mode. If omitted, the light color is reused in dark mode.

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.

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:

"topRight" (default) - Close button in the top-right corner
"topLeft" - Close button in the top-left corner

Help Button Position

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

"bottomRight" (default) - Help button in the bottom-right corner
"topRight" - Help button in the top-right corner
"topLeft" - Help button in the top-left corner

Realtime Feedback Message UI Flavor

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

"standard" (default) - Full feedback messages with detailed information
"minimal" - Simplified, minimal feedback messages

Show Footer

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

true (default) - Footer is visible
false - Footer is hidden

Header Alignment

Controls the alignment of header content on certain screens:

"center" (default) - Header content is center-aligned
"start" - Header content is left-aligned
"end" - Header content is right-aligned