MAdvertise CMP

MAdvertise CMP

This documentation will go through all the steps required to integrate MAdvertiseCMP on IOS platform.

Prerequisites

Before You Start, MAdvertiseCMP requires minimum :

Xcode 11.4 + target on Swift 5.x
ios 10 or later

Integration Guide

Step 1: Import the MAdvertiseCMP SDK

First you will need to add the framework to you project:

Using Cocoapods:

The MAdvertiseCMP framework is available through Cocoapods. see Using CocoaPods section.

Manually :

download the latest version of MAdvertiseCMP framework, add it to your project and make sure it s included in 'Embedded binaries' in the general tab of your project configuration.

You can find the file here : MAdvertiseCMP-v34

Step 2: Prepare the configuration file

Introduction

Through this file, you can:

Defining Strings : You can edit the content of text to allow the same field to display different content based on the language of the user.
Customizing Appearance : You can change global properties to alter the look and feel of the default instance interface (Functionality is not affected).

For more details on how to prepare the file, you can find it in this link : MAdvertiseCMP - Configuration File.

Integration

The configuration files for the following languages are present in the Config Files :
- German (de)
- Italian (it)
- French (fr)
- English (en)

Step 3: Initialize the configuration file

once the consent settings is configured and added to your target, you can then initialise/configure the CMPConsentManager shared instance by providing the name of you consent settings file, eg :

The configure method takes the following parameters:

the App Id of your application.
the Consent Tool Configuration object.
the publisherCC value (corresponds to the country code (Two-letter) of the country in which the publisher's business entity is established like "FR", "DE", "IT"...).

        // Configure the CMPConsentManager shared instance.
         CMPLanguage *cmpLanguage = [[CMPLanguage alloc]initWithString:@"fr"];
         [CMPConsentManager.sharedInstance configure:@"MAdvertiseCMPSettingsTCFV2_config_fr" language:cmpLanguage appId:Your_APP_ID publisherCC:@"FR"];
         CMPConsentManager.sharedInstance.delegate = self;

     CMPConsentManager.shared.delegate = self

        // Configure the CMPConsentManager shared instance.
        let cmpLanguage = CMPLanguage(string: "fr") ?? CMPLanguage.DEFAULT_LANGUAGE
        CMPConsentManager.shared.configure("MAdvertiseCMPSettingsTCFV2_config_fr", language: cmpLanguage, appId: "APPid", publisherCC: "FR")

# Since v54 : Configure with AutoClose Option :

Since v54 you can then initialise/configure with the option autoClose when the user clicked Custom link:

autoClose: Boolean to activate the dismiss of the popup automatically:

True: when user clicked the custom link the popup is dismissed
False: when user clicked the custom link the popup is not dismissed

        // Configure the CMPConsentManager shared instance.
         CMPLanguage *cmpLanguage = [[CMPLanguage alloc]initWithString:@"fr"];
         [CMPConsentManager.sharedInstance configure:@"MAdvertiseCMPSettingsTCFV2_config_fr" language:cmpLanguage appId:Your_APP_ID publisherCC:@"FR" autoClose:true];
         CMPConsentManager.sharedInstance.delegate = self;

     CMPConsentManager.shared.delegate = self

        // Configure the CMPConsentManager shared instance.
        let cmpLanguage = CMPLanguage(string: "fr") ?? CMPLanguage.DEFAULT_LANGUAGE
        CMPConsentManager.shared.configure("MAdvertiseCMPSettingsTCFV2_config_fr", language: cmpLanguage, appId: "APPid", publisherCC: "FR",autoClose:true)

now once the consent manager finishes its setup process it will call on its delegate by invoking the following method to let the publisher know that the manager is ready and he should display the consent tool to the user :

 // MARK: - CMPConsentManagerDelegate

- (void)consentManagerRequestsToShowConsentTool:(CMPConsentManager * _Nonnull)consentManager
        if ([consentManager showConsentToolFromController:self withPopup:false]) {
        NSLog(@"------> Consent consentManagerRequestsToShowConsentTool ");
    }
     }

func consentManagerRequestsToShowConsentTool(_ consentManager: CMPConsentManager, forVendorList vendorList: CMPVendorList) {
        NSLog("CMP Requested ConsentTool Display");

        // You should display the consent tool UI, when user is ready…
        if let controller = self.window?.rootViewController {
            let _ = consentManager.showConsentTool(fromController: controller, withPopup: true)
        }

    }

once the above delegate is called you should display the consent tool (or use your own) using the following line :

 [consentManager showConsentToolFromController:self withPopup:false];

 let _ = consentManager.showConsentTool(fromController: controller, withPopup: true)

Also every time the TC string changes its value another callback method of the CMPConsentManagerDelegate delegate will be invoked to inform you of the recent change :

-(void)tcfConsentStringDidChange:(TCFString *)newTcfConsentString {
    NSLog(@"------> TCFStrin did changed : %@", newConsentString.tcfString);

func tcfConsentStringDidChange(_ newTcfConsentString: TCFString) {
    print("TCFString string did change")
}

Since V41 : tcfConsentStringDidChange:(TCFString *)newTcfConsentString is depreceated :

Use the new callback method of the CMPConsentManagerDelegate delegate will be invoked to inform you of the recent change (tcfOnConsentStringDidChange:newTcfConsentString consentProvided) with new attribut consentProvided :

In the consentProvided String , you can get the answer of the user. The Answer (actionType variable) has one of the following values:

ConsentToolAcceptButton : The user has approved all vendors and all purposes displayed in the consent notice
ConsentToolRefuseButton : The user has refused all vendors and all purposes displayed in the consent notice.
ConsentToolSettingsButton :The user has approved some vendors and/or some purposes displayed in the consent notice.

-(void)tcfOnConsentStringDidChange:(TCFString *)newTcfConsentString consentProvided:(NSString *)consentProvided {
    NSLog(@"------> TCFStrin did changed : %@ with status : %@", newConsentString.tcfString, consentProvided);
}

func tcfOnConsentStringDidChange(_ newTcfConsentString: MAdvertiseCMP.TCFString, consentProvided: String){
    print("TCFString string did change with \(consentProvided) status")

}

Custom Privacy Policy Link

Note as well that some of the users might want to view (review) the publisher's privacy policy, and for that purpose we dedicated another callback method on CMPConsentManager.shared.delegate with the url clicked :

Objective-c

- (void)consentManagerRequestsToPresentPrivacyPolicyWithUrl:(NSString*)url{}

Swift

func consentManagerRequestsToPresentPrivacyPolicy(url:String){ }

Note :

By default an HTTP link that open the browser
You can use these links to open our internal pages:
- "bluestack://vendors" to see the list of vendors.
- "bluestack://features" to see the list of features and special features.
- "bluestack://specialPurposes" to see the list of special uses.
- "bluestack://managementStoredData" to manage your stored personal data.
- "bluestack://vendorsGoogle" to see the list of Advertising Technology Suppliers.

once the above delegate Tells that an error occurred during initialisation Or Showing :

-(void)consentManagerDidFailWithErrorWithError:(NSError *)error{

}

 func consentManagerDidFailWithError(error: Error){

}

Step 4: Initialize the MAdvertiseCMP SDK

Objective-c

In case you find some kind of issue importing the framework to your objective c classes, you should know that just importing MAdvertiseCMP-Swift.h header will be enough to have the entire framework imported, so wherever you want to use the framework just add this line :

#import <MAdvertiseCMP/MAdvertiseCMP-Swift.h>

the current version of the framework doesnt support bitcode, so when archiving your app you will need to disable bitcode.

Advanced Topics

Fullscreen Page

You can use a fullscreen page instead of a Popup, you need to the following method to your ConsentToolConfiguration :

You can display the view ConsentTool location either in pop-up form or in full screen by the bollean attribut withPopup

- (void)consentManagerRequestsToShowConsentTool:(CMPConsentManager * _Nonnull)consentManager forVendorList:(CMPVendorList * _Nonnull)vendorList {
    if ([CMPConsentManager.sharedInstance showConsentToolFromController:self withPopup:YES]) {
    }
}

func consentManagerRequestsToShowConsentTool(_ consentManager: CMPConsentManager, forVendorList vendorList: CMPVendorList) {
        NSLog("CMP Requested ConsentTool Display");

        // You should display the consent tool UI, when user is ready…
        if let controller = self.window?.rootViewController {
            let _ = consentManager.showConsentTool(fromController: controller, withPopup: true)
        }

    }

Collect External Purposes IDs

Option 1 :

To collect external purposes IDs, you can use the method :

[CMPConsentManager.sharedInstance getExternalPurposesIDs]

CMPConsentManager.shared.getExternalPurposesIDs()

Here's an example:

    NSArray * purposeIDs =    [CMPConsentManager.sharedInstance getExternalPurposesIDs];

    NSLog(@"------> ExternalPurposesIDs : %@",[NSString stringWithFormat:@"%@",[purposeIDs description]]);

You will get something like this: : TAG: [3,4,5]

Option 2 :

You can get it directly through NSUserDefaults with tag IABTCF_PublisherConsent.

Collect IAB Purposes IDs