Colors

Theming Document

Please refer to this theming document for more detailed information on how to best brand colors within the Guided Scan SDK.

How to Customize Colors

The Guided Scan SDK colors can be customized to a great extent. Please check out the above theming document for a high level overview and reference images.

We can set color customizations using Guided Scan SDK's public CustomColorConfig. We can choose to change any number of or all the colors. Once those are set, we'll pass the CustomColorConfig into the GuidedScanThemeConfig when we initialize it.

class ViewController: UIViewControllerSupport {
  ...
  
  func newGuidedScanTapped() {
    ...

    // NOTE: If we leave the parameters empty when initializing CustomColorConfig
    // our experience will use the default colors.
    let brandedColorConfig = CustomColorConfig()
    let brandedGuidedScanThemeConfig = GuidedScanThemeConfig(customColorConfig: brandedColorConfig)

    StreemGuidedScan.shared.guidedScanThemeConfig = brandedGuidedScanThemeConfig
    StreemGuidedScan.shared.startGuidedScan(presenter: self)
  }
  
  ...
}

Now that we know how to initialize the CustomColorConfig. There is Swift documentation for CustomColorConfig init and each parameter. Also, please refer to the above mentioned theming document for more details and images.

To fully brand the Guided Scan SDK, we only need to focus on these colors: primaryAction, positiveAction, negativeAction, buttonBackground, and subduedBrandBackground. There are other colors that can be customized, but we'll keep them nil in the below example. If we do plan to leave a parameter nil, we can just remove the parameter all together.

class ViewController: UIViewControllerSupport {
  ...
  
  func newGuidedScanTapped() {
    ...

    let brandedColorConfig = CustomColorConfig(
      primaryText: nil
      secondaryText: nil,
      tertiaryText: nil,
      primaryAction: UIColor(red: 0, green: 0.478, blue: 1, alpha: 1),
      positiveAction: UIColor(red: 0.204, green: 0.78, blue: 0.349, alpha: 1),
      negativeAction: UIColor(red: 1, green: 0.231, blue: 0.188, alpha: 1),
      primaryBackground: nil,
      secondaryBackground: nil,
      tertiaryBackground: nil,
      subduedBrandBackground: UIColor(red: 0.988, green: 0.89, blue: 0.902, alpha: 1),
      subduedNegativeBackground: nil,
      buttonBackground: UIColor(red: 0, green: 0.478, blue: 1, alpha: 1,
      navigationBar: nil)
    let brandedGuidedScanThemeConfig = GuidedScanThemeConfig(customColorConfig: brandedColorConfig)

    StreemGuidedScan.shared.guidedScanThemeConfig = brandedGuidedScanThemeConfig
    StreemGuidedScan.shared.startGuidedScan(presenter: self)
  }
  
  ...
}

In the previous example, we left the parameter navigationBar equal to nil. We'll use CustomColorConfig.NavigationBarColors to set the colors and pass them into the CustomColorConfig. Again we can just focus on certain colors to fully brand the navigation bar: primaryAction, positiveAction, negativeAction, buttonBackground. It is encouraged to share the colors between CustomColorConfig and CustomColorConfig.NavigationBarColors.

If we want to change the color of the navigation bar background, there is one extra thing to consider. If the background is a dark color, the iOS status bar icons will not be as visible or accessible. To make them white and more visible and accessible, we pass true to the isDarkBackground parameter. Also, it is best practice to make titleText, primaryAction, positiveAction, and negativeAction a lighter color, for example, .white when using a dark background.

In the below example, we'll use a dark background.

class ViewController: UIViewControllerSupport {
  ...
  
  func newGuidedScanTapped() {
    ...
		
    
		let brandedNavBarConfig = CustomColorConfig.NavigationBarColors(
      background: UIColor(red: 0.094, green: 0.094, blue: 0.094, alpha: 0.7),
      titleText: .white,
      primaryAction: .white,
      positiveAction: .white,
      negativeAction: .white,
      buttonBackground: UIColor(red: 0, green: 0.478, blue: 1, alpha: 1),
      buttonForeground: .white,
    	isDarkBackground: true)
      
    let brandedColorConfig = CustomColorConfig(
      ...
      navigationBar: brandedNavBarConfig)
    let brandedGuidedScanThemeConfig = GuidedScanThemeConfig(customColorConfig: brandedColorConfig)

    StreemGuidedScan.shared.guidedScanThemeConfig = brandedGuidedScanThemeConfig
    StreemGuidedScan.shared.startGuidedScan(presenter: self)
  }
  
  ...
}

We can use dark mode compatible colors, by passing a dark mode compatible color into the CustomColorConfig init, for example, .systemBlue. If a dark mode compatible color isn't available, we can create one with the Guided Scan SDK's public UIColor extension UIColor.createDarkModeCompatibleColor(with lightMode: UIColor, and darkMode: UIColor).

The darkMode parameter is optional. If only a lightMode color is passed into the parameters, it will be used for light and dark modes.

// Light and Dark mode using the same color
UIColor.createDarkModeCompatibleColor(with: .white)

// Light and Dark mode using different colors
UIColor.createDarkModeCompatibleColor(
	with: UIColor(red: 0/255, green: 122/255, blue: 255/255, alpha: 1)
	and: UIColor(red: 10/255, green: 132/255, blue: 255/255, alpha: 1))