Android
Last update : 19/07/2022
Release version : 4.10.6
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:
TCPrivacy.getInstance().setConsentDuration(6);
Privacy module requires a minimum SDK version of 17.
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 TCPrivacy 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 String.
TCPrivacy.getInstance().setSiteIDPrivacyIDAppContextTCInstance(site_id, privacy_id, context, TC);
If you're using you're own Privacy Center, use the following function instead:
TCPrivacy.getInstance().initWithCustomPCMAndTCInstance(site_id, privacy_id, context, TC);
This call will check the saved consent, putting the SDK on hold if nothing is found, and start/stop the SDK if something is saved.
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.
TCPrivacy.getInstance().setSiteIDPrivacyIDAppContext(site_id, privacy_id, appContext);
If you're using you're own Privacy Center, use the following function instead:
TCPrivacy.getInstance().initWithCustomPCM(site_id, privacy_id, context);
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:
Map<String, String> consent = new HashMap<>();
consent.put("PRIVACY_CAT_1", "1");
consent.put("PRIVACY_CAT_2", "0");
consent.put("PRIVACY_CAT_3", "1");
consent.put("PRIVACY_VEN_61", "1");
TCPrivacy.getInstance().saveConsentFromConsentSourceWithPrivacyAction(consent, PrivacyCenter, 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.
TCPrivacy.getInstance().acceptAllConsent();
TCPrivacy.getInstance().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:
TCPrivacy.getInstance().setUserID(TCCoreConstants.kTCPredefinedVariable_NormalizedID);
If you want to use an ID from your data layer, please first add it to the permanent store:
TC.addPermanentData("MY_ID", "12345");
TCPrivacy.getInstance().setUserID("MY_ID");
and if you simply want to simply pass the information:
TCPrivacy.getInstance().setUserID("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.
TCPrivacy.getInstance().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(Map<String, String> categories);
Called when either:
- We load the saved consent
- consent is given inside the privacy center
- you manually give us the user selected consents
We have a Map which is the same as the one given to our SDK with keys PRIVACY_CAT_n and PRIVACY_VEN_n and value "0" or "1". In the case nothing was consented to, you might also have an empty map (but not null).
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.
Please also note that you can listen to starting and stopping the SDK events, you'll need to register your Observer that implements 'TCEventManager.TCLifecycleListener' interface via 'TCEventManager.registerLifecycleListener()' method.
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.
public String 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:
TCPrivacy.getInstance().consentVersion = "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.
* @param appContext the application context.
* @return True or False.
*/
public static boolean shouldDisplayPrivacyCenter(Context context)
/**
* Checks if consent has already been given by checking if consent information is saved.
* @param appContext the application context.
* @return true if the consent was already given, false otherwise.
*/
public static boolean isConsentAlreadyGiven(Context appContext);
/**
* Return the epochformatted timestamp of the last time the consent was saved.
* @param appContext the application context.
* @return epochformatted timestamp or 0.
*/
public static Long getLastTimeConsentWasSaved(Context appContext);
/**
* Check if a Category has been accepted.
* @param ID the category ID.
* @param appContext the application context.
* @return true or false.
*/
public static boolean isCategoryAccepted(int ID, Context appContext);
/**
* Check if a vendor has been accepted.
* @param ID the vendor ID.
* @param appContext the application context.
* @return true or false.
*/
public static boolean isVendorAccepted(int ID, Context appContext);
/**
* Get the list of all accepted categories.
* @param appContext the application context.
* @return a List of PRIVACY_CAT_IDs.
*/
public static List<String> getAcceptedCategories(Context appContext);
/**
* Get the list of all accepted vendors.
* @param appContext the application context.
* @return a List of PRIVACY_VEN_IDs.
*/
public static List<String> getAcceptedVendors(Context appContext);
/**
* Get the list of all google vendors accepted.
* @param appContext the application context.
* @return a List of acm_ID.
*/
public static List<String> getAcceptedGoogleVendors(Context appContext);
/**
* Get the list of everything that was accepted.
* @param appContext the application context.
* @return a List of PRIVACY_VEN_IDs and PRIVACY_CAT_IDs.
*/
public static List<String> getAllAcceptedConsent(Context appContext);
/**
* Check if a purpose has been accepted.
* @param ID the purpose ID.
* @param appContext the application context.
* @return true or false.
*/
public static boolean isIABPurposeAccepted(int ID, Context appContext);
/**
* Check if a vendor has been accepted.
* @param ID the vendor ID.
* @param appContext the application context.
* @return true or false.
*/
public static boolean isIABVendorAccepted(int ID, Context appContext);
/**
* Check if a special feature has been accepted.
* @param ID the vendor ID.
* @param appContext the application context.
* @return true or false.
*/
public static boolean isIABSpecialFeatureAccepted(int ID, Context appContext);
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.
In the Android SDK we create an Activity which is an easy way to display a "page" without have to create a specific fragment space for it. Offline JSON has to be saved in the src/main/assets folder.
To start the Privacy Center, you have to launch the corresponding activity.
Intent PCM = new Intent(getContext(), com.tagcommander.lib.privacy.TCPrivacyCenter.class);
startActivity(PCM);
Some part of the Privacy Center can be customised with your code.
TCPrivacy.getInstance().switchDefaultState = false;
Going back without consenting will result in a user not consenting at all. This means that no privacy will be saved, no tag can be called and no consent-string will be created if you use IAB.
TCPrivacy.getInstance().deactivateBackButton = true;
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 support@commandersact.com
Commanders Act | 3/5 rue Saint Georges - 75009 PARIS - France
This documentation was generated on 19/07/2022 16:25:24