Consent Manager

1. Choose your type of installation

CocoaPods

1.Add following line into your Podfile

pod 'StackConsentManager', '~> 1.1.0'

2.Run pod install

2. Synchronize

Default

Consent manager SDK can be synchronized at any moment of application lifecycle. We recommend to synchronize it at application launch. Multiple synchronization calls are allowed.

Import StackConsentManager/StackConsentManager.h in AppDelegate.m

import StackConsentManager

Call synchronise consent in -application:didFinishLaunchingWithOptions: .

Required parameter is appKey - Appodeal API Key.

Optional parameters are customParameters (string - any dictionary of custom parameters) and completion (block that invokes after synchronization)

/// Initialisation 
class YourAppDelegate: AppDelegate {
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]?) -> Bool {
        STKConsentManager.shared().synchronize(withAppKey: "Your app key") { [unowned self] error in
			error.map { print("Error while synchronising consent manager: \($0)") }
			guard STKConsentManager.shared().shouldShowConsentDialog == .true else {
                // Initialise SDK here
                return
            }
			// Load and present consent dialog                                   
		}
        return true
    }
}

/// Initialisation 
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    __weak typeof(self) weakSelf = self;
    [STKConsentManager.sharedManager synchronizeWithAppKey:APP_KEY completion:^(NSError *error) {
        __strong typeof(self) strongSelf = weakSelf;
        if (error) {
            NSLog(@"Error while synchronising consent manager: %@", error);
        }
        
        if (STKConsentManager.sharedManager.shouldShowConsentDialog != STKConsentBoolTrue) {
            // Initialise SDK here
            return ;
        }
        
		// Load and present consent dialog        
    }];
    return YES;
}

After synchronization completion, you can receive information about the previous user consent and regulation zone. Before synchronization these parameters are undefined

// Check regulation
let regulation = STKConsentManager.shared().regulation
// Check consent status
let status = STKConsentManager.shared().consentStatus
// Available after first show (synchronisation is required)
let consentString = STKConsentManager.shared().iabConsentString

Advanced

You can force consent manager to write iAB keys in NSUserDefaults by setting up storage property before synchronization to STKConsentDialogStorageUserDefaults

SDK does not remove iAB keys from NSUserDefaults and only overrides them

// Store IAB strings in user defaults
// should be called before synchronize
STKConsentManager.shared().storage = .userDefaults

You can register yourself as a vendor before synchronization.

Parameter	Type	Description
id	Integer	iAB id. If you are not registered as iAB vendor you can use custom id
name	String	Display name. Will be displayed in the consent window
status	String	Custom string to check consent result for the concrete vendor
purposesIds	Array of integers	iAB purposes ids array
featuresIds	Array of integers	iAB features ids array
legIntPurposeIds	Array of integers	iAB leg int purposes ids array

// Register custom vendor (will be displayed on consent window)
// should be called before synchronize
STKConsentManager.shared().registerCustomVendor { builder in
	let _ = builder
        .appendPolicyURL(URL(string: "https://cmg.com/privacy")!)
        .appendName("My app")
        .appendBundle("com.app.bundle")
        .appendPurposesIds([1, 2, 3])
        .appendFeaturesIds([5, 6])
        .appendLegIntPurposeIds([1])
}

// Register custom vendor (will be displayed on consent window)
// should be called before synchronize
[STKConsentManager.sharedManager registerCustomVendor:^(STKVendorBuilder * _Nonnull builder) {
	STKVendorBuilder *builder = [STKVendorBuilder new]
		.appendPolicyURL([NSURL URLWithString:@"https://cmg.com/privacy"])
		.appendName(@"My app")
		.appendBundle(@"com.app.bundle")
		.appendPurposesIds([1, 2, 3])
		.appendFeaturesIds([5, 6])
		.appendLegIntPurposeIds([1]);
}];

3. Consent window

SDK allows to call consent window api only after synchronization

After SDK synchronized, you can load the consent window. Loading allowed in any regulation zone and independent from previous consent.

class YourViewController: UIViewController {
	override func viewDidLoad() {
		super.viewDidLoad()
		STKConsentManager.shared().loadConsentDialog { [unowned self] error in
			error.map { print("Error while loading consent dialog: \($0)") }
			guard 
				let controller = self.window?.rootViewController, 
				STKConsentManager.shared().isConsentDialogReady 
			else {
				// Initialise SDK here
				return
			}
			STKConsentManager.shared().showConsentDialog(fromRootViewController: controller, 
				delegate: self)
		}
	}
}

@implementation YourViewController

- (void)viewDidLoad
{
  [super viewDidLoad];
	__weak typeof(self) weakSelf = self;
	[STKConsentManager.sharedManager loadConsentDialog:^(NSError *error) {
		__strong typeof(self) strongSelf = weakSelf;
		if (error) {
			NSLog(@"Error while loading consent dialog: %@", error);
        }
		if (!STKConsentManager.sharedManager.isConsentDialogReady) {
			// Initialise SDK here
			return ;
        }
		UIViewController *rootViewController = strongSelf.window.rootViewController;
		[STKConsentManager.sharedManager showConsentDialogFromRootViewController:rootViewController 
				delegate:strongSelf];
        }];
}

You can check that the consent window is ready or not

// Indicates that consent window ready to present
let isReady = STKConsentManager.shared().isConsentDialogReady

After consent window Is ready you can present it from the top view controller

// Show consent dialog
STKConsentManager.shared().showConsentDialog(fromRootViewController: controller, delegate: self)

Handling presentation callbacks

/// Get consent manager presentation callbacks
class YourViewController: UIViewController, STKConsentManagerDisplayDelegate {
    
	// MARK: STKConsentManagerDisplayDelegate
	func consentManagerWillShowDialog(_ consentManager: STKConsentManager) {}
    
	func consentManager(_ consentManager: STKConsentManager, didFailToPresent error: Error) {
		// Something went wrong
		initializeAppodealSDK()
	}
    
	func consentManagerDidDismissDialog(_ consentManager: STKConsentManager) {
		// Resume app
		initializeAppodealSDK()
	}
}

/// Get consent manager presentation callbacks
@interface YourViewController() <STKConsentManagerDisplayDelegate>
@end

@implementation YourViewController
    
	// MARK: STKConsentManagerDisplayDelegate
	- (void)consentManagerWillShowDialog:(STKConsentManager *)consentManager {}
    
	- (void)consentManagerDidDismissDialog:(STKConsentManager *)consentManager {
		// Something went wrong
		[self initializeAppodealSDK];
	}
    
	- (void)consentManager:(STKConsentManager *)consentManager didFailToPresent:(NSError *)error {
		// Resume app
		[self initializeAppodealSDK];
	}

@end

4. App Tracking Transparency

App Tracking transparency request is enabled by default for new users with iOS 14.5 or higher. It will be presented after showConsentDialog method call. To use this your need to add AppTrackingTransparency.framework to your project.

And add NSUserTrackingUsageDescription key into your project info.plist file.

<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to deliver personalized ads to you.</string>

Because of Consent Manager will show ATT request only for users under iOS 14.5 or higher you might be to add some notes in App Review Information section of app version page in App Store Connect. For example it can be something like: App Tracking Transparency request is only available for users under iOS 14.5 or higher. This step can be needed because Apple can reject builds that contains AppTrackingTransparency.framework but which ATT requests are not showing at app launch.

In case you have your own ATT logic, you can disable it before synchronisation.

class YourAppDelegate: AppDelegate {
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]?) -> Bool {
		STKConsentManager.shared().disableAppTrackingTransparencyRequest()
        STKConsentManager.shared().synchronize(withAppKey: "Your app key") { error in
            guard let error = error else { return }
            print("Error occurred during synchronization: \(error)")
        }
        return true
    }
}

@implementation YourAppDelegate  
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
 	[STKConsentManager.sharedManager disableAppTrackingTransparencyRequest];
    [STKConsentManager.sharedManager synchronizeWithAppKey:APP_KEY completion:^(NSError *error) {
		if (error) {
			NSLog(@"Error occurred during synchronization %@", error);
		}
	}];
}

Actual tracking authorisation status can be received by trackingAuthorizationStatus:

switch STKConsentManager.shared().trackingAuthorizationStatus {
	case .restricted: print("Tracking is restricted via device settings")
    case .denied: print("Tracking is denied")
    case .authorized: print("Tracking is allowed")
    default: print("Status is unknown")
}

switch(STKConsentManager.sharedManager.trackingAuthorizationStatus) {
 	case STKTrackingAuthorizationStatusRestricted: NSLog("Tracking is restricted via device settings"); break;
    case STKTrackingAuthorizationStatusDenied: NSLog("Tracking is denied"); break;
    case STKTrackingAuthorizationStatusAuthorized: NSLog("Tracking is allowed"); break;
    default: NSLog("Status is unknown"); break;
}

5. Appodeal SDK initialisation

func initializeAppodealSDK() {        
	guard let consent = STKConsentManager.shared().consent
	else {
		let consent = STKConsentManager.shared().consentStatus != .nonPersonalized
		Appodeal.initialize(
			withApiKey: AppodealConstants.key,
			types: AppodealConstants.adTypes,
			hasConsent: consent
		)
		return 
	}
        
	Appodeal.initialize(
		withApiKey: AppodealConstants.key, 
		types: AppodealConstants.adTypes,
		consentReport: consent
	)
}

func initializeAppodealSDK() {        
	id consent = [STKConsentManager.sharedManager consent];
	if (consent != nil) {
		[Appodeal initializeWithApiKey:@"YOUR_API_KEY" 
								 types:types 	
						 consentReport:consent];
	} else {
		BOOL consent = STKConsentManager.sharedManager.consentStatus != STKConsentStatusNonPersonalized;
		[Appodeal initializeWithApiKey:APP_KEY
								 types:types
							hasConsent:consent];
    }
}

You can use our demo app as a reference project.

6. Error handling

All returned errors are NSError instances with custom codes:

Code	Description
STKConsentManagerErrorInternal	Error on SDK side. Includes JS-bridge or encoding/decoding errors
STKConsentManagerErrorNetworking	HTTP errors
STKConsentManagerErrorInconsistent	Incorrect SDK API usage
STKConsentManagerErrorUnknown	Any other errors