Adding Consent Management to Your App

Adding Consent Management to Your App

by 3 weeks ago - edited 3 weeks ago by Community Manager (87 Views)

This guide shows how to use Tealium Consent Manager for iOS, tvOS, and watchOS using Objective-C which can help your app to comply with legal obligations, such as GDPR. Once implemented, your user will be able to easily consent to or decline tracking, and the Tealium SDK will store and respect their 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 "not consented", the following will happen:

If the user consents to tracking

  • All previously-queued tracking 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 tracking call will be sent to Universal Data Hub (UDH), to keep track of the user's consent preferences for auditing purposes only

If the user declines tracking

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

Supported Platforms

iOS, tvOS, watchOS

Recommended Usage

Usage of this module is recommended.

It is automatically included in CocoaPods framework builds.

Included Variables

The following variables will be transmitted with each tracking call while the module 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"]

Public API

consentManager

// TealiumHelper.h

@import TealiumIOS;

@interface TealiumHelper : NSObject<TealiumDelegate, TEALConsentManagerDelegate>

@property (nonatomic, strong) Tealium *tealium;

@end

// TealiumHelper.m

@implementation TealiumHelper

+ (instancetype _Nonnull)sharedInstance {
  static TealiumHelper *tealiumHelper = nil;
  static dispatch_once_t onceToken;
  dispatch_once(&onceToken, ^{
  tealiumHelper = [[self alloc] init];
});

  return tealiumHelper;
}

- (instancetype)init {
  if (self = [super init]) {
  TEALConfiguration *configuration = [TEALConfiguration configurationWithAccount:@"tealiummobile" profile:@"demo" environment:@"dev"];
  [configuration setLogLevel: TEALLogLevelDev];

  // enable Tealium Consent Manager
  [configuration setEnableConsentManager:YES];

  _tealium = [Tealium newInstanceForKey:@"TEALIUM_INSTANCE" configuration:configuration];
  _tealium.delegate = self;

  // set optional Tealium Consent Manager Delegate
  _tealium.consentManagerDelegate = self;
  NSLog(@"%s, %@", __FUNCTION__, [TEALConsentManager consentStatusString:_tealium.consentManager.userConsentStatus]);
}

  return self;
}

@end

This code shows how to enable the consent manager on Tealium initialization.

enable

[_tealium.consentManager enable];

Enable consent manager. This method can be used to enable consent manager at a later time and not on Tealium initialization.

  The recommended approach is to enable consent manager on Tealium initialization.  

isEnabled

[_tealium.consentManager isEnabled];

Checks if consent manager is enabled.

disable

[_tealium.consentManager disable];

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

isDisabled

[_tealium.consentManager isDisabled];

Checks if the consent manager is disabled.

consentManagerDelegate

self.tealium.consentManagerDelegate = self;

Registers a specific class conforming to the TEALConsentManagerDelegate protocol.

setUserConsentStatus

[_tealium.consentManager setUserConsentStatus:Consented];

Sets the user's consent status. Designed to be called from your consent management preferences screen in your app when the user enables or disables tracking.

  Consent Manager will always set the list of consented categories to include ALL available consent categories if the status is Consented. This method does not allow categories to be set selectively.  

Parameters Description Example Value
TEALConsentStatus A value from TEALConsentStatus enum Consented / NotConsented / Disabled

setUserConsentCategories

[_tealium.consentManager setUserConsentCategories:@[@"analytics"]];

Sets the user's consent categories. Designed to be called from your consent management preferences screen in your app.

Will always set consent status to Consented when any number of categories are set.

Parameters Description Example Value
NSArray An array of predefined NSString categories @[@"analytics", @"big_data"]

setUserConsentStatus:withUserConsentCategories

[_tealium.consentManager setUserConsentStatus:Consented withUserConsentCategories:@[@"analytics"]];

Sets the user's consent status and user's consent categories in a single method.

Parameters Description Example Value
TEALConsentStatus A value from TEALConsentStatus enum Consented / NotConsented
NSArray An array of predefined NSString categories @[@"analytics", @"big_data"]

userConsentStatus

[_tealium.consentManager userConsentStatus];

Returns the current consent status of the user.

userConsentCategories

[_tealium.consentManager userConsentCategories];

Returns the current consent categories of the user.

isConsented

[_tealium.consentManager isConsented];

Convenience method to determine if the user is consented.

consentStatusString

[TEALConsentManager consentStatusString:_tealium.consentManager.userConsentStatus];

Convenience method for human-readable string of the TEALConsentStatus enum.

resetUserConsentPreferences

[_tealium.consentManager resetUserConsentPreferences];

Resets all currently stored consent preferences. Reverts to Unknown consent status with no categories.

setConsentLoggingEnabled

[_tealium.consentManager setConsentLoggingEnabled:YES];

Enables the Consent Logging feature, which sends all consent status changes to UDH for auditing purposes.

Parameters Description Example Value
BOOL Enables or disables consent logging YES / NO

isConsentLoggingEnabled

[_tealium.consentManager isConsentLoggingEnabled];

Returns the current state of the consent logging feature.

allCategories

[_tealium.consentManager allCategories];

Returns the complete list of supported consent categories.

TEALConfiguration Methods

enableConsentManager

self.configuration.enableConsentManager = YES;

Sets the initial consent status for the user when the library starts up for the first time. If there are saved preferences, these will override any preferences passed in the config object.

Consent Manager will always set the list of consented categories to include ALL available consent categories, if the status is Consented. This method does not allow categories to be set selectively.

userConsentStatus

self.configuration.userConsentStatus = Consented;
Parameters Description Example Value
TEALConsentStatus A value from TEALConsentStatus enum Consented / NotConsented / Disabled

Sets the user's initial consent status when the library starts up for the first time. If there are saved preferences, these will override any preferences passed in the config object.

userConsentCategories

self.configuration.userConsentCategories = @[@"analytics", @"retargeting"];
Parameters Description Example Value
NSArray An array of predefined NSString categories @[@"analytics", @"big_data"]

Sets the user's initial consent categories when the library starts up for the first time. If there are saved preferences, these will override any preferences passed in the config object.

TEALConsentManagerDelegate Methods

consentManagerDidChangeWithState

- (void)consentManagerDidChangeWithState:(TEALConsentStatus)consentStatus;

This method is called whenever the consent manager user consent status is changed (e.g. the user has consented or declined tracking).

consentManagerDidUpdateConsentCategories

- (void)consentManagerDidUpdateConsentCategories:(NSArray * _Nullable)categories;

This method is called whenever the consent manager user consent categories are updated.

consentManagerWillDropDispatch

- (void)consentManagerWillDropDispatch:(TEALDispatch * _Nullable)dispatch;

This method is called whenever the consent manager is going to drop a tracking call (e.g. the user has declined tracking).

consentManagerWillQueueDispatch

- (void)consentManagerWillQueueDispatch:(TEALDispatch * _Nullable)dispatch;

This method is called whenever the consent manager is in the Unknown state. Tracking calls are being queued locally until the user grants or declines consent.

Consent Categories

  • analytics
  • affiliates
  • display_ads
  • email
  • personalization
  • search
  • social
  • big_data
  • mobile
  • engagement
  • monitoring
  • cdm
  • cdp
  • cookiematch
  • misc

This list contains all the supported consent categories.

TEALConsentStatus

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 / NotConsented status is provided.

self.tealium.consentManager.userConsentStatus = Unknown

Consented

self.tealium.consentManager.userConsentStatus = Consented

The Consented status is set when the user has consented to tracking. In this state, the consent manager will allow all tracking calls to continue as normal.

NotConsented

self.tealium.consentManager.userConsentStatus = NotConsented

The NotConsented status is set when the user has declined tracking. In this state, the consent manager will drop all tracking calls and halt further processing by the SDK.

Code Examples

Use Case 1: Simple Opt-in

[_tealium.consentManager setUserConsentStatus: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.

simple.gif 

Use Case 2: Grouped Opt-in

[_tealium.consentManager setUserConsentStatus:Consented withUserConsentCategories:@[@"analytics", @"monitoring", @"big_data", @"mobile", @"crm"]];

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 example, you may choose to group the Tealium consent categories "analytics", "monitoring", "big_data", "mobile", and "crm" 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).

 grouped.gif

Use Case 3: Category-based Opt-in

[_tealium.consentManager setUserConsentStatus:Consented withUserConsentCategories:@[@"analytics", @"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 state of the Consent Manager is "Unknown", which will queue hits until the user provides their consent. If the user consents to any category, events are dequeued, and the consented category data is appended to each tracking call.

 individual.gif

Video

Please see this video for an implemented example.

Future Improvements

  • Remote configuration options via Tealium iQ

Samples

Change Log

Build 1

  • Initial release