Overview

When a user updates their consent choices or interacts with the OT SDK UI, 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 USP String to 3rd Party SDKs
• Routing the User to another location in the App
• Displaying messages to the User of their changes
• Logging updates to internally owned APIs
• etc...

The SDK offers 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 listeners and rely on the OT SDK broadcasts as the primary method to action on consent.

Observing Broadcast Events

Alternative Approach:

If for some reason you are unable to utilize broadcast events to action on consent, the SDK provides a way to rely on UI interaction events and querying for consent. In this case, OneTrust recommends you Query for Consent inside UI Interaction Events to action on consent.

Observing Broadcast Events

Every time the SDK is initialized or the user's consent changes, the OT SDK will broadcast an event for each Category ID and SDK ID and passes the latest consent value. You can use these events and consent values to trigger some action.

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

In the 202209.2.0 release, the SDK will broadcast events for always active categories/SDKs as well.

Use Case: Applications needs listeners for the SDKs or Categories that require some action to be taken when a user gives/withdraws their consent.

Example: When a user opts out of the "Sale of Personal Data" category, set a privacy or opt out flag in Targeting SDKs in scope so no personalized ads or ads of any kind are shown to the user.

Category IDs

When setting up your listeners, you'll want to listen for changes based on the category's ID (OptanonGroupId).

Note: These OptanonGroupIds are friendly variables which can be updated in the OneTrust tenant under Cookie Consent > Categorization > Categories.

Here are the default values as set by OneTrust:

SDK IDs

When setting up your listeners, you'll want to listen for changes based on each SDK's ID. SDK IDs can be found in your tenant under Cookie Categories > SDKs > Your App > Instructions

Intent (to be used with a broadcast receiver)

The intent 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)

Setting it up

1. Define the name(s) of the receivers in your Activity that will be used by your application

private BroadcastReceiver categoryReceiver, sdkReceiver;

2. Initialize each broadcast receiver

categoryReceiver = new BroadcastReceiver() {
	@Override
	// Callback when consent changed for this Category. 
	public void onReceive(Context context, Intent intent) {
	
		// Write Category related logic here...
		
		Log.i("BroadcastService", "Intent name: " + intent.getAction() +
		" status = " + intent.getIntExtra(OTBroadcastServiceKeys.EVENT_STATUS, -1));
	}
};

sdkReceiver = new BroadcastReceiver() {
	@Override
	
	// Callback when consent changed for this SDK.
	public void onReceive(Context context, Intent intent) {

		// Write SDK related logic here...
		
		Log.i("BroadcastService", "Intent name: " + intent.getAction() +
		" status = " + intent.getIntExtra(OTBroadcastServiceKeys.EVENT_STATUS, -1));
	}
};

3. Register the broadcast receivers in the onCreate() method of your Activity. Pass in the category ID or SDK ID into the IntentFilter method.

// Register the category receiver
registerReceiver(categoryReceiver, new IntentFilter("C0004"));

// Register the SDK receiver
registerReceiver(sdkReceiver, new IntentFilter("sdkID"));

4. Unregister the receivers in the onDestroy() method of your Activity.

// Unregister category receiver
unregisterReceiver(categoryReceiver);

// Unregister SDK receiver
unregisterReceiver(sdkReceiver);

OTConsentUpdated

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

Use case: Applications need to know when they can query for latest consent for vendors, categories, SDKs, etc. This is useful in cases where you do not or cannot set up multiple listeners for each category or SDK.

Event name: OTConsentUpdated

Public key exposed from SDK: OTBroadcastServiceKeys.OT_CONSENT_UPDATED

Receiver call back

//receiver callback 
BroadcastReceiver otConsentUpdatedBroadCastReceiver; 

Initialize OT Consent update Broadcast Receiver

// Initialize OT Consent update broadcast receiver 
otConsentUpdatedBroadCastReceiver = new BroadcastReceiver() { 
            @Override 
            public void onReceive(Context context, Intent intent) { 
              //callback when consent updated/user interacted. 
              //receiver callback 
						 BroadcastReceiver otConsentUpdatedBroadCastReceiver; 

//Initialize OT Consent update broadcast receiver 
otConsentUpdatedBroadCastReceiver = new BroadcastReceiver() { 
            @Override 
            public void onReceive(Context context, Intent intent) { 
				    //callback when consent updated/user interacted. 
					  // Application can consume the user consent status for category, SDK , vendorlist. 
           Log.i("BroadcastService", "Intent name: " + intent.getAction()); 
            } 
       }; 
              

Register the Broadcast Receiver

//Register the broadcast receiver 
registerReceiver(otConsentUpdatedBroadCastReceiver, new IntentFilter(OTBroadcastServiceKeys.OT_CONSENT_UPDATED)); 

Unregister the broadcast receiver

// Unregister the broadcast receiver 
unregisterReceiver(otConsentUpdatedBroadCastReceiver); 
            Log.i("BroadcastService", "Intent name: " + intent.getAction()); 
            } 
       };

Querying for Consent

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

Querying Consent Status for a Category

Query the current consent status for any of the categories included in your application. 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. Simply pass in the Category ID (eg. C0001) and the method 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)

new OTPublishersHeadlessSDK(this).getConsentStatusForGroupId("C0004");

Parameters

• GroupId: This is the ID for the categories in scope. It can be found in the OneTrust tenant under Cookie Consent > Categorizations > Categories

Query Consent Status for a Specific SDK

Query the current consent status for any of the SDKs included in 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 method 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)

Tip: SDK IDs can be found in your tenant under Cookie Consent > SDKs > Your App > Instructions

new OTPublishersHeadlessSDK(this).getConsentStatusForSDKId("2368810c-94da-4f18-ab92-c55c5f74cca9");

Parameters

• SDKId - This is the ID for the SDKs assigned to your app. It can be found in the OneTrust tenant under Cookie Categories > SDKs > Your App > Instructions

Query Consent for Vendors

If your app includes a list of vendors such as General Vendors, IAB Vendors or Google Vendors that you need to account for in terms of consent, you query for the status on a vendor level.

Value Returned

getVendorDetails() returns a JSON containing all information regarding a vendor list you specify. Because we're only concerned with the consent status, we'll want to target the consent key. Reference the example code below.

• 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:

• OTVendorListMode - Type of vendor list to retrieve
  • General: returns a list of general vendors
  • Google: returns a lsit of google vendors
  • IAB: returns a list of IAB vendors
• Vendor ID

Tip: Vendor IDs can be found in your tenant under Cookie Consent > Vendors

General Vendor

String vendorConsent = new OTPublishersHeadlessSDK(this).getVendorDetails(OTVendorListMode.GENERAL, "V1").getString("consent");
Log.v("General Vendor", "Vendor Consent: " + vendorConsent);

IAB Vendor

String vendorConsent = new OTPublishersHeadlessSDK(this).getVendorDetails(OTVendorListMode.IAB, "755").getString("consent");
Log.v("IAB Vendor", "IAB Vendor Consent: " + vendorConsent);

Google Vendor

String vendorConsent = new OTPublishersHeadlessSDK(this).getVendorDetails(OTVendorListMode.GOOGLE, "755").getString("consent");
Log.v("Google Vendor", "Google ATP Vendor Consent: " + vendorConsent);

Recommended Approaches

• Set an observer to listen for the OTConsentUpdated broadcast. In the callback, query for general vendor consent
• Use one of the UI Interaction Listener events (such as allSDKViewsDismissed) and query for general vendor consent when it is triggered

Query Consent Status for Universal Consent Purposes

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

Get Purpose Consent

new OTPublishersHeadlessSDK(this).getUCPurposeConsent("purposeID");

Get Topic Consent

new OTPublishersHeadlessSDK(this).getUCPurposeConsent("topicID", "purposeID")

Get Custom Preferences Consent

new OTPublishersHeadlessSDK(this).getUCPurposeConsent("customPreferenceOptionID", "customPreferenceID", "purposeID")

Returns

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

Intitializing Broadcast Listener - Universal Purposes

Universal Consent Purposes broadcast steps are same as the normal category broadcasts. The app will be listening to each of the purpose Ids (intent filter will be purposeId GUID).
This code is to be added to the activity on which the user interacts (RenderNativeUIActivity in Demo app.)

First, declare the broadcast listener variables.

private BroadcastReceiver purpose1Receiver;

Second, initialize and register the listeners in the onCreate method of activity.

// Initialize purpose1 Receiver
purpose1Receiver = new BroadcastReceiver() {
	@Override
	
	// Callback when consent changed for this UC Purpose. 
	public void onReceive(Context context, Intent intent) {
		
		// Write Purpose related logic here...
		
		Log.i("BroadcastService", "Intent name: " + intent.getAction() +
		" status = " + intent.getStringExtra(OTBroadcastServiceKeys.UCP_EVENT_STATUS));
	}
};

registerReceiver(purpose1Receiver, new IntentFilter("replace wth purposeId GUID"));

This will give a JSON string which contains Topics, Custom Preferences and id statuses with respect to the Purpose app is listening for in the following format:

{
	status: 0, 
	custom_preferences”: {
		"cpId": {
			“cpOptionID1”: 0, 
			”cpOptionID1”: 0
		}
	}, 
	”topics”: {
		"topicOpId1": 0,
		"topicOpId2": 1
	}
}

Finally, unregister listeners in the onDestroy method of activity
unregisterReceiver(purpose1Receiver);

The broadcast will be triggered only for those purpose Ids which have a change in its saved consent values. If any of the Topic and Custom Preference options consent of a purpose ID changes, then SDK will trigger broadcasts for that purposeId.

Listening for UI Interaction Events

Note: 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 OT SDK UI, the SDK sends an interaction event that the application can listen for and action on.

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

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

Example 1: 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.

Example 2: In lieu of broadcast events, the app can listen for allSDKViewsDismissed to know when the OneTrust UI has been dismissed and query for user consent. It can then use this consent to fire/suppress SDKs.

Types of Events

The allSDKViewsDismissed(String interactionType) event is often used because:

• It is the last event to fire
• It only fires once all SDK UIs are dismissed from the view heirarchy
• It passes a interactionType to provide context to application on the user's action.

Setting It Up

new OTPublishersHeadlessSDK(this).addEventListener(new OTEventListener() {
	
	@Override
	public void onShowBanner() {}

	@Override
	public void onHideBanner() {}

	@Override
	public void onBannerClickedAcceptAll() {}
	
	@Override
	public void onBannerClickedRejectAll() {}
	
	@Override
	public void onShowPreferenceCenter() {}
	
	@Override
	public void onHidePreferenceCenter() {}
	
	@Override
	public void onPreferenceCenterAcceptAll() {}
	
	@Override
	public void onPreferenceCenterRejectAll() {}
	
	@Override
	public void onPreferenceCenterConfirmChoices() {}
	
	@Override
	public void onShowVendorList() {}
	
	@Override
	public void onHideVendorList() {}
	
	@Override
	public void onVendorConfirmChoices() {}
	
	@Override
	public void onVendorListVendorConsentChanged(String vendorId, int consentStatus) {}
	
	@Override
	public void onVendorListVendorLegitimateInterestChanged(String vendorId, int legitInterest) {}
	
	@Override
	public void onPreferenceCenterPurposeConsentChanged(String purposeId, int consentStatus) {}
	
	@Override
	public void onPreferenceCenterPurposeLegitimateInterestChanged(String purposeId, int legitInterest) {}
  
  @Override
  public void onSdkListSdkConsentChanged(String sdkId, int consentStatus) {}
	
});