[Android] 1. ConsentManager SDK Integration
The ConsentManager SDK for Android 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.
How it works
- Integrate the SDK into the app and configure the SDK settings
- Once the SDK is intergated into an app, the SDK will provide functions for the app developer in order to retrieve consent data
- 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.
- 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. - When the app wants to process personal data, it should "ask" the SDK if consent was given for the specific purpose and vendor.
Installation
Repository on Bitbucket: https://bitbucket.org/consentmanager/android-consentmanager/src/master/
Gradle
Step 1. Add the jitpack repository to your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}Step 2. Add the dependency to your apps build.gradle. (To always get the latest version use the + symbol to get the newest updates. You can for example always get the newest versions for minor updates through 1.x.+)
dependencies {
implementation 'org.bitbucket.consentmanager:android-consentmanager:1.5.+'
}
Maven
Step 1. Add the jitpack repository to your build.gradle at the end of repositories:
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
Step 2. Add the dependency to your apps build.gradle. (To always get the latest version in maven you can use different methods to decline the version range. you can look them up here )
<dependency>
<groupId>org.bitbucket.consentmanager</groupId>
<artifactId>android-consentmanager</artifactId>
<version>1.5.7</version>
</dependency>
Using the library
Permissions
This SDK requires the following permissions, please ensure to add them to your AndroidManifest.xml:
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.INTERNET" />Initiate ConsentTool
With the app-start (usually your viewDidAppear 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.
To initiate the ConsentTool, go to your targeted class and create a instance of CMPConsentTool like shown below:
//...
import net.consentmanager.sdk.CMPConsentTool;
//...
public class MainActivity extends AppCompatActivity {
private CMPConsentTool consentTool;
//...
@Override
protected void onCreate(Bundle savedInstanceState) {
//..
consentTool = CMPConsentTool.createInstance(this, 123456, "consentmanager.mgr.consensu.org", "MyFavouriteApp", "");
}
//...
}
In order to create the instance of CMPConsentTool you need to configure the instance. You will need to provide the CMP-ID, server domain , an app name and a language. The CMP-ID and server domain can be found in your ConsentManager account under Menu > Get Code. The app name can be used in order to distinguis different apps in the ConsentManager reporting. For the language you can either use an empty string ("") for auto-detection or a 2-letter language code ("EN", "DE", "FR" and so on).
The configuration values can be inserted via different ways:
a) SDK-Configuration via CMPConfig
Add the following lines to your code:
val config = CMPConfig.apply {
serverDomain = CMP_DOMAIN
appName = CMP_APP_NAME
language = LANG
id = APP_ID
}
val consentTool = CMPConsentTool.createInstance(this, config);b) SDK-Configuration via createInstance()
Add the following line to your code:
consentTool = CMPConsentTool.createInstance(this, 1234567, "consentmanager.mgr.consensu.org", "MyFavouriteApp", "EN");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(this,"52",false))
{
if(consentTool.hasVendorConsent(this,"s26", 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(this);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:
String consentData = CMPConsentTool.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);Custom Event Listeners
To add additional process logic you can make use of Event Listeners. Following Event Listeners are available:
| Name |
Occurrs
|
| OnOpenCallback |
Listener for Event when CMP opened |
| OnCMPCloseCallback |
Listener for Event when CMP is closed |
| OnCMPNotOpenedCallback |
Listener for Event when CMP doesn't need to be opened |
|
OnErrorCallback |
Listener for Event when there is an error in the consent management process. |
Import/Export Consent
To import or export the consent you can use the function exportCMPData(Context context) and importCMPData(Context context, String cmpData). Check the example below:
// Importing consent data if you like
CMPConsentTool.importCMPData(this, "${your consentString}");
// Instantiate CMPConsentTool()
consentTool = CMPConsentTool.createInstance(...)
// ... Your code here ...
// Exporting Consent data
String consentString = CMPConsentTool.exportCMPData(this);The consentString you need to pass should be base64 encoded.
CMP SDK Sequence Diagram
.png)
Shared preferences
The SDK will set the shared preferences values for IAB TCF v1, IAB TCF v2, IAB USPrivacy and Google AC String. These values can be read by using the following code:
Context mContext = getApplicationContext();
SharedPreferences mPreferences = PreferenceManager.getDefaultSharedPreferences(mContext);
SharedPreferences.OnSharedPreferenceChangeListener mListener;
mListener = new SharedPreferences.OnSharedPreferenceChangeListener() {
public void onSharedPreferenceChanged(SharedPreferences preferences, String key) {
if (key.equals([Specific Consent Key])) {
// Update Consent settings
}
}
};
mPreferences.registerOnSharedPreferenceChangeListener(mListener);
The following keys are defined:
| IAB TCF v1 | |
IABConsent_CMPPresent |
Boolean: Set to true if a CMP implementing this specification is present in the application. Ideally set by the Publisher as soon as possible but can also be set by the CMP alternatively. |
IABConsent_SubjectToGDPR |
String 1 - (subject to GDPR), 0 - (not subject to GDPR), Nil - undetermined (default before initialization). Aligns with IAB OpenRTB GDPR Advisory. Decided to be String, to have the uninitialized status. |
IABConsent_ConsentString |
String: Consent string |
IABConsent_ParsedPurposeConsents |
String (of "0" and "1") where the character in position N indicates the consent status to purpose ID N as defined in the Global Vendor List. String of consent given to enable simple checking. First character from the left being Purpose 1, ... |
IABConsent_ParsedVendorConsents |
String (of "0" and "1") where the character in position N indicates the consent status to vendor ID N as defined in the Global Vendor List. String of consent given to enable simple checking. First character from the left being Vendor 1, ... |
| IAB TCF v2 | |
IABTCF_CmpSdkID |
Number: The unsigned integer ID of CMP SDK |
IABTCF_CmpSdkVersion |
Number: The unsigned integer version number of CMP SDK |
IABTCF_PolicyVersion |
Number: The unsigned integer representing the version of the TCF that these consents adhere to. |
IABTCF_gdprApplies |
Number:
Unset - undetermined (default before initialization) |
IABTCF_PublisherCC |
String: Two-letter ISO 3166-1 alpha-2 code – Default: AA (unknown) |
IABTCF_PurposeOneTreatment |
Number:
Unset default - Vendors can use this value to determine whether consent for purpose one is required. |
IABTCF_UseNonStandardStacks |
Number:
|
IABTCF_TCString |
String: Full encoded TC string |
IABTCF_VendorConsents |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the consent status for Vendor ID n+1; false and true respectively. eg. '1' at index 0 is consent true for vendor ID 1
|
IABTCF_VendorLegitimateInterests |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the legitimate interest status for Vendor ID n+1; false and true respectively. eg. '1' at index 0 is legitimate interest established true for vendor ID 1
|
IABTCF_PurposeConsents |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the consent status for purpose ID n+1; false and true respectively. eg. '1' at index 0 is consent true for purpose ID 1
|
IABTCF_PurposeLegitimateInterests |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the legitimate interest status for purpose ID n+1; false and true respectively. eg. '1' at index 0 is legitimate interest established true for purpose ID 1
|
IABTCF_SpecialFeaturesOptIns |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the opt-in status for special feature ID n+1; false and true respectively. eg. '1' at index 0 is opt-in true for special feature ID 1
|
IABTCF_PublisherRestrictions{ID} |
String ['0','1', or '2']: The value at position n – where n's indexing begins at 0 – indicates the publisher restriction type (0-2) for vendor n+1; (see Publisher Restrictions Types). eg. '2' at index 0 is restrictionType 2 for vendor ID 1. {ID} refers to the purpose ID. |
IABTCF_PublisherConsent |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the purpose consent status for purpose ID n+1 for the publisher as they correspond to the Global Vendor List Purposes; false and true respectively. eg. '1' at index 0 is consent true for purpose ID 1
|
IABTCF_PublisherLegitimateInterests |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the purpose legitimate interest status for purpose ID n+1 for the publisher as they correspond to the Global Vendor List Purposes; false and true respectively. eg. '1' at index 0 is legitimate interest established true for purpose ID 1
|
IABTCF_PublisherCustomPurposesConsents |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the purpose consent status for the publisher's custom purpose ID n+1 for the publisher; false and true respectively. eg. '1' at index 0 is consent true for custom purpose ID 1
|
IABTCF_PublisherCustomPurposesLegitimateInterests |
Binary String: The '0' or '1' at position n – where n's indexing begins at 0 – indicates the purpose legitimate interest status for the publisher's custom purpose ID n+1 for the publisher; false and true respectively. eg. '1' at index 0 is legitimate interest established true for custom purpose ID 1
|
| IAB USPrivacy | |
IABUSPrivacy_String |
String: Aligns with IAB OpenRTB CCPA Advisory. The String encodes all choices and information. |
| Google AC String | |
IABTCF_AddtlConsent |
|
(Deprecated) Dynamic content blocking with placeholder webView
This function has been deprecated and will be removed in the future. The reason for deprecation is that with the enable and disable vendor and purpose APIs, there is no need to create a Placeholder anymore. You can add your own UI and your own business logic and activate and deactivate vendors dynamically. Instead of using this function, you should use the enableVendorList() and disableVendorList() functions to manage which vendors are enabled or disabled, and create your own UI to display this information to the user.
The placeholder viewObject can be implemented to get the functionality of dynamic content blocking here.You can create the view with the following method:
CMPPlaceholder placeholderView = CMPConsentTool.createPlaceholder(getApplicationContext(),CMPPlaceholderParams
.ofVendor("${vendorId}"), new CMPPlaceholderEventListener() {
@Override
public void vendorAccepted(WebView view) {
//... Actions to trigger if Consent is accepted
// Like showing Youtube Video View
}
});With the Wrapper Object CMPPlaceholderParams you can also pass optional parameters like custom texts or a optional preview image. The builder functions are called setCustomplaceholder(String headline, String mainText, String checkboxText, String buttonText) and setOptionalImageUrl(String imageUrl).
The required business Logic, when you want to show the view and when not need to be applied by the developer. You can pass required condition and actions by using the EvenListener Callbacks from the CMPPlaceholderEventlistener. Following required Event need to be implemented:
Required: vendorAccepted(CMPPlaceholderView view) { // Your logic }
Optional: errorOccurred(String message) { // Error handling }
