UI Theme Customization

The Entrupy Android SDK provides comprehensive theming capabilities to match your app's design language and brand identity. This guide covers how to customize the appearance of SDK components.

Overview

The SDK supports customization of:

• Colors and backgrounds
• Typography and text styles
• Button styles and interactions
• Layout spacing and dimensions
• Branding elements

Basic Theme Configuration

1. Define Custom Theme

Create a custom theme in your res/values/themes.xml:

<!-- res/values/themes.xml -->
<resources>
    <!-- Base application theme -->
    <style name="Theme.YourApp" parent="Theme.Material3.DayNight">
        <!-- Primary brand color -->
        <item name="colorPrimary">@color/your_primary_color</item>
        <item name="colorPrimaryVariant">@color/your_primary_variant</item>
        <item name="colorOnPrimary">@color/your_on_primary_color</item>
        
        <!-- Secondary brand color -->
        <item name="colorSecondary">@color/your_secondary_color</item>
        <item name="colorSecondaryVariant">@color/your_secondary_variant</item>
        <item name="colorOnSecondary">@color/your_on_secondary_color</item>
        
        <!-- Status bar color -->
        <item name="android:statusBarColor">@color/your_status_bar_color</item>
        
        <!-- Navigation bar color -->
        <item name="android:navigationBarColor">@color/your_navigation_bar_color</item>
    </style>
</resources>

2. Define Colors

Create your color palette in res/values/colors.xml:

<!-- res/values/colors.xml -->
<resources>
    <!-- Primary colors -->
    <color name="your_primary_color">#1976D2</color>
    <color name="your_primary_variant">#1565C0</color>
    <color name="your_on_primary_color">#FFFFFF</color>
    
    <!-- Secondary colors -->
    <color name="your_secondary_color">#FFC107</color>
    <color name="your_secondary_variant">#FFB300</color>
    <color name="your_on_secondary_color">#000000</color>
    
    <!-- Status and navigation -->
    <color name="your_status_bar_color">#1565C0</color>
    <color name="your_navigation_bar_color">#FFFFFF</color>
    
    <!-- Background colors -->
    <color name="your_background_color">#FFFFFF</color>
    <color name="your_surface_color">#F5F5F5</color>
    
    <!-- Text colors -->
    <color name="your_text_primary">#212121</color>
    <color name="your_text_secondary">#757575</color>
    <color name="your_text_disabled">#BDBDBD</color>
    
    <!-- Error colors -->
    <color name="your_error_color">#D32F2F</color>
    <color name="your_on_error_color">#FFFFFF</color>
    
    <!-- Success colors -->
    <color name="your_success_color">#388E3C</color>
    <color name="your_on_success_color">#FFFFFF</color>
</resources>

3. Apply Theme to SDK

Configure the SDK to use your custom theme:

// In your Application class or main activity
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Initialize SDK with custom theme
        Entrupy.init(
            context = this,
            apiKey = "your-api-key",
            themeConfig = EntrupyThemeConfig(
                themeResId = R.style.Theme_YourApp,
                colorsResId = R.color.class
            )
        )
    }
}

Advanced Theme Customization

1. Custom Color Overrides

Override specific SDK colors while keeping the base theme:

val customColors = EntrupyColors(
    primary = Color.parseColor("#1976D2"),
    primaryVariant = Color.parseColor("#1565C0"),
    onPrimary = Color.parseColor("#FFFFFF"),
    secondary = Color.parseColor("#FFC107"),
    secondaryVariant = Color.parseColor("#FFB300"),
    onSecondary = Color.parseColor("#000000"),
    background = Color.parseColor("#FFFFFF"),
    surface = Color.parseColor("#F5F5F5"),
    error = Color.parseColor("#D32F2F"),
    onError = Color.parseColor("#FFFFFF"),
    success = Color.parseColor("#388E3C"),
    onSuccess = Color.parseColor("#FFFFFF")
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        colors = customColors
    )
)

2. Typography Customization

Customize text styles and fonts:

val customTypography = EntrupyTypography(
    headlineLarge = TextStyle(
        fontFamily = FontFamily(Font(R.font.your_headline_font)),
        fontSize = 32.sp,
        fontWeight = FontWeight.Bold,
        color = Color.parseColor("#212121")
    ),
    headlineMedium = TextStyle(
        fontFamily = FontFamily(Font(R.font.your_headline_font)),
        fontSize = 28.sp,
        fontWeight = FontWeight.SemiBold,
        color = Color.parseColor("#212121")
    ),
    bodyLarge = TextStyle(
        fontFamily = FontFamily(Font(R.font.your_body_font)),
        fontSize = 16.sp,
        fontWeight = FontWeight.Normal,
        color = Color.parseColor("#212121")
    ),
    bodyMedium = TextStyle(
        fontFamily = FontFamily(Font(R.font.your_body_font)),
        fontSize = 14.sp,
        fontWeight = FontWeight.Normal,
        color = Color.parseColor("#757575")
    ),
    labelLarge = TextStyle(
        fontFamily = FontFamily(Font(R.font.your_label_font)),
        fontSize = 14.sp,
        fontWeight = FontWeight.Medium,
        color = Color.parseColor("#212121")
    )
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        typography = customTypography
    )
)

3. Component-Specific Styling

Customize specific SDK components:

val componentStyles = EntrupyComponentStyles(
    button = ButtonStyle(
        backgroundColor = Color.parseColor("#1976D2"),
        textColor = Color.parseColor("#FFFFFF"),
        cornerRadius = 8.dp,
        elevation = 2.dp
    ),
    card = CardStyle(
        backgroundColor = Color.parseColor("#FFFFFF"),
        cornerRadius = 12.dp,
        elevation = 4.dp,
        strokeColor = Color.parseColor("#E0E0E0"),
        strokeWidth = 1.dp
    ),
    inputField = InputFieldStyle(
        backgroundColor = Color.parseColor("#F5F5F5"),
        textColor = Color.parseColor("#212121"),
        placeholderColor = Color.parseColor("#757575"),
        cornerRadius = 8.dp,
        borderColor = Color.parseColor("#E0E0E0"),
        borderWidth = 1.dp
    )
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        componentStyles = componentStyles
    )
)

Dark Theme Support

1. Define Dark Theme Colors

<!-- res/values-night/colors.xml -->
<resources>
    <!-- Dark theme colors -->
    <color name="your_primary_color">#90CAF9</color>
    <color name="your_primary_variant">#64B5F6</color>
    <color name="your_on_primary_color">#000000</color>
    
    <color name="your_secondary_color">#FFD54F</color>
    <color name="your_secondary_variant">#FFCA28</color>
    <color name="your_on_secondary_color">#000000</color>
    
    <color name="your_background_color">#121212</color>
    <color name="your_surface_color">#1E1E1E</color>
    
    <color name="your_text_primary">#FFFFFF</color>
    <color name="your_text_secondary">#B3FFFFFF</color>
    <color name="your_text_disabled">#80FFFFFF</color>
</resources>

2. Dark Theme Configuration

val darkThemeColors = EntrupyColors(
    primary = Color.parseColor("#90CAF9"),
    primaryVariant = Color.parseColor("#64B5F6"),
    onPrimary = Color.parseColor("#000000"),
    background = Color.parseColor("#121212"),
    surface = Color.parseColor("#1E1E1E"),
    textPrimary = Color.parseColor("#FFFFFF"),
    textSecondary = Color.parseColor("#B3FFFFFF")
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        colors = if (isDarkTheme()) darkThemeColors else lightThemeColors
    )
)

Branding Elements

1. Custom Logo

val brandingConfig = EntrupyBrandingConfig(
    logo = R.drawable.your_logo,
    logoWidth = 120.dp,
    logoHeight = 40.dp,
    showPoweredByEntrupy = false // Hide "Powered by Entrupy" text
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        branding = brandingConfig
    )
)

2. Custom Loading Animation

val loadingConfig = EntrupyLoadingConfig(
    customAnimation = R.raw.your_loading_animation,
    backgroundColor = Color.parseColor("#FFFFFF"),
    showProgressText = true,
    progressTextColor = Color.parseColor("#212121")
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        loading = loadingConfig
    )
)

Dynamic Theme Updates

1. Runtime Theme Changes

class ThemeManager {
    
    fun updateTheme(isDark: Boolean) {
        val newColors = if (isDark) darkThemeColors else lightThemeColors
        
        EntrupySdk.getInstance().updateTheme(
            EntrupyThemeConfig(colors = newColors)
        )
    }
    
    fun updateBranding(newLogo: Int) {
        val newBranding = EntrupyBrandingConfig(
            logo = newLogo,
            logoWidth = 120.dp,
            logoHeight = 40.dp
        )
        
        EntrupySdk.getInstance().updateTheme(
            EntrupyThemeConfig(branding = newBranding)
        )
    }
}

2. Seasonal Themes

class SeasonalThemeManager {
    
    fun applySeasonalTheme(season: Season) {
        val seasonalColors = when (season) {
            Season.SPRING -> springColors
            Season.SUMMER -> summerColors
            Season.FALL -> fallColors
            Season.WINTER -> winterColors
        }
        
        EntrupySdk.getInstance().updateTheme(
            EntrupyThemeConfig(colors = seasonalColors)
        )
    }
}

Accessibility Support

1. High Contrast Mode

val accessibilityConfig = EntrupyAccessibilityConfig(
    highContrast = isHighContrastEnabled(),
    largeText = isLargeTextEnabled(),
    reduceMotion = isReduceMotionEnabled()
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        accessibility = accessibilityConfig
    )
)

2. Content Descriptions

val contentDescriptions = EntrupyContentDescriptions(
    captureButton = "Start item authentication",
    retakeButton = "Retake photos",
    submitButton = "Submit for authentication",
    cancelButton = "Cancel authentication"
)

Entrupy.init(
    context = this,
    apiKey = "your-api-key",
    themeConfig = EntrupyThemeConfig(
        contentDescriptions = contentDescriptions
    )
)

Testing Theme Customization

1. Theme Preview

class ThemePreviewActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_theme_preview)
        
        // Preview different themes
        findViewById<Button>(R.id.btn_light_theme).setOnClickListener {
            applyTheme(lightThemeConfig)
        }
        
        findViewById<Button>(R.id.btn_dark_theme).setOnClickListener {
            applyTheme(darkThemeConfig)
        }
        
        findViewById<Button>(R.id.btn_custom_theme).setOnClickListener {
            applyTheme(customThemeConfig)
        }
    }
    
    private fun applyTheme(themeConfig: EntrupyThemeConfig) {
        EntrupySdk.getInstance().updateTheme(themeConfig)
        // Refresh UI to show changes
        recreate()
    }
}

2. Theme Validation

class ThemeValidator {
    
    fun validateTheme(themeConfig: EntrupyThemeConfig): ValidationResult {
        val errors = mutableListOf<String>()
        
        // Check color contrast ratios
        if (!hasAdequateContrast(themeConfig.colors.primary, themeConfig.colors.onPrimary)) {
            errors.add("Primary color contrast is insufficient")
        }
        
        // Check text readability
        if (!isTextReadable(themeConfig.colors.textPrimary, themeConfig.colors.background)) {
            errors.add("Text is not readable on background")
        }
        
        return ValidationResult(
            isValid = errors.isEmpty(),
            errors = errors
        )
    }
}

Best Practices

1. Color Consistency

• Use a consistent color palette throughout your app
• Ensure adequate contrast ratios for accessibility
• Test themes in both light and dark modes

2. Typography Hierarchy

• Use clear typography hierarchy for different content types
• Ensure font sizes are readable on all device sizes
• Support system font scaling for accessibility

3. Component Consistency

• Maintain consistent spacing and sizing across components
• Use consistent corner radii and elevation values
• Ensure interactive elements have clear visual feedback

4. Performance Considerations

• Cache theme configurations to avoid repeated parsing
• Use vector drawables for logos and icons
• Minimize theme updates during user interactions

This comprehensive theming system allows you to create a seamless, branded experience that integrates perfectly with your Android application's design language.