Mobile Android Implementation Guide

Quantcast Choice allows site owners to manage consent across multiple devices and environments, including Android. Quantcast Choice Mobile CMP (the CMP) follows the IAB TCF v2 standard. It requires at least Android 5.0 (API 21) and greater. We also highly recommend using Android Studio 4+, but this is not mandatory. 

The CMP uses native UI components inside a DialogFragment which will be presented on top of the current Activity. All consent data is stored as outlined in the IAB TCFv2 mobile specs using SharedPreferences. With our recent release (Android v2007) we have added UI customization to our Choice mobile SDK. The UI customization allows the developer to customize color and font styles for all the UI components used in the Choice Mobile CMP, allowing the developer to match the UI style of the host application. For information on how to customize styles, see our UI Customization for Mobile Android article.

Follow these steps to set up the Choice Android SDK:

• CMP SDK & Configuration
• Set up Android Studio Project
• Integrate Choice for Mobile Apps
• Find Your Account ID

Known Issue

Currently the consent rates are not being exposed properly on the Privacy Properties page.  However the full analytic reports are still visible using the Reports button.

CMP SDK & Configuration

Start in our Choice portal by configuring your app under the general setting in the Protect an App page. After you configure your app in our Choice Configuration Portal, you can download the SDK using the Download SDK button on the top right of the portal.

Set up Android Studio Project

From Downloaded aar

1. Put the .aar file into your projects/libs directory of the application.
2. In the applications build.gradle file add the following gradle dependencies

   implementation files('libs/Choice-Mobile.aar')
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
   implementation "androidx.lifecycle:lifecycle-livedata-ktx:$lifecycle_version"
   implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:$lifecycle_version
   implementation 'com.jakewharton.threetenabp:threetenabp:1.3.1'

   
3. If you are using Java you need to add the kotlin standard library dependency.

   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"

4. Also in the application build.gradle file you need to activate the viewBinding feature by adding the following code inside the android block

   buildFeatures {
   viewBinding true
   }

Integrate Choice for Mobile Apps

SDK Integration (Kotlin)

1. Implement the ChoiceCmpCallback interface

   class ChoiceSampleApp : Application(), ChoiceCmpCallback {

2. Implement the required methods for ChoiceCmpCallback. There is more info on callbacks best practices in the next section.
   

   override fun onCmpLoaded(info: PingReturn) { /* code */ }
   override fun onCmpUIShown(info: PingReturn) { /* code */ }
   override fun onIABVendorConsentGiven(tcData: TCData) { /* code */ }
   override fun onNonIABVendorConsentGiven(nonIABData: NonIABData) { /* code */ }
   override fun onCmpError(error: ChoiceError) { /* code */ }
   override fun onGoogleVendorConsentGiven(acData: ACData) { /* code */ }
   override fun onCCPAConsentGiven(consentString: String) { /* code */ }

3. In your Application onCreate method, place the below snippet. The startChoice method takes the application, the packageId of your app (should match the web portal), your pcode, and a delegate object, it also take one more parameter related to customization styles but if you are using Kotlin you do not have to worry about since it is a optional parameter, if you are using Java you can pass a empty object of ChoiceStylesResources. Know more about it in the UI Customization for Mobile Android section.
   

   class ChoiceSampleApp : Application(), ChoiceCmpCallback {
   override fun onCreate() {
           super.onCreate()
           ChoiceCmp.startChoice(
                   app = this, 
                   packageId = packageId,
                   pCode = <YOUR PCODE>, 
                   callback = this
           )
   }
   }

4. Implement a way to force the CMP dialog to show. This is required in order to allow a user to change consent at any time they want. Usually this can be put in a menu next to your app’s privacy policy or other settings. Note: The startChoice method will take care of showing the popup if it is required. This method is only needed to show the popup on demand. To pop open the CMP just call:

   ChoiceCmp.forceDisplayUI()

   This is all that is required at this point. The SDK will monitor any lifecycle events and be sure that consent is available. If consent is not found, the CMP will automatically pop up and prompt the user. Every time a user has been prompted, the callbacks will fire.
5.  Since the latest version of the SDK is using the ViewBinding feature you have to make sure that the gradle version and gradle plugin version are up to date or are at least in version 7+ otherwise the app will throw an exception. This problem is usually faced by developers that use React Native because the generated Android project is setted with a previous gradle version.

Implement Callback

You must implement the three different consent callbacks even though you may not have configured all of the consent features. We just want to be sure no consent handling is missed.   

1. onIABVendorConsentGiven is called with user consent for IAB compliant vendors. A list of IAB compliant vendors can be found here. Ideally IAB compliant mobile frameworks will automatically pick up this consent and configure themselves on or off. However, there are not many IAB compliant mobile frameworks so if you are in doubt reach out to your vendor and ask. If the framework is not compliant, then you are responsible for handling the consent yourself. If the framework has a setup method that is supposed to be called in the onCreate, that should instead be moved here and called after consent is checked. For example:
   

   override fun onIABVendorConsentGiven(tcData: TCData) {  
       // if GDPR does NOT apply, feel free to start up all your vendors
       if (tcData.gdprApplies == false || tcData.vendor.consents["200"] == true){
          // start up Quantcast Measure SDK (This is just an example mobile SDK)
          QuantcastClient.startQuantcast(...)
       }
   }

2. onNonIABVendorConsentGiven callback. These are vendors that have been set up in the Choice Portal and will not automatically check for consent. Consent is given as a simple "yes, everything" or "no, nothing". To check consent look up the specific vendor by id (given in the Choice Portal) with the following:
   

   override fun onNonIABVendorConsentGiven(nonIabData: NonIABData) {
       if( !nonIABData.gdprApplies || nonIABData.nonIabVendorConsents[vendorId] == true){
   
       }else {
           //turnoff vendor
       }
   }

3. The other main callback to be aware of is onGoogleVendorConsentGiven. This callback is called only if you have Google Vendors turned on in the portal. For more information about Google Vendors, please see https://support.google.com/admanager/answer/9681920. Similar to the other callbacks, you should use this callback to manage the Google Vendors.
   

   override fun onGoogleVendorConsentGiven (acData: ACData) {
       if(!acData.gdprApplies || acData.additionalVendorConsent[vendorID]){
           //startup vendor SDK
       }else {
           //turnoff vendor
       }
   }

The rest of the callbacks are not necessary but are provided for debugging or advanced uses. onCmpError will fire any time the CMP exits unexpectedly and fails to collect consent for whatever reason.

CCPA Integration

Once you have initialized the SDK and all the loading process is completed you can show CCPA screen by calling the following method from ChoiceCmp object passing the activity: argument AppCompatActivity:

ChoiceCmp.showCCPAScreen(activity: AppCompatActivity)

Then you will be able to get the IABUSPrivacy_String through SharePreferences using the same name as the key or throughChoiceCmpCallback with onCCPAConsentGiven method which will be called when the user gives the consent in the CCPA screen.

Find Your Account ID

The SDK initialization requires you to pass us your account id (or p-code) for identification. This id can be found on the Choice Portal in the top right corner. Click on the account name and a dropdown will appear with the pcode next to it.