Adding Consent Management to your App

Adding Consent Management to your App

by on ‎08-16-2018 08:52 AM - edited on ‎08-17-2018 07:24 AM by (192 Views)

This guide provides step-by-step instruction on how to enable Tealium Consent Manager for Android, which can help you comply with legal obligations, such as GDPR. Once implemented, your user will be able to easily consent to or decline tracking, and Tealium SDK will store and respect thier choice from that point on.

In this article:

Table of Contents Placeholder

Overview

How It Works

The Consent Manager is disabled by default. Once it is enabled, before any consent preferences have been set, the consent manager's user consent status will be in an "unknown" state and will queue all events until consent is granted or revoked by the user. Once the consent status is "consented" or "notConsented", the following will happen:

If the user consents to tracking:

  • All previously-queued calls will be sent
  • The user's consent status will be stored permanently and will be checked each time a new tracking call is made
  • if the user has set customized preferences and consented only to specific categories, these categories will be respected when tags or connectors are fired in Tealium iQ and EventStream respectively
  • If Consent Logging is enabled, a single track call will be sent to Universal Data Hub (UDH) to keep track of the user's consent preferences for auditing puposes only

If the user declines to tracking:

  • All previously-queued tracking calls will be purged from the queue
  • All future calls will not be sent
  • No events will be sent to the UDH. Declined consent state cannot be tracked in the UDH

Supported Platforms

Android Mobile, Android TV, Android Wear

Recommended Usage

Usage of this module is recommended. It is automatically included in Tealium Android Library.

Included Variables

The following variables will be transmitted with each tracking call while the Consent Manager is enabled:

Variable Name Description Example Value
policy The policy under which consent was collected gdpr
consent_status The user's current consent status consented
consent_categories The user's current categories they are consented to [ANALYTICS, CDP]

Public API

ConsentManager

//TealiumHelper.java
import com.tealium.library.ConsentManager;

public static final String TEALIUM_MAIN = "main";

public static void initialize(Application application) {
	final Tealium.Config config = Tealium.Config.create(application, "<your_account>", "<your_profile>", "<environment>");

	config.enableConsentManager(TEALIUM_MAIN); //enable with tealium instance name

	final Tealium tealiumInstance = Tealium.createInstance(TEALIUM_MAIN, config);
}

setUserConsentStatus

tealiumInstance.getConsentManager().setUserConsentStatus(ConsentManager.ConsentStatus.CONSENTED);

Sets the user's consent status. Designed to be called from your consent management preferences screen in your app when the user opts in or opts out of tracking. If the user's status is set to CONSENTED using this method, the consent manager automatically subscribes the user to ALL available consent categories. This does not allow a subset of the available categories to be set selectively.

Parameter Description Example Value
status A value from ConsentManager.ConsentStatus constants  CONSENTED / NOT_CONSENTED 

setUserConsentCategories

tealiumInstance.getConsentManager().setUserConsentCategories(new String[]{ConsentManager.ConsentCategory.ANALYTICS, 
																ConsentManager.ConsentCategory.BIG_DATA});

Sets the user's consent categories. Designed to be called from your consent management preferences screen in your app. This method automatically sets the user's consent status to CONSENTED  if any number of categories are set.

Parameter Description Example Value
categories An array of category values from ConsentManager.ConsentCategory constants [ConsentManager.ConsentCategory.ANALYTICS,ConsentManager.ConsentCategory.BIG_DATA]

setUserConsentStatusWithCategories

tealiumInstance.getConsentManager().setUserConsentStatusWithCategories(ConsentManager.ConsentStatus.CONSENTED, new String[] {ConsentManager.ConsentCategory.ANALYTICS});

Sets the consent status and categories in a single call.

Parameter Description Example Value
status A value from ConsentManager.ConsentStatus constants CONSENTED / NOT_CONSENTED 
categories An array of category values from ConsentManager.ConsentCategory constants [ConsentManager.ConsentCategory.ANALYTICS,ConsentManager.ConsentCategory.BIG_DATA]

getUserConsentStatus

final String userStatus = tealiumInstance.getUserConsentStatus();

Returns the current consent status of the user.

getUserConsentCategories

final String[] userCategories = tealiumInstance.getUserConsentCategories();

Returns the current consent categories of the user.

getUserConsentPreferences

final UserConsentPreferences userPreferences = tealiumInstance.getConsentManager().getUserConsentPreferences();

Returns the UserConsentPreferences object.

resetUserConsentPreferences

tealiumInstance.resetUserConsentPreferences();

Clears all currently stored consent preferences. Reverts to UNKNOWN consent state with no categories.

setPolicy

tealiumInstance.getConsentManager().setPolicy("custompolicy");

Overrides the default policy parameter. Default is gdpr.

getPolicy

final String currentPolicy = tealiumInstance.getConsentManager().getPolicy();

Returns the current policy.

Tealium.Config Methods

enableConsentManager

public final String TEALIUM_INSTANCE = "main";
final Tealium.Config config = Tealium.Config.create(...);
config.enableConsentManager(TEALIUM_INSTANCE);

Enable consent manager. This method is to be used before Tealium initialization.

Parameter Description Example Value
instance Tealium instance name "main"

isConsentManagerEnabled

config.isConsentMangerEnabled()

Checks if consent manager is enabled.

Tealium Methods

getConsentManager

final Tealium tealiumInstance = Tealium.createInstance(TEALIUM_MAIN, config);

ConsentManager consentManager = tealiumInstance.getConsentManager();

Returns the instance of consent manager if enabled.

disableConsentManager

final Tealium tealiumInstance = Tealium.createInstance(TEALIUM_MAIN, config);

tealiumInstance.disableConsentManager();

Disables consent manager. This method is to be used to disable consent manager after Tealium is fully initialized.

Constants

ConsentManager.ConsentCategories

AFFILIATES
ANALYTICS
BIG_DATA
CDP
COOKIEMATCH
CRM
DISPLAY_ADS
EMAIL
ENGAGEMENT
MOBILE
MONITORING
PERSONALIZATION
SEARCH
SOCIAL
MISC

These static constants are the complete list of supported consent categories.

ConsentManager.ConsentStatus

CONSENTED
NOT_CONSENTED
UNKNOWN

These static constants are the complete list of supported consent statuses.

UNKNOWN

The UNKNOWN status is the default setting for the consent manager. In this state, the consent manager will queue events locally until an affirmative CONSENTED/NOT_CONSENTED status is provided.

tealiumInstance.getConsentManager().setUserConsentStatus(ConsentManager.ConsentStatus.UNKNOWN);

CONSENTED

The CONSENTED status is set when the user has consented to tracking. In this status, the consent manager will dequeue any previously-queued track calls and allow all subsequent tracking calls to continue as normal.

tealiumInstance.getConsentManager().setUserConsentStatus(ConsentManager.ConsentStatus.CONSENTED);

NOT_CONSENTED

The NOT_CONSENTED status is set when the user has declined tracking. In this state, the consent manager will purge any previously-queued track calls and will drop all subsequent tracking calls from being further processed by the SDK.

tealiumInstance.getConsentManager().setUserConsentStatus(ConsentManager.ConsentStatus.NOT_CONSENTED);

Code Example

Use Case 1: Simple Opt-in

tealiumInstance.getConsentManager().setUserConsentStatus(ConsentManager.ConsentStatus.CONSENTED);

This example shows you how to give your users a simple "Opt-in/Opt-out" option. If the user consents, they will be automatically opted-in to all tracking categories. If they revoke their consent, no categories will be active, and no tracking calls will be sent.

Define and call the following method in your Tealium Helper class when your app user consents to or declines tracking. If the user consents to tracking, the Consent Manager will automatically opt them in to all tracking categories.

simple1.gif

 Use Case 2: Group Opt-in

tealiumInstance.getConsentManager().setUserConsentStatusWithCategories(ConsentManager.ConsentStatus.CONSENTED, new String[] {ConsentManager.ConsentCategory.ANALYTICS});

This example shows a category-based consent model, where tracking categories are grouped into a smaller number of higher-level categories, defined by you. For examples, you may choose to group the Tealium consent categories "big_data", "analytics", and "monitoring" under a single category called "performance". This may be easier for the user than selecting from the full list of categories. You may choose to represent this in a slider interface, ranging from least-permissive to most permissive (all categories).

slide1.gif

Use Case 3: Category-based Opt-in

tealiumInstance.getConsentManager().setUserConsentStatusWithCategories(ConsentManager.ConsentStatus.CONSENTED, new String[] {ConsentManager.ConsentCategory.ANALYTICS, ConsentManager.ConsentCategory.PERSONALIZATION});

This example shows a category-based consent model where the user must explicitly select each category from the full list of categories. The default is UNKNOWN, which will queue hits until the user provides their consent. If the user consents to any categories, events are de-queued, and the consent category data is appended to each tracking call.

List1.gif