ConsentManager GDPR/CCPA SDK for iOS

The ConsentManager SDK for iOS apps implements and provides functionality to inform the user about data protection and ask and collect consent from the user. It enables app-developers to easily integrate the ConsentManager service into their app.

Supported Standards

The ConsentManager GDPR/CCPA SDK for Android supports the following industry standards:

• IAB TCF v1
• IAB TCF v2
• IAB USPrivacy v1
• ConsentManager custom vendors/purposes
• Google Additional Consent Mode (Google AC String)

How it works

1. Integrate the SDK into the app and configure the SDK settings
2. Once the SDK is intergated into an app, the SDK will provide functions for the app developer in order to retrieve consent data
3. As soon as the app starts, the SDK will automatically retrieve information from the ConsentManager servers in order to prepare the SDK for its usage.
4. It is recommended, that on startup of the app, the app creates an instance of class CMPConsentTool. Once the this is created, the SDK will automatically show the consent screen if necessary.
5. When the app wants to process personal data, it should "ask" the SDK if consent was given for the specific purpose and vendor.

Installation via Cocoapod

Add Library with Cocoapod

You can install the consentmanager SDK by adding consentmanager to your Podfile as explained in the example below:

target 'YourProject' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  pod 'cmpSdk'

  target 'YourProjectTests' do
    inherit! :search_paths
     # Pods for testing
  end
  
...
      
end

Once this is done, you need to run pod install in your project directory to install the consentmanager SDK. After this, please open the *.xcworkspace and build. 

After you have followed all the steps, your dependency should be installed, and you can proceed and use it in your project.

Installation via XCFramework

We strongly recommend installing and using the library with Cocoapod. Without it, it will be harder to maintain for the user as well as for the developer. This way, updates need to be integrated manually, and there are some version control issues. Therefore, we are planning to stop the active service for this library. 

Download the SDK

Please download the latest version of the SDK here:

XCFramework: https://bitbucket.org/consentmanager/consentmanager-xcframework/src/master/

The SDK is configured for iOS Version 10 and higher.

Integration

In order to integrate the SDK into your existing project, please follow these steps:

1. Pull the files from the folder ConsentManager.framework into the main folder of your app:
   

   
   
   

2. Click on your project and go to tab General and expand the part under Frameworks, Libraries, and Embedded Content:
   

   

    

3. If the module is not embedded yet, click on + (Plus) > Add Other > Add Files ...:
   

   

4. Select the ConsentManager.framework folder from this project and click on Open:
   

   

5. You should now see the Framework as "Embed & Sign" in the list:
   

   

6. Navigate to your Main View Controller of your app and import the framework by using:
   

   #import <ConsentManager/CmpConsentTool.h>

Initiate the SDK

With the app-start (usually your viewDidLoad function) you must create an instance of class CMPConsentTool.  This will automatically fetch the necessary data from our server and determine if the consent screen needs to be shown or not. If so, the SDK will automatically show the consent screen at this point, collect the data and provide the data to the app. The instance can then be used in order to get consent details from the SDK in order to use it in the app.

#import "ViewController.h"
#import <ConsentManager/CMPConsentTool.h>

@interface ViewController ()
@property (weak, nonatomic) IBOutlet UILabel *GDPRConsentStringLabel;
@end

@implementation ViewController
static CMPConsentTool *cmpConsentTool = nil;

- (void)viewDidLoad {
    [super viewDidLoad];
  	cmpConsentTool = [[CMPConsentTool alloc] init:@"consentmanager.mgr.consensu.org" addId:@"123456" addAppName:@"my%20Test%20App" addLanguage:@"DE" 							addViewController:self];
}

- (IBAction)showGDPRConsentTool:(id)sender {
    [cmpConsentTool openCmpConsentToolView];
}
@end

Example for Swift:

cmpConsentTool = CMPConsentTool.init("consentmanager.mgr.consensu.org", addId: "123456", addAppName: "my%20test%20app", addLanguage: "DE", add: self)

Please note that is is important to initialize the SDK in the didAppear Method. Otherwise the view may not be ready to use and the SDK may fail.

Please ensure to use the correct configuration data. The configuration data can be found in your ConsentManager account at Menu > Get Code.

SwiftUI

To integrate the SDK in a SwiftUI environment you must provide a UIViewController which is wrapped inside a UIViewControllerRepresentable. You can find more information about on the official apple documentation. Before integrating the SDK make sure you already integrated the Module in your project. 

1. We start with creating a usual UiViewController similar to the examples for Swift/Objective C

import UIKit
import consentmanager


class CmpViewController: UIViewController {
    struct CmpConfig {
           static let domain = "www.consentmanager.net"
           static let appId = "123456"
           static let appName = "test App"
           static let language = "DE"
       }
    var cmpConsentTool: CMPConsentTool? = nil
    func onClose() -> Void {
        NSLog("closed event");
    }

    func onOpen() -> Void {
        NSLog("opened event");
    }

    func onCMPNotOpened() -> Void {
        NSLog("not opened event");
    }
    
    override func viewDidLoad() {
        cmpConsentTool = CMPConsentTool.init(CmpConfig.domain, addId: CmpConfig.appId, addAppName: CmpConfig.appName, addLanguage: CmpConfig.language, add: self, autoupdate: true, addOpenListener: onOpen, addOnCMPNotOpenedListener: onCMPNotOpened);
        
        // creating a example button to manually open the consent screen
        let button = UIButton.init(frame: CGRect.init(x: 10, y: 100, width: 100, height: 50))
        button.setTitle("Consent", for: .normal)
        button.backgroundColor = .red
        button.addTarget(self, action: #selector(onShowConsentClicked), for: .touchUpInside)
        self.view.addSubview(button)
    }
    
    /**
     * Show consent button was clicked
     */
    @objc func onShowConsentClicked(sender: UIButton!) {
        cmpConsentTool!.openView()
    }
}

2. In order to use the controller in the swiftUI you have to create a UIViewControllerRepresentable which is instantiating the CmpViewController:

import SwiftUI

struct CmpViewControllerRepresentable: UIViewControllerRepresentable {
    func makeUIViewController(context: Context) -> UIViewController {
        let cmpViewController = CmpViewController()
        
        return cmpViewController
    }
    
    func updateUIViewController(_ uiViewController: UIViewController, context: Context) {
    }
}

3. Now we can use the ControllerView inside the SwiftUI context :

import SwiftUI

@main
struct cmpApp: App {
    var body: some Scene {
        WindowGroup {
            CmpViewControllerRepresentable()
        }
        
        
    }
}

An example project is provided here

Using the latest version of the SDK

In order to find out which version of the SDK is the latest, please check the tags in our repro:

Using the SDK

Check for consent

In order to check whether a vendor or purpose have consent, you can use the two methods:

if(consentTool!.hasPurposeConsent("52", purposeIsV1orV2: false))
{
    if(consentTool!.hasVendorConsent("s26", purposeIsV1orV2: false))
    {
        //do something with data
    }
}

Both methods hasPurposeConsent and hasVendorConsent require two parameter:

• id - String of the vendor or purpose ID. Please note that vendor IDs can have different formats ("123", "s123" and "c123"), please double-check with Menu > Vendors and Menu > Purposes in your ConsentManager account.
• isIABVendor / isIABPurpose - If the vendor or purpose is a vendor/purpose that follows the IAB TCF standard, you will need to set a true, otherwise a false.

Remember: All vendor that do not belong to the IAB have IDs starting with a "s" or "c" (e.g. "s123"); vendors that belong to the IAB have IDs not starting with a "s" or "c".

Re-Opening the Consent Screen

In order to allow the user to change the choices, you can simply call openCmpConsentToolView():

consentTool.openCmpConsentToolView();

Swift:

cmpConsentTool!.openView()

Passing Consent information to other sources

In some cases an native app might contain webviews in order to display certain things like advertising oder content. In order to transmit the consent information from the SDK to the webview, please use the function:

consentData = CMPStorageConsentManager.exportCMPData(this);

This will export the consent information and all further data that is needed by the CMP. You can then pass this information to the CMP that is in your webview by adding it to the URL that is called in the webview:

myWebView.loadURL("https://mywebsite.com/....#cmpimport=" + consentData);

Dynamic content blocking with placeholder UIView

The placeholder viewObject can be implemented to get the functionality of dynamic content blocking here.You can create the view with the following method: 

class ViewController: UIViewController, CmpPlaceholderAcceptedDelegate {
//...
  
@objc func createPlaceholderView{
	let params : CmpPlaceholderParams = CmpPlaceholderParams.init(vendorId: "123");
	let placeholder : CmpPlaceholderView = (cmpConsentTool?.createPlaceholder(CGRect.init(x: 0, y: 300, width: view.frame.size.width, height: 				view.frame.size.height), params))!;
	placeholder.vendorDelegate = self;
	view.addSubview(placeholder);	
}



func vendorAccepted(_ placeholderView: CmpPlaceholderView!) {
	//... actions to do when the consent is accepted
  	// Like showing youtube video view
}
// ...
}

With the Wrapper Object CMPPlaceholderParams you can also pass optional parameters like custom texts or an optional preview image. you can add custom Texts like shown below: 

params.buttonText = "Click me";

The required business Logic, when you want to show the view and when not need to be applied by the developer. To get information when the user is interacting with the placeholder, you can use the prepared delegate CmpPlaceholderAcceptedDelegate. With the delegate you will need to implement vendorAccepted function where you can control additional logic when the user accepted the consent. 

Integration with Apple Tracking Transparency (ATT)

Since iOS 14 Apple introduced the Apple Tracking Transparency framework, which requires that every app needs to expose which tracking data it uses. The ATT framework on its own is not compliant with the IAB TCF/GDPR, etc. and is only an apple specific version for asking user consent for tracking data. To enable the user a better experience we support a solution to synchronise the consents between the CMP SDK and the ATT interface . The SDK offers two different solutions for this. 

1. The developer integrates the ATT Framework on it's own and then pass the resulting information to the CMP SDK. Apples documentation can be found here

We're recommending this integration. You're still able to get full control of the ATT interface and implement your customised process depending of the user.  

The integration could look like this. 

       func requestPermission() {
           if #available(iOS 14, *) {
               ATTrackingManager.requestTrackingAuthorization(completionHandler: { status in
                   switch status {
                   case .authorized:
                       // Tracking authorization dialog was shown and accepted
                       // TODO custom code here:
                   case .denied:
                       // Tracking authorization dialog was shown and permission is denied
                       // TODO custom code here:
                   case .notDetermined:
                       // Tracking authorization dialog has not been shown
                       // TODO custom code here:
                   case .restricted:
                       // Tracking authorization dialog has not been shown app is restricted for tracking
                       // TODO custom code here:
                   }
                   // After determination of the att status, pass the information to the cmp sdk                                                           
                   CmpConfig.setAppleTrackingStatus(status.rawValue);
               })
           }
       }

The permission request could look like this. The important line of code is 19 where the information is passed to the CMP SDK. Depending on the ATT Status the CMP SDK sets predefined consent information. 

2. The developer activates the the automatic apple tracking. The CMP SDK handles the request with a default protocol. The status then will be handled by the CMP SDK. Afterwards it's possible to get the ATT status by the developer custom actions should be nevertheless handled on request like in option 1. You can activate the automatic ATT request with:

This will show the ATT layer from the operating system. 

CmpConfig.setAutoAppleTracking(true);

Make sure to activate this function before instantiation of the CMP SDK. 

If you not using ATT, you may have to take a note for the automatic Apple Review. Since the Apple ATT is integrated as an option but not used. Apple might not approve the Application automatically.

Custom Event Listeners

To add additional process logic you can make use of Event Listeners. Following Event Listeners are available:

Import/Export Consent

To import or export the consent you can use the function exportCMPData() and importCMPData(String cmpData). Check the example below: 

// Instanstiate CMPConsentTool()
cmpConsentTool = CMPConsentTool.init(...)

// Importing consent data if you like
cmpConsentTool.importCMPData("${your consentString}");

// ... Your code here ...


// Exporting Consent data 
let consentString : String = CMPConsentTool.exportCMPData()

The consentString you need to pass should be base64 encoded.

Compiling / Upload to AppStore

In order to compile the SDK for the AppStore you might want to use the following script in order to clean the working directory:

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
FRAMEWORK_NAME="ConsentManager.framework"
# Check if Framework is present.
FRAMEWORK_LOCATION=$(find "$APP_PATH" -name "$FRAMEWORK_NAME" -type d)
if [ -z $FRAMEWORK_LOCATION ]; then
echo "Couldn't find ConsentManager.framework in $APP_PATH. Make sure 'Embed Frameworks' build phase is listed before the 'Strip Unused Architectures' build phase."
exit 1
fi
# This script strips unused architectures
find "$APP_PATH" -name "$FRAMEWORK_NAME" -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
EXTRACTED_ARCHS=()
for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done

Changelog

Changelog can be found here in our repository.

NSUserDefaults preferences

The SDK will set NSUserDefaults values for IAB TCF v1, IAB TCF v2, IAB USPrivacy and Google AC String.

The following keys are defined:

API Overview