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

Recommended Approach:

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

Observing Broadcast Events

Alternatively, if the app can't set up multiple listeners, you can set up a single listener for the OTConsentUpdated event and query for consent. More information here.

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.

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.

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 listeners, 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

Intent

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 with 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. Define the name(s) of the receivers in your Activity

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 consent actioning 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 consent actioning 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("categoryID"));

// 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 SDK will broadcast a generic event every time a OneTrust UI (banner or preference center) is dismissed and consent has been updated locally.

Use case: The app needs to know when it can query for the latest consents for vendors, categories, SDKs, etc.

Event name: OTConsentUpdated

SDK public key: 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

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 initialized OR there are no SDKs associated to this category)

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

Parameters

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

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)

new OTPublishersHeadlessSDK(this).getConsentStatusForSDKId("sdkID");

Parameters

• SDKId: 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 for Vendors

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

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.

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:

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

Tip: Vendor IDs can be found in your tenant under Mobile App 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 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.

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)

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.

❗️

We do not recommend using interaction events to handle any consent actioning logic. Interaction events are triggered after the UI is dismissed but before consent may be updated in local storage. As a result, querying for consent based off these interactions may return the old consent values and not updated ones.

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.

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 hierarchy
• It passes an 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) {}
	
});