Android SDK UI Customization

Restyle the CICReader Android SDK's chip-scanning screen — text, buttons, the NFC icon, the loading indicator, the container window and custom fonts — by passing a CICUIConfig into your CICConfig.

Adding CICUIConfig to CICConfig

Pass the uiConfig parameter when you build your CICConfig:

val config = CICConfig(
  baseUrl           = "<BASE_URL>",
  connectTimeoutMs  = 60_000,
  readTimeoutMs     = 60_000,
  cacheScanStrategy = CICCacheScanStrategy.NO_CACHE,
  uiConfig          = CICUIConfig(...)
)

class CICUIConfig {
  val cancelButton: ButtonElement? = null,
  val scanningGuide: TextElement? = null,
  val waitingForCard: TextElement? = null,
  val connectedCard: TextElement? = null,
  val verifyingCard: TextElement? = null,
  val readingText: TextElement? = null,
  val nfcIcon: ImageElement? = null,
  val loadingIndicator: ProgressBarElement? = null,
  val windowView: WindowElement? = null,
  val customFont: List<FontSource>? = null,
}

Parameters:

Param	Type	Required	Default	Description
cancelButton	ButtonElement?	No	null	The cancel action button.
scanningGuide	TextElement?	No	null	Instructional text shown while the user positions the card.
waitingForCard	TextElement?	No	null	Text shown while waiting for a card to enter the NFC field.
connectedCard	TextElement?	No	null	Text shown once the chip connects.
verifyingCard	TextElement?	No	null	Text shown during verification.
readingText	TextElement?	No	null	Text shown while the chip is being read.
nfcIcon	ImageElement?	No	null	The NFC icon asset.
loadingIndicator	ProgressBarElement?	No	null	The loading spinner.
windowView	WindowElement?	No	null	The scanner container window.
customFont	List<FontSource>?	No	null	Fonts to register before they can be referenced by name.

Core UI Elements

CICUIConfig is built from five element types:

Field	Type	Description
TextElement	class	Customize text content, size, color and font.
ButtonElement	class	Style buttons — text, background, border.
ImageElement	class	Set a custom icon or image asset.
ProgressBarElement	class	Configure loading indicator colors.
WindowElement	class	Adjust window background and corner radii.

TextElement

Overrides the default string and styling for a scanner step.

TextElement(
  text     = "My custom string",
  textSize = 12f,
  color    = Color.parseColor("#BB86FC"),
  fontName = "MyRoboto"
)

Param	Type	Required	Default	Description
text	String	No	SDK default	The display string.
textSize	Float	No	SDK default	Font size.
color	Int	No	SDK default	ARGB color via Color.parseColor("#rrggbb").
fontName	String	No	SDK default	A font name registered through customFont.

ButtonElement

Styles an action button.

ButtonElement(
  text            = TextElement("Cancel", textSize = 18f),
  backgroundColor = Color.parseColor("#008000"),
  strokeColor     = Color.parseColor("#fcba03"),
  borderRadius    = 32f
)

Param	Type	Required	Default	Description
text	TextElement	No	SDK default	A nested TextElement for the button label.
backgroundColor	Int	No	SDK default	Button fill color.
strokeColor	Int	No	SDK default	Border color.
borderRadius	Float	No	SDK default	Corner radius.

ImageElement

Replaces the NFC icon.

ImageElement(
  path      = "ic_android_nfc_wave.png",
  assetType = AssetType.ASSET
)

Param	Type	Required	Default	Description
path	String	Yes	—	File name in assets/, or an absolute file path.
assetType	AssetType	Yes	—	Source type: ASSET or FILE.

ProgressBarElement

Replaces the default spinner.

ProgressBarElement(
  backgroundColor = Color.parseColor("#333333"),
  progressColor   = Color.parseColor("#BB86FC")
)

Param	Type	Required	Default	Description
backgroundColor	Int	No	SDK default	Track color behind the progress indicator.
progressColor	Int	No	SDK default	Color of the progress indicator itself.

WindowElement

Adjusts the container's look.

WindowElement(
  backgroundColor   = Color.parseColor("#d9bd71"),
  topLeftRadius     = 32,
  topRightRadius    = 32,
  bottomLeftRadius  = 32,
  bottomRightRadius = 32
)

Param	Type	Required	Default	Description
backgroundColor	Int	No	SDK default	Window background color.
topLeftRadius	Int	No	SDK default	Top-left corner radius.
topRightRadius	Int	No	SDK default	Top-right corner radius.
bottomLeftRadius	Int	No	SDK default	Bottom-left corner radius.
bottomRightRadius	Int	No	SDK default	Bottom-right corner radius.

Custom Fonts

Register fonts with FontSource before referencing them by fontName on any TextElement.

CICUIConfig(
  customFont = listOf(
    FontSource.Asset(
      fontName = "MyRoboto",
      file     = "playwrite.ttf"
    ),
    FontSource.File(
      fontName = "GoogleSans",
      path     = iconWavePath
    )
  ),
  scanningGuide = TextElement(
    text     = "Please insert your card",
    textSize = 12f,
    color    = Color.parseColor("#BB86FC"),
    fontName = "MyRoboto"
  )
)

Param	Type	Required	Default	Description
FontSource.Asset.fontName	String	Yes	—	The name to register the font under.
FontSource.Asset.file	String	Yes	—	Font file name in assets/.
FontSource.File.fontName	String	Yes	—	The name to register the font under.
FontSource.File.path	String	Yes	—	Absolute path to the font file.

INFO

A fontName on a TextElement only resolves if the same name was registered in customFont. An unregistered name falls back to the SDK default rather than raising an error, so a typo shows up as an unchanged typeface, not a crash.

Full Example

val uiConfig = CICUIConfig(
  customFont = listOf(
    FontSource.Asset(fontName = "MyRoboto", file = "playwrite.ttf")
  ),
  scanningGuide = TextElement(
    text     = "Đặt thẻ CCCD lên mặt sau điện thoại",
    textSize = 12f,
    color    = Color.parseColor("#BB86FC"),
    fontName = "MyRoboto"
  ),
  cancelButton = ButtonElement(
    text            = TextElement("Huỷ", textSize = 18f),
    backgroundColor = Color.parseColor("#008000"),
    strokeColor     = Color.parseColor("#fcba03"),
    borderRadius    = 32f
  ),
  nfcIcon = ImageElement(
    path      = "ic_android_nfc_wave.png",
    assetType = AssetType.ASSET
  ),
  loadingIndicator = ProgressBarElement(
    backgroundColor = Color.parseColor("#333333"),
    progressColor   = Color.parseColor("#BB86FC")
  ),
  windowView = WindowElement(
    backgroundColor   = Color.parseColor("#d9bd71"),
    topLeftRadius     = 32,
    topRightRadius    = 32,
    bottomLeftRadius  = 32,
    bottomRightRadius = 32
  )
)

val config = CICConfig(
  baseUrl           = "<BASE_URL>",
  connectTimeoutMs  = 60_000,
  readTimeoutMs     = 60_000,
  cacheScanStrategy = CICCacheScanStrategy.NO_CACHE,
  uiConfig          = uiConfig
)

Next Steps

• Create Transaction — mint the token the SDK authenticates with
• Read NFC — what the SDK submits once the chip read completes