Global Theme

Overview

SDK provides a Branding object, which allows customization of all aspects of branding:

• Colors (via the BrandingColorsProvider protocol)
• Fonts (via the BrandingFontsProvider protocol)
• Images (via the BrandingImagesProvider protocol)
• Strings and localization (via the BrandingL10NProvider protocol)

The Branding object is always initialized with default implementation for all protocols, which provides a flexibility that allows the integrator to customize only the aspects they care about:

• If custom implementations are not provided for some provider protocols, default implementations will be used.

• If a custom implementation is provided, it does not need to implement all properties. The default protocol implementation will be used for any properties not provided by your custom implementation.

  For example an integrator can override all colors, stay with defaults for all fonts, and only override some images.

• Finally, Branding does not have specific requirements on how colors, fonts, and images are stored in the app. For example some developers may use assets to store colors, while others prefer a programmatic way of defining the colors. Because integrators implement the protocols, they can choose how and where various customization entities are stored.

Once a Branding object has been created and adjusted to satisfy the integrator app’s needs, it (together with the Capture.FeatureFlags) is passed to Capture.RuntimeSettings to construct Capture runtime settings for a specific document type (receipt or invoice). The Capture.RuntimeSettings can then be adjusted further to customize specific elements of Capture. Finally, the Capture.RuntimeSettings is passed to CaptureNavigationController on initialization. After CaptureNavigationController has been initialized, the Capture.RuntimeSettings will remain immutable until the completion of that capture session.

Steps:

1. Create custom implementation for one or more Branding providers.
2. Create the instance of Branding.
3. Customize some or all aspects of the branding by using custom providers.
4. (Optional) Customize Capture.FeatureFlags. You can skip this step to use default feature flags (as in the example below).
5. Pass the created Branding instance to the Capture.RuntimeSettings, created for a specified document type
6. Pass the created Capture.RuntimeSettings instance to the CaptureNavigationController on initialization
7. Follow Launch Capture to present the Capture.

// 1. Create custom implementation for one or more Branding providers
class MyColors: BrandingColorsProvider {
    // ...
}

// 2. Create Branding object
let branding = Branding()

// 3. Customize some or all aspects of the branding
branding.colors = MyColors()
// ...

// 5. Pass a created Branding object to the Capture.RuntimeSettings.

// ..when creating runtime settings for receipt
let receiptRuntimeSettings = Capture.RuntimeSettings.receipt(branding: branding) 

// ..or when creating runtime settings for invoice
let invoiceRuntimeSettings = Capture.RuntimeSettings.receipt(branding: branding) 

// 6. Pass the created Capture.RuntimeSettings to CaptureNavigationController
let capture = CaptureNavigationController(settings: receiptRuntimeSettings)

// 7. Present the Capture
capture.modalPresentationStyle = ...

Usage with Objective-C

While Branding itself is available in Objective-C as SBLBranding, direct access to branding provider protocols is not possible as they use SwiftUI structures, such as Color, or Font. Instead, use the following steps:

1. Create an instance of SBLBrandingBridge
2. Customize colors, fonts, etc in the created bridge instance. Note that the bridge uses UIKit equivalents of SwiftUI structures (e.g. UIColor instead of Color)
3. Convert the bridge to SBLBranding using convertToBranding function of the bridge.
4. Create an instance of SBLCaptureFeatureFlags. Optionally you can customize them.
5. Create an instance of SBLCaptureRuntimeSettings for a selected document type (receipt or invoice)
6. Pass the created SBLCaptureRuntimeSettings instance to SBLCaptureNavigationController
7. Present the Capture

// 1. Create an SBLBrandingBridge object
SBLBrandingBridge * bridge = [[SBLBrandingBridge alloc] init];

// 2. Customize colors, fonts, etc
bridge.colors.primary =  [UIColor colorWithRed:0.6 green:0.8 blue:1.0 alpha:1.0]

// 3. Convert the bridge to SBLBranding
SBLBranding * branding = [bridge convertToBranding];

// 4. Create an instance of SBLCaptureFeatureFlags.
SBLCaptureFeatureFlags * featureFlags = [[SBLCaptureFeatureFlags alloc]init];

// 5. Create an instance of SBLCaptureRuntimeSettings
SBLCaptureRuntimeSettings * runtimeSettings = [SBLCaptureRuntimeSettings receiptWithBranding:branding featureFlags:featureFlags];

// 6. Pass the created SBLCaptureRuntimeSettings to SBLCaptureNavigationController
SBLCaptureNavigationController *capture = [[SBLCaptureNavigationController alloc] initWithSettings:captureRuntimeSettings];

// 7. Present the Capture
// ...

Custom Colors (BrandingColorsProvider)

The BrandingColorsProvider mostly follows the Palette described at the top of the page. Capture uses the following subset of these colors:

Other colors defined in BrandingColorsProvider and Palette are not used by Capture.

Example

In the following example the colors of Primary and Secondary action buttons are customized. All other colors are left with their default values

class MyColors: BrandingColorsProvider {
    
    var primary: Color { Color(red: 1.00, green: 0.80, blue: 0.00) }
    var onPrimary: Color { Color(red: 0.0, green: 0.0, blue: 0.0) }
    
    var secondary: Color { Color(red: 1.0, green: 0.0, blue: 0.0) }
    var onSecondary: Color { Color(red: 1.0, green: 1.0, blue: 0.0) }
}

let branding = Branding()
branding.colors = MyColors()
// ...

Custom Fonts (BrandingFontsProvider)

The BrandingFontsProvider is based on Apple’s Topography section of the Human Interface Guidelines. It uses the same names and defaults, as in the Specifications > Large (Default) section of the guide.

As the SDK uses both UIKit and SwiftUI, both UIFont and Font may be used in various views. For consistency and ease of use, SDK encapsulate the font styles in a universal way, using a custom class Branding.FontDefinition.

For correct scaling, integrators must also provide a UIFont.TextStyle which will be used for both, UIFont and Font (converted to Font.TextStyle)

For example: BrandingFontsProvider.largeTitle style by default is defined as:

• Font.system(.largeTitle)
• UIFont.systemFont(ofSize: 30)
• With scaling based on UIFont.TextStyle.largeTitle / Font.TextStyle.largeTitle

The custom Branding.FontDefinition can be initialized in one of two ways:

• A name, size, and style of the font can be provided. Note that the name must incorporate both the font family name and the specific style information for the font (similar to Font.custom(_:size:relativeTo:) or UIFont(name:size:))
• Instances of Font and UIFont objects, as well as the style.

Integrators can override all or some font styles. The default style will be used for styles that were not overridden.

Fonts Usage in Capture

In Capture, the following font styles are used:

Steps:

1. Follow the Apple’s Adding a Custom Font to Your App guide to register custom fonts in your app. If your custom fonts are already registered with your iOS app, you can skip this step.

2. Create a custom BrandingFontsProvider implementation and override the styles you want.

3. Test capture with custom fonts, to ensure that all elements are displayed correctly. The testing must include changing the font size via the device’s Settings > Accessibility, and ensuring that the fonts are displayed correctly when Larger Accessibility Sizes setting is on and font sizes are increased.

Example

In the following example the fonts for Primary and Secondary action buttons are customized, as well as the font used for buttons on Preview screen. All other fonts are left with their default values

class MyFonts: BrandingFontsProvider {
    
    var subheadline: SensibillCapture.Branding.FontDefinition {
        Branding.FontDefinition(name: "Zapfino", size: 14, style: .subheadline)
    }
    
    var footnote: SensibillCapture.Branding.FontDefinition {
        Branding.FontDefinition(name: "DINCondensed-Bold", size: 12, style: .footnote)
    }
}

let branding = Branding()
branding.fonts = MyFonts()
// ...

Custom Icons and Images (BrandingImagesProvider)

Depending on the usage, custom icons and images are provided as either Image (for SwiftUI components) or UIImage (for UIKit components). All images used by Capture are used as templates, and their color is changed based on BrandingColorProvider (either default or custom):

• For Image the .renderingMode(.template) setting is used. See Apple’s documentation
• For UIImage the withRenderingMode(.alwaysTemplate) setting is used. See Apple’s documentation for more information.

The sizes of the images must match their usage in Capture UI. This can be achieved in multiple ways, for example by providing an Image Set , or providing a single image, which looks fine on larger and smaller devices.

BrandingImagesProvider contains definitions for all images used by the SDK. All images used in Capture have the capture prefix (the properties from captureAutoCaptureIconOff to captureTipsSteadyIcon alphabetically). If using the Standalone Capture, only those images with the capture prefix need overriding.

Example

In the following example, the crop icon is overridden with the “crop” SF Symbol.

class MyImages: BrandingImagesProvider {
    
    var capturePreviewCropIcon: UIImage {
        UIImage(systemName: "crop")
    }
}

let branding = Branding()
branding.images = MyImages()
// ...

Custom Strings (BrandingL10NProvider)

See Localization page.