Managing Application Themes

(Native/MDK only) As an administrator, you can manage application themes from SAP mobile service cockpit and indicate a default theme for the selected mobile app.

Themes change the appearance of the mobile client on the user's device. The mobile services server uses the settings to apply themes to the mobile app client. Each theme definition includes a light and dark version of the theme. Mobile client users can set the active theme from the device. Themes are managed at the space level.

Themes must be defined using the SAP Theme Designer and the SAP Horizon Dark / Light theme as the base. Only changes to the background color and text color can be made. The theme must be exported to the ZIP format. Once uploaded, you can set the active theme. If you decide to deselect themes, the SDK application does not get the theme from the mobile services server.

Note that for a single application cockpit (Software as a Service, SaaS), only one customized theme is available for the user to use. The theme is automatically enabled for the application once the customized theme is enabled. You can update and delete themes. If the theme is deleted, the SDK application uses the initial default theme instead of getting the theme from the mobile services server. The appearance information is cleared and you can import another theme.

Managing App Themes

You can manage all themes from a central place using SAP mobile service cockpit. Themes must be created using SAP Theme Designer and the SAP Horizon Dark/Light theme as the base. Only changes to the background color and text color can be made. The theme must be exported to ZIP format using the export option Optional Settings (for Experts) > Source files + CSS, and deselecting the UI technologies

The theme.zip file contains light and dark versions of the theme, including company logos in JPG format, a JSON source file for Android apps, and an NSS source file for iOS apps.

The SAP Mobile Services server validates the theme.zip file upon upload to the storage service, to ensure security and artifact validity. These validation rules are checked:

• The uploaded theme file must be in a ZIP format.

• The uploaded theme file maximum size is 10M.

• The uploaded theme designer ZIP must be of the sap_horizon type.

• The virus scan must pass for the uploaded theme ZIP file.

• The user can upload up to two theme ZIP files in one request.

• The following ZIP file content checks must pass:

  • The Base/baseLib/<theme_name>/.theming file must be included and the file content must be a valid JSON format.

    The JSON content must contain the following properties and corresponding values: * sId * sLabel * oExtends * aBadgeParameters

  • The Base/baseLib/<theme_name>/.less_variables.less file must be included.

• If any validation fails, an event log is created for it. Check the Event Log using the Mobile Settings Exchange filter for the storage service, as described in Viewing Event Logs.

After the initial upload to App Theme Manager, to update themes you can either:

• Use the SAP Theme Designer to modify the theme, export it to a new ZIP file, and upload it in the SAP mobile service cockpit Theme Manager.

• Download the ZIP file that contains the NSS and JSON files from Theme Manager (provider) and Appearance (SaaS application). Modify the final processed theme ZIP directly, and upload it when finished.

To manage themes:

1. In SAP mobile service cockpit, select Settings > App Theme Manager.

2. View the list of themes that have been uploaded.

   Column	Description
   Name	The unique name associated with a theme listed in the cockpit theme list.
   ID	The identifier that was assigned in the SAP Theme Designer. Note that an ID may be reused, for example, if a Theme Designer ZIP file contains both light and dark themes.
   Title	The descriptive theme title, such as Custom High Contrast Morning, or Custom Evening.
   Color	The light and dark color palettes defined for the theme.
   Creation Date (UTC+0000)	The date and time the theme was created, in the format YYYY-MM-DD HH:MM:SS:ss.
   User Selection	Whether the theme appears in the application Appearance theme list. If the theme appears in the theme list, the user can select it to make the theme active for the application.
   As Default	Whether the theme should be used as the default theme. A default theme becomes the active theme for all the applications in the space.
   Actions	The actions the administrator can take, such as download the theme ZIP file locally; update the theme with the latest version from SAP Theme Designer or modified locally; or delete the theme definition.

3. Select to add a new theme. In Add a Theme, provide the theme definition, and select Save.

   Theme Definition

   Field	Description
   Theme Name	Provide a descriptive name to identify the app theme. Both light and dark versions of the theme are identified with this name. You cannot change the theme name once you save.
   Light Theme	Browse to select the lighter version of an app theme.
   Dark Theme	Browse to select the darker version of an app theme. To learn more about implementing Android dark theme, see Dark Theme.

4. Select to download the theme.zip file to your local device. Optionally, you can update the files to change the themes.

5. Select Update to update the theme using the latest version. You can:

   • Upload Theme Designer zip - select this option to upload the latest light or dark theme version.

   • Upload Processed Theme zip - select this option to upload a modified ZIP file (if you modified the files locally to change the theme definition).

6. Select to delete the theme.

Managing Themes at the App Level

(Native/MDK only) You can manage the themes available for the selected application.

1. In SAP mobile service cockpit, select Mobile Applications > Native/MDK.

2. Select an application, then select Mobile Settings Exchange under Assigned Features (or add it first).

3. Select Client Configuration.

4. Under Appearance, make sure Enable Custom Theme is selected.

5. View the list of themes that have been uploaded. The theme list reflects settings made in the App Theme Manager. See Managing App Themes.

6. In the Active column, select the theme to be active for the selected application, and then Save. Both the light and dark versions of the theme will be available for the mobile client user to select.

Application Theme Color Mapping

Describes the color mapping that is used by Application Theme Manager, between web colors and runtime applied colors for iOS and Android.

iOS Color Mapping

Web Color	Light Theme	Dark Theme
sapBrandColor	@tintColor @tintColor_elevatedLightBackground @tintColor2 @tintColor2_elevatedLightBackground @tintColorTapState @tintColorTapState_elevatedLightBackground	@tintColor_darkBackground @tintColor_elevatedDarkBackground @tintColor2_darkBackground @tintColor2_elevatedDarkBackground @tintColorTapState_darkBackground @tintColorTapState_elevatedDarkBackground
sapShellColor	@header @header_elevatedLightBackground @headerBlended @headerBlended_elevatedLightBackground @barTransparent @barTransparent_elevatedLightBackground	@header_darkBackground @header_elevatedDarkBackground @headerBlended_darkBackground @headerBlended_elevatedDarkBackground @barTransparent_darkBackground @barTransparent_elevatedDarkBackground
sapBaseColor	@primaryBackground @primaryBackground_elevatedLightBackground @tertiaryBackground @tertiaryBackground_elevatedLightBackground @secondaryGroupedBackground @secondaryGroupedBackground_elevatedLightBackground	@primaryBackground_darkBackground @primaryBackground_elevatedDarkBackground @tertiaryBackground_darkBackground @tertiaryBackground_elevatedDarkBackground @secondaryGroupedBackground_darkBackground @secondaryGroupedBackground_elevatedDarkBackground
sapBackgroundColor	@secondaryBackground @secondaryBackground_elevatedLightBackground @primaryGroupedBackground @primaryGroupedBackground_elevatedLightBackground @tertiaryGroupedBackground @tertiaryGroupedBackground_elevatedLightBackground	@secondaryBackground_darkBackground @secondaryBackground_elevatedDarkBackground @primaryGroupedBackground_darkBackground @primaryGroupedBackground_elevatedDarkBackground @tertiaryGroupedBackground_darkBackground @tertiaryGroupedBackground_elevatedDarkBackground
sapShell_TextColor	@customColor1 @customColor1_elevatedLightBackground @navBarTitleLabel @navBarTitleLabel_elevatedLightBackground	@customColor1_darkBackground @customColor1_elevatedDarkBackground @navBarTitleLabel_darkBackground @navBarTitleLabel_elevatedDarkBackground
sapTextColor	@primaryLabel @primaryLabel_elevatedLightBackground	@primaryLabel_darkBackground @primaryLabel_elevatedDarkBackground
sapContent_LabelColor	@secondaryLabel @secondaryLabel_elevatedLightBackground @tertiaryLabel @tertiaryLabel_elevatedLightBackground @quarternaryLabel @quarternaryLabel_elevatedLightBackground	@secondaryLabel_darkBackground @secondaryLabel_elevatedDarkBackground @tertiaryLabel_darkBackground @tertiaryLabel_elevatedDarkBackground @quarternaryLabel_darkBackground @quarternaryLabel_elevatedDarkBackground
sapNegativeColor	@negativeLabel @negativeLabel_elevatedLightBackground	@negativeLabel_darkBackground @negativeLabel_elevatedDarkBackground
sapCriticalColor	@criticalLabel @criticalLabel_elevatedLightBackground	@criticalLabel_darkBackground @criticalLabel_elevatedDarkBackground
sapPositiveColor	@positiveLabel @positiveLabel_elevatedLightBackground	@positiveLabel_darkBackground @positiveLabel_elevatedDarkBackground

Android Color Mapping

Web Color	Light Theme	Dark Theme
sapBrandColor	s2 t4 t6 t7 b3 b4 r3	s2_dark t4_dark t6_dark t7_dark b3_dark b4_dark r3_dark
sapShellColor	s6	s6_dark
sapBaseColor	s1	s1_dark
sapBackgroundColor	s0 s4	s0_dark s4_dark
sapShell_TextColor	t8	t8_dark
sapTextColor	t1	t1_dark
sapContent_LabelColor	t2 t3	t2_dark t3_dark
sapNegativeColor	semantic_negative	semantic_negative_dark
sapCriticalColor	semantic_critical	semantic_critical_dark
sapPositiveColor	semantic_positive	semantic_positive_dark

---

Last update: July 18, 2023