Skip to main content

UI Theme Customization

The Entrupy iOS SDK allows for basic customization of its user interface appearance through a theming system. This enables you to align the SDK's views more closely with your application's branding and visual style.

This guide explains how to define and apply a custom theme.

Overview​

The SDK provides an EntrupyTheme protocol (or a similar mechanism). By creating a class that conforms to this protocol and setting its properties, you can specify custom colors for various UI elements within the SDK's views, such as background colors, foreground (text) colors, and border colors.

Custom theming applies globally to the Entrupy SDK views presented by your application.

Defining a Custom Theme​

To create a custom theme, you need to define a class that implements the EntrupyTheme protocol (or conforms to the SDK's specified theming mechanism). Within this class, you set the desired UIColor values for the theme properties.

// Swift
import EntrupySDK
import UIKit // Required for UIColor

class MyAppEntrupyTheme: EntrupyTheme {
    // Example: Light theme with custom blue accents
    var backgroundColor: UIColor? = UIColor.white
    var foregroundColor: UIColor? = UIColor.black // For primary text
    var borderColor: UIColor? = UIColor.lightGray

    // Additional color properties might be available, for example:
    // var accentColor: UIColor? = UIColor(red: 0.0, green: 0.4, blue: 0.8, alpha: 1.0) // A custom blue
    // var secondaryForegroundColor: UIColor? = UIColor.darkGray // For less prominent text
    // var buttonBackgroundColor: UIColor? = UIColor(red: 0.0, green: 0.4, blue: 0.8, alpha: 1.0)
    // var buttonTextColor: UIColor? = UIColor.white

    // Initialize any custom colors if not using system or standard colors
    init() {
        // If you had custom colors defined programmatically:
        // self.accentColor = UIColor(named: "MyAppBlue") ?? UIColor.blue
    }
}

(The exact properties available on the EntrupyTheme protocol, such as accentColor, secondaryForegroundColor, buttonBackgroundColor, buttonTextColor, etc., must be verified from the current SDK's definition of this protocol. Section 16 of sdk-v1-legacy.md shows borderColor, backgroundColor, and foregroundColor as the primary examples.)

Applying the Custom Theme​

Once you have defined your custom theme class, you need to instantiate it and assign it to the theme property of the EntrupyApp.sharedInstance().

This should typically be done early in your application's lifecycle, such as in your AppDelegate or SceneDelegate, before any Entrupy SDK views are presented. It must be set before any other SDK calls that might present UI.

// Swift
// In your AppDelegate.swift or SceneDelegate.swift, or early in your app setup

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ... other application setup ...

    // Apply the custom Entrupy SDK theme
    EntrupyApp.sharedInstance().theme = MyAppEntrupyTheme()
    print("Custom Entrupy SDK theme applied.")

    // ... continue with SDK initialization and other setup ...

    return true
}

Scope of Theming​

The custom theme will affect the visual appearance of standard UI elements within the Entrupy SDK, including:

  • Backgrounds of views and screens.
  • Text colors for labels and messages.
  • Border colors for containers or separators.
  • Potentially, colors for interactive elements like buttons if more detailed theme properties are available.

Visual Examples​

(The following descriptions are based on the images in sdk-v1-legacy.md, Section 16)

Default Entrupy Theme:

  • Typically features darker backgrounds (e.g., dark gray or near-black) with light-colored text (e.g., white or light gray) and accents that align with Entrupy's branding.

**Custom Theme (Example - Light Theme from sdk-v1-legacy.md):

  • backgroundColor: UIColor.white
  • foregroundColor: UIColor.black
  • borderColor: UIColor.lightGray
  • This results in SDK views with a white background, black text, and light gray borders, offering a significantly different look that might better match apps with a light color scheme.

Best Practices​

  • Early Application: Apply the theme as early as possible in your app's lifecycle to ensure all SDK views are presented with the custom theme from their first appearance.
  • Contrast and Accessibility: When choosing colors, ensure sufficient contrast between background and foreground elements to maintain readability and accessibility for all users.
  • Test Thoroughly: After applying a custom theme, test all Entrupy SDK flows within your app to ensure the UI is visually coherent and all elements are clearly discernible.
  • Consistency: Aim for a theme that complements your overall application design for a seamless user experience.
  • Check SDK Updates: When updating the Entrupy SDK, review the EntrupyTheme protocol or theming mechanism for any new properties or changes that might affect your custom theme.

By using UI theme customization, you can provide a more integrated and branded experience for your users when they interact with the Entrupy authentication flows within your application.

Guidance for Custom UI Results Screens​

While the Entrupy SDK provides a comprehensive Detail View for displaying authentication results, ETAs, and related information, some integrators may choose to build their own custom UI to present these outcomes to the end-user after the SDK's Capture Flow is complete and the results are obtained (e.g., via API polling or webhooks).

If you opt to create a custom UI for results:

  • Clarity of Results:
    • Ensure the authentication outcome (e.g., "Authentic", "Unidentified" or your platform-specific equivalents) is displayed prominently and unambiguously.
    • Use clear visual cues (e.g., color, icons) that are consistent with the meaning of the result.
  • Essential Information:
    • At a minimum, display the final authentication status.
    • Consider including the Entrupy ID or your customer_item_id for reference.
    • If an Entrupy Certificate is generated for "Authentic" items, provide a clear way for the user to access it (e.g., a "View Certificate" button linking to the certificate URL obtained via the API).
  • Consistency with SDK Experience:
    • If users interact with the SDK's Capture Flow, ensure your custom results screen provides a logical and consistent continuation of that experience.
  • Next Steps and Support:
    • Provide clear calls to action or next steps for the user based on the result (e.g., "List your item," "Contact support," "Learn more").
    • If the result requires further action or clarification, guide the user appropriately.

Next Steps​

  • Review the Capture Flow UI Guide and Detail View Controller Guide to see the primary UI components that will be affected by theming.
  • Consult the official Entrupy iOS SDK documentation or API reference for the exact definition of the EntrupyTheme protocol and all available themable properties.