Overview

The OneTrust SDK manages several user interfaces that can be displayed to a user.

setupUI

The SDK provides the capability to determine if the OneTrust Banner or Preference Center UI needs to be shown once it retrieves, parses and saves the data from the server as part of the startSDK() call.

setupUI(_:, UIType:)

When combined with a UIType, setupUI() automatically evaluates the shouldShowBanner logic to determine whether the specified UI should be shown to users.

Automatically Show the Banner UI:

This is commonly used if the app needs to show a banner UI to collect first time consent.

//iOS and tvOS
OTPublishersHeadlessSDK.shared.setupUI(appViewController, UIType: .banner)

Automatically Show the Preference Center UI:

This is a less common occurrence as the Preference Center UI is usually explicitly surfaced by the user.

//iOS and tvOS
OTPublishersHeadlessSDK.shared.setupUI(appViewController, UIType: .preferenceCenter)

Automatically Show the Universal Consent Preferences UI

//iOS
OTPublishersHeadlessSDK.shared.setupUI(self, UIType: .consentPurposes)

This method is not supported for tvOS

Don't Show Any UI Automatically

If you don't want any of the UIs to be surfaced automatically (if applicable), only pass in the viewController. Even if the app does not want to automatically surface UIs, this method still needs to be called ahead of showBannerUI or showPreferenceCenterUI.

//iOS and tvOS
OTPublishersHeadlessSDK.shared.setupUI(appViewController)

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

👍

Recommended Approaches

For more information, see Recommended Approaches Based on Regulatory Use Case .

Recommended Approaches Based on Regulatory Use Case

GDPR / CCPA / CPRA type 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.

//iOS and tvOS
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. When coupled with a UIType, setupUI() automatically evaluates the shouldShowBanner logic and surfaces the set UI if it evaluates to true.

//iOS and tvOS
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 a settings page) in your app that surfaces the Preference Center. This can be accomplished with the showPreferenceCenterUI() method. As this method has no conditional logic attached to it, calling it will surface the preference center UI every time.

🚧

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

CCPA/CPRA type Implementations without Banner

Although no banner UI is used, most implementations require a button (usually behind a 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 UI every time.

//iOS and tvOS
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 surface the Banner UI, regardless of the shouldShowBanner() logic. Before calling this, you will need to pass a ViewController to setupUI().

//iOS and tvOS
OTPublishersHeadlessSDK.shared.setupUI(self)
OTPublishersHeadlessSDK.shared.showBannerUI()

showPreferenceCenterUI

This method will always surface the Preference Center UI, regardless of the shouldShowBanner() logic. Before calling this, you will need to pass a ViewController to setupUI().

//iOS and tvOS
OTPublishersHeadlessSDK.shared.setupUI(self)
OTPublishersHeadlessSDK.shared.showPreferenceCenterUI()

shouldShowBanner

This method determines if the Banner UI should be displayed to the user.

//iOS and tvOS
OTPublishersHeadlessSDK.shared.shouldShowBanner()

How shouldShowBanner is 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 after 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.

isBannerShown

This method determines if the Banner or Preference Center UI has already been shown to the user.

This is commonly used in cases where the application needs to hide or prevent a user from accessing the Preference Center UI button before they have seen the Banner UI at least once.

Returns:

• -1 if the SDK has not been initialized at least once
• 0 when the Banner or Preference Center UI has never been shown
• 1 when a Banner or Preference Center UI has been shown
• 2 when the Banner or Preference Center UI has never been shown, but the cross device profile was synced automatically (only applicable for implementations using Cross Device Consent)

dismissUI

This method can be used to dismiss the SDK's UI at any time. Although dismissing the OneTrust UI is often handled by the SDK when a user saves 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 consent value updates not yet committed to disk will be reset
• The value of shouldShowBanner will remain the same
• A warning message will be logged if this method is called and no OneTrust UI is being shown

//iOS and tvOS
OTPublishersHeadlessSDK.shared.dismissUI()

showConsentUI

This method surfaces an Age Gate Prompt or ATT Pre and Settings Prompts.

//iOS and tvOS
OTPublishersHeadlessSDK.shared.showConsentUI(.ageGate)
OTPublishersHeadlessSDK.shared.showConsentUI(.idfa)

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, see Universal Consent Purposes for Mobile App Consent.

//iOS
OTPublishersHeadlessSDK.shared.showConsentPurposesUI()

This method is not supported on tvOS.