Info
Content
Books
CMP
Integration into your App
ConsentManager GDPR/CC...

ConsentManager GDPR/CCPA SDK for Android

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.

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

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.3.+'
}

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.3.3</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", "");
    //.. You can also instantiate the consentmanager with the advertisement id:
    // consentTool = CMPConsentTool.createWIthIDFA(this,123456,"www.consentmanager.mgr.consensu.org", "myFavouriteApp", "EN", "38400000-8cf0-11bd-b23e-10b96e40000d"); 

    }
//...
}

 

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 Manifest

Add the following lines to your AndroidManifest.xml under section <application ...> ... </application>:

<meta-data android:name="com.consentmanager.sdk.ID" android:value="1234567" />
<meta-data android:name="com.consentmanager.sdk.SERVER_DOMAIN" android:value="consentmanager.mgr.consensu.org" />
<meta-data android:name="com.consentmanager.sdk.APP_NAME" android:value="MyFavouriteApp" />
<meta-data android:name="com.consentmanager.sdk.LANGUAGE" android:value="EN" />

If you use this way of configuration, create an instance of CMPConsentTool via:

consentTool = CMPConsentTool.createInstance(this);
b) SDK-Configuration via CMPConfig

Add the following lines to your code:

CMPConfig conf = CMPConfig.createInstance(1234567, "consentmanager.mgr.consensu.org", "MyFavouriteApp", "EN");
consentTool = CMPConsentTool.createInstance(this, conf);
c) SDK-Configuration via createInstance()

Add the following line to your code:

consentTool = CMPConsentTool.createInstance(this, 1234567, "consentmanager.mgr.consensu.org", "MyFavouriteApp", "EN");

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

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);

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);

 

Dynamic content blocking with placeholder webView

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 }

 

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
OnNetworkExceptionCallback

Listener for Event when CMP has network problems

OnErrorDialogCallback

Listener for Event when CMP can not reach the Consentmanager server

CustomOpenActionCallback

Listener for Event when CMP opens

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: 

The consentString you need to pass should be base64 encoded.

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:

1 GDPR applies in current context

0 - GDPR does not apply in current context

Unset - undetermined (default before initialization)
IABTCF_PublisherCC String: Two-letter ISO 3166-1 alpha-2 code – Default: AA (unknown)
IABTCF_PurposeOneTreatment Number:

0 - no special treatment of purpose one

1 - purpose one not disclosed

Unset default - 0

Vendors can use this value to determine whether consent for purpose one is required.
IABTCF_UseNonStandardStacks Number:

1 - CMP used a non-standard stack

0 - CMP did not use a non-standard stack
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

String: Aligns with Google’s Additional Consent Mode technical specification. 

API Overview

API

 Parameters Returns

Description

 

openCmpConsentToolView(

Context context

)

 context: The Context of the App void  Displays a modal view with the consent web view. If the Compliance is accepted or rejected, a close function will be called. You can override this close function with your own. Therefore implement the OnCloseCallback and add this as a parameter. @apiNote User Interface -> example: Open Layer by button action
       

openCmpConsentToolView(

Context context,

OnCloseCallback callback

)

context: The Context of the App

 

callback: The OnCloseCallback that should be called when the webview is closed by action

 

 void Displays a modal view with the consent web view. If the Compliance is accepted or rejected, a close function will be called. You can override this close function with your own. Therefor implement the OnCloseCallback and give it to this function. This Method will not send a request to the consentTool Server again. It will use the last state. If you only want to open the consent Tool View again, if the server gives a response status == 1 use the checkAndProceedConsentUpdate method @apiNote User Interface -> example: Open Layer by button action

setCloseCmpConsentToolViewListener(

OnCloseCallback callback

)

 callback: The OnCloseCallback that should be called when the webview is closed by action void Sets a Listener. If the Compliance is accepted or rejected, this function will be called. You can override this close function with your own. Therefor implement the OnCloseCallback and add this as the parameter.
       
       

setCustomCmpConsentToolViewAction(

CustomOpenActionCallback customAction

)

 customAction: The customAction that should be called, apart from showing the consentTool void Sets a Custom action to a server response.

setErrorDialogCmpConsentToolViewListener(

OnErrorDialogCallback callback

)

 callback: The OnOpenCallback, that should be called, when the View will be opened. void Sets a Listener. If the Compliance View is opened this function will be called. You can override this open function with your own. Therefor implement the OnOpenCallback and add this as the parameter.

setNetworkErrorExceptionListener(

OnNetworkExceptionCallback callback

)

 callback: The OnErrorNetworkCallback that needs to be called. void Sets a listener that is called, if a network error occurs.

setOnCMPNotOpenedCallback(

OnCMPNotOpenedCallback callback

)

 callback:  The cmpNotOpenedCallback action which will be called void Sets a action when the Consentlayer is not going to open

setOpenCmpConsentToolViewListener(

Context context,

Button gdprButton

)

context: Then Context of the App

gdprButton: The Button, the openCmpConsentToolViewListener should be added to

 void Sets a Listener to the given button, If the Button is clicked, a modal view will be displayed with the consent web view. If the Compliance is accepted or rejected, a close function will be called. You can override this close function with your own. Therefor implement the OnCloseCallback and add this as an other parameter. If the parameter is not set, but the setCloseCmpConsentToolViewListener was used to add a listener to the close event, this will be used.

setOpenCmpConsentToolViewListener(

Context context,

Button gdprButton,

OnCloseCallback callback

)

context: The Context of the App

gdprButton: The Button, the openCmpConsentToolViewListener should be added to

 

callback: The OnCloseCallback that should be called when the webview is closed by action

 void Sets a Listener to the given button, If the Button is clicked, a modal view will be displayed with the consent web view. If the Compliance is accepted or rejected, a close function will be called. You can override this close function with your own. Therefor implement the OnCloseCallback and add this as the last parameter.

setOpenCmpConsentToolViewListener(

OnCloseCallback callback

)

callback: The OnCloseCallback that should be called when the webview is closed by action

 void Sets a Listener. If the Compliance View is opened this function will be called. You can override this open function with your own. Therefor implement the OnOpenCallback and add this as the parameter.

setOpenPlaceHolderViewListener(

Context context,

Button button,

String vendor

)

context: The Context of the App

button: A actionbutton to create the placeholderview

vendor: The vendor which is assigned to the placeholder

 void Opens the placeholder view on button click for the assigned vendor 
 

 

    

calledThisDay(

Context context)

context: The Context of the App

 boolean: if the server was already contacted this day Returns if the server was already contacted this day.

clearAllValues(Context context)

context: The Context of the App

 void Resets consent data

createPlaceholder(

Context context, 

CMPPlaceholderParams cmpPlaceholderParams, 

CmpPlaceholderEventListener cmpPlaceholderEventListener)

context: The app Context

cmpPlaceholderParams: 

assign required placeholder parameters

cmpPlaceholderEventListener: EventListener Interface for custom process functions

 CmpPlaceholder: UIView of the Placeholder Creates a placeholder view for dynamic content blocking

exportCMPData(Context context)

context: The app context

 String: The consentstring An export Function that can be called to export the full consentString generated by a ConsentWebView and saved in the Shared Preferences of this device.

getCalledLast(Context context)

context: The app context

 Date: Date when the server was called last Gives information about the last date the server was contacted

getConfig()

 

CMPConfig:

CMPConfig object

 Returns the CMPConfig which is set currently

getGoogleACString()

context: The app context

String: US Privacy String of vendors that was set through consentmanager

 Returns the US Privacy String, that was set by consentmanager

getInstance()

 

CMPConsentTool:

The initialized singleton instant of the consentmanager

 Returns the CMPConsentTool. If you have not initialised the CMPConsentTool before, The CMPConsentToolInitialisation Exception will be thrown.

getInstanceUnsafe()

 

CMPConsentTool:

the initialised singleton Instant of the consent Manager, or null.

 Returns the CMPConsentTool, or null if it wasn't initialised. This method is unsafe, because it can lead to null pointer exceptions, but if you are sure, the ConsentTool was initialised before, you can use this Method, without the need to catch the error. We recommend to save the returned Object from the createInstant Method, to use the Methods of the consentManager.

getLastConsentString(

Context context)

context: The app context

String: 

The last set consentstring

 Returns the last given Consent, presented in base64 by consentManager

getPurposes(Context context)

context: The app context

String: The String of purposes that was set through consentmanager

 Returns the purposes String, that was set by consentmanager

getUSPrivacyString(Context context)

context: The app context

String: The US Privacy String of vendors that was set through consentmanager

 Returns the US Privacy String, that was set by consentmanager

getVendorsString(Context context)

context: The app context

String: The String of vendors that was set through consentmanager

 Returns the Vendor String, that was set by consentmanager

hasPurposeConsent(Context context,

String id,

boolean isIABPurpose)

context: the app context

id: The id of the purpose

isIABPurpose: If the purpose is set by IAB standard (V1/V2)

boolean: 

If the purpose has the consent to set cookies

Returns, if the purpose (id) has the rights to set cookies.

Attention: The purpose id is the same as shown in the purpose list and can have a prefix like C

hasVendorConsent(

Context context,

String id,

boolean isIABVendor)

context: The app context

id: The id of the vendor

isIABVendor: if the vendor is set by IAB standard (V1/V2)

boolean: If the Vendor has the Consent to set cookies.

Returns, if the Vendor (id) has the rights to set cookies

 

Attention: The vendor id is the same as shown in the vendor list and can have a prefix like C, S

importCMPData(

Context context, 

String cmpData

)

context: The app context

cmpData: The String that will be set. The consentString should be passed as encoded base64 

boolean: 

If the import was successful, or  if errors occurs in the String

 An import Method that can be called to import the full consentString generated by a ConsentWebView into the Shared Preferences of this device.

needsAcceptance(Context context)

context: The app context

boolean: if the user needs to give a consent

 Returns if the user needs to give a consent, cause he didn't do so in the past, or because the consent Server returned, that a new consent is required

needsServerUpdate(Context context)

context: The app context

boolean: If the consentmanager needs to be updated

If the CMPSettings need to be updated from the server, cause they were not at this day.

 

 

 

 

 

Details
Revision #34
Created 2 years ago by Jan
Updated 2 months ago by Jan
Don't have an account yet?

Become GDPR compliant with our GDPR Cookie Consent Manager solution. Try now for free!

GDPR Cookie Consent Manager
Back to top