This document provides you with the information for Quantcast’s CMP Android integration (supporting the TCFv2 framework), currently in Beta. This Android CMP only supported for GDPR.
This document assumes that you are familiar with Android development.
Introduction
Quantcast Choice Mobile CMP (the CMP) follows the IAB TCFv2 standard. It requires at least Android 5.1 (API 22) and greater. We also highly recommend using Android Studio 4+, but this is not mandatory. The CMP UX is rendered as a DialogFragment on top of the active activity. All consent data is stored as outlined in the IAB TCFv2 mobile specs using SharedPreferences.
UI Configuration Limitations
- The CMP uses native UI components inside a DialogFragment which will be presented on top of the current Activity.
- We currently don’t support any UI customization but it is on the roadmap for future builds.
Other Limitations
The beta version does not yet support the features listed below. These will be available in the general release, and this limitation will not affect GDPR TCFv2 compliance.
- Stacks
- CCPA support
- Group level support
- Publisher restrictions
- Vendor blacklist and vendor ids
- Themes/customized styles
Known Bugs and Issues
The following known bugs and issues will be fixed in an upcoming release:
- No known issues in the latest version (2.0.0)
CMP SDK & Config
Your implementation will look something like this. You 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 button on the top right of the portal labeled "Download SDK"
Optional: You can also get the SDK using JCenter by adding the following to your build.gradle: implementation 'com.quantcast:choicecmp:1.0.0'.
Setup Android Studio Project
From Downloaded aar
- Put the .aar file into your projects /libs directory of the application.
- In the applications build.gradle file add the following gradel dependency
implementation files('libs/app-debug.aar')
From JCenter Repo
- Simply add the dependency to your application build.gradle. Remember to replace "choice_version" with the most up to date version of the library
Integrating Choice for Mobile Apps
SDK Integration (Swift)
- Implement the ChoiceCmpCallback interface
class ChoiceSampleApp : Application(), ChoiceCmpCallback {
- Implement the required callbacks. There is more info on callbacks best practices in the next section.
override fun onIABVendorConsentGiven(tcData: TCData) { }
override fun onNonIABVendorConsentGiven(nonIABData: NonIABData) { }
override fun onGoogleVendorConsentGiven(acData: ACData) { }
3. In your `Application` `onCreate` method, place the following:
class ChoiceSampleApp : Application(), ChoiceCmpCallback {
override fun onCreate() {
super.onCreate()
ChoiceCmp.startChoice(this, packageName, <YOUR PCODE>, 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. 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.
Implementing Delegate
-----------------------
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.
`didReceiveIABVendorConsent` 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 `didFinishLaunchingWithOptions`, that should instead be moved here and called after consent is checked. For example:
func onIABVendorConsentGiven(tcData: TCData) {
// if GDPR does NOT apply, feel free to start up all your vendors
If !gdprapplies || tcData.vendor.consents[200]{
// start up Quantcast Measure SDK
QuantcastClient.startQuantcast(...)
}
}
`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:
func onNonIABVendorConsentGiven(nonIabData: NonIABData) {
if(!nonIabData.gdprApplies || nonIabData.nonIabVendorConsents[vendorID]){
//startup vendor SDK
}else {
//turnoff vendor
}
}
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
func 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.
Finding Your Pcode
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.
