UI Theme Customization
You can change the colors of the Entrupy iOS SDK screens so they match your app. The SDK reads three colors from a theme object you provide: background, foreground (text), and border.
This guide explains how to define and apply a custom theme, which screens it changes, and what stays in the default Entrupy styling.
The EntrupyTheme protocol
EntrupyTheme has three optional properties:
| Property | Type | What it colors |
|---|---|---|
backgroundColor | UIColor? | Screen, card, and navigation bar backgrounds |
foregroundColor | UIColor? | Primary text, titles, and secondary button titles |
borderColor | UIColor? | Borders and separators on cards and containers |
Each color falls back to the default Entrupy color on its own. If you leave a property nil, the SDK paints that element exactly as it does without a theme.
Defining a custom theme
Create a class that conforms to EntrupyTheme and set the colors you want.
// Swift
import EntrupySDK
import UIKit
class MyAppEntrupyTheme: EntrupyTheme {
var backgroundColor: UIColor? = UIColor.white
var foregroundColor: UIColor? = UIColor.black
var borderColor: UIColor? = UIColor.lightGray
}
A theme can set only some of the colors:
class MyDarkEntrupyTheme: EntrupyTheme {
var backgroundColor: UIColor? = UIColor.black
var foregroundColor: UIColor? = UIColor.white
var borderColor: UIColor? = nil // keeps the default border color
}
If you set a light backgroundColor, also set foregroundColor. The default text color is white, so a light background with no foreground leaves text hard to read.
Applying the custom theme
Assign an instance of your theme to EntrupyApp.sharedInstance().theme at app launch, before you present any SDK UI.
// Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
EntrupyApp.sharedInstance().theme = MyAppEntrupyTheme()
// ... continue with SDK initialization and other setup ...
return true
}
Setting theme to nil returns SDK screens presented after that point to the default Entrupy styling.
Screens the theme affects
From SDK 2.3.4, a configured theme applies to these screens:
- The capture flow, including the Upload Images screen and the image guide
- Retake capture
- The result detail screen, its menu, the flag sheet, and the timeline
- Market Edge
- Certificate and certificate transfer screens
The status bar style on full-screen SDK screens follows the theme background, so light backgrounds get a dark status bar.
What the theme does not change
These keep the default Entrupy styling with or without a theme:
- Gold buttons and gold borders
- Banners and the pull-to-refresh control
- Result state and other semantic colors (for example, authentic or unidentified indicators)
- Muted grey helper text
- Camera overlays
- The image crop screen
- System UI such as alerts and share sheets
Default styling
When no theme is set, or a property is nil, the SDK uses the default Entrupy styling: dark navy backgrounds, white text, and gold accents.
Default Entrupy theme
The light theme from the first example above produces white backgrounds, black text, and light gray borders:
Custom light theme
Best Practices
- Early Application: Set the theme before presenting any SDK UI so every screen uses it from its first appearance.
- Contrast and Accessibility: Keep enough contrast between
backgroundColorandforegroundColor. Remember that gold buttons and semantic colors are not themed, so check that they stay readable on your background. - Test Thoroughly: Run each SDK flow you use (capture, retake, result detail, flagging) with your theme in both light and dark mode on the device.
- Check SDK Updates: Review this page when you update the SDK, in case the protocol or the list of themed screens changes.
Guidance for Custom UI Results Screens
While the Entrupy SDK provides a comprehensive Detail Screen 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_idfor 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 Screen UI Guide to see the primary screens the theme changes.