1. madvertise Avatar madvertise
  2. bluestack-public
  3. madvertise-gdpr-cmp-android

Wiki

Clone wiki

madvertise-gdpr-cmp-android / cmp_setup

View History

BlueStack CMP SDK

This documentation will go through all the steps required to integrate BlueStack CMP SDK on Android platform.

Prerequisites

Before You Start, MAdvertiseCMP requires minimum :

  • CompileSdkVersion at least 29.
  • Android Studio 4.0 or higher.
  • Android 4.4 (API level 19) or higher (But it work only in Android 7.0 (API level 24) or higher).
  • Since Version 30 and later, it's required that your project migrates from Android Support Libraries to Jetpack Libraries (Android X).

Integration Guide

Step 1: Import the BlueStack CMP SDK

In the main build.gradle of your project, you must declare the Bluestack repository: 

allprojects {
    repositories {
        google()
        jcenter()

    // For All Bluestack SDKs (Mediation, CMP, Location)
    maven 
    {
     credentials 
        {
         username "madvertise-maven"
         password "GpdGZ9GE9SK7ByWdM987"
        } 
     url "https://api.bitbucket.org/2.0/repositories/mngcorp/deploy-maven-bluestack/src/master"
     authentication 
        {
        basic(BasicAuthentication)
        }
     }
    }
}

In the build.gradle of to your application module, you can now import the Bluestack CMP by declaring it in the dependencies section:

implementation 'com.madvertise:cmp-sdk:65.0.0'

Step 2: Enable support for the new language APIs of Java 1.8

Add the following line to your app's build.gradle :

android {
  defaultConfig {
    // Required when setting minSdkVersion to 20 or lower
    multiDexEnabled true
  }

  compileOptions {
    // Flag to enable support for the new language APIs
    coreLibraryDesugaringEnabled true
    // Sets Java compatibility to Java 8
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

dependencies {
 coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.0.10'
}

Step 3: 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 file should be added to your main/res/raw folder.

  • The configuration files for the following languages are present in the main/res/raw of the demo:

    • German
    • Italian
    • French
    • English

  • Here's an example of how you can use the configuration files depending on the language :

int configRes;
switch (Locale.getDefault().getISO3Language()) {
                case "fra":
                    configRes = R.raw.madvertise_config_fr;
                    break;
                case "ita":
                    configRes = R.raw.madvertise_config_it;
                    break;
                case "deu":
                    configRes = R.raw.madvertise_config_de;
                    break;
                default:
                    configRes = R.raw.madvertise_config_en;
                    break;
 }

Step 4: Initialize the configuration file

You have to init the configuration in your application class :

ConsentToolConfiguration consentToolConfiguration = new ConsentToolConfiguration(R.raw.madvertise_config_fr);

You can customize appearance :

Background :

To change the default background of the consent tool (optional) you'll have to specify the resource id of your background, it can be either a color or a drawable, using the configuration tool method with this signature

public ConsentToolConfiguration setHomeBackgroundRes(int homeBackgroundRes)

Size :

To change the default size of the consent tool (optional) you'll have to add the width and height of the desired tool using the configuration tool method with this signature

public ConsentToolConfiguration setConsentToolSize(int pxWidth, int pxHeight)

Step 5: Initialize BlueStack CMP SDK

Once our SDK has been added to your project, you need to configure it. The configuration process will run in a background thread and prepare the SDK for interactions with the user and your application. It is important to launch the SDK initialization as soon as possible.

You have to init the SDK in the onCreate function of your main Application class :

ConsentManager.sharedInstance.configure(this,YOUR_APP_ID, new ConsentToolConfiguration(configRes),YOUR_PUBLISHER_CC);

The configure method takes the following parameters:

  • the Application context.
  • 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"...).

Integration example :

Here's an example of how to do that in onCreate on an application subclass:

public class YourApp extends Application {

  @Override  
  public void onCreate() {
    super.onCreate();

ConsentManager.sharedInstance.configure(this,1234567,  new ConsentToolConfiguration(configRes),"FR");

  }
}

Enforce a specific language :

You can enforce your preferred language for the cmp with these init :

ConsentManager.sharedInstance.configure(this,YOUR_APP_ID,YOUR_PREFERRED_LANG, new ConsentToolConfiguration(configRes),YOUR_PUBLISHER_CC);
  • the language you want to show CMP with it((Two-letter) like "fr","en","it"....) (Optional)

Integration example :

Here's an example of how to do that in onCreate on an application subclass:

public class YourApp extends Application {

  @Override  
  public void onCreate() {
    super.onCreate();

ConsentManager.sharedInstance.configure(YourActivity,1234567, "fr", new ConsentToolConfiguration(configRes),"FR");

  }
}

Step 6: Show BlueStack CMP SDK (Starting from V57)

To collect the user consent, call the showCMP method in the onCreate method of your Activity.

ConsentManager.sharedInstance.showCMP(YourApplication, new OnConsentProvidedListener() {
            @Override
            public void consentProvided(String actionType) {

            }

            @Override
            public void consentFailed( String error) { 

            }
        });

Note :

  • The showCMP method takes the following parameters:

    • the current Activity.
    • a OnConsentProvidedListener interface to listen to changes of the consent signal.

  • The SDK will notify your listener OnConsentProvidedListener of all possible events listed below :

    • consentProvided(actionType: String) : A consent notice has been displayed to the user or the consent status has been synchronized. you can get the type of button which the user clicked. The 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.

    • consentFailed(error: String): This method is called when an error occurs during initialisation or configuration of CMP.This method provides an string error that contains the reason of the failure.

  • The showCMP method must be called at each launch of your application to be sure to have an up-to-date consent status.

Advanced Topics

As per the GDPR regulation, publishers need to ensure the users can access and edit their consent choices through their application at any time.

Integration :

The openCMPUI method behaves the same way as the showCMP method but enforces the display. 

ConsentManager.sharedInstance.openCMP(YourActivity,new OnConsentProvidedListener() {
                            @Override
                            public void consentProvided(@NotNull String actionType) {

                            }

                            @Override
                            public void consentFailed(String error) {

                            }
                        });
Note :

  • The openCMP method takes the following parameters:

    • the current Activity.
    • a OnConsentProvidedListener interface to listen to changes of the consent signal.

  • We recommend to expose a button to edit the consent in the application settings.

  • You can use this simple method : openCMP with the current Activity:

ConsentManager.sharedInstance.openCMP(YourActivity);

Enable Debug Mode

Add following line before adding your configurations in order to add debug logs : 

ConsentManager.sharedInstance.setDebugModeEnable(true)

Get TCString

The TC data values can be retrieved from the application Shared Preferences by key name using the get methods on the android.content.SharedPreferences class.

Example:

SharedPreferences mPreferences = PreferenceManager.getDefaultSharedPreferences(getApplicationContext());
String consentString = mPreferences.getString("IABTCF_TCString", "");

Note: The preference manager does not currently store a strong reference to the listener. If you do not store a strong reference, the listener will be susceptible to garbage collection. External guidance such as this documentation on setting listeners may provide more information on listening for preference changes.

Example:

SharedPreferences mPreferences = PreferenceManager.getDefaultSharedPreferences(getApplicationContext());
SharedPreferences.OnSharedPreferenceChangeListener mListener;
mListener = new SharedPreferences.OnSharedPreferenceChangeListener() {
            public void onSharedPreferenceChanged(SharedPreferences preferences, String key) {
                        if (key.equals("IABTCF_TCString")) {
                                   // Update Consent settings
                                   }
                        }
            };
mPreferences.registerOnSharedPreferenceChangeListener(mListener);

Fullscreen Page

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

setConsentToolSize(ConsentToolConfiguration.MATCH_PARENT,ConsentToolConfiguration.MATCH_PARENT);

Here's an example:

public class YourApp extends Application {

  @Override
  public void onCreate() {
    super.onCreate();
    ConsentManager.sharedInstance.configure(this, YOUR_APP_ID , Locale.getDefault(), 
    new ConsentToolConfiguration(R.raw.madvertise_config)
                .setConsentToolSize(ConsentToolConfiguration.MATCH_PARENT,ConsentToolConfiguration.MATCH_PARENT),"FR");
  }
}

This listener is called by clicking in the custom privacy policy.

        ConsentManager.sharedInstance.setOnPrivacyPolicyRequestedListener(new OnPrivacyPolicyRequestedListener() {
            @Override
            public void onPrivacyPolicyRequested(@NotNull String url) {

            }
        });

Here's an example:

Privacy Policy URL = "Test://readme"

        ConsentManager.sharedInstance.setOnPrivacyPolicyRequestedListener(new OnPrivacyPolicyRequestedListener() {
            @Override
            public void onPrivacyPolicyRequested(@NotNull String url) {
                Intent i = new Intent(SplashActivity.this, ReadMeActivity.class);
                startActivity(i);
            }
        });

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.

Collect External Purposes IDs

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

ConsentManager.sharedInstance.getExternalPurposesIDs(context)

Here's an example:

Log.e(TAG,ConsentManager.sharedInstance.getExternalPurposesIDs(mContext))

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

Collect Purposes IDs

To collect purposes IDs, you can use the method :

ConsentManager.sharedInstance.getPurposesIDs(context)

Here's an example:

Log.e(TAG,ConsentManager.sharedInstance.getPurposesIDs(mContext))

You will get something like this: : TAG: [1,2,3,4,5,6,7,8,9,10]

To check whether the consent tool is shown, you can use the method : 

ConsentManager.sharedInstance.isConsentToolShown()

Here's an example:

if (!ConsentManager.sharedInstance.isConsentToolShown()){
    startActivity(new Intent(this, HomeActivity.class))
}

Check if user close CMP Popup with close button

To check if user close CMP Popup with close button, you can use the method :

ConsentManager.sharedInstance.isConsentToolClosed()

Here's an example:

if (!ConsentManager.sharedInstance.isConsentToolClosed()){
   .....
}

Change state of external purposes IDs, vendors IDs or external vendors IDs

To change state of external purposes IDs , vendors IDs or external vendors IDs in TcfString consent, you can use the method : 

ConsentManager.sharedInstance.updateExternalIDs(Context,listOfPurposes, listOfVendors,listOfExternalVendors,type)

The updateExternalIDs method takes the following parameters:

  • the context.
  • the list of external purposes IDs.
  • the list of vendors IDs.
  • the list of external vendors IDs.
  • type of change : True -> Add or false --> Delete.

Updated