This document provides you with the information for Quantcast’s CMP iOS integration (supporting the TCFv2 framework), currently in Beta. This CMP iOS integration is only supported for GDPR.
This document assumes that you are familiar with iOS development.
Introduction
Quantcast Choice Mobile CMP (the CMP) follows the IAB TCFv2 standard. It requires at least iOS 10.0 and greater. The CMP UX is rendered within a view controller presented on top of the rootViewController of the application. All consent data is stored as outlined in the IAB TCFv2 mobile specs using UserDefaults.
UI Configuration Limitations
- The CMP uses native UI components inside a viewController which will presented on top of the rootViewController.
- The publisher logo is not displayed in the in-App CMP yet.
- 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
- 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. Your application's bundleID must match the Package ID field given here.
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 Cocoapods with the pod name: Quantcast-Choice-CMP
Setup Xcode Project
From Downloaded zip
- From your open XCode project, select the top (blue) project file from the left file pane.
- On the General tab, find the 'Frameworks, Libraries, and Embedded Content' section and click the + button.
- On the bottom left of the popover, click the 'Add Other…' dropdown and select 'Add Files…', select ChoiceMobile.framework file.
From CocoaPods
Simply add the pod to your CocoaPods dependency file:
pod 'ChoiceMobile'
Integrating Choice for Mobile Apps
SDK Integration (Swift)
- Import `import ChoiceMobile` into your `UIApplicationDelegate` class
import ChoiceMobile
- Make your delegate class implement the `ChoiceCmpDelegate` or create separate delegate class
class AppDelegate: UIResponder, UIApplicationDelegate, ChoiceCmpDelegate {
- Implement the required callbacks. There is more info on callbacks best practices in the next section.
func didReceiveIABVendorConsent(tcData: TCData, updated:Bool) { }
func didRecieveNonIABVendorConsent(nonIabData: NonIABData, updated:Bool) { }
func didRecieveAdditionalConsent(acData: ACData, updated:Bool) { }
func cmpDidError(error: Error)
- In your `UIApplication` delegate's `application:didFinishLaunchingWithOptions:` method, place the following below any rootViewController initialization:
ChoiceCmp.shared.startChoice(pcode: <Quantcast_Pcode_here>, delegate: ChoiceDelegate())
- 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 apps privacy policy or other settings. To pop open the CMP just call:
ChoiceCmp.shared.forceDisplayUI()
SDK Integration (SwiftUI)
- Import `import ChoiceMobile` into your `App` class
import ChoiceMobile
- Make a simple delegate class that implements the `ChoiceCmpDelegate` at the top of the file (or wherever you'd like)
class ChoiceDelegate: NSObject, ChoiceCmpDelegate {
- Implement the required callbacks. More info on callbacks best practices in the next section.
func didReceiveIABVendorConsent(tcData: TCData, updated:Bool) { }
func didRecieveNonIABVendorConsent(nonIabData: NonIABData, updated:Bool) { }
func didReceiveAdditionalConsent(acData: ACData, updated:Bool) {}
func cmpDidError(error: Error)
- Set up an onChange notification of the main WindowGroup, and initialize the CMP on the active state:
.onChange(of: scenePhase) { newScenePhase in
if newScenePhase == .active {
ChoiceCmp.shared.startChoice(pcode: <Quantcast_Pcode_here>, delegate: ChoiceDelegate())
}
}
- 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.shared.forceDisplayUI()
SDK Integration (Objective C)
The Choice CMP is also compatible with Objective C. These steps would be required for products using React Native
- Import ChoiceMobile into your `UIApplicationDelegate` header (.h) file
#import<ChoiceMobile/ChoiceMobile-Swift.h>
- Make your delegate class implement the `ChoiceCmpDelegate` or create separate delegate class
@interface AppDelegate : UIResponder <UIApplicationDelegate, ChoiceCmpDelegate>Implement the required callbacks. More info best practices in the callbacks in the next section.
- Implement the required callbacks. More info best practices in the callbacks in the next section.
- (void)cmpDidErrorWithError:(NSError * _Nonnull)error {}
- (void)cmpDidLoadWithInfo:(PingResponse * _Nonnull)info {}
- (void)cmpDidShowWithInfo:(PingResponse * _Nonnull)info {}
- (void)didReceiveAdditionalConsentWithAcData:(ACData * _Nonnull)acData updated:(BOOL)updated {}
- (void)didReceiveIABVendorConsentWithTcData:(TCData * _Nonnull)tcData updated:(BOOL)updated {}
- (void)didReceiveNonIABVendorConsentWithNonIabData:(NonIABData * _Nonnull)nonIabData updated:(BOOL)updated {}
- In your `UIApplication` delegate's `application:didFinishLaunchingWithOptions:` method, place the following below any rootViewController initialization:
[[ChoiceCmp shared] startChoiceWithPcode:@<Quantcast_Pcode_here>" delegate:self];
- 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 shared] 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 didReceiveIABVendorConsent(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
QuantcastMeasurement.sharedInstance.setupMeasurementSessionWithAPIKey(...)
}
}
`didRecieveNonIABVendorConsent` 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 didRecieveNonIABVendorConsent(nonIabData: NonIABData) {
if(!nonIabData.gdprApplies || nonIabData.nonIabVendorConsents[vendorID]){
//startup vendor SDK
}else {
//turnoff vendor
}
}
The other main callback to be aware of is `didReceiveAdditionalConsent`. 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 didReceiveAdditionalConsent (acData: ACData) {
if(!acData.gdprApplies || acData.additionalVendorConsent[vendorID]){
//startup vendor SDK
}else {
//turnoff vendor
}
}
The rest of the callbacks are probably not necessary but are provided for debugging or advanced uses. `cmpDidError` 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.
