iOS
Last update : 15/07/2022
Release version : 4.9.8
The privacy module can be used in a lot of different ways, after this short introduction, you will find links to each of the different ways and their specific documentations.
Having the user consent is essential to send sensible information like the IDFA/AAID or using any personal information to serve advertising.
We created this module to simplify the management of you user's privacy and the way to use it.
This module can:
- Display a consent page (if needed)
- Save consent inside the phone and reload it every time the application is launched.
- Check the validity of the consent. The validity duration is set to 13 months.
- Send a hit to our servers to record the consent. For statisical purposes.
- Save the consent String (if used alongside IAB)
- Enable or disable the SDK. (if used alongside the SDK)
- Add the categories automatically to the hits the SDK sends. (if used alongside the SDK)
- Forward the consent to the developpers if they need it outside of the module.
Privacy comes with two major flavors:
- With Tag Management (With SDK)
- Standalone
And 3 different ways to display it:
- Manually and then forwarding us the information
- Using our Privacy Center for IAB version 2
- Using our Privacy Center for simple Privacy
If you're unsure of which one you should use, please contact the person in charge of your account.
/!\ If you are using our interface, you need to have a version of privacy.json inside your project. This will prevent any issues with users with bad or no internet at all. If you are using IAB please also take vendor-list.json and the translation file purposes-fr.json. If you are not using our interface, you can't use our privacy.json, if you want a way to use a configuration file, please ask your dev team to manage this file.
After initialisation the Privacy module will check the consent validity. If the consent is too old a callback will be called. Please check the Callback part. The default value is 13 months.
If you're using our interface, and thus our privacy.json, you can change the duration on this validity. To do this, add "consentDurationInMonths": "6" inside the "information" bloc.
If you're not using our interface, you'll have to manually change it in the code. We express this duration in months. The duration of a month is calculated by 365/12 days. Please first call the following method before initializing the Privacy module else:
[[TCMobilePrivacy sharedInstance] setConsentDuration: 6];
Modules: Core, Privacy, SDK
This module can use the same model you are using on the web, if you do so, please start by getting the IDs of the categories you are going to use. Join those IDs with a "consent version". Default is 001, but if you change the implementation, it's better to increment this version.
The setup is really simple, pass to the TCMobilePrivacy object your site ID, application context and a pointer to your TagCommanders' SDK instance. If you want to add your consent version, you can add it to the parameters as a NSString.
[[TCMobilePrivacy sharedInstance] setSiteID: 3311 TCInstance: tc AndVersion: @"001"];
If you're using you're own Privacy Center, use the following function instead:
[[TCMobilePrivacy sharedInstance] customPCMSetSiteID: siteID privacyID: privacyID andTCInstance: tc];
This call will check the saved consent, putting the SDK on hold if nothing is fount, and start/stop the SDK if something is saved. It will then the check the consent validity, if it's too old, you can implement a callback treating what to do then. Please check the Callback part.
Please note that start and stop have a notification sent with them, you can listen to them if needed: kTCNotification_StartingTheSDK and kTCNotification_StoppingTheSDK.
If you need to store configuration files in another bundle than the main one, you can call the following line:
[[TCConfigurationFileFactory sharedInstance] setBundle: myBundle forConfiguration: @"vendorlist"];
But please call this before calling [TCMobilePrivacy sharedInstance].
Modules: Core, Privacy
You won't need the SDK module, and will need to implement a callback to manage your solutions when consent is given or re-loaded.
The setup is really simple, pass to the TCPrivacy object your site ID application context. If you want to add your consent version, you can add it to the parameters as a String.
[[TCMobilePrivacy sharedInstance] setSiteID: siteID andPrivacyID: privacyID];
If you're using you're own Privacy Center, use the following function instead:
[[TCMobilePrivacy sharedInstance] customPCMSetSiteID: siteID privacyID: privacyID];
Here is where the IDs of the categories matters.
If you're using the Privacy Center, nothing has to be done here, it will automatically propagate the consent to all other systems. And the ID will be the one used in the configuration file. Please check the Privacy Center part for more information.
Please keep your category IDs between 1 and 999.
Once the user validated his consent, you can the send the information to the Privacy module as follow:
NSMutableDictionary *consent = [[NSMutableDictionary alloc] initWithCapacity: 3];
[consent setObject: @"1" forKey: @"PRIVACY_CAT_1"];
[consent setObject: @"0" forKey: @"PRIVACY_CAT_2"];
[consent setObject: @"2" forKey: @"PRIVACY_CAT_3"];
[[TCMobilePrivacy sharedInstance] saveConsent: consent fromConsentSource: Popup withPrivacyAction: Save];
ETCConsentSource is either "Popup" or "PrivacyCenter".
ETCConsentAction is either "AcceptAll", "RefuseAll", "Save"
Please prefix your category IDs with "PRIVACY_CAT_" and your vendor IDs with "PRIVACY_VEN_. 1 means accepting this category or vendor, 2 is for mandatory vendors or categorues, 0 is refusing.
If you're using the SDK, this will propagate the information to the SDK and manage its state.
/!\ Those methods only work if you are using our interface and thus have a privacy.json in your project (and maybe IAB's JSON as well).
Those are intended for clients that are displaying a first "popup" screen before our interfaces and that have a way to either open the privacy center of accept/refuse the consent.
We created functions to call if you want to create a simple way to accept or refuse all consent from outside our user interface.
[[TCMobilePrivacy sharedInstance] acceptAllConsent];
[[TCMobilePrivacy sharedInstance] refuseAllConsent];
The saving of the consent on our servers is done automatically.
But since we are saving the consent in our servers, we need to identify the user one way or another. By default the variable used to identify the user consenting is #TC_SDK_ID#, but you can change it to anything you'd like.
If you're looking for a way to proove consent or reset saved information, you'll need to create a specific screen in app for this.
If you want to use an ID already inside the SDK:
[[TCMobilePrivacy sharedInstance] setConsentUser: @"#TC_IDFA#"];
If you want to use an ID from your data layer, please first add it to the permanant store:
[tc addPermanentData: @"MY_ID" withValue: @"12345"];
[[TCMobilePrivacy sharedInstance] setConsentUser: @"MY_ID"];
and if you simply want to simply pass the information:
[[TCMobilePrivacy sharedInstance] setConsentUser: @"123456765432"];
This can be used to save the display of the consent, and giving the consent.
This ID is very important because it will be the basic information used to get back the consent when you need a proof.
You will be able to get the information more easily since this is an ID available by several means for you.
This is the defaul variable used to save privacy. It's generated by the SDK the first time you open the app and never changes.
You might want to be able to display to your end user the ID used to save the consent, in this case we created a function to easily get it.
[[TCMobilePrivacy sharedInstance] getPrivacyUserID];
If you are familiar with Commanders Act privacy for web, you know that we actually record two things. The first thing is "displaying the consent form". This allow you to prove that a user has indeed been shown the consent screen even if he somehow left without accepting/refusing to give his consent.
In some cases, client also use this to infer user consent since he continued using the application after he was shown the consent screen. We don't recommend this behaviour, please discuss it with your setup team first.
Some of the event happening in the SDK have callbacks associated with them in the case you need to do specific actions at this specific moment.
Currently we have a callback function that lets you get back the categories and setup your other partners accordingly. This is the function where you would tell your ad partner "the user don't wan't to receive personalized ads" for example.
/!\ Don't forget to register to the callbacks before the initialisation of the Privacy Module since the module will check consent at init and use the callback at this step.
Implement TCPrivacyCallbacks to get access to those callbacks:
- (void) consentUpdated: (NSDictionary *) consent;
Called when you give us the user selected consents, or when we load the saved consent from the SDK. We have a Dictionnary which is the same as the one given to our SDK with keys PRIVACY_CAT_n and value @"0" or @"1".
- (void) consentOutdated;
This is called after 13 months without change in the user consent. This can allow you to force displaying the consent the same way you would on first launch.
- (void) consentCategoryChanged;
When you make a change in the JSON, there is nothing special to do. But when this change is adding or removing a category, or changing an ID, we should re-display the Privacy Center.
- (void) significantChangesInPrivacy;
This one is slightly different from the last one, it was created for IAB and will not be sent automatically. It is conditionned by the field "significantChanges" in the privacy.json so that it will only launch when you need it to.
Some clients need to have the consent forwarded in their webViews to manage a web container inside it. We created a function to get the privacy as a JSON string so you can save it inside the webView's local storage. /!\ This function only help saving it to the local storage by giving the required format, you will still need to have JS code in the web container to use it. Please ask your consultant for this part.
- (NSString *) getConsentAsJson;
If the case you need to manually change the consent version (if you're using your own privacy center for example), you can use the following:
[[TCMobilePrivacy sharedInstance] setConsentVersion: @"132"];
We created several methods to check given consent. They are simple, but make it easier to work with consent information at any given time. You'll find those in the class TCPrivacyAPI:
/**
* Checks if we should display privacy center for any reason.
* @return True or False.
*/
+ (BOOL) shouldDisplayPrivacyCenter
/**
* Checks if consent has already been given by checking if consent information is saved.
* @return YES if the consent was already given, NO otherwise.
*/
+ (BOOL) isConsentAlreadyGiven;
/**
* Return the epochformatted timestamp of the last time the consent was saved.
* @return epochformatted timestamp or 0.
*/
+ (unsigned long long) getLastTimeConsentWasSaved;
/**
* Check if a Category has been accepted.
* @param ID the category ID.
* @return YES or NO.
*/
+ (BOOL) isCategoryAccepted: (int) catID;
/**
* Check if a vendor has been accepted.
* @param ID the vendor ID.
* @return YES or NO.
*/
+ (BOOL) isVendorAccepted: (int) venID;
/**
* Get the list of all accepted vendors.
* @return a List of PRIVACY_VEN_IDs.
*/
+ (NSArray<NSString *> *) getAcceptedCategories;
/**
* Get the list of all accepted vendors.
* @return a List of PRIVACY_VEN_IDs.
*/
+ (NSArray<NSString *> *) getAcceptedVendors;
/**
* Get the list of everything that was accepted.
* @return a List of PRIVACY_VEN_IDs and PRIVACY_CAT_IDs.
*/
+ (NSArray<NSString *> *) getAllAcceptedConsent;
/**
* Check if a purpose has been accepted.
* @param ID the purpose ID.
* @return YES or NO
*/
+ (BOOL) isIABPurposeAccepted: (int) ID;
/**
* Check if a vendor has been accepted.
* @param ID the vendor ID.
* @return YES or NO
*/
+ (BOOL) isIABVendorAccepted: (int) ID;
/**
* Check if a special feature has been accepted.
* @param ID the vendor ID.
* @return YES or NO
*/
+ (BOOL) isIABSpecialFeatureAccepted: (int) ID;
/**
* Get the list of all google vendor accepted.
* @return a list of acm_IDs.
*/
+ (NSArray <NSString *> *) getAcceptedGoogleVendors;
The Privacy Center is represented by a JSON file that describes the interfaces that will be created by native code inside the application.
For now this JSON has to be created and managed manually. And the SDK will check for updates of the file automatically.
Your account should have a consultant that will provide you the corresponding JSON for your project.
We create an UIViewController to create the privacy center view. The offline JSON should be inside the project code folder.
TCPrivacyCenterViewController *PCM = [[TCPrivacyCenterViewController alloc] init];
[self.navigationController pushViewController: PCM animated: YES];
Since we have a view controller, you can call it by pushing it. It's quite easy.
Some part of the Privacy Center can be customised with your code.
[TCMobilePrivacy sharedInstance].switchDefaultState = NO;
If you wanna implement your own UI Testing on your app, you might need the following accessibilities keys for accessing our multiple UI Buttons :
please make sure you've already imported TCPrivacyConstants.h
| Key | Description |
|---|---|
| TC_POPUP_SCREEN_DETAILS_BTN | First layer's details button |
| TC_POPUP_SCREEN_ACCEPT_ALL_BTN | First layer's accept all button |
| TC_POPUP_SCREEN_REFUSE_ALL_BTN | First layer's refuse all button |
| TC_VENDORS_SCREEN_SAVE_EXIT_BTN | Vendors screen save and exit button |
| TC_VENDORS_SCREEN_ACCEPT_ALL_BTN | Vendors screen accept all button |
| TC_VENDORS_SCREEN_REFUSE_ALL_BTN | Vendors screen refuse all button |
| TC_VENDORS_SCREEN_SHOW_PURPOSES_BTN | Vendors screen's show purposes screen button |
| TC_PURPOSES_SCREEN_SAVE_EXIT_BTN | Purposes screen save and exit button |
| TC_PURPOSES_SCREEN_ACCEPT_ALL_BTN | Purposes screen accept all button |
| TC_PURPOSES_SCREEN_REFUSE_ALL_BTN | Purposes screen refuse all button |
| TC_PURPOSES_SCREEN_SHOW_VENDORS_BTN | Purposes screen's show vendor screen button |
Switches on the UI hold the following accessibility identifier :
| Type | Description |
|---|---|
| IAB Purpose | PRIVACY_CAT_X where X = iabId * 2 - 1 + 10000 |
| IAB Special Feature | PRIVACY_CAT_X where X = iabId + 13000 |
| IAB Vendor | PRIVACY_VEN_X where X = ( IAB.id * 2 ) + 1000 - 1 |
| Custom Vendor | PRIVACY_VEN_ID |
| Custom Category | PRIVACY_CAT_ID |
| Google Vendor | acm_ID |
We have dashboards that allow to have detailed statistics on the choices your users are making. Depending on your app privacy configuration you might have to call some additional functions.
- Custom « banner/popup » -> our privacy center
- Custom « banner/popup » -> Custom privacy center
- Directly to our privacy center
- Custom privacy center
Whenever saveConsent* is called you will need to provide the full list of purposes and vendors that have been consented to and refused.
We reworked saveConsent methods to only use one. If you are using the old functions they will still work for now. Otherwise please check the above section "Manually displayed consent" for how this method works.
Also please note that you will need to call statViewBanner when you display your custom banner.
You can, of course, check our demo project for a simple implementation example.
Support [email protected]
Commanders Act | 3/5 rue Saint Georges - 75009 PARIS - France
This documentation was generated on 15/07/2022 14:25:57