- Created by Silvan Frey on Jul 15, 2026 5 minute read
You have English selected as language but this page has not been translated yet. Translate the page or view the content in the default space language below.
Display defaultLanguage
In order to change the language of the VICARD SDK, call the setLanguage method of the VicSettings:
VicSettings.Language.setLanguage(language: VicLang.EN)
The languages supported by the VICARD SDK are: German, English, Italian, French.
Typography
Font Families
In order to customize the font families of the VICARD SDK, change the following settings after initializing the SDK:
VicSettings.Typography.FontFamily.light VicSettings.Typography.FontFamily.regular VicSettings.Typography.FontFamily.medium VicSettings.Typography.FontFamily.semibold VicSettings.Typography.FontFamily.bold
Text Styles
In order to customize the text styles of the VICARD SDK, change the following settings after initializing the SDK:
VicSettings.Typography.TextStyle.pageTitle VicSettings.Typography.TextStyle.pageTitleInverted VicSettings.Typography.TextStyle.subhead VicSettings.Typography.TextStyle.subheadInverted VicSettings.Typography.TextStyle.copytext VicSettings.Typography.TextStyle.copytextInverted VicSettings.Typography.TextStyle.copytextBold VicSettings.Typography.TextStyle.copytextBoldInverted
Each typography object can be customized by the following settings:
family: String
size: UInt8
weight: UIFont.Weight
spacing: Float
uppercase: Bool
color: {
normal: UIColor
disabled: UIColor
error: UIColor
}
Buttons
In order to customize the buttons of the VICARD SDK, change the following settings after initializing the SDK:
VicSettings.Button.primary VicSettings.Button.primaryInverted VicSettings.Button.secondary VicSettings.Button.secondaryInverted
Each button object can be customized by the following settings:
text: {
family: String
size: UInt8
weight: UIFont.Weight
spacing: Float
uppercase: Bool
color: {
normal: UIColor
disabled: UIColor
selected: UIColor
}
}
backgroundColor: {
normal: UIColor
disabled: UIColor
selected: UIColor
}
border: {
width: UInt8,
radius: UInt8,
color: {
normal: UIColor
disabled: UIColor
selected: UIColor
}
}
iconColor: {
normal: UIColor
disabled: UIColor
selected: UIColor
}
Icons
In order to customize the icons color of the VICARD SDK, change the following settings after initializing the SDK:
VicSettings.Icon.close VicSettings.Icon.info VicSettings.Icon.flip VicSettings.Icon.error VicSettings.Icon.system VicSettings.Icon.systemInverted
Each icon object can be customized by the following settings color: UIColor.
Cards
Card Data
On the front card, by default, the following card data attributes are shown in this order:
cardNumber, institutionIdentificationNumber, personalIdentificationNumber, birthDate, policyNumber, expiryDate, barcode, appleWallet
The visibility and order of these attributes can be changed using defineCardListItemOrder(_:):
var listItemOrder: [VicSDK.VicCardListItem] cardViewController.defineCardListItemOrder(listItemOrder)
Card Appearance
Card appearance is configured via VicCardConfig objects. There are two levels of configuration:
- Type-level defaults —
VicSettings.Card.cardConfigKVGandVicSettings.Card.cardConfigVVGapply to all KVG or VVG cards respectively. - Per-card overrides —
VicSettings.Card.cardConfigs([String: VicCardConfig]) allows overrides keyed by exact card number. Per-card values take precedence over type-level defaults.
VicCardConfig
VicCardConfig bundles all per-card visual settings:
VicCardConfig(
freeField: String = "", // Free field text on the card back side
isMagneticStripEnabled: Bool = false, // Show magnetic strip on back side
showBackSide: Bool = true, // Enable flipping to card back side
cardFrontsideImage: UIImage? = nil, // Custom front background image
cardBacksideImageVVG: UIImage? = nil, // Custom VVG back background image
imageTextColors: VicLabelColorState? = nil, // Primary text color overlay on card image
imageSecondaryTextColors: VicLabelColorState? = nil // Secondary text color overlay on card image
)
Setting Type-Level Defaults
VicSettings.Card.cardConfigKVG = VicCardConfig(
showBackSide: true,
cardFrontsideImage: UIImage(named: "kvg_card_front")
)
VicSettings.Card.cardConfigVVG = VicCardConfig(
showBackSide: false,
isMagneticStripEnabled: true,
cardFrontsideImage: UIImage(named: "vvg_card_front"),
cardBacksideImageVVG: UIImage(named: "vvg_card_back")
)
Setting Per-Card Overrides
VicSettings.Card.cardConfigs["YOUR_CARD_NUMBER"] = VicCardConfig(
freeField: "YOUR_FREE_FIELD_TEXT",
showBackSide: true,
cardFrontsideImage: UIImage(named: "YOUR_CARD_DESIGN"),
imageTextColors: VicLabelColorState(normal: .white, disabled: .gray, error: .red),
imageSecondaryTextColors: VicLabelColorState(color: .purple)
)
Card Style
VicSettings.Card.style (VicCardState) controls the visual style of all card UI elements:
VicSettings.Card.style
├── front (VicCardFrontSideState)
│ ├── title — VicLabelTextState (family, size, weight, spacing, uppercase, color)
│ ├── label — VicLabelTextState
│ └── text — VicLabelTextState
├── backsideVVG (BacksideStateVVG)
│ └── freeField — VicLabelTextState
├── inner (VicCardInnerState)
│ ├── text — VicLabelTextState
│ └── border — VicCardBorderState (width, radius, color)
├── banner (VicCardBannerState)
│ ├── text — VicLabelTextState
│ ├── backgroundColor — VicBackgroundColorState (normal, disabled, error)
│ └── iconColor — VicBackgroundColorState
├── selection (VicCardSelectionState)
│ ├── label — VicLabelTextState
│ └── text — VicLabelTextState
├── backgroundColor — VicBackgroundColorState (normal, disabled, error)
└── border — VicCardBorderState (width, radius, color)
Deprecated
VicCardState.complementaryBack is deprecated — use VicCardState.backsideVVG instead.VicCardComplementaryBackSideState is deprecated — use BacksideStateVVG instead.
Free Field
Set the free field text via the type-level config:
// KVG default var kvgConfig = VicSettings.Card.cardConfigKVG kvgConfig.freeField = "YOUR_MANDATORY_FREE_FIELD_TEXT" VicSettings.Card.cardConfigKVG = kvgConfig // VVG default var vvgConfig = VicSettings.Card.cardConfigVVG vvgConfig.freeField = "YOUR_COMPLEMENTARY_FREE_FIELD_TEXT" VicSettings.Card.cardConfigVVG = vvgConfig
VicSettings.Card.cardConfigs["YOUR_CARD_NUMBER"] = VicCardConfig(freeField: "YOUR_FREE_FIELD_TEXT")
Deprecated
VicSettings.Card.freeField (VicCardFreeFieldState) is deprecated — use cardConfigKVG.freeField / cardConfigVVG.freeField directly.VicSettings.Card.setMandatoryFreeField(freeText:cardNumber:) is deprecated — set cardConfigs["YOUR_CARD_NUMBER"]?.freeField instead.VicSettings.Card.getMandatoryFreeField(cardNumber:) is deprecated — read cardConfigs["YOUR_CARD_NUMBER"]?.freeField instead.
Card Background Image
The VicSDK comes with a built-in default background image. To use a custom image, add it to your Xcode assets (e.g. Assets.xcassets). The image must meet the following rules:
- Must be a PNG with the bottom part empty (card-holder info is placed there dynamically)
- Form factor 1:1.73 — e.g. 945 × 546 px
- Logo placed in the right half, horizontally right-aligned and vertically centered; max size 70% width × 60% height of the total image
Set images via VicCardConfig:
// Type-level default
VicSettings.Card.cardConfigKVG = VicCardConfig(cardFrontsideImage: UIImage(named: "kvg_front"))
VicSettings.Card.cardConfigVVG = VicCardConfig(
cardFrontsideImage: UIImage(named: "vvg_front"),
cardBacksideImageVVG: UIImage(named: "vvg_back")
)
// Per-card override
VicSettings.Card.cardConfigs["YOUR_CARD_NUMBER"] = VicCardConfig(
cardFrontsideImage: UIImage(named: "YOUR_FRONT_DESIGN"),
cardBacksideImageVVG: UIImage(named: "YOUR_BACK_DESIGN")
)
Deprecated
VicSettings.Card.Image enum (.default, .mandatoryFront, .complementaryFront, .complementaryBack) is deprecated.VicSettings.Card.setImage(image:design:cardNumber:) is deprecated — use VicCardConfig.cardFrontsideImage / VicCardConfig.cardBacksideImageVVG via cardConfigKVG, cardConfigVVG, or cardConfigs.VicSettings.Card.getImage(design:cardNumber:) and getImageOrDefault(design:cardNumber:) are deprecated and no longer intended as public API.
Card Image Text Color
Set text color overlays via VicCardConfig:
VicSettings.Card.cardConfigs["YOUR_CARD_NUMBER"] = VicCardConfig(
imageTextColors: VicLabelColorState(normal: .white, disabled: .gray, error: .red),
imageSecondaryTextColors: VicLabelColorState(color: .purple)
)
Deprecated
VicSettings.Card.setImageTextColor(color:cardNumber:) and getImageTextColor(cardNumber:) are deprecated — use cardConfigs[cardNumber]?.imageTextColors instead.VicSettings.Card.setImageSecondaryTextColor(color:cardNumber:) and getImageSecondaryTextColor(cardNumber:) are deprecated — use cardConfigs[cardNumber]?.imageSecondaryTextColors instead.
Card Backside visibility
Control whether the card can be flipped via VicCardConfig.showBackSide. Default: true.
// Disable backside for all VVG cards VicSettings.Card.cardConfigVVG = VicCardConfig(showBackSide: false) // Or per-card VicSettings.Card.cardConfigs["YOUR_CARD_NUMBER"] = VicCardConfig(showBackSide: false)
Disabling this also hides the flip button and prevents rotation when tapping the card front.
Deprecated
VicSettings.Card.showComplementaryCardBackside is deprecated — use VicSettings.Card.cardConfigVVG.showBackSide instead.
Card Backside
The European back side of cards can be displayed in English regardless of the app language. Default: false.
VicSettings.Card.enableEnglishEuropeanCard = true
Use Alternative Label for Policy Number
The policy number label defaults to Policy Number To relabel it to Insured Person no.:
VicSettings.Card.useAlternativeLabelForPolicyNumber = true
Hiding Tutorial Screens
Individual tutorial screens can be hidden via hideTutorialScreen(_:) on the card view controller. Available cases in VicTutorialScreen:
| Case | Description |
|---|---|
.welcome | Welcome / intro screen |
.backcard | Back-of-card tutorial |
.barcode | Barcode tutorial |
.nfc | NFC tutorial |
.qrcode | QR code tutorial |
Indicators
In order to customize the indicators of the VICARD SDK, change the following settings after initializing the SDK:
VicSettings.Indicator.loading VicSettings.Indicator.page VicSettings.Indicator.scroll
The loading object can be customized by the following settings:
color: UIColor
The page object can be customized by the following settings:
color: {
normal: UIColor
active: UIColor
}
The scroll object can be customized by the following settings:
color: UIColor radius: UInt8
Apple Wallet Pass
Important
If no PassConfig is provided (neither global nor per-card), the Apple Wallet integration remains hidden in the UI.
PassConfig
PassConfig controls the appearance of a Wallet Pass:
PassConfig(
iconImage: UIImage, // 38×38 points
logoImage: UIImage, // 160×50 points max
foregroundColor: String, // Hex e.g. "#000000"
backgroundColor: String, // Hex e.g. "#FFFFFF"
labelColor: String, // Hex e.g. "#000000" — color of the pass title
barcodeFormat: BarcodeFormat = .pKBarcodeFormatCode128 // optional, defaults to Code128
)
Available BarcodeFormat values: .PKBarcodeFormatQR, .pKBarcodeFormatPDF417, .PKBarcodeFormatAztec, .pKBarcodeFormatCode128
Setting a Global Fallback
VicSettings.passConfig is used as a fallback when no card-specific config is available:
VicSettings.passConfig = PassConfig(
iconImage: UIImage(named: "wallet_icon")!,
logoImage: UIImage(named: "wallet_logo")!,
foregroundColor: "#000000",
backgroundColor: "#FFFFFF",
labelColor: "#000000"
)
Setting a Per-Card Config
To customize the pass for a specific card number, use setPassConfig(_:forCardNumber:). This takes precedence over the global fallback:
VicSettings.setPassConfig(
PassConfig(
iconImage: UIImage(named: "card_icon")!,
logoImage: UIImage(named: "card_logo")!,
foregroundColor: "#FFFFFF",
backgroundColor: "#003366",
labelColor: "#CCCCCC",
barcodeFormat: .PKBarcodeFormatQR
),
forCardNumber: "YOUR_CARD_NUMBER"
)
To read back the resolved config for a card (falls back to global if no per-card config is set):
let config = VicSettings.passConfig(forCardNumber: "YOUR_CARD_NUMBER")
- No labels