Overview

The OneTrust SDK manages several different user interfaces to display to a User. Here's a list below for your reference:

The user interfaces without methods indicate they can only be navigated to based on User navigation and Admin Portal settings.

setupUI

This method can be used to render a UI for Banner or Preference Center. When coupled with a UIType, setupUI()automatically evaluates the shouldShowBanner() logic to determine whether or the specified UI should be shown to users. See below for more info on how shouldShowBanner() gets calculated.

For iOS,setupUI() must be called at least once to pass in your ViewController before calling showBannerUI() or showPreferenceCenterUI(). It's recommended you pass in your root controller, such as a root navigation controller (if applicable) so this method only has to be set once in your code.

🚧

Important

If you'd like to explicitly call the banner or preference center UI without the automation of setupUI(), do not specify a UIType with setupUI(). View the Recommended Approaches Based on Regulatory Use Case section for more information.

📘

Note

Although multiple UITypes are available for setupUI(), it is recommended to only use it for banner. Typically, only a banner should be shown automatically to users for first time consent while all other UITypes should be surfaced explicitly by the user.

iOS

// Swift
OTPublishersHeadlessSDK.shared.setupUI(self)
OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .banner)
OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .preferenceCenter)
OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .consentPurposes)

// ObjC
[OTPublishersHeadlessSDK.shared setupUI:self UIType:.banner];
[OTPublishersHeadlessSDK.shared showBannerUI];

tvOS

// Swift
OTPublishersHeadlessSDK.shared.setupUI(self)
OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .banner)
OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .preferenceCenter)
//.consentPurposes not supported on tvOS at this time

Recommended Approaches Based on Regulatory Use Case

GDPR / CCPA / CPRA Implementations with Banner

For implementations that require a banner, there are two approaches you can take to surface the banner.

Option 1: shouldShowBanner() + showBannerUI()

This option is recommended for apps that have an involved onboarding process which require you to control when UIs are surfaced from OneTrust.

Example Code:

if OTPublishersHeadlessSDK.shared.shouldShowBanner() {
   OTPublishersHeadlessSDK.shared.setupUI(self)
   OTPublishersHeadlessSDK.shared.showBannerUI()
}
else {
   //move on to the next step
}

Option 2: setupUI()

This option is recommended for apps that that can show the OneTrust UI without restriction. setupUI() automatically evaluates shouldShowBanner() to determine if a banner should be shown.

Example Code:

OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .banner)

Preference Center

In order to give users the ability to change their consent settings at any time, most implementations require a button (usually behind the settings page) in your app that surfaces the Preference Center. This can be accomplished with showPreferenceCenterUI(). As this method has no conditional logic attached to it, calling it will surface the preference center every time.

Remember to call setupUI() at least once to pass in your desired ViewController

CCPA/CPRA Implementations without Banner

Although no banner is used, most implementations require a button (usually behind the settings page) in your app that surfaces the Preference Center in order to give users the ability to change their consent settings at any time. This can be accomplished with showPreferenceCenterUI(). As this method has no conditional logic attached to it, calling it will surface the preference center every time.

Example Code:

OTPublishersHeadlessSDK.shared.setupUI(self)
OTPublishersHeadlessSDK.shared.showPreferenceCenterUI()

Remember to call setupUI() at least once to pass in your desired ViewController

showBannerUI

This method will always show the Banner UI, regardless of the shouldShowBanner() value. Before calling this, you will need to pass a UIViewController to setupUI().

// Swift
OTPublishersHeadlessSDK.shared.setupUI(self)
OTPublishersHeadlessSDK.shared.showBannerUI()

showPreferenceCenterUI

This method will always show the Preference Center UI, regardless of theshouldShowBanner() value. Before calling this, you will need to pass a UIViewController to setupUI().

// Swift
OTPublishersHeadlessSDK.shared.setupUI(self)
OTPublishersHeadlessSDK.shared.showPreferenceCenterUI()

shouldShowBanner

This method determines if a Banner should be displayed to the user or not based on SDK determined logic.

// Swift
OTPublishersHeadlessSDK.shared.shouldShowBanner()

// ObjC
[OTPublishersHeadlessSDK.shared shouldShowBanner];

How shouldShowBanner gets computed:

1. Is the geolocation rule configured to show a banner? This is controlled by the showAlertNotice property in the JSON being true.

   • If showAlertNotice = false, the method returns false and a banner should not be shown for this region.
   • If showAlertNotice = true, move to the next check.

2. Was the most recent SDK Publish configured to re-consent users? This is controlled by the presence of 2 values. 1) A LastReconsentDate property in JSON with non-null value. 2) A OneTrustLastReconsentDate value saved on disk

   • If the LastReconsentDate JSON is newer than the OneTrustLastReconsentDate on disk, the method returns true and a banner should be shown.
   • If no, move to the next check

3. Is the geolocation rule configured for automatic re-consent AND did the user's automatic re-consent timer expire? This is controlled by measuring the difference between OneTrustLastConsentDate saved on disk and the Current Date and seeing if it is greater than or equal to OneTrustReconsentFrequencyDays in the JSON saved on disk. The SDK considers the date itself and not the time consent was given. For example, if the re-consent period is set to 1 day in my geolocation rule and the user provides consent at 11:59pm GMT, the banner will reappear at 12:00am GMT (1 minute later, but the next day).

   • If yes, the method returns true and a banner should be shown.
   • If no, move to the next check

4. Is Cross Device Consent enabled and were 100% of Purposes synced? This is controlled by the profile.sync.allPurposesUpdatedAfterSync property in JSON being true.

   • If yes, the method returns false and a banner should not be shown. This is because each of the Categories/Purposes managed by the SDK were 100% synced from the user's profile on the OneTrust server.
   • If no, move to the next check.

5. Is Cross Device Consent enabled and is the user being exposed to new Categories/Purposes since the last time their consent was saved? This would only occur if Cross Device Consent is enabled and there was a new publish to the SDK which exposes new Categories/Purposes that have at least 1 SDK assigned to it.

   • If yes, the method returns true and a banner should be shown.
   • If no, move to the next check.

6. Has the user previously given consent and is that consent stored at disk?

   • If yes, the method returns false and a banner should not be shown.
   • If no, the method returns true and a banner should be shown because this is the first time they are being asked to give consent on the app.

7. Has a new category been added post giving consent?

   • If yes, the method returns true and a banner should be shown again because user needs to give consent to the new category.
   • If no, the method returns false and a banner should not be shown.

Note: If you are using OneTrust's pre-built UI, it is likely you won't need to call this method, but good to know how it works as it is decides the outcome of setupUI method.

Note: If you are building your own UI (BYOUI), then the method below will likely be part of your implementation.

isBannerShown

This method is used, in some implementations, where the application needs to hide a "Privacy Settings" application tab or prevent a user from accessing the Preference Center before they have seen the Banner notice at least once.

The logic for computing this value is:

• Returns -1 when the SDK has not been intialized yet
• Returns 0 when a Banner / Preference Center has never been shown
• Returns 1 when a Banner / Preference Center has been shown
• Returns 2 when the Banner / Preference Center has never been shown, but the User Profile was synced automatically (only applicable for implementations using Cross Device profile syncing).

For most implementations, the application logic can be:

• If the value returned is greater than 0, then show "Privacy Settings" or some link to show a Preference Center.

// Swift
OTPublishersHeadlessSDK.shared.isBannerShown()

// ObjC
[OTPublishersHeadlessSDK.shared isBannerShown];

dismissUI

This method can be used to dismiss the OneTrust SDK's UI at any time. Although dismissing the OneTrust UI is often handled by a user saving their choices, there are some situations where the application may want manual control over this:

When this method is called:

• The Banner/PC UI will be dismissed from view
• Consent will NOT be saved or logged to OneTrust
• Any Category/Purpose value updates will be Reset
• The value of shouldShowBanner will remain Same
• A warning message will be logged if this method is called and OneTrust UI is not currently being shown

// Swift
OTPublishersHeadlessSDK.shared.dismissUI()

// ObjC
[OTPublishersHeadlessSDK.shared dismissUI];

showConsentUI

This method surfaces prompts for gathering different types of consent such as an age gate.

In order to render the Age Gate UI, you will need to pass .ageGate as the param.

//swift 
OTPublishersHeadlessSDK.shared.showConsentUI(.ageGate)

showConsentPurposesUI

This method displays the Universal Consent Preference Center. Universal Consent is a separate module and serves a different use case than Mobile App Consent. For more information, reference the following document: https://my.onetrust.com/s/article/UUID-23e87737-2b1d-f741-5ab3-400d06c4bdd4

Swift:

// Swift
OTPublishersHeadlessSDK.shared.showConsentPurposesUI()

shouldEnableDarkMode

This method will enable Dark Mode and can override existing Dark Mode configurations on a device.

To enable dark mode, pass in true to the param.

// Swift
OTPublishersHeadlessSDK.shared.shouldEnableDarkMode(true)