With the new release SAP BTP SDK for iOS 9.0 and SAP BTP SDK for Android 5.1 earlier this month, customers now have the opportunity to easily apply their corporate branding to all their mobile enterprise applications, built with the SDKs. This allows companies to provide a consistent user experience to their employees and using the native SDKs, new libraries allow to easily apply changes to the themes at runtime.   

In this blog, I want to describe end-to-end, the steps required to apply theming to custom-built applications.   

In case you want to enable theming for your SAP Mobile Start application make sure to also check this blog by Thilo Berndt.

Prerequisites

To enable theming for mobile applications a few prerequisites need to be met:

• Mobile Application utilizes either the SAP BTP SDK for iOS (Version 9.0 or later) or the SAP BTP SDK for Android (Version 5.1 or later) and  
• SAP Mobile Services instance on Cloud Foundry 
• Access to a UI Theme Designer subscription  or an already created theme based on SAP Horizon 

UI Theme Designer

The SAP UI Theme Designer is a browser-based tool to brand and theme key SAP user interfaces. It is used to build your corporate identity themes quickly and easily by modifying and adapting templates based on the latest SAP themes. That way corporate branding resources like logos or a color scheme can be applied to UIs.

To prepare a theme for mobile usage you need to download it from the UI Theme Designer as a zip file and store it on your local disk. For this blog, I will reuse an existing theme for our imaginary company called “Mahlwerk”. They already have a light and dark theme for their Fiori Launchpad and want to adapt their company branding and logo to their mobile applications. See also this GitHub Repository, for more information on the “Mahlwerk” company used in this example.

Mahlwerk – Light Theme

Mahlwerk – Dark Theme

Applying Themes with SAP Mobile Services

Once a theme has been designed and downloaded it needs to be uploaded to SAP Mobile Services to be provided to the mobile applications. This is a two-step process that consists of maintaining the available themes for all applications and then applying one of the maintained themes to the application. The following section goes over the steps required to do both and then shows the required code changes for mobile applications for both iOS and Android.

Changes in SAP Mobile Services Admin Cockpit

In the first step we need to upload and enable themes to the SAP Mobile Services Cockpit. The upload is done at the instance level for all applications. Afterwards, every application can select from the uploaded applications. This way the SAP Mobile Services administrator can manage and update themes and instantly apply changes to all applications that have adopted the theme.

SAP Mobile Services Configuration Level

As a Mobile Services Administrator, you can upload and manage several themes that can be then utilized by the applications. Go to Settings > App Theme Manager and press the plus button to upload a new theme. A theme always consists of a light and a dark theme. But it is also possible to only apply a light theme in case the application doesn’t support the dark theme.

Add a Theme Popup

Upload the downloaded zip files from the UI Theme Designer. After providing the themes, the web themes are transformed and mapped to their mobile counterparts. The resulting themes.json file can be also downloaded and adapted now.

App Theme Manager

Furthermore, the themes can be downloaded, updated, or deleted in this table. However, themes may not be deleted if they are set as default for all applications. Updating a theme allows the adaptation of already applied themes for all applications using the theme. Instead of updating with a zip file provided by the UI Theme Designer, you may also customize the transformed mobile theming file to include properties that are not part of the current theme mapping.

Application Configuration Level

To enable the custom theming for a specific application, go to the Appearance section within the Settings Exchange feature and click the checkbox to enable theming for that application.

Appearance Section

Once enabled a table with themes that are available for selection is presented. We can now see and select the Mahlwerk theme uploaded earlier for this application.

Theming Enabled

If more than one theme is available, you can switch between these, by using the Radio button from the “Active” column. If you want to disable custom theming for the application, uncheck the Enable Custom Theme checkbox.

If theming should be applied already on the onboarding screens, enable anonymous access and create an API Key in the Anonymous Access section within the Security  section. Note down the API Key, you will need it later. If you do not want to allow anonymous access, you can move the theme download to take place after onboarding is done and skip this step.

Generate API Key for anonymous access

Mobile Client changes

To consume the mobile theme in custom applications the download and adoption of the theme has to be built into the applications. With the release of the SAP BTP SDK for iOS 9.0 and SAP BTP SDK for Android 5.1.0 the SDKs support the developer with this task.

In general, once enabled all standard SAP BTP SDK UI components will directly conform the theme applied, as long as their properties have been covered by the theme transformation from web to mobile . For missing theming support on specific control, you need to adapt the “theme.json” file to add missing style attributes  . If an application uses custom UI controls, they need to adapt the standard Fiori style names to allow for the theming to be applied directly.Please see this documentation for iOS and Android, for more information on the naming guidelines for the styling attributes.

The following section describes the code changes required to perform theming for native iOS and Android applications.

Changes for iOS Client (SAP BTP SDK for iOS 9.0)

In the SAP BTP SDK for iOS 9.0 the SAPcpmsThemeManager class was introduced, which is used to download and apply the assigned theme from the SAP Mobile Services Theme Service API endpoint.

For new applications created and generated with the SAP BTP SDK Assistant for iOS the code to apply the theming may be applied and implemented automatically. With the SAP BTP SDK for iOS 9.0 the assistant has been enhanced with a checkbox to apply the customized theme as shown in the picture below.

Apply custom theme with SAP BTP SDK Assistant for iOS

For applications generated with older versions of the SAP BTP SDK Assistant for iOS or created without it, this needs to be adapted manually. The following section highlights the required code changes.

To add themes to the application a new onboarding step called “NUIStyleSheetApplyStep “is added.

Depending on whether anonymous access is enabled for the application this step can be added before the authentication is done or after. If anonymous access is enabled, the step can be added right at the beginning of the onboardingSteps array. It will then be required to paste the API key generated in the anonymous authentication section in the admin cockpit.

 func getAPIKeyAuthenticationConfig() -> APIKeyAuthenticationConfig? {
        return APIKeyAuthenticationConfig(apikeys: [""], isAPIKeyAccessOnly: false, allowAnonymousAccessFlag: true)
    }

   // NUIStyleSheetApplyStep can be used after AuthenticationStep without apiKeyAuthenticationConfig
    public var onboardingSteps: [OnboardingStep] {
        return [
            NUIStyleSheetApplyStep(apiKeyAuthenticationConfig: getAPIKeyAuthenticationConfig()!),
            configuredWelcomeScreenStep(),
            CompositeStep(steps: SAPcpmsDefaultSteps.configuration),
            OAuth2AuthenticationStep(presenter: FioriWKWebViewPresenter(webViewDelegate: self)),
            CompositeStep(steps: SAPcpmsDefaultSteps.settingsDownload),
            CompositeStep(steps: SAPcpmsDefaultSteps.applyDuringOnboard),
            configuredUserConsentStep(),
            configuredDataCollectionConsentStep(),
            StoreManagerStep(),
            ODataOnboardingStep()
        ]
    }

    public var restoringSteps: [OnboardingStep] {
        return [
            NUIStyleSheetApplyStep(apiKeyAuthenticationConfig: getAPIKeyAuthenticationConfig()!),
            StoreManagerStep(),
            configuredWelcomeScreenStep(),
            CompositeStep(steps: SAPcpmsDefaultSteps.configuration),
            OAuth2AuthenticationStep(presenter: FioriWKWebViewPresenter(webViewDelegate: self)),
            CompositeStep(steps: SAPcpmsDefaultSteps.settingsDownload),
            CompositeStep(steps: SAPcpmsDefaultSteps.applyDuringRestore),
            configuredDataCollectionConsentStep(),
            ODataOnboardingStep()
        ]
    }

To add the logo to the Welcome Screen you may also want to adapt the “configureWelcomeScreenStep” to use the provided logos from the screens. As mentioned before the theming of the Welcome Screen will only be possible with anonymous access enabled:

if let welcomeScreen = welcomeStepUI as? FUIWelcomeScreen {
                // Configuring WelcomeScreen to prefill the email domain and set the logo

                welcomeScreen.emailTextField.text = "user@"

                do {
                    let themeDirURL = try SAPcpmsThemeManager.getThemeDirectoryURL()
                    let lightModeLogoPath = themeDirURL.appendingPathComponent("CompanyLogo-light.jpg").path
                    let darkModeLogoPath = themeDirURL.appendingPathComponent("CompanyLogo-dark.jpg").path
                    if FileManager.default.fileExists(atPath: lightModeLogoPath), FileManager.default.fileExists(atPath: darkModeLogoPath) {
                        welcomeScreen.logoImageView.image = UIImage.dynamicImage(lightModeImage: UIImage(contentsOfFile: lightModeLogoPath), darkModeImage: UIImage(contentsOfFile: darkModeLogoPath))
                    }
                } catch {
                    // Handle error
                }
            }

When launching now the application on your device the resulting Welcome Screen will be themed with our custom theme. Switching to dark mode on the phone will directly apply the corresponding dark theme.

Custom themed Welcome Screen – Light Mode

Custom themed Welcome Screen – Dark Mode

For more information on Theming of SwiftUI-based UI components from the cloud-sdk-ios-fiori open-source package, please refer to the SAP Mobile Services guide here.

Changes for Android Client (SAP BTP SDK for Android 5.1.0)

The Application Themes module allows you to download custom theming files for an application at runtime. The application is then responsible for providing these files to the Fiori UI Theming component.

The Foundation framework’s API ThemeDownloadService.downloadTheme() can check for available themes on the server side for the application and download them. The application can automatically apply theming on the controls used from the Fiori library. This feature requires Android API Level 30 and above as it makes use of the ResourceProvider feature of Android OS. The following sample code provided is relevant for view-based applications built using Kotlin.

In order to apply the theme the application needs to use the “Theme.Fiori.Custom” theme to pick up custom colors. This can be changed in the  styles.xml file in the res/values folder like this:

<style name="AppTheme" parent="Theme.Fiori.Custom">

The ThemeDownloadService then needs to be used within the application to download and apply the custom them. If the theme should be applied before authentication is done, the SDKInitializer must be passed the API Key copied earlier from the Anonymous Access section of the SAP Mobile Services Cockpit. The resulting code can look like this:

services.add(ThemeDownloadService())
//Add the apiKey here to enable anonymous access
SDKInitializer.start(this,  * services.toTypedArray(), apiKey = "<apiKey>“)

The specific point in the lifecycle of the application where the download of the theme takes place, is up to the application. The downloadTheme function needs to be passed the SAP Mobile Services Endpoint URL as well as the App-ID. It returns an array of files downloaded. Note that the downloadTheme function uses a delta token so that the function returns “304 Not Modified” if the theme has not been updated in SAP Mobile Services since the last download.

The resulting code then can looks like this:

private fun downloadTheme(){
    val serviceUrl = "<mobileServicesURL>”
    val app_id = "<App-ID>"

    MainScope().launch {
        when(val result = SDKInitializer.getService(ThemeDownloadService::class)?.downloadTheme(serviceUrl, app_id, false)){

            is ServiceResult.SUCCESS ->{
                Log.e("download theme succeed: ", result.data.toString())
                val appContext =  baseContext
                val mapper = CustomColorMapper(appContext)
                val themeFile = result.data?.find { it.contains("theme.json")  }
                if (themeFile != null) {
                        mapper.updateColors(File(themeFile).inputStream())
                }
            }
            is ServiceResult.FAILURE -> {
                val message = result.message
                val code = result.code
                Log.e("download theme fail: ", message + code)
            }
        }
    }
    val mapper = CustomColorMapper(applicationContext)
    val themeFile = File(applicationContext.filesDir,"theme.json")
    if(themeFile.isFile){
      mapper.updateColors(themeFile.inputStream())
    }
} 

Regarding custom logos, there is no SDK logic currently available to apply them to the application.  Most of the screens currently in the SDK assume that the logo is in the application resources (i.e., bundled into the app at build time), so there is no easy way to apply it broadly in this case.  It is up to the application to use them where appropriate.

Limitations

Please note that:

1. Themes need to be created based on SAP Horizon Morning or Evening Theme
2. Not every control property that may be themed in the UI Theme Designer has a mobile control equivalent. That is why not all controls may have the correct theming applied. The mapping may be refined by the developer to add missing properties. The manually changed themes.json file may be uploaded to Mobile Services to update the respective theme.
3. For Android API Level 30 is required

Conclusion

In this blog the new theming feature has been shown. Using this feature allows for fast and easy theming of the core UI element of mobile applications and therefore provides and seamless and coherent experience across all apps of a company. One big advantage is that the theming is provided and applied at runtime of the application, which omits the need to publish and distribute applications again in case of any branding changes.

Based on this new release, SAP provided standard applications and the SAP Mobile Development Kit will include the theming feature in future releases so stay tuned for more updates on this great new functionality!

Please also see the following references:

Blog on how to enable theming with SAP Mobile Start application

SAP Fiori Design Guidelines Article on Theming 

Documentation Mobile Services Administration

SAP BTP SDK for iOS Reference

SAP BTP Android Guide

I would encourage you to read through other blog posts on such topics at: SAP Mobile Services

You can post and answer questions on related topics at: All Questions in SAP Mobile Services | SAP Community

Please provide your feedback and ask questions in the comments section.