Overview

📘

Note

This section is optional as most UI configurations are primarily made through the OneTrust tenant. If your app has a use case where it needs make additional configurations (e.g. font family) otherwise not available in the tenant OR if it needs to control the UI configurations locally, you can use these custom configurations.

❗️

Note

Custom UI Parameters are only supported on Native iOS (Mobile platform). This is not supported for tvOS.

As of version 6.10.0, the Native SDK supports Custom UI Parameters, which are maintained in-application through an info.plist resource.

You can find the latest info.plist in the latest demo application downloaded from OneTrust tenant. Here's how to Download latest demo app from OneTrust.

This document covers:

• Prerequisites for Customizing the UI
• Approaches to modify the plist
• Customizing the Navigation Bar
• Customizing the Banner View
• Customizing the Preference Center View
• Customizing the Purpose Details View
• Customizing the Vendor List View [for IAB TCF Customers]
• Customizing the Vendor Details View [for IAB TCF Customers]
• Customizing the SDK List View
• Customize CNIL Button

Prerequisites for customizing the UI in Native SDK views:

In order for the application to customize the UI (look and feel of SDK views), the following would be required:

• OneTrust SDK on 6.10 or above.
• The consumer application will have to conform to the uiConfigurator delegate in OTPublishersHeadlessSDK.
• Upon conforming to uiConfigurator:
  • The application would have to return true for the method shouldUseCustomUIConfig().
  • The application can also conform to the method customUIConfigFilePath() and provide a custom location of the OTSDK-UIConfig.plist.

    Note: Make sure that the plist is copied from the OT SDK framework to keep the format of the plist the same as the framework.

• The application can override the values (empty by default) adjacent to the keys though.
• Recommended to NOT add any rows or change the keys in the plist.
• If the application is using this approach to customize the UI, the customized items in plist will be given priority (i.e., the customized items will override the server configured values for those items).

Approaches to Modifying the OTSDK-UIConfig.plist file:

Approach 1 (Recommended)

1. Set the return value as true for the shouldUseCustomUICOnfig() method in UIConfigurator protocol (refer to Sample App provided by OneTrust for example).
2. Locate the OTSDK-UIConfig.plist file from the OTPublishersHeadlessSDK.framework or OTPublishersHeadlessSDK.xcframework.

   Note:
   The OTSDK-UIConfig.plist will be present in the first level of OTPublishersHeadlessSDK.framework. The OTSDK-UIConfig.plist will be present in the each architecture folder under OTPublishersHeadlessSDK.xcframework. You can pick it from any of the folders.

3. Copy this OTSDK-UIConfig.plist to the application project (refer to Sample App provided by OneTrust for example).

   Note: Make sure that when we drag and drop the plist from the framework to the application project, we select Copy items if needed. This will copy the plist to the application folder hierarchy.

4. Now conform to the customUIConfigFilePath() method which is part of the UIConfigurator protocol (OTPublishersHeadlessSDK.shared.uiConfigurator).

   Notes: While conforming to this method, provide the path to the plist in the application bundle (refer to Sample App provided by OneTrust for example).

5. We can now edit this copied plist and the UI will automatically update.

func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        // Conform to this in order to customize the UI.
        OTPublishersHeadlessSDK.shared.uiConfigurator = self
}

extension AppDelegate: UIConfigurator {
    func shouldUseCustomUIConfig() -> Bool {
        return true
    }
    
    func customUIConfigFilePath() -> String? {
        let customPath = Bundle.main.path(forResource: "OTSDK-UIConfig-iOS", ofType: "plist")
        return customPath
    }
}

Approach 2

1. Set the return value as true for the shouldUseCustomUICOnfig() method in UIConfigurator protocol (refer to Sample App provided by OneTrust, for example).
2. Locate the OTSDK-UIConfig.plist file from the OTPublishersHeadlessSDK.framework or OTPublishersHeadlessSDK.xcframework.

   Note: The OTSDK-UIConfig.plist will be present in the first level of OTPublishersHeadlessSDK.framework. The OTSDK-UIConfig.plist will be present in the each architecture folder under OTPublishersHeadlessSDK.xcframework.

3. Users can now edit the appropriate plist and the UI will automatically update.

Important Notes

• Approach 1 will provide a centralized place for the plist even if the application wants to switch between .framework and .xcframework. This will avoid updating the plist file in multiple places (.framework as well as .xcframework).
• In the future, whenever there are changes to the plist, it will be easier to figure out and resolve the changeset if Approach 1 chosen.
• By default all the values in the OTSDK-UIConfig.plist in the OT SDK framework will be empty.
• In order to customize an element, we will need to enter a valid value for the associated key we want to customize.
• When a custom fontName is provided, at least one of the fontSize or fontTextStyle should also be provided in order for it to reflect.
• In order for dynamic font size to be supported, the application will have to provide a valid value for fontTextStyle if customizing the fonts.
• Button color for Mobile templates can updated in the SDK using UX Params. For more information, see JSON Structure.

The following are the different fontTextStyle options supported:

• largeTitle
• title1
• title2
• title3
• headline
• subheadline
• body
• callout
• footnote
• caption1
• caption2

UI Customization for Page Header (Navigation Bar) in all SDK Views:

The consumer application has to edit the OTSDK-UIConfig.plist file located in the SDK bundle in order to customize the UI. All the page header related customization would be present under the pageHeader dictionary. This is a common theme that will be applied to all the OT SDK views' navigation bars.

The following are the customizations available:

• backgroundColor (String) - A hex string representing the background color of the page header/navigation bar.
  • (ex: #FFFFFF)
• tintColor (String) - A hex string representing the tint color of the page header/navigation bar.
  • (ex: #FFFFFF)
• fontName (String) - The name of the custom font.
  • (ex: HelveticaNeue).
• fontSize (Int) - The size of the font.
  • (ex: 17)
• fontTextStyle (String) - The preferred text style of the font.
  • (ex: Headline, callout, sub headline etc.)
• textAlignment (String) - The alignment of the text.
  • (Options - Center, Left, Right)
• textColor (String) - A hex string representing the color of the text.
  • (ex: #000000)

Banner View

The consumer application has to edit the OTSDK-UIConfig.plist file in order to customize the UI. All the banner view related customization would be present under the bannerTheme dictionary.

The following color options are available for the Banner View:

• backgroundColor (String) - A hex string representing the background color of the banner view
  • (ex: #FFFFFF)

The following are the customizations available for the Banner View:

Preference Center View

The consumer application has to edit the OTSDK-UIConfig.plist file in order to customize the UI. All the preference center related customization would be present under the preferenceCenterTheme dictionary in the plist.

The following color options are available for the Preference Center View:

• backgroundColor (String) - A hex string representing the background color of the Preference Center.
  • (ex: #FFFFFF)
• lineBreakColor (String) - A hex string representing the separator lines color
  • (ex: #FFFFFF)
• toggleColor (String) - A hex string representing the switch color when toggled ON
  • (ex: #FFFFFF)

The following UI elements are the customizations available for the Preference Center View:

Purposes Details View

The consumer application has to edit the OTSDK-UIConfig.plist file in order to customize the UI. All the purpose details view related customization would be present under the purposeDetailsTheme dictionary in the plist.

The following color options are customizations available for the Purposes Details View:

• backgroundColor (String) - A hex string representing the background color of the purposes details view
  • (ex: #FFFFFF)
• lineBreakColor (String) - A hex string representing the separator lines color
  • (ex: #FFFFFF)
• toggleColor (String) - A hex string representing the switch color when toggled On
  • (ex: #FFFFFF)

The following UI Elements are the customizations available for the Purposes Details View:

Vendor List View

The consumer application has to edit the OTSDK-UIConfig.plist file in order to customize the UI. All the vendor list view related customization would be present under the vendorListTheme dictionary in the plist.

The following color options are customizations available for the Vendor List View:

• backgroundColor (String) - A hex string representing the background color of the vendor list
  • (ex: #FFFFFF)
• lineBreakColor (String) - A hex string representing the separator lines color
  • (ex: #FFFFFF)
• toggleColor (String) - A hex string representing the switch color when toggled ON
  • (ex: #FFFFFF)
• filterOnColor (String) - A hex string representing the filter icon color when filter is applied
  • (ex: #FFFFFF)
• filterOffColor (String) - A hex string representing the switch color when no filter is applied
  • (ex: #FFFFFF)
• filterSelectionColor (String) - A hex string representing the tint color of the check mark in the vendor filter list
  • (ex: #FFFFFF)

The following UI Elements are the customizations available for the Vendor List View:

Vendor Details View

The consumer application has to edit the OTSDK-UIConfig.plist file in order to customize the UI. All the vendor details view related customization would be present under the vendorDetailsTheme dictionary in the plist.

The following color options are customizations available for the Vendor Details View:

• backgroundColor (String) - A hex string representing the background color of the vendor details view
  • (ex: #FFFFFF)
• toggleColor (String) - A hex string representing the switch color when toggled ON
  • (ex: #FFFFFF)

The following UI Elements are the customizations available for the Vendor Details View:

SDK List View

The consumer application has to edit the OTSDK-UIConfig.plist file in order to customize the UI. All the SDK list view related customization would be present under the sdkListTheme dictionary in the plist.

The following color options are customizations available for the SDK List View:

• backgroundColor (String) - A hex string representing the background color of the SDK list
  • (ex: #FFFFFF)
• lineBreakColor (String) - A hex string representing the separator lines color
  • (ex: #FFFFFF)
• filterOnColor (String) - A hex string representing the filter icon color when filter is applied
  • (ex: #FFFFFF)
• filterOffColor (String) - A hex string representing the switch color when no filter is applied
  • (ex: #FFFFFF)

The following UI Elements are the customizations available for the SDK List View:

Display CNIL as Button

With OneTrust 6.22.0, mobile app customers can now customize the Continue Without Accepting link as a button to promote a consistent experience when presented with a close option. For more information on the app-side configuration of mobile templates to display as text or link, see CNIL Mobile App Requirements on the myOneTrust Knowledge Base.

UIConfigurator - Return True

1. Open the AppDelegate.swift file.
2. Locate the shouldUseCustomUIConfig() -> Bool function.
3. Update the value as return true. It will be set to return false by default.

extension AppDelegate: UIConfigurator {

    func shouldUseCustomUIConfig() -> Bool {
        return true
    }

Customize closeButton

1. Open the OTSDK-UIConfig-iOS.plist file.
2. Locate Root > bannerTheme > buttons > closeButton.
3. The parameters for closeButton will be blank by default. Provide your customizations for the Continue Without Accepting button.

Using Custom Fonts

The Native SDK can support a Font Name override to support custom fonts.

1. Add custom fonts to Xcode: Apple documentation
2. Reference the fonts in the SDK plist. Ensure you specify a font size in the plist for the custom font to take effect.