iOS Activation — Theming Guide

This guide covers everything a developer needs to customize the visual appearance of BlinkEngage SDK screens. The SDK uses a protocol-based theming system: you implement a single Theme protocol and hand it to the SDK. Every color, font, and icon flows through three key enums — AppearanceColorKey, AppearanceFontNameKey, and AppearanceIconKey.

---

Table of Contents

1. Architecture
2. Setup (Host App)
   • Swift Example
   • Objective-C Example
   • Assigning the Theme
   • Changing Theme at Runtime
3. Theme Protocol Reference
4. AppearanceColorKey Reference
5. AppearanceIconKey Reference
6. AppearanceFontNameKey Reference
7. AppearanceTextKey Reference
8. AppearanceGlobalColorKey Reference
9. Global Font Matrix
10. Tips and Pitfalls

---

1. Architecture

BlinkEngage/
└── Appearance/
    ├── AppearanceKey.swift         # AppearanceColorKey, AppearanceIconKey, AppearanceFontNameKey
    ├── Theme.swift                 # Theme protocol
    ├── Appearance.swift            # Appearance class

Type	Role
AppearanceColorKey (enum)	Identifies every customizable color — backgrounds, label text, icon tints.
AppearanceFontNameKey (enum)	Identifies every customizable font. Return a font name string; the SDK applies the correct point size.
AppearanceIconKey (enum)	Identifies every customizable image — reward icons, button icons, placeholders.
AppearanceTextKey (enum)	Identifies every customizable string — button labels and other SDK-controlled copy.
Theme (protocol)	Your class conforms to this. The SDK calls color(forKey:), fontName(forKey:), image(forKey:), and text(forKey:) to resolve styling.
Appearance (class)	Holds an optional Theme. Assigned to BlinkEngageSDK.shared.appearance.

All UI customization flows exclusively through the Theme protocol and these key enums. There are no per-property setters on Appearance.

---

2. Setup (Host App)

Swift Example

import BlinkEngage
import UIKit

class MyTheme: Theme {

    var isRewardIconEnabled: Bool { true }

    var isMerchantIconEnabled: Bool { true }

    var globalFontMatrix: NSDictionary? {
        [
            NSNumber(value: UIFont.Weight.regular.rawValue): "Outfit-Regular",
            NSNumber(value: UIFont.Weight.medium.rawValue):  "Outfit-Medium",
            NSNumber(value: UIFont.Weight.bold.rawValue):    "Outfit-Bold",
            NSNumber(value: UIFont.Weight.black.rawValue):   "Outfit-Black"
        ]
    }

    func color(forKey key: AppearanceColorKey) -> UIColor? {
        switch key {
        case .postScanHeaderBackground:
            return UIColor(named: "BrandPrimary")
        case .postScanFooterButtonTitle:
            return .white
        default:
            return nil   // SDK default
        }
    }

    func fontName(forKey key: AppearanceFontNameKey) -> String? {
        switch key {
        case .postScanSuccessTitleLabel:
            return "Outfit-ExtraBold"
        default:
            return nil   // falls back to globalFontMatrix, then system font
        }
    }

    func image(forKey key: AppearanceIconKey) -> UIImage? {
        switch key {
        case .offerRewardIcon:
            return UIImage(named: "my_coin_icon")
        default:
            return nil   // SDK default
        }
    }

    func text(forKey key: AppearanceTextKey) -> String? {
        return nil  // return a String to override SDK defaults
    }
}

Objective-C Example

// MyTheme.h
@import BlinkEngage;

@interface MyTheme : NSObject <Theme>
@end

// MyTheme.m
@implementation MyTheme

- (BOOL)isRewardIconEnabled { return YES; }
- (BOOL)isMerchantIconEnabled { return YES; }
- (NSDictionary *)globalFontMatrix { return nil; }

- (UIColor *)colorForKey:(AppearanceColorKey)key {
    switch (key) {
        case AppearanceColorKeyPostScanHeaderBackground:
            return [UIColor colorNamed:@"BrandPrimary"];
        default:
            return nil;
    }
}

- (NSString *)fontNameForKey:(AppearanceFontNameKey)key {
    return nil;  // Use SDK defaults
}

- (UIImage *)imageForKey:(AppearanceIconKey)key {
    return nil;  // Use SDK defaults
}

- (NSString *)textForKey:(AppearanceTextKey)key {
    return nil;  // Use SDK defaults
}

@end

Assigning the Theme

Set the theme before presenting any SDK view controller:

// In AppDelegate or wherever you configure BlinkEngage
let theme = MyTheme()
BlinkEngageSDK.shared.appearance = Appearance(theme: theme)

To use SDK defaults with no customization, use the parameterless initializer (this is the default):

BlinkEngageSDK.shared.appearance = Appearance()

Changing Theme at Runtime

You can reassign appearance at any time. The new theme takes effect the next time the SDK creates or reloads a view:

BlinkEngageSDK.shared.appearance = Appearance(theme: MyDarkTheme())

---

3. Theme Protocol Reference

@objc public protocol Theme: AnyObject {
    @objc var isMerchantIconEnabled: Bool { get }
    @objc var globalFontMatrix: NSDictionary? { get }
    @objc optional func color(forGlobalKey key: AppearanceGlobalColorKey) -> UIColor?
    @objc func color(forKey key: AppearanceColorKey) -> UIColor?
    @objc func fontName(forKey key: AppearanceFontNameKey) -> String?
    @objc func image(forKey key: AppearanceIconKey) -> UIImage?
    @objc func text(forKey key: AppearanceTextKey) -> String?
}

Member	Type	Purpose
isMerchantIconEnabled	Bool	true loads store logos from URL in the Stores screen. false always shows the default storefront icon.
globalFontMatrix	NSDictionary?	Maps UIFont.Weight raw values to font name strings. Used as a fallback when fontName(forKey:) returns nil. See Global Font Matrix.
color(forGlobalKey:) (optional)	UIColor?	Return a color for a semantic palette role (e.g. .primary, .textAccent). The SDK calls this after color(forKey:) returns nil for keys that map to a global role. Lets you apply a shared palette without matching every individual key. See AppearanceGlobalColorKey Reference.
color(forKey:)	UIColor?	Return a custom color for a specific UI element, or nil to fall through to color(forGlobalKey:) and then the SDK default.
fontName(forKey:)	String?	Return a PostScript font name (e.g. "Outfit-Bold"), or nil. The SDK creates the font at its expected point size.
image(forKey:)	UIImage?	Return a custom UIImage, or nil for the SDK default.
text(forKey:)	String?	Return a custom string to override SDK-controlled copy, or nil to keep the SDK default. See AppearanceTextKey Reference.

---

4. AppearanceColorKey Reference

Return a UIColor from color(forKey:) for any key below. Return nil to use the SDK default.

Offer Wall

Key	Description	Default
offerWallBackground	Background of the offer list area.	#FFFFFF
offerWallHeaderBackground	Header bar at the top of the offer wall.	Removed in v1.7.0 — use UINavigationController theming instead.
offerWallHeaderTitleLabel	Main title text in the offer wall header.	Removed in v1.7.0
offerWallHeaderSubtitleLabel	Subtitle or secondary line in the offer wall header.	Removed in v1.7.0
offerWallHeaderBackButtonIcon	Back / close arrow in the offer wall header.	Removed in v1.7.0
offerWallSectionHeaderLabel	Section title (e.g. "Offers for you") above a group of offers.	#142641
offerWallSectionHeaderShowMoreIcon	Arrow or chevron in the "Show more" section header button.	#0062F2
offerWallSectionHeaderShowMoreBackground	Background of the "Show more" section header button.	#0062F2 @ 8% opacity
offerWallFloatingButtonBackground	Background of the floating action button.	#0062F2
offerWallFloatingButtonLabel	Label text and icon tint on the floating button.	#FFFFFF
offerWallMoreMerchantsIcon	"More stores" icon in the stores row.	#0062F2

Offer Cards

Key	Description	Default
offerBackground	Background of each offer card.	#FCFBFA
offerBrandLabel	Brand or offer title on each offer card.	#142641
offerDescriptionLabel	Description or requirements text on each offer card.	#374151
offerEligibleMerchantsLabel	"Eligible at" or merchants list text on each offer card.	#0062F2
offerRewardPointsLabel	Reward amount or points text on each offer card.	#0062F2
offerTagBackground	Background of the promo badge on offer cards; also "BUY X" badge on offer details.	#D6E6FD
offerTagLabel	Promo badge label (e.g. "BUY 2") on offer cards; also "BUY X" badge on offer details.	#0062F2

Offer Clip / Clipped

Key	Description	Default
offerClipButtonBackground	Background of the clip button on an offer card.	#0062F2
offerClipButtonIcon	Icon for the clip button on an offer card.	#FFFFFF
offerClippedButtonBackground	Background of the clipped-state button on an offer card.	#29CC6A
offerClippedButtonIcon	Icon for the clipped-state button on an offer card.	#FFFFFF
offerClippedToastMessageBackground	Background of the "Offer clipped!" toast message.	#F3F4F6
offerClippedToastMessageLabel	Label text in the "Offer clipped!" toast message.	#142641

Offer Details

Key	Description	Default
offerDetailsTitleLabel	Primary title on the offer details screen.	#142641
offerDetailsEarnRewardLabel	"Earn …" reward line below the primary title on the offer details screen.	#0062F2
offerDetailsShortDescription	Short description under the offer title (e.g. coupon description and payout).	#142641
offerDetailsExpirationLabel	Expiration / "X Days Left" on the offer details screen.	#6B7280
offerDetailsClipLabel	"Clip this offer" label on the offer details screen.	#142641
offerDetailsClipRequiredBackground	"Clip Required" badge background.	#F3F4F6
offerDetailsClipRequiredLabel	"Clip Required" badge label.	#6B7280
offerDetailsSectionHeaderTitleLabel	Section header titles (e.g. "Eligible Products", "Description", "Fine Print").	#142641
offerDetailsSectionHeaderToggleLabel	Section header toggle text ("See all" / "See less").	#0062F2
offerDetailsSectionBodyLabel	Section body text (e.g. long description).	#142641
offerDetailsFinePrintLabel	Fine print / full terms body.	#9CA3AF
offerDetailsBuyOptionLabel	Label text in the buying options list.	#142641
offerDetailsBuyOptionBackground	Background of each row in the buying options list.	#FCFBFA
offerDetailsTagChipLabel	Tag chip label text on the offer details screen.	#727D8D
offerDetailsTagChipBorder	Tag chip outline / border on the offer details screen.	#E5E7EB
offerDetailsSectionNumberedListBadgeLabel	Digit inside each numbered step badge in a section's ordered list.	#FFFFFF
offerDetailsSectionNumberedListBadgeBackground	Background circle of each numbered step badge in a section's ordered list.	#0062F2

Ad Loading (Loading Screen)

Key	Description	Default
adLoadingDefaultTitleLabel	Title label (e.g. "Hang tight!").	#FFFFFF
adLoadingDefaultDescriptionLabel	Description label (e.g. "Exclusive rewards are coming your way!").	#FFFFFF
adLoadingLoadingBarBackground	Background of the progress bar track.	Black @ 8% opacity
adLoadingLoadingBarLabel	Label text and icon tint on the progress bar.	#FFFFFF
adLoadingLoadingBarProgress	Progress fill color.	#0062F2

Error Modal

Key	Description	Default
errorModalBackground	Background of the error modal card container.	#FCFBFA
errorModalIconBackground	Background of the warning icon (e.g. "!") on the error modal.	#FCA355
errorModalTitleLabel	Title label (e.g. "Oops!", "Invalid Receipt").	#142641
errorModalDescriptionLabel	Description / message label.	#142641
errorModalBackButtonLabel	"Back to offers" / dismiss button label.	#0062F2

Post Scan (Receipt Summary)

Key	Description	Default
postScanHeaderBackground	Background of the receipt summary header bar.	#0062F2
postScanTotalPointsBackground	Background of the total points pill (coin + amount) in the header.	Black @ 16% opacity
postScanTotalPointsLabel	Total points amount label in the header.	#FFFFFF
postScanReceiptButtonIcon	Icon tint for the receipt / missed earnings button in the header. When nil, the image uses original colors (no template tint).	nil (original colors)
postScanReceiptButtonBackground	Background of the receipt / missed earnings button in the header.	Black @ 16% opacity
postScanFooterBackground	Background of the receipt summary footer.	#FCFBFA
postScanFooterButtonTitle	Title (text color) of the continue button in the footer.	#0062F2
postScanSectionHeaderTitleLabel	Section header title label (e.g. "Your Rewards").	#9CA3AF
postScanMerchantNameLabel	Merchant name label in the trip summary.	#142641
postScanTripInfoLabel	Trip info label (date and total) in the trip summary.	#142641
postScanSuccessTitleLabel	Title label (e.g. "Nice Scan!") in the success state of the boost area.	#142641
postScanSuccessDescriptionLabel	Description label in the success state (e.g. points earned).	#142641
postScanNoBoostsLabel	Label in the "no boosts" empty state.	#142641
postScanBoostTitleLabel	Title label on post-scan boost cards.	#142641
postScanBoostDescriptionLabel	Description label on post-scan boost cards.	#142641
postScanBoostSkipButtonLabel	Label (text color) on the "Skip" button below boost cards.	#0062F2
postScanBoostClaimButtonLabel	Label (text color) on the "Claim" button below boost cards.	#FFFFFF
postScanBoostClaimButtonIcon	Icon tint on the "Claim" button. When nil, the icon uses original colors.	nil
postScanBoostClaimButtonBackground	Background of the "Claim" button below boost cards.	#0062F2
postScanPurchasePointsLabel	Points label (e.g. "+100") on purchase rows.	#0062F2
postScanPurchaseBackground	Background of a standard product row (no offer, not UGC).	#FFFFFF
postScanQualifiedPurchaseBackground	Background of qualified product rows.	#F9FAFB
postScanPurchaseInfoIcon	Info icon tint on product rows with an active earn task.	#D1D4D9
postScanInlineProductTaskBackground	Row background for products showing an inline earn task ("Snap & Earn" or "Watch & Earn").	#EBF2FE
postScanInlineProductTaskScanAndEarnBackground	"Snap & Earn" pill background and camera icon tint on UGC inline task rows.	#0062F2
postScanInlineProductTaskWatchAndEarnBackground	"Watch & Earn" pill background and play icon tint on rewarded-video inline task rows.	#0062F2
postScanInlineProductTaskScanAndEarnLabel	"Snap & Earn" pill text color on UGC inline task rows.	#FFFFFF
postScanInlineProductTaskWatchAndEarnLabel	"Watch & Earn" pill text color on rewarded-video inline task rows.	#FFFFFF
postScanInlineProductTaskPointsLabel	"+100" reward amount label on inline earn-task rows.	#0062F2

Purchase Row (Shared)

Key	Description	Default
purchaseRowLabelColor	Product name / description label color on purchase rows (receipt summary and Missed Earnings).	#142641
purchaseRowMetadataLabelColor	Metadata line label color on purchase rows (receipt summary and Missed Earnings).	#142641

Stores

Key	Description	Default
storesHeaderBackground	Background of the stores screen header bar.	#FFFFFF
storesHeaderTitleLabel	Title label in the stores screen header (e.g. "Stores").	#142641
storesListBackground	Background of the stores list area (view, cells, section headers).	#FFFFFF
storesListSectionHeaderLabel	Section header label in the stores list.	#142641
storesListItemBackground	Background of each store item (cell) in the list.	#FFFFFF
storesListItemDefaultIcon	Default thumbnail icon tint for each store item.	#D1D5DB
storesListItemTitleLabel	Title label for each store item.	#142641
storesListItemSubtitleLabel	Subtitle label for each store item.	#374151

Missed Earnings

Key	Description	Default
missedEarningsNavigationTitleLabel	Title label in the navigation header (e.g. "Missing rewards?").	#142641
missedEarningsNavigationDescriptionLabel	Description label in the navigation header.	#142641
missedEarningsNavigationEditButtonIcon	Icon tint for the Edit button in the navigation header.	#0062F2
missedEarningsNavigationEditButtonBackground	Background of the Edit button in the navigation header.	#F2F7FF
missedEarningsNavigationSaveButtonIcon	Icon tint of the Save button in the navigation header.	#FFFFFF
missedEarningsNavigationSaveButtonBackground	Background of the Save button in the navigation header.	#0062F2
missedEarningsFieldEditIcon	Icon tint of the edit (pen) button on each field row.	#0062F2
missedEarningsAddNewFieldLabel	Label and icon color for the "add new field" control.	#0062F2
missedEarningsModifiedFieldBackground	Background of modified field rows.	#ECFDF5
missedEarningsListSectionTitleLabel	Section header title in the list (e.g. "Merchant", "Date", "Products").	#262626
missedEarningsTripItemLabel	Label text in merchant and date rows only.	#142641
missedEarningsEditModalBackground	Background of the edit field modal.	#FCFBFA
missedEarningsEditModalTitleLabel	Title label at the top of the edit field modal.	#142641
missedEarningsEditModalSubtitleLabel	Subtitle label at the top of the edit field modal.	#142641
missedEarningsEditModalInputLabel	Label for text field titles in the edit field modal.	#262626
missedEarningsEditModalInputPlaceholderLabel	Placeholder text color in the edit field modal text fields.	#9CA3AF
missedEarningsEditModalInputValueLabel	Text field value / caption labels in the edit field modal.	#142641
missedEarningsEditModalCancelButtonLabel	Cancel button label (text color) in the edit field modal.	#0062F2
missedEarningsEditModalSaveButtonLabel	Save button label (text color) in the edit field modal.	#FFFFFF
missedEarningsEditModalSaveButtonBackground	Save button background in the edit field modal.	#0062F2
missedEarningsEditModalDatePicker	Tint color of the date picker (e.g. selected date highlight).	#0062F2
missedEarningsAlertTitleLabel	Title label in the alert modal (e.g. "No updates made", "Submit Receipt").	#142641
missedEarningsAlertMessageLabel	Message/body label in the alert modal.	#142641

UGC (Product Capture)

Key	Description	Default
ugcBarcodeDetectedBorder	Border color when a barcode is detected in the camera.	#10B990
ugcBarcodeDetectedIcon	Icon tint when a barcode is detected.	#FFFFFF
ugcNavigationButtonIcon	Icon tint for navigation buttons (close, torch) in the header.	#FFFFFF
ugcNavigationButtonBackground	Background of navigation buttons (close, torch) in the header.	#434343
ugcProductInfoBackground	Background of the product info badges (product name and barcode/UPC).	#262626
ugcProductInfoLabel	Label text color in the product info badges.	#FFFFFF
ugcToastMessageWarningIcon	Warning icon tint in the toast message.	#F43F5E
ugcRetakeButtonLabel	"Retake" button label (text color) in the footer.	#FFFFFF
ugcRetakeButtonBackground	"Retake" button background in the footer.	#434343
ugcSubmitButtonLabel	"Submit" button label (text color) in the footer.	#FFFFFF
ugcSubmitButtonBackground	"Submit" button background in the footer.	#0062F2

---

5. AppearanceIconKey Reference

Return a UIImage from image(forKey:) for any key below. Return nil to use the SDK default.

Key	Description	Default Behavior
offerRewardIcon	Reward / currency icon shown with reward amounts (offer cards, receipt summary).	When nil: controlled by isRewardIconEnabled — true shows default coin, false hides it.
offerWallFloatingButtonIcon	Floating action button icon (e.g. scan receipt). Tint uses offerWallFloatingButtonLabel color.	Default camera icon (SF Symbol).
missedEarningsNavigationEditButtonIcon	Edit button icon in the Missed Earnings header. Tint uses missedEarningsNavigationEditButtonIcon color.	Default pen icon.
missedEarningsFieldEditIcon	Edit (pen) button icon on each field row in Missed Earnings. Tint uses missedEarningsFieldEditIcon color.	Default pen icon.
postScanReceiptButtonIcon	Receipt / missed earnings button icon in the receipt summary header. Tint uses postScanReceiptButtonIcon color when set; nil color shows original image colors.	Default receipt icon.
postScanBoostDefaultIcon	Placeholder image for boost cards when no image URL is provided.	Default boost icon.
postScanSuccessIcon	Icon in the success state of the boost area (e.g. "Nice Scan!").	Default coin icon.
ugcBarcodeDetectedIcon	Icon when a barcode is detected in the product capture camera. Tint uses ugcBarcodeDetectedIcon color.	No default image (camera uses Lottie animation).
ugcToastMessageWarningIcon	Warning icon in the product capture toast message. Tint uses ugcToastMessageWarningIcon color.	info.circle.fill SF Symbol.

---

6. AppearanceFontNameKey Reference

Return a PostScript font name (e.g. "Outfit-Bold") from fontName(forKey:) for any key below. Return nil to fall back to the globalFontMatrix (by weight), then the system font. The SDK applies the correct point size for each key automatically.

Offer Wall

Key	Default Size	Default Weight
offerWallHeaderTitleLabel	24	Removed in v1.7.0
offerWallHeaderSubtitleLabel	14	Removed in v1.7.0
offerWallSectionHeaderLabel	18	700
offerWallFloatingButtonLabel	16	700

Offer Cards

Key	Default Size	Default Weight
offerRewardPointsLabel	16	900
offerTagLabel	12	700
offerBrandLabel	16	700
offerDescriptionLabel	12	400
offerEligibleMerchantsLabel	12	500

Offer Clipped

Key	Default Size	Default Weight
offerClippedToastMessageLabel	14	500

Offer Details

Key	Default Size	Default Weight
offerDetailsTitleLabel	20	700
offerDetailsEarnRewardLabel	16	700
offerDetailsShortDescription	20	700
offerDetailsExpirationLabel	14	400 (Italic)
offerDetailsClipLabel	14	700
offerDetailsClipRequiredLabel	14	700
offerDetailsSectionHeaderTitleLabel	16	700
offerDetailsSectionHeaderToggleLabel	12	600
offerDetailsSectionBodyLabel	14	400
offerDetailsFinePrintLabel	12	400
offerDetailsBuyOptionLabel	14	500
offerDetailsTagChipLabel	12	500

Ad Loading (Loading Screen)

Key	Default Size	Default Weight
adLoadingDefaultTitleLabel	20	700
adLoadingDefaultDescriptionLabel	16	400
adLoadingLoadingBarLabel	14	700

Error Modal

Key	Default Size	Default Weight
errorModalTitleLabel	18	700
errorModalDescriptionLabel	14	400
errorModalBackButtonLabel	14	700

Post Scan (Receipt Summary)

Key	Default Size	Default Weight
postScanTotalPointsLabel	24	900
postScanFooterButtonTitle	14	700
postScanSectionHeaderTitleLabel	14	400
postScanMerchantNameLabel	24	700
postScanTripInfoLabel	14	500
postScanSuccessTitleLabel	18	700
postScanSuccessDescriptionLabel	14	500
postScanNoBoostsLabel	16	400
postScanBoostTitleLabel	14	700
postScanBoostDescriptionLabel	13	400
postScanBoostSkipButtonLabel	14	700
postScanBoostClaimButtonLabel	14	700
postScanPurchasePointsLabel	18	900
postScanInlineProductTaskPointsLabel	14	700
postScanInlineProductTaskScanAndEarnLabel	12	600
postScanInlineProductTaskWatchAndEarnLabel	12	600

Purchase Row (Shared)

Key	Default Size	Default Weight
purchaseRowLabelFont	14	700
purchaseRowMetadataLabelFont	14	400

Stores

Key	Default Size	Default Weight
storesHeaderTitleLabel	20	700
storesListSectionHeaderLabel	18	700
storesListItemTitleLabel	14	700
storesListItemSubtitleLabel	14	400

Missed Earnings

Key	Default Size	Default Weight
missedEarningsNavigationTitleLabel	20	700
missedEarningsNavigationDescriptionLabel	14	400
missedEarningsListSectionTitleLabel	14	400
missedEarningsTripItemLabel	14	500
missedEarningsEditModalTitleLabel	18	700
missedEarningsEditModalSubtitleLabel	16	400
missedEarningsEditModalInputLabel	14	400
missedEarningsEditModalInputPlaceholderLabel	14	400
missedEarningsEditModalInputValueLabel	14	500
missedEarningsEditModalCancelButtonLabel	14	700
missedEarningsEditModalSaveButtonLabel	14	700
missedEarningsAlertTitleLabel	18	700
missedEarningsAlertMessageLabel	16	400

UGC (Product Capture)

Key	Default Size	Default Weight
ugcProductInfoLabel	14	400
ugcRetakeButtonLabel	16	400
ugcSubmitButtonLabel	16	700

---

7. AppearanceTextKey Reference

Return a String from text(forKey:) for any key below. Return nil to use the SDK default.

Key	Default	Description
offerWallFloatingButtonExpandedLabel	"Scan Receipt"	Label on the floating action button when it is in its expanded (full-width) state.
offerWallFloatingButtonCollapsedLabel	"Scan"	Label on the floating action button when it is collapsed to a compact size.

---

8. AppearanceGlobalColorKey Reference

AppearanceGlobalColorKey defines a small semantic palette. Implement the optional color(forGlobalKey:) method on your Theme to set shared brand colors that the SDK automatically distributes across related UI elements — without having to match every individual AppearanceColorKey.

Color resolution order for any given key:

1. color(forKey:) — specific per-element override
2. color(forGlobalKey:) — semantic palette role (if the key maps to one)
3. Built-in SDK default

func color(forGlobalKey key: AppearanceGlobalColorKey) -> UIColor? {
    switch key {
    case .primary:       return UIColor(named: "BrandPrimary")
    case .textAccent:    return UIColor(named: "BrandAccent")
    case .success:       return UIColor(named: "BrandSuccess")
    default:             return nil
    }
}

Key	Semantic role	Example elements
primary	Main brand color for actions and prominent interactive elements.	Floating button background, clip button, progress bar fill.
secondary	Supporting accent for secondary action surfaces.	Section headers, secondary buttons.
success	Completed, clipped, or valid states.	Clipped button background, "Offer clipped!" toast.
warning	Cautionary or non-blocking alert states.	Error modal warning icon.
error	Destructive, invalid, or blocking states.	Error modal icon background.
border	Borders, dividers, and neutral icon tints.	Tag chip border, default store icon.
textPrimary	Titles and high-emphasis copy.	Offer brand labels, section titles, modal headlines.
textSecondary	Captions, metadata, and muted copy.	Offer description, expiration labels.
textAccent	Links, rewards, and branded inline emphasis.	Reward amount labels, eligible merchants line, earn-reward line.
background	Main page or screen background.	Offer wall background, stores list background.
surfaceBackground	Cards, modals, rows, and elevated surfaces.	Offer card background, error modal background.
accentBackground	Tinted pills, badges, and highlights.	Offer tag pill, "show more" button.
backgroundInverse	Foreground content on dark, saturated, or inverse surfaces.	Floating button label, clipped button icon.

Return nil for any key to keep the SDK default for that role.

---

9. Global Font Matrix

The globalFontMatrix property lets you define a single set of brand fonts mapped by weight. When fontName(forKey:) returns nil for a given key, the SDK looks up the expected weight in this matrix before falling back to the system font.

var globalFontMatrix: NSDictionary? {
    [
        NSNumber(value: UIFont.Weight.regular.rawValue):  "Outfit-Regular",
        NSNumber(value: UIFont.Weight.medium.rawValue):   "Outfit-Medium",
        NSNumber(value: UIFont.Weight.semibold.rawValue): "Outfit-SemiBold",
        NSNumber(value: UIFont.Weight.bold.rawValue):     "Outfit-Bold",
        NSNumber(value: UIFont.Weight.black.rawValue):    "Outfit-Black"
    ]
}

Font resolution order:

1. fontName(forKey:) — specific override for this key
2. globalFontMatrix — weight-based lookup
3. System font at the expected weight and size

---

10. Tips and Pitfalls

Set the theme before presenting SDK views. The Appearance instance is read when views are created. If you assign it after a view controller is already on screen, the old styling persists until the view is recreated.

Return nil to keep SDK defaults. You do not need to handle every case in your color(forKey:) / fontName(forKey:) / image(forKey:) implementations. A default: return nil is sufficient for any keys you don't want to customize.

Font sizing is automatic. When you return a font name from fontName(forKey:), the SDK creates the font at its own expected point size for that key. You control the typeface; the SDK controls the size. Do not try to encode size into the font name.

color(forGlobalKey:) is additive, not a replacement. Per-key overrides from color(forKey:) always take priority. Use the global palette to cover the common case, then add per-key overrides only where you need to diverge.

isMerchantIconEnabled controls URL loading, not the icon slot. When false, the stores list always shows the default storefront icon rather than downloading merchant logos.

Icon tinting pairs. Several icon keys share a tint color key with the same name (e.g. AppearanceIconKey.missedEarningsFieldEditIcon is tinted by AppearanceColorKey.missedEarningsFieldEditIcon). If you provide a custom image for an icon key, check whether you also want to override the corresponding color key, since the SDK renders many icons with template mode.

Objective-C compatibility. All enums are @objc backed by Int. In Objective-C, use the prefixed names (e.g. AppearanceColorKeyOfferWallHeaderBackground).

---