Overview

When a user interacts with the CMP UI and updates their consent choices, the application needs to become aware so that it can control the next set of actions like:

• Allowing or restricting processing of 3rd party SDKs based on their categorization
• Passing latest user consent values to 3rd Party SDKs
• Passing the IAB's encoded TC String to 3rd party SDKs
• Passing the IAB's GPP String to 3rd Party SDKs
• Routing the user to another location in the app
• Displaying toast messages to the user
• Logging updates to internal APIs
• etc...

Detecting user consent

The SDK provides two options to detect user consent:

• Observing Broadcast Events
• Querying for User Consent

The SDK also provides a way to listen for UI interaction events. More detail below: Listening for UI Interaction Events

Recommended Approach:

OneTrust recommends you set up observers and rely on the SDK broadcasts as the primary method to action on consent.

Observing Broadcast Events

Alternative Approach:

If you are unable to utilize broadcast events to action on consent, we recommend you Query for Consent coupled with UI Interaction Events to action on consent.

Observing Broadcast Events

Every time the SDK is initialized or the user's consent changes, it will broadcast an event with the consent status for each Category ID and SDK ID. You can use these events and consent values to trigger a subsequent action.

Your app can listen to either the categories itself or each individual SDK you want to manage. OneTrust recommends setting up observers on the category level to minimize the amount of observers you have to initialize.

The SDK will broadcast events for always active categories/SDKs as well.

Use Case: The app needs to know when consent has changed so it can trigger an appropriate action.

Example: When a user opts out of the "Sale of Personal Data" category, set a privacy/opt out flag in the Google Ads SDK so no personalized ads are shown to the user.

Category IDs

When setting up your observers, you can listen for changes based on the category's ID (OptanonGroupId).

OptanonGroupIds are friendly variables which can be updated in the OneTrust tenant under Mobile App Consent > Categorization > Categories.

Here are the default values as set by OneTrust:

SDK IDs

When setting up your observers, you can listen for changes based on each SDK's ID.

SDK IDs can be found in your tenant under Mobile App Consent > SDKs > Your App > Instructions > Scroll to the bottom

Notification Object

The notification object returns an integer value and indicates the consent of the user.

• 1 = Consent is given
• 0 = Consent is not given
• -1 = Consent has not been collected (The SDK is not yet initialized OR there are no SDKs associated to this category)

🚧

There must be at least one SDK categorized to a category in order for it to appear on the CMP UI and for consent to be written for it. For example, if there are no SDKs categorized as 'Targeting', this category will not appear on the UI and no consents will be available for it (will return a -1 if queried).

Setting it up

1. Create a function that will be called when the observer is triggered. You will need to create a function for each category or SDK that needs to be actioned.

//iOS and tvOS

//category level
@objc func actionConsent_Category_Name(_ notification:Notification){
  let consentValue = notification.object as? String
  NSLog("Category Consent Value = \(consentValue ?? "false")")
  //trigger other actions
}

//SDK level
@objc func actionConsent_SDK_Name(_ notification:Notification){
  let consentValue = notification.object as? String
  NSLog("SDK Consent Value = \(consentValue ?? "false")")
  //trigger other actions
}

2. Register the observer. Your application will need to register an observer for each category/SDK you created an observer function for.

//iOS and tvOS

//category level
NotificationCenter.default.addObserver(
  self,
  selector: #selector(actionConsent_Category_Name(_:)),
  name: NSNotification.Name(rawValue: "C0003"),
  object: nil
)

//SDK level
NotificationCenter.default.addObserver(
  self,
  selector: #selector(actionConsent_SDK_Name(_:)),
  name: NSNotification.Name(rawValue: "SDK ID Value"),
  object: nil
)

3. Unregister the observer when the view is destroyed.

//iOS and tvOS

//category level
NotificationCenter.default.removeObserver(NSNotification.Name(rawValue: "C0003"))

//SDK level
NotificationCenter.default.removeObserver(NSNotification.Name(rawValue: "SDK ID Value"))

OTConsentUpdated

The SDK will also broadcast a generic event every time a OneTrust UI (banner or preference center) is dismissed.

Use case: The app needs to know when they can query for the latest consents for vendors, categories, SDKs, etc. This is useful in cases where you do not or cannot set up multiple observers for each category or SDK.

Event name: OTConsentUpdated

1. Create the observer callback.

//iOS and tvOS
 @objc func returnConsentOTConsentUpdated(_ notification:Notification){ 
   NSLog("OT Consent Updated Notification Fired") 
   //query for consent and trigger next actions
 } 

2. Register the observer.

//iOS and tvOS
NotificationCenter.default.addObserver(self, selector:
                                       #selector(returnConsentOTConsentUpdated(_:)),
                                       name: Notification.Name("OTConsentUpdated"),
                                       object: nil) 

3. Destroy the observer.

//iOS and tvOS
NotificationCenter.default.removeObserver(NSNotification.Name(rawValue: "OTConsentUpdated"))

Querying for Consent

You can query for consent on a category or SDK level.

Querying Consent Status for a Category

You can query for the current consent status of any category used by your app. This can be used to determine what privacy action is needed at app launch or anytime the consent status is needed without being notified by an event broadcast. Pass in the Category ID (eg. C0004) and the SDK will return the current consent status (integer value).

Value Returned

• 1 = Consent is given
• 0 = Consent is not given
• -1 = Consent has not been collected (The SDK is not yet initialized OR there are no SDKs associated to this category)

//iOS and tvOS
OTPublishersHeadlessSDK.shared.getConsentStatus(forCategory: "catID")

Parameters

• forCategory: This is the ID of the category. It can be found in the OneTrust tenant under Mobile App Consent > Categorizations > Categories

🚧

There must be at least one SDK categorized to a category in order for it to appear on the CMP UI and for consent to be written for it. For example, if there are no SDKs categorized as 'Targeting', this category will not appear on the UI and no consents will be available for it (will return a -1 if queried).

Query Consent Status for an SDK

You can query for the current consent status of any SDK used your application. This can be used to determine what privacy action is needed at application launch or anytime the consent status is needed without being notified by an event broadcast. Pass in the SDK ID and the SDK will return the current consent status (integer value).

Value Returned

• 1 = Consent is given
• 0 = Consent is not given
• -1 = Consent has not been collected (The SDK is not initialized OR there are no SDKs associated to this category)

//iOS and tvOS
OTPublishersHeadlessSDK.shared.getConsentStatus(forSDKId: "sdkID")

Parameters

• forSDKId: This is the ID of the SDK assigned to your app. It can be found in the OneTrust tenant under Mobile App Consent > SDKs > Your App > Instructions > Scroll to the bottom

Query Consent Status for Vendors

If your app uses General Vendors, IAB Vendors or Google Vendors, you can query for the consent status on a vendor level.

OTPublishersHeadlessSDK.shared.getVendorDetails(vendorId: <String>, for: <VendorListMode>) returns a JSON containing all information regarding a vendor list you specify. Example code below.

Value Returned

• 2 = Vendor mapped to an always active category (e.g. Strictly Necessary)
• 1 = Consent is given
• 0 = Consent is not given

Parameters

The method takes in two parameters:

• Vendor ID
• OTVendorListMode: Type of vendor list to retrieve
  • .general: returns a list of General Vendors
  • .google: returns a list of Google Vendors
  • .iab: returns a list of IAB Vendors

Vendor IDs can be found in your tenant under Mobile App Consent > Vendors

General Vendor

//iOS
if let vendorConsent = OTPublishersHeadlessSDK.shared.getVendorDetails(vendorId: "vendorID", for: .general) {
    print("General Vendor Consent: \(vendorConsent.getLatestConsent() ?? 5)")
}

IAB Vendor

//iOS and tvOS
if let vendorConsent = OTPublishersHeadlessSDK.shared.getVendorDetails(vendorId: "vendorID", for: .iab) {
    print("IAB Vendor Consent: \(vendorConsent.getLatestConsent() ?? 5)")
}

Google Vendor

//iOS and tvOS
if let vendorConsent = OTPublishersHeadlessSDK.shared.getVendorDetails(vendorId: "vendorID", for: .google) {
    print("Google ATP Vendor Consent: \(vendorConsent.getLatestConsent() ?? 5)")
}

Recommended Approaches for Vendor Consent

When querying for vendor consent, we recommend setting an observer to listen for the OTConsentUpdated broadcast. In the callback, query for desired vendor consent.

Alternatively, you can also use one of the UI Interaction Events (such as allSDKViewsDismissed) and query for the desired vendor consent when triggered.

Query Consent Status for Universal Consent Purposes

If your app is utilizing Universal Consent, you can query for the consent status of Universal Consent Purposes, Custom Preferences, and Topics.

❗️

Universal Consent functionality is currently not supported for tvOS.

Get Purpose Consent

//iOS
OTPublishersHeadlessSDK.shared.getUCPurposeConsent(purposeID: "Purpose ID")

Get Custom Preferences Consent

//iOS
OTPublishersHeadlessSDK.shared.getUCPurposeConsent(customPreferenceOptionID: "custPrefOptionID", customPreferenceID: "custPrefID", purposeID: "purposeID")

Value Returned

• 1 = Consent is given
• 0 = Consent is not given
• -1 = Consent has not been collected (The SDK is not yet initialized or purpose does not exist)

Listening for UI Interaction Events

🚧

UI Interaction Events are only relevant if the app is using the out of the box OneTrust UI. If you have built your own UI, disregard this section.

When a user interacts with the CMP UI, the SDK sends an interaction event that the application can listen for.

Use Case: The app needs to trigger certain actions based on interaction with the UI.

Example: User selects the "Confirm My Choices" button on the OT Preference Center UI, which saves their consent choices. An app might want to listen for the onPreferenceCenterConfirmChoices() to show a success toaster to the user and navigate them to the App's home page.

Use Case 2: In the event that broadcast events cannot be used to action on consent, the app can rely solely on interaction events and querying for consent to fire/suppress SDKs and trigger other actions.

Example: In lieu of notifications, the app can listen for allSDKViewsDismissed to know when the OneTrust UI has been dismissed and query for user consent to trigger consent actions.

Types of Events

Here are the supported OTEventListener events:

The allSDKViewsDismissed(interactionType: ConsentInteractionType) event is often used as:

• It is the last event to fire when a CMP UI is dismissed
• It only fires once all CMP UIs are dismissed from the view hierarchy
• It passes a ConsentInteractionType to provide context on the user's action to dismiss the UI

Setting it up

1. Register the class that will be extended to handle the OTEventListener events.

//iOS and tvOS
OTPublishersHeadlessSDK.shared.addEventListener(self)

2. Extend the class to include the protocol OTEventListenermethods.

//iOS and tvOS
class YourCustomClass: UIViewController {
  override func viewDidLoad() {
    super.viewDidLoad()
    OTPublishersHeadlessSDK.shared.addEventListener(self)
  }
}

extension YourCustomClass: OTEventListener {
  func onHideBanner() {}
  func onShowBanner() {}
  func onBannerClickedRejectAll() {}
  func onBannerClickedAcceptAll() {}
  func onShowPreferenceCenter() {}
  func onHidePreferenceCenter() {}
  func onPreferenceCenterRejectAll() {}
  func onPreferenceCenterAcceptAll() {}
  func onPreferenceCenterConfirmChoices() {}
  func onPreferenceCenterPurposeLegitimateInterestChanged(purposeId: String, legitInterest: Int8) {}
  func onPreferenceCenterPurposeConsentChanged(purposeId: String, consentStatus: Int8) {}
  func onShowVendorList() {}
  func onHideVendorList() {}
  func onVendorListVendorConsentChanged(vendorId: String, consentStatus: Int8) {}
  func onVendorListVendorLegitimateInterestChanged(vendorId: String, legitInterest: Int8) {}
  func onVendorConfirmChoices() {}
  func allSDKViewsDismissed(interactionType: ConsentInteractionType) {}
}