Customize Branding

Overview

The SDKConfiguration class, and the types it contains, encapsulate the configuration and branding aspects of the SDK. The singleton instance SDKConfiguration.shared provides an access to all current configuration and branding values, and allows to change any of the values.

The ColorPalette class, accessible via the SDKConfiguration.shared.colors property, provides the way to map your branding to all the visual elements of the SDK components.

In addition, using the CaptureStyle class, accessible via the SDKConfiguration.shared.capture.theme property, you can tweak the colors and appearance of each element of the Capture experience.

Changing the color palette

When SDKConfiguration.shared is created, its colors property is initialized with the colors from the default palette, described above. You can override this default palette with your colors before starting the SDK:

let configuration = SDKConfiguration.shared

configuration.colors.primary = .blue
configuration.colors.primaryVariant = .purple
configuration.colors.onPrimary = .white

configuration.colors.secondary = .magenta
configuration.colors.onSecondary = .white

configuration.colors.background = .white
configuration.colors.onBackground = .black

configuration.colors.surface = .cyan
configuration.colors.surfaceVariant = .orange
configuration.colors.onSurface = .black
configuration.colors.onSurfaceFocus = .green

configuration.colors.error = .red
configuration.colors.onError = .white

Since you are setting these properties on the singleton SDKConfiguration.shared object, there are no other changes needed (i.e. you don’t need to pass this object anywhere) as any UI created in the SDK will use these new values.

Fine-grained branding of the Capture experience inside the SDK

By default Capture is using a minimalistic, mostly black and white theme, with the few touches from the color pallete we discussed above. This matches with the colors of the theme in camera apps most users are familiar with. You can, however, override the styling of every element of the capture experience. See CaptureTheme in the Capture reference documentation for a complete list of properties you can override, and their default values. When integrating with SDK, override desired properties of the CaptureTheme using CaptureStyle class. Only provide the overrides for properties you want to override, all other properties will be filled automatically, using capture colors, and your brand palette. In the following example, we are changing the color of the area identified as a receipt by auto-capture, and a color of the Done button on Crop screen, using the colors from main theme:

let configuration = SDKConfiguration.shared
configuration.capture.theme.detectionStrokeColor = configuration.colors.primary
configuration.capture.theme.cropDoneButtonBackgroundColor = configuration.colors.secondary

Branding on standalone Capture

When integrating with standalone capture, the following steps should be performed to customize the theme:

1. Create an instance of DefaultTheme object. You can optionally provide a bundle with assets and colors to be used with the Capture. If no bundle is provided, the default assets and colors will be used.
2. Optionally you can tweak properties of the DefaultTheme object you created.
3. Next, create an instance of CaptureTheme object, providing a created DefaultTheme instance as an argument.
4. Optionally you can tweak the properties of the CaptureTheme.
5. Build CaptureConfiguration object, using CaptureConfigurationBuilder, and include a CaptureTheme instance, created in step 3.
6. Create an instance of CaptureNavigationController and provide an instance of CaptureConfiguration object you created in previous step.
7. Follow the normal presentation process for the standalone Capture.

Example:

// Step 1: Create an instance of DefaultTheme. 
let defaultTheme = DefaultTheme(overrideBundle: nil) // can also provide a bundle

// Step 2 (optional): Customize default theme properties
//...

// Step 3: Create an instance of CaptureTheme
let captureTheme = CaptureTheme(defaults: defaultTheme)

// Step 4 (optional): Customize additional properties here
//...

// Step 5: Build CaptureConfiguration object
let captureConfiguration = CaptureConfigurationBuilder()
                .add(theme: captureTheme)
                .build()

// Step 6: Create CaptureNavigationController with previously created configuration
let capture = CaptureNavigationController(configuration: captureConfiguration)

// Step 7: proceed with normal capture presentation process.
capture.modalPresentationStyle = .fullScreen
capture.captureDelegate = self
present(capture, animated: true, completion: nil)

Font Customization

• To customize the fonts used for Capture, and Error views, specify the desired fonts in the SDKConfiguration.shared.fonts property. You can customize regularFont and boldFont.

• To customize the Web fonts used in Sensibill UI, override the fonts in configuration.sensibillUI.webFonts property. Currently only changing regular font is supported. Other fonts will be updated by Sensibill UI automatically, based on regular font. See the SensibillUIFont for more information on font properties.

Example:

let configuration = SDKConfiguration.shared

// Changing fonts for Capture and error screens
configuration.fonts = SDKConfiguration.FontSet(
    regularFont: .systemFont(ofSize: 14),
    boldFont: .systemFont(ofSize: 16, weight: .bold)
)

// Changing Web font for sensibill UI
configuration.sensibillUI.webFonts.regular = SDKConfiguration.SensibillUIFont(
    family: "Lobster, Times, serif", 
    url: "https://fonts.googleapis.com/css2?family=Lobster&display=swap"
)

Asset Customization

To customize assets in the Sensibill SDK, an external Bundle must be added to the SDK first. The SDK will use this added bundle to check for assets to use in the Sensibill UI. The assets inside of the Bundle must have the same name as assets already used in the SDK. By doing so, the provided assets override what is in the SDK.

1. Follow Using External Bundle instructions to create an external bundle, and to provide its name to the SDK using SDKConfiguration .
2. Inside the Bundle created in Step 1, create an Asset Catalog called SensibillAssets.xcassets

Image Customization

Once you have provided an external bundle that the Sensibill SDK will use to retrieve assets, and created an Asset Catalog, images in the SDK can be overridden.

1. Follow the steps in Asset Customization first
2. Prepare the desired imageset and rename it to match the imageset you want to replaced. For example, you can name an imageset to capture-close to override the close icon in the Receipt capture screen
3. Copy the imageset from step 1 into the Asset Catalog SensibillAssets.xcassets from the Asset Customization steps above.

Example Bundle Structure:

Custom Resources

• Images and colors must be added to an assets folder called SensibillAssets.xcassets. The name of the color or image must be the same as the one you’re overriding.
• Configuration keys must be added to a plist named SensibillConfiguration.plist. The key name in the file must be the same as a the one you’re overriding.
• Specify the localization strings you’d like to override in a Localizable.strings file.

SensibillAssets.xcassets, SensibillConfiguration.plist, and Localizable.strings files can be provided in your project’s main bundle, or in a custom bundle.

Note: Colors and fonts can also be overridden programmatically. Please see the following sections fore more information.

Initialization

In order to provide Capture with custom resources, colors, fonts, or feature flags, a CaptureConfiguration object can be passed to CaptureNavigationController on initialization. The object can contain some or all of the following components:

• A Bundle object containing the resources for the Capture module
• An instance of CaptureFeatures, with custom values for Capture feature flags
• An instance of CaptureTheme, with custom fonts and colors

Example:

Swift:

let captureConfig = CaptureConfiguration(...)
let captureNavigationController = CaptureNavigationController(config: captureConfig)

Objective-C:

SBLCaptureConfiguration *config = [[SBLCaptureConfiguration alloc] initWith...];
SBLCaptureNavigationController *capture = [[SBLCaptureNavigationController alloc] initWithConfig:config];

Bundle

You can initialize the module with a bundle that contains your custom resources. This is commonly your application’s main bundle, or a custom bundle you created.

1. Instantiate a Bundle you want to use.

   • To use the main application bundle:

     Swift:

     let bundle = Bundle.main

     Objective-C:

     NSBundle *bundle = [NSBundle mainBundle];

   • To use a custom bundle, named MyBundleName:

     Swift:

     let bundle = Bundle.main.path(forResource: "MyBundleName", ofType: "bundle")

     Objective-C:

     NSBundle *bundle = [NSBundle bundleWithPath: [[NSBundle mainBundle] pathForResource:@"CustomBundle" ofType:@"bundle"]];

2. Create a CaptureConfiguration instance by providing the bundle instance you created above.

3. Instantiate a CaptureNavigationController with the instance of CaptureConfiguration you created in the previous step:

   let bundle = ... // Created using one of the above methods
   
   let captureConfig = CaptureConfiguration(bundle: bundle)
   let captureNavigationController = CaptureNavigationController(config: captureConfig)

Note: If you are not using your main application bundle and you are including custom colors in the bundle, you will need to compile your assets using the following run script:

PATH_TO_BUNDLE=${PROJECT_DIR}/Custom.bundle/
PATH_TO_ASSETS=${PROJECT_DIR}/Custom.bundle/SensibillAssets.xcassets
xcrun actool ${PATH_TO_ASSETS} --compile ${PATH_TO_BUNDLE} --platform iphoneos --minimum-deployment-target ${IPHONEOS_DEPLOYMENT_TARGET}

Feature Flags

The capture module provides the CaptureFeatures class, which provides access to all of Capture’s feature flags. To override any of the flags create an instance of this class and set the flags available in the instance. Pass the object to the CaptureConfiguration object that you’re using to initialize the module:

let features = CaptureFeatures.getInstance() // Default configuration

// Customize contiguration
features.enableFlash = false
features.enableImageGallery = false
features.defaultToAutoCapture = false
features.enableCrop = false
features.enableAddPage = false
// ...
let captureConfiguration = CaptureConfigurationBuilder()
                .add(features: features)
                .build()
// Initialize and present the module

Using a Theme to Customize Colors

The Capture module provides 2 levels of customization:

• a DefaultTheme allows you to specify the colors globally for a module
• a CaptureTheme allows you to customize individual components, overriding colors provided by the default theme

In order to override colors and fonts:

1. Create a DefaultTheme instance, by providing a bundle instance you created in the Initialization section.
2. Override the DefaultTheme’s properties, to apply a global style to the Capture module
3. Create an instance of a CaptureTheme object by providing the default theme you created above.
4. Override the individual components to further customize your application.

Swift

let bundle = //... See Bundle section above

// Create Defaults
// Colors defined in the default theme will effect the entire module
let defaultTheme = DefaultTheme(overrideBundle: bundle)
defaultTheme.surfaceVariant = .purple

// Create Capture theme with defaults
// Colors defined in the capture theme will customize individual components, overriding colors provided by the default theme
let captureTheme = CaptureTheme(defaults: defaultTheme)
captureTheme.cropDoneButtonBackgroundColor = .green

// Create Config with capture theme
let captureConfiguration = CaptureConfigurationBuilder()
                .add(theme: captureTheme)
                .build()
// Initialize and present the module with the created config.

Objective-C

NSBundle *bundle = //... See Bundle section above

// Create Defaults
// Colors defined in the default theme will effect the entire module
SBLDefaultTheme *defaults = [[SBLDefaultTheme alloc] initWithOverrideBundle:bundle];
defaults.surfaceVariant = [UIColor purpleColor];

// Create Capture theme with defaults
// Colors defined in the capture theme will customize individual components, overriding colors provided by the default theme
SBLCaptureTheme *captureTheme = [[SBLCaptureTheme alloc] initWithDefaults:defaults];
captureTheme.capturePreviewDoneButtonBackgroundColor = [UIColor greenColor];

// Create Config with capture theme
SBLCaptureConfigurationBuilder *captureConfigurationBuilder = [[SBLCaptureConfigurationBuilder alloc] init];
captureConfigurationBuilder = [captureConfigurationBuilder addWithTheme:captureTheme];
SBLCaptureConfiguration *captureConfiguration = [captureConfigurationBuilder build];

// Initialize and present the module with the created config.

Using a Theme to Customize Fonts

The DefaultTheme class allows the integrator to override default fonts using the fonts property.

• Integrator can specify a FontSet to be used for regular, semi-bold, and bold styles throughout the Capture module via the fonts.defaultFontSet property.
• The integrator can also override the more specific font styles. For a full list of overridable font styles, see the FontManager documentation.

Example

let myRegularFont = UIFont(name: "Zapfino", size: 12)
let mySemiboldFont = UIFont(name: "Georgia-Regular", size: 12) // optional, will be mapped to bold if not provided
let myBoldFont = UIFont(name: "Georgia-Bold", size: 12)

let myFontSet = FontSet(regular: myRegularFont, semibold: mySemiboldFont, bold: myBoldFont)

let defaultTheme = DefaultTheme(overrideBundle: bundle)

// Override the default fonts that are mapped to the 10 font styles
defaultTheme.fonts.defaultFontSet = myFontSet

// Override a specific font style and size
defaultTheme.fonts.titleThree = UIFont.systemFont(ofSize: 50)